Compartilhar via

Agentes de teste usando o Microsoft Agent 365 SDK

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. Prévias da Frontier estão sujeitas aos termos de pré-visualização existentes dos seus contratos com clientes. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Teste seu agente localmente usando o Agents Playground antes da implantação. Este guia aborda como configurar seu ambiente de desenvolvimento, configurar a autenticação e validar a funcionalidade do seu agente usando a ferramenta de testes Agents Playground.

Assim que seu agente atuar localmente, você pode seguir o Ciclo de Vida do Desenvolvimento do Agente 365 para testar em aplicativos do Microsoft 365 como Teams, Word e Outlook.

Pré-requisitos

Antes de começar, verifique se de que tem os seguintes pré-requisitos:

Pré-requisitos do curso

Pré-requisitos específicos de cada idioma

  • Python 3.11 ou posterior: Baixe na python.org ou na Microsoft Store
  • Gerenciador de pacotes UV: Instale UV usando pip install uv
  • Verifique a instalação:

Configurar o ambiente de teste do agente

Esta seção descreve como definir variáveis de ambiente, autenticar seu ambiente de desenvolvimento e preparar seu agente alimentado por Agent 365 para testes.

Configurar seu ambiente de teste de agentes segue um fluxo de trabalho sequencial:

  1. Configure seu ambiente - Crie ou atualize seu arquivo de configuração do ambiente.

  2. Configuração do LLM - Obtenha chaves de API e configure configurações do OpenAI ou Azure OpenAI.

  3. Configurar autenticação - Configurar autenticação agente.

  4. Referência de variáveis de ambiente - Configure as variáveis de ambiente necessárias:

    1. Variáveis de autenticação
    2. Configuração do ponto final MCP
    3. Variáveis de observabilidade
    4. Configuração do servidor de aplicação agente

Após completar esses passos, você está pronto para começar a testar seu agente no Agents Playground.

Etapa 1: Configurar seu ambiente

Definir o arquivo de configuração

cp .env.template .env

Observação

Para modelos de configuração que mostram os campos necessários, veja os exemplos do Microsoft Agent 365 SDK.

Etapa 2: Configuração

Configure as configurações do OpenAI ou Azure OpenAI para testes locais. Adicione suas chaves de API e endpoints de serviço dos pré-requisitos ao seu arquivo de configuração junto com quaisquer parâmetros do modelo.

Adicione ao arquivo :

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Variáveis de ambiente em Python LLM

Variável Description Necessário Exemplo
OPENAI_API_KEY A chave da API para o serviço OpenAI. Para o OpenAI: sk-proj-...
AZURE_OPENAI_API_KEY A chave de API para o Serviço OpenAI do Azure. Para o OpenAI do Azure: a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT : ponto de extremidade do serviço OpenAI do Azure. Para o OpenAI do Azure: https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT : nome da implantação do OpenAI do Azure Para o OpenAI do Azure: gpt-4
AZURE_OPENAI_API_VERSION Versão da API do Azure OpenAI Para o OpenAI do Azure: 2024-02-15-preview

Passo 3: Configure a autenticação para seu agente

Escolha um dos seguintes métodos de autenticação para seu agente:

  • Autenticação agente - Uso em cenários de produção quando uma identidade de usuário agente está disponível.
  • Autenticação OBO - Use para cenários de produção quando você precisa de permissões de usuário delegadas sem uma identidade agente.
  • Autenticação de token de portador - Use apenas para cenários iniciais de desenvolvimento e testes antes da configuração da autenticação em produção.

Autenticação agente

Use o comando CLI a365 config display Agent 365 para recuperar as credenciais do seu projeto de agente.

a365 config display -g

Este comando exibe a configuração do seu blueprint do agente. Copie os valores a seguir:

Value Description
agentBlueprintId O ID do cliente do seu corretor
agentBlueprintClientSecret Segredo de cliente do seu agente
tenantId Sua ID de locatário do Microsoft Entra

Use estes valores para configurar a autenticação agente no seu agente:

Adicione as seguintes configurações ao seu .env arquivo, substituindo os valores provisórios pelos seus credenciais reais:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variável Description Necessário Exemplo
USE_AGENTIC_AUTH Ativar o modo de autenticação agente Sim true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID do cliente do projeto do agente a partir de a365 config display -g Sim 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Secreto do cliente do projeto de agente a365 config display -g Sim abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID A ID do locatário do Microsoft Entra Sim adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

autenticação em nome do usuário

A autenticação on-Behalf-Of (OBO) permite que seu agente acesse as ferramentas do servidor MCP usando permissões de usuário delegadas sem exigir uma identidade agente. Nesse fluxo, o agente recebe o token delegado pelo usuário e o troca para realizar ações em nome do usuário.

A autenticação OBO é adequada para cenários de produção onde:

  • Seu agente não tem uma identidade de usuário agente.
  • Você precisa acessar recursos com permissões específicas para cada usuário.
  • Você quer que o agente atue em nome do usuário autenticado.

Para detalhes sobre como funciona o fluxo OBO, veja Fluxos de autenticação. Para um exemplo completo de implementação, veja o exemplo de autorização OBO no Microsoft 365 Agents SDK.

Autenticação de token de portador

Para cenários iniciais de desenvolvimento e testes, quando a autenticação em produção não está configurada, use a autenticação por token portador para testar seu agente. Esse método utiliza autenticação interativa do navegador para obter um token de acesso delegado. Ao usar esse token, seu agente pode chamar ferramentas do MCP Server usando suas permissões de usuário. Essa abordagem simula como um usuário agente acessa recursos em produção sem exigir uma instância real de agente.

Primeiro, use a365 develop add-permissions para adicionar as permissões necessárias do servidor MCP à sua aplicação:

a365 develop add-permissions

Depois, use a365 develop get-token para recuperar e configurar os tokens portadores:

a365 develop get-token

O get-token comando automaticamente:

  • Recupera tokens portadores de todos os servidores MCP configurados no seu ToolingManifest.json arquivo
  • Atualiza os arquivos de configuração do seu projeto com a BEARER_TOKEN variável ambiente

Observação

As fichas de portador expiram após cerca de uma hora. Use a365 develop get-token para atualizar tokens expirados.

Etapa 2: variáveis de ambiente

Complete a configuração do seu ambiente configurando as seguintes variáveis de ambiente obrigatórias:

  • Variáveis de autenticação - Configurações obrigatórias para autenticação agente
  • Configuração do endpoint MCP - Especificar o endpoint da plataforma Agent 365
  • Variáveis de observabilidade - Permitir registro e rastreamento distribuído
  • Configuração do servidor de aplicação agente - Configure a porta onde seu servidor agente roda

Variáveis de autenticação

Configure as configurações do handler de autenticação necessárias para que a autenticação agente funcione corretamente.

Adicione ao arquivo :

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Variável Description Necessário
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Manipulador de autenticação Sim
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Escopos de autenticação para Microsoft Graph Sim
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nome alternativo da conexão do blueprint Sim
CONNECTIONSMAP_0_SERVICEURL Padrão de URL de serviço para mapeamento de conexão Sim
CONNECTIONSMAP_0_CONNECTION Nome da conexão para mapeamento Sim

Configuração do ponto de extremidade

Especifique o endpoint da plataforma Agent 365 ao qual seu agente se conecta. Quando você gerar o manifesto de ferramentas que define os servidores de ferramentas para seu agente, especifique o endpoint da plataforma MCP. Esse endpoint determina a qual ambiente (pré-prod, teste ou produção) os servidores da ferramenta MCP se conectam para as capacidades de integração com o Microsoft 365.

Adicione ao arquivo :

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variável Description Necessário Padrão Exemplo
MCP_PLATFORM_ENDPOINT URL do endpoint da plataforma MCP (preprod, test ou prod) Não Para ponto de extremidade de produção:

Importante: Se você não especificar MCP_PLATFORM_ENDPOINT, o app usa o endpoint de produção.

Observação

Se você estiver usando o servidor de ferramentas simuladas da CLI, defina o endpoint usando http://localhost:<port> o número de porta que você usou. A porta padrão é 5309.

Variáveis de observabilidade

Configure essas variáveis necessárias para habilitar o registro e o rastreamento distribuído para seu agente. Saiba mais sobre características de observabilidade e melhores práticas.

Observação

A configuração de observabilidade é a mesma em todas as línguas.

Variável Description Padrão Exemplo
ENABLE_A365_OBSERVABILITY Ativar ou desativar a observabilidade false true
ENABLE_A365_OBSERVABILITY_EXPORTER Exportar rastreios para serviço de observabilidade false true
OBSERVABILITY_SERVICE_NAME Nome do serviço para rastreamento Nome do agente my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Namespace de serviço. agent365-samples my-company-agents

Configuração do servidor de aplicação agente

Configure a porta onde seu servidor de aplicação agente roda. Essa configuração é opcional e se aplica a agentes em Python e JavaScript.

Adicione ao arquivo :

# Server Configuration
PORT=3978
Variável Description Necessário Padrão Exemplo
PORT Número da porta onde o servidor agente roda Não 3978 3978

Instale dependências e inicie o servidor de aplicações agente

Após configurar seu ambiente, instale as dependências necessárias e inicie o servidor de aplicação do agente localmente para testes.

Instalar dependências

uv pip install -e .

Esse comando lê as dependências de pacotes definidas em pyproject.toml e as instala a partir do PyPI. Ao criar uma aplicação agente do zero, crie um pyproject.toml arquivo para definir suas dependências. Agentes de amostra do repositório de samples já têm esses pacotes definidos. Você pode atualizar, adicionar ou excluir linhas conforme necessário.

Inicie o servidor de aplicativos

python <main.py>

Substitua <main.py> pelo nome do seu arquivo principal em Python que contém o ponto de entrada da sua aplicação agente (por exemplo, start_with_generic_host.py, app.py, ou main.py).

Ou use UV:

uv run python <main.py>

Seu servidor de agentes agora está rodando e pronto para receber solicitações do Agents Playground ou aplicações do Microsoft 365.

Depurar e testar o agente no Agents Playground

O Agents Playground é uma ferramenta local de teste que simula o ambiente Microsoft 365 sem exigir uma configuração completa de um tenant. É a maneira mais rápida de validar a lógica e as invocações de ferramentas do seu agente. Para mais informações, veja Teste com Agentes Playground.

Configurar o Agents Playground para autenticação agentical

Observação

Essa configuração só é necessária ao usar autenticação agente. Se você estiver usando autenticação de token de portador, pode pular esta seção e ir diretamente para o teste Básico.

Ao usar autenticação agente, configure o arquivo YAML do Agents Playground com os dados do seu agente:

  1. Configure o arquivo de configuração: Crie ou atualize o .m365agentsplayground.yml arquivo na pasta onde você executa o Agents Playground. Para instruções detalhadas de configuração, veja o contexto Personalizar Teams.

  2. Atualize a configuração do bot: Adicione os seguintes detalhes do bot ao seu .m365agentsplayground.yml arquivo, substituindo os valores provisórios pelas credenciais reais do seu agente:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Propriedade Description Necessário
    id O endereço de e-mail do usuário do seu agente no formato agentusername@tenant.onmicrosoft.com Sim
    name Nome exibido para o usuário do seu agente Sim
    role Deve ser definido como agenticUser para autenticação agential Sim
    agenticUserId O ID do objeto do usuário agente. Encontre esse valor no centro de administração do Microsoft Entra, na página de perfil do usuário do agente. Sim
    agenticAppId O ID do agente do usuário do agente. Encontre esse valor no centro de administração do Microsoft Entra, na página de perfil do usuário do agente. Sim

Abra um novo terminal (PowerShell no Windows) e inicie o Agents Playground:

agentsplayground

Esse comando abre um navegador web com a interface do Agents Playground. A ferramenta exibe uma interface de chat onde você pode enviar mensagens para seu agente.

Testes básicos

Comece verificando se seu agente está devidamente configurado. // Send a message to the queue

What can you do?

O agente responde com as instruções que está configurado, com base no prompt e nas capacidades do seu agente. Esta resposta confirma que:

  • Seu agente está funcionando corretamente.
  • O agente pode processar mensagens e responder.
  • A comunicação entre o Agente Playground e seu agente está funcionando.

Invocações de ferramentas de teste

Após configurar seus servidores de ferramentas MCP em toolingManifest.json ( veja Ferramentas para instruções de configuração), teste invocações de ferramentas usando exemplos como estes:

Primeiro, verifique quais ferramentas estão disponíveis:

List all tools I have access to

Depois, teste invocações específicas de ferramentas:

Ferramentas de correio

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Resposta esperada: O agente envia um e-mail usando o servidor Mail MCP e confirma que a mensagem foi enviada.

Ferramentas de calendário

List my calendar events for today

Resposta esperada: O agente recupera e exibe seus eventos do calendário do dia atual.

Ferramentas do SharePoint

List all SharePoint sites I have access to

Resposta esperada: O agente consulta o SharePoint e retorna uma lista dos sites aos quais você tem acesso.

Você pode ver as invocações da ferramenta em:

  • A janela de chat - veja a resposta do agente e qualquer chamada de ferramenta
  • O painel de Log - veja informações detalhadas de atividade, incluindo parâmetros e respostas da ferramenta

Teste com atividades de notificação

Durante o desenvolvimento local, teste cenários de notificação usando os gatilhos de notificação embutidos no Agents Playground.

Captura de tela mostrando a interface do Agents Playground com o menu Mock an Activity expandido, exibindo opções de Ativação de Notificação de Gatilho, incluindo Enviar e-mail e Menção no Word.

Antes de testar as atividades de notificação, certifique-se de:

Notificações de e-mail de teste

Para testar o gerenciamento de notificações por e-mail:

  1. Comece seu Agente e Agents Playground.
  2. No Agents Playground, vá em Simular uma atividade>que aciona a notificação de disparo.
  3. Selecione Enviar email.
  4. No diálogo do payload, atualize os detalhes do e-mail simulado, como o nome do remetente e o conteúdo do corpo do e-mail, conforme necessário.
  5. Selecione Enviar atividade.
  6. Veja o resultado tanto na conversa de chat quanto no painel de log.

O agente recebe uma notificação simulada por e-mail e a processa de acordo com a lógica do seu tratamento de notificações. Para detalhes sobre a estrutura da carga útil de notificação por e-mail, veja Carga útil de notificação por e-mail.

Notificações de menção do Word de Teste

Para testar notificações de menção a documentos do Word:

  1. Comece seu Agente e Agents Playground.
  2. No Agents Playground, vá em Simular uma atividade>que aciona a notificação de disparo.
  3. Selecione Menção no Word.
  4. No diálogo de payload, atualize os detalhes do comentário simulado, como o id do documento e o texto do comentário, conforme necessário.
  5. Selecione Enviar atividade.
  6. Veja o resultado tanto na conversa de chat quanto no painel de log.

O agente recebe uma notificação simulada de menção no Word e responde de acordo com a lógica de tratamento da notificação. Para detalhes sobre a estrutura de payload de notificação de comentários no Word, veja Payload de notificação de comentários de documentos.

Visualize os registros de observabilidade

Para visualizar logs de observabilidade durante o desenvolvimento local, instrumente seu agente com código de observabilidade (veja Observabilidade para exemplos de código) e configure as variáveis de ambiente conforme descrito em variáveis de observabilidade. Uma vez configurados, rastreios em tempo real aparecem no console que mostram:

  • Rastreamentos de invocação de agentes
  • Detalhes da execução
  • Chamadas de inferência LLM
  • Mensagens de entrada e saída
  • Uso de token
  • Tempos de resposta
  • Informações de erro

Esses logs ajudam a depurar problemas, entender o comportamento dos agentes e otimizar o desempenho.

Próximas etapas

Depois de testar seu agente localmente, você está pronto para implantá-lo no Azure e publicá-lo no Microsoft 365.

Siga o ciclo de vida do Agent 365 para testar em aplicações do Microsoft 365 como Teams, Word e Outlook.

Solução de problemas

Esta seção oferece soluções para problemas comuns que você pode encontrar ao testar seu agente localmente.

Dica

O Guia de Solução de Problemas do Agente 365 contém recomendações de resolução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de desenvolvimento do Agente 365.

Problemas de conexão e ambiente

Esses problemas estão relacionados à conectividade de rede, conflitos de portas e problemas de configuração do ambiente que podem impedir que seu agente se comunique adequadamente.

Problemas de conexão com o Agents Playground

Sintoma: O Playground dos agentes não consegue se conectar ao seu agente.

Soluções:

  • Verifique se seu servidor de agentes está funcionando.
  • Verifique se os números de porta correspondem entre seu agente e o Agents Playground.
  • Certifique-se de que não existam regras de firewall bloqueando conexões locais.
  • Tente reiniciar tanto o Playground do Agente quanto o do Agente.

Versão desatualizada do Agents Playground

Sintoma: Erros inesperados ou recursos ausentes no Agents Playground.

Solução: Desinstalar e reinstalar o Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Conflitos de porta

Sintoma: A porta indicando erro já está em uso.

Solução:

  • Pare com qualquer outra situação do seu agente.
  • Mude a porta na sua configuração.
  • Elimine qualquer processo que use a porta.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Não é possível adicionar o DeveloperMCPServer

Sintoma: Erro ao tentar adicionar o DeveloperMCPServer no VS Code.

Solução: Feche e reabra o Visual Studio Code, depois tente adicionar o servidor novamente.

Autenticação e problemas com tokens

Esses problemas ocorrem quando seu agente não consegue autenticar corretamente com os serviços do Microsoft 365 ou quando credenciais expiram ou são configuradas incorretamente.

Sintomas:

  • 401 Erros não autorizados
  • Mensagens "Token de portador expirado"
  • Falhas de autenticação agental

Causa raiz:

  • Tokens expiram após cerca de uma hora
  • Configuração incorreta de autenticação
  • Credenciais ausentes ou inválidas

Soluções:

  • Para o vencimento do token de portador

    Atualize seu token e atualize suas variáveis de ambiente.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Para erros de autenticação agential (Python)

    Confira seu .env arquivo:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Por credenciais ausentes

    Confirme que as credenciais exigidas estão presentes antes do teste.

    Garanta .env ou appsettings.json contém:

    • Chaves e segredos de API
    • ID do locatário
    • ID do cliente
    • ID de blueprint (se estiver usando autenticação agente)

    Verificação:

    Teste com uma solicitação simples no Agents Playground. Você deve receber uma resposta sem erros 401.

  • Problemas com ferramentas e notificações

    Esses problemas envolvem questões com invocações de ferramentas, interações com servidores MCP e entrega de notificações.

E-mails não recebidos

Sintoma: O agente indica que o e-mail foi enviado, mas você não o recebe

Soluções:

  • Verifique sua pasta de Lixo ou Spam.
  • A entrega de e-mails pode atrasar alguns minutos. Espere até cinco minutos.
  • Verifique se o endereço de e-mail do destinatário está correto.
  • Verifique os logs dos agentes para detectar erros durante o envio do e-mail.

Respostas de comentários em palavras não funcionam

Problema conhecido: O serviço de notificações atualmente não consegue responder diretamente aos comentários do Word. Algumas dessas funcionalidades estão sendo desenvolvidas na onda 1.

Mensagens não chegam ao agente

Sintoma: Sua aplicação de agente não recebe mensagens enviadas ao agente no Teams.

Causas possíveis::

  • O Portal do Desenvolvedor não está configurado com o blueprint do agente.
  • Problemas com o Azure Web App (falhas de implantação, app não rodando, erros de configuração).
  • A instância do agente não é criada corretamente no Teams.

Soluções:

  • Verificar configuração do Portal do Desenvolvedor:

    Certifique-se de completar a configuração do blueprint do agente no Portal do Desenvolvedor. Aprenda a configurar o blueprint do agente no Portal do Desenvolvedor.

  • Verifique a saúde do Azure Web App:

    Se você implantar seu agente no Azure, verifique se o Web App está rodando corretamente:

    1. Vá para o portal do Azure.
    2. Acesse o recurso do seu Web App.
    3. Verifiqueo status> (deve mostrar "Em Execução").
    4. Verifique o fluxo de logs em Monitoramento para erros de runtime.
    5. Revise os logs do Centro de Implantação para verificar se a implantação foi bem-sucedida.
    6. Verifique Configurações>Configurações da aplicação contêm todas as variáveis de ambiente necessárias.

  • Verificar a criação da instância do agente:

    Certifique-se de criar corretamente a instância do agente no Microsoft Teams:

    1. Abra o Microsoft Teams.
    2. Vá em Apps e pesquise pelo seu agente.
    3. Verifique se o agente aparece nos resultados de busca.
    4. Se não for encontrado, verifique se está publicado no centro de administração do Microsoft 365 - Agentes.
    5. Crie uma nova instância selecionando Adicionar seu agente.
    6. Para instruções detalhadas, veja Agentes a bordo.
  • Last updated on