Testar agentes usando o Microsoft Agent 365 SDK

Antes da implantação, teste o agente localmente usando o Agents Playground. 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.

Depois que o agente funcionar localmente, siga o Ciclo de Vida de Desenvolvimento do Agent 365 para testar em aplicativos do Microsoft 365, como Teams, Word e Outlook.

Pré-requisitos

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

Pré-requisitos comuns

• Editor de Código: Qualquer editor de código de sua escolha. Visual Studio Code é recomendável.
• Agents Playground: Instale o Agents Playground usando um dos seguintes métodos:
  • Windows: winget install agentsplayground
  • Npm: npm install -g @microsoft/m365agentsplayground
• A365 CLI: Necessária para implantação e gerenciamento de agentes. Instale a CLI do Agent 365.
• Acesso à API LLM: Escolha o serviço apropriado com base na configuração do seu agente ou no seu provedor de modelo preferido:
  • Chave da API OpenAI: Obtenha sua chave da API OpenAI.
  • Azure OpenAI: Criar e implantar um recurso Azure OpenAI para obter a chave e o ponto de extremidade da API.
• Configuração do Portal do Desenvolvedor: Após publicar seu agente, você deve configurar o blueprint do agente no Portal do Desenvolvedor antes de criar as instâncias. Aprenda como configurar o blueprint do agente no Portal do Desenvolvedor

Pré-requisitos específicos de cada idioma

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.

Configure o ambiente de teste do agente seguindo este fluxo de trabalho sequencial:

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

2. LLM configuration – Obter chaves de API e configurar as configurações do OpenAI ou do 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

Depois de concluir essas etapas, você estará 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

cp .env.template .env

Etapa 2: Configuração do LLM

Defina as configurações 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.

# 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=

# 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=

{
  "AIServices": {
    "AzureOpenAI": {
      "DeploymentName": "", // Deployment (as opposed to model) name of the Azure OpenAI model
      "Endpoint": "", // Endpoint of the Azure OpenAI model deployment
      "ApiKey": "" // API Key of the Azure OpenAI model deployment
    },
    "OpenAI": {
      "ModelId": "", // Model ID of the OpenAI model
      "ApiKey": "" // API Key of the OpenAI model
    },
    "UseAzureOpenAI": true // Flag to use Azure OpenAI vs OpenAI
  }
}

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 agentiva

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

a365 config display -g

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

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

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

USE_AGENTIC_AUTH=true
connections__service_connection__settings__clientId=<agentBlueprintId>
connections__service_connection__settings__clientSecret=<agentBlueprintClientSecret>
connections__service_connection__settings__tenantId=<your-tenant-id>

{
  "AgentBluePrint": {
    "Settings": {
      "ClientId": "<agentBlueprintId>",
      "ClientSecret": "<agentBlueprintClientSecret>",
      "TenantId": "<your-tenant-id>"
    }
  }
}

autenticação em nome do usuário

Usando a autenticação on-Behalf-Of (OBO), seu agente pode acessar as ferramentas do servidor MCP usando permissões de usuário delegadas sem a necessidade de uma identidade de usuário 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 possui uma identidade de usuário agentic.
• 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 obter um exemplo de implementação completo, consulte 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 de portador para todos os servidores MCP configurados em seu ToolingManifest.json arquivo.
• Atualiza os arquivos de configuração do projeto com a variável ambiente BEARER_TOKEN.

Antes de executar get-token, configure o arquivo de configuração do projeto para que o comando saiba onde salvar o token:

• .NET: adicione "BEARER_TOKEN": "" a environmentVariables em cada perfil em Properties/launchSettings.json. O comando atualiza apenas perfis que já têm essa chave definida.
• Python/Node.js: crie um arquivo .env com BEARER_TOKEN= antes de ser executado. Se o arquivo estiver ausente, o comando ignorará o salvamento e mostrará as diretrizes.

Etapa 4: variáveis de ambiente referência

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.

# 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

# Agentic Authentication Options
agentic_type=agentic
agentic_altBlueprintConnectionName=service_connection
agentic_scopes=ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default

# Set service connection as default
connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

{
  "AgentApplication": {
    "StartTypingTimer": false,
    "RemoveRecipientMention": false,
    "NormalizeMentions": false,
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": {
            "Scopes": [
              "https://graph.microsoft.com/.default"
            ]
          }
        }
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]
}

Configuração do ponto final MCP

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é-produção, teste ou produção) os servidores de ferramentas MCP se conectam para os recursos de integração do Microsoft 365.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

{
  "profiles": {
    "Sample Agent": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MCP_PLATFORM_ENDPOINT": "<MCP endpoint>"
      },
      "applicationUrl": "https://localhost:64896;http://localhost:64897"
    }
  }
}

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.

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 Python e JavaScript.

# Server Configuration
PORT=3978

# Server Configuration
PORT=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 .

python <main.py>

uv run python <main.py>

npm install

npm run dev

dotnet restore

dotnet build

dotnet run --launch-profile "Sample Agent with MCP Platform"

O servidor do agente agora está em execução e pronto para receber solicitações do Agents Playground ou dos aplicativos Microsoft 365.

Testar agente no Agents Playground

Agents Playground é uma ferramenta de teste local que simula o ambiente do Microsoft 365 sem a necessidade de uma configuração completa do 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 agenética

Ao usar a autenticação agente, configure o arquivo YAML do Agents Playground com os detalhes do 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 Personalizar contexto do 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	Descrição	Necessário
   id	O endereço de e-mail do usuário agente no formato agentusername@tenant.onmicrosoft.com	Sim
   name	Nome exibido para o usuário agente	Sim
   role	Deve ser definido como agenticUser para autenticação do agente	Sim
   agenticUserId	O ID do objeto do usuário agente. Localize 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 usuário agente. Localize 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. Envie uma mensagem para o agente

What can you do?

O agente responde com as instruções com que está configurado, de acordo com o prompt do sistema e as capacidades do 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 de SharePoint

List all SharePoint sites I have access to

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

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

• A janela de chat – consulte a resposta do agente e todas as chamadas de ferramenta.
• O painel Log – consulte informações detalhadas da atividade, incluindo parâmetros de ferramenta e respostas.

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.

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

• Configure os servidores de ferramentas MCP necessários no seu toolingManifest.json. Saiba mais sobre ferramentas.
• Ative as notificações para seu agente. Saiba como configurar a notificação.
• Configure o .m365agentsplayground.yml arquivo com os detalhes de autenticação agêntica do seu agente, conforme descrito no Configurar o Agents Playground para autenticação agêntica.

Notificações de e-mail de teste

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

1. Comece seus Agentes e Agents Playground.
2. No Agents Playground, vá para Simular uma Atividade>Atividade de Acionamento de Notificação.
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.

Testar notificações de menção Word

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

1. Comece seus Agentes e Agents Playground.
2. No Agents Playground, vá para Simular uma Atividade>Atividade de Acionamento de Notificação.
3. Selecione Mention no Word.
4. Na caixa de diálogo de conteúdo, atualize os detalhes do comentário fictício, como a 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 de menção do Word simulada e responde de acordo com a sua lógica de tratamento de notificações. Para obter detalhes sobre a estrutura da carga de notificação de comentário do Word, consulte A carga de notificação de comentário do Document.

Eventos de instalação e desinstalação do agente de teste

Quando o Agents Playground se conecta ao seu agente, ele envia automaticamente uma InstallationUpdate atividade com ação add. Se você implementar um manipulador de instalação, a mensagem de boas-vindas do agente será exibida no chat imediatamente após a conexão ser estabelecida.

Para verificar o tratamento de eventos de instalação:

1. Inicie o servidor do agente.
2. Abra o Playground dos Agentes. O playground se conecta ao seu agente e dispara automaticamente o evento de instalação.
3. Confirme se a mensagem de boas-vindas aparece na conversa de chat.

Para obter detalhes sobre como implementar o manipulador, consulte Os eventos de instalação e desinstalação do agente do Handle.

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:

• Traces de chamada de agentes
• Detalhes da execução da ferramenta
• 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 o agente localmente, implante-o no Azure e publique-o no Microsoft 365.

Para testar seu agente em aplicativos do Microsoft 365, como Teams, Word e Outlook, consulte o Ciclo de Vida de Desenvolvimento do Agente 365.

Solução de problemas

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

Problemas de conexão e ambiente

Esses problemas estão relacionados à conectividade de rede, conflitos de porta e problemas de configuração de ambiente que impedem o agente de se comunicar corretamente.

Problemas de conexão com o Agents Playground

Sintoma: O Agents Playground 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 agente quanto o Agents Playground.

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 portas

Sintoma: Erro indicando que a porta 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 DeveloperMCPServer no Visual Studio Code.

Solução: feche e reabra o Visual Studio Code e tente adicionar o servidor novamente.

Autenticação e problemas com tokens

Esses problemas ocorrem quando seu agente não pode se autenticar corretamente com Microsoft 365 serviços ou quando as 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
  

• No caso de erros de autenticação de agentes (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
  

• Para credenciais ausentes

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

  Assegure que .env ou appsettings.json contenham:

  • 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-mail não recebido

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.

Word respostas de comentário não estão funcionando

Problema conhecido: no momento, o serviço de notificação não pode responder diretamente aos comentários do Word. Essa funcionalidade está em desenvolvimento.

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.
• Azure problemas de aplicativo Web (falhas de implantação, aplicativo não em execução, 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.

• Verificar a saúde do aplicativo Web do Azure:

  Se você implantar seu agente no Azure, verifique se o aplicativo Web está sendo executado corretamente:

  1. Acesse Azure portal.
  2. Acesse o recurso do seu Web App.
  3. VerifiqueVisão Geral>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 a instância do agente corretamente no Microsoft Teams:

  1. Abra 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 ele foi publicado no Microsoft 365 centro de administração – Agentes.
  5. Crie uma nova instância em seu agente selecionando Adicionar.
  6. Para instruções detalhadas, veja Agentes a bordo.