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 com a ferramenta de testes Agents Playground.

Quando seu agente estiver trabalhando localmente, você pode implantá-lo e publicá-lo para testá-lo em aplicações do Microsoft 365 como o Teams.

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

Configurar o ambiente de teste do agente

Esta seção aborda a definição de variáveis do ambiente, autenticação do seu ambiente de desenvolvimento e preparação do seu agente alimentado pelo Agente 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 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

Consulte os exemplos do SDK do Microsoft Agent 365 para encontrar modelos de configuração que mostram os campos necessários.

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 obtidos 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 - Recomendada para cenários de produção ou onde há um usuário agente disponível.
  • Autenticação de token portador - A ser usada apenas para cenários iniciais de desenvolvimento e teste antes que usuários agentes estejam disponíveis.

Autenticação agente

Use o comando CLI a365 config display do A365 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 de token de portador

Para cenários iniciais de desenvolvimento e teste, quando usuários de agentes não estiverem disponíveis, você pode usar autenticação por token de portador para testar seu 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 portadoras expiram após aproximadamente 1 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

A configuração do endpoint MCP (Model Context Protocol) é obrigatória para especificar a qual endpoint da plataforma Agent 365 seu agente deve se conectar. Quando você gera o manifesto de ferramentas que define os servidores de ferramentas para seu agente, deve especificar 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 MCP_PLATFORM_ENDPOINT não for especificado, ele é direcionado por padrão para o endpoint de produção.

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 Habilitar/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

Depois que seu ambiente estiver configurado, você precisa instalar as dependências necessárias e iniciar 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, você precisa criar 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 usar UV:

uv run python <main.py>

Seu servidor de agentes agora deve estar rodando e pronto para receber solicitações do Agents Playground ou dos aplicativos 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.

Observação

Quando você usa autenticação agente, mensagens diretas no Agents Playground não são suportadas atualmente. Você deve testar por meio de atividades personalizadas. Veja atividades de Teste com notificação para detalhes.

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 corretor 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), invocações de ferramentas de teste com 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 pelo 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, você pode testar cenários de notificação simulando atividades personalizadas no Agents Playground. Essa simulação permite que você verifique o tratamento das notificações do seu agente antes de implantá-lo em produção.

Antes de testar as atividades de notificação, certifique-se de que você tem:

  • Configurou os servidores de ferramentas MCP necessários em seu toolingManifest.jsonarquivo . Saiba mais sobre as ferramentas de
  • Notificações ativadas para seu agente Aprenda como configurar notificações

Notificações exigem tanto a configuração adequada da ferramenta quanto a configuração de notificações para funcionar corretamente. Você pode testar cenários como notificações por e-mail ou comentários no Word usando o recurso de atividade personalizada.

Para enviar atividades personalizadas:

  1. Depurar e testar o agente no Agents Playground
  2. No Agents Playground, navegue para simular uma>atividade personalizada
  3. Copie a conversationId parte da atividade (o ID da conversa muda toda vez que o Agents Playground é reiniciado)
  4. Cole seu JSON personalizado de atividade e atualize o personal-chat-id campo com o ID de conversa que você copiou. Consulte o exemplo de notificação por e-mail
  5. Selecione Adicionar atividade.
  6. Veja o resultado tanto na conversa de chat quanto no painel de logs

Notificação por email

Essa configuração simula um e-mail enviado ao agente. Substitua os espaços reservados por seus detalhes reais.

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

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 mostrando:

  • 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 você a depurar problemas, entender o comportamento dos agentes e otimizar o desempenho.

Solução de problemas

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

Questões de conexão e meio ambiente

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

Problemas de conexão com o Playground dos Agentes

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

Soluções:

  • Verifique se seu servidor de agentes está rodando
  • Verifique se os números de porta correspondem entre seu agente e o Agents Playground
  • Verifique se não existem regras de firewall bloqueando o acesso ao contêiner de Blob.
  • 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 porta

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

Solução:

  • Pare qualquer outra situação com seu agente
  • Salve as alterações na 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.

Problemas de autenticação

Esses problemas ocorrem quando seu agente não consegue se autenticar corretamente com os serviços do Microsoft 365 ou quando credenciais estão expiradas ou configuradas de forma incorreta.

Token de portador expirado

Sintoma: Erros de autenticação ou 401 Respostas não autorizadas

Solução: Tokens de portador expiram após aproximadamente 1 hora. Adquira um novo token e atualize sua configuração.

Erros de autenticação agente em Python

Sintoma: Erro na aquisição do token de instância agentica

Solução: Verifique a ALT_BLUEPRINT_NAME configuração em seus .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Notificações e problemas conhecidos

Esses problemas envolvem 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 a pasta de spam/lixo eletrônico.
  • A entrega do e-mail pode atrasar alguns minutos - espere até 5 minutos
  • Verifique se o endereço de email está correto.
  • Verifique os logs dos agentes para detectar quaisquer erros durante o envio de e-mails

Respostas de comentários em palavras não funcionam

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

Mensagens não chegando ao agente

Sintoma: Mensagens enviadas ao agente no Teams não são recebidas pela sua candidatura

Causas possíveis::

  • Blueprint do agente não configurado no Portal de Desenvolvedores
  • Problemas com o Azure Web App (falhas de implantação, app não rodando, erros de configuração)
  • Instância de agente não criada corretamente no Teams

Soluções:

  1. Verificar configuração do Portal do Desenvolvedor:

    Certifique-se de ter completado a configuração do blueprint do agente no Portal do Desenvolvedor. Veja Configurar o blueprint do agente no Portal do Desenvolvedor para passos detalhados.

  2. Verifique a saúde do Azure Web App:

    Se seu agente for implantado no Azure, verifique se o Web App está rodando corretamente:

    1. Navegar até Azure Portal
    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 execução
    5. Revise os logs do Centro de Implantação para verificar se a implantação foi bem-sucedida
    6. Verificar Configurações>Configurações da aplicação contêm todas as variáveis de ambiente necessárias

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

    Certifique-se de que você criou corretamente a instância do agente no Microsoft Teams:

    1. Open Microsoft Teams
    2. Vá em Apps e procure seu agente
    3. Verifique se o agente aparece nos resultados de busca
    4. Se não for encontrado, verifique se está publicado no Microsoft 365 Admin Center - Agentes
    5. Crie uma nova instância selecionando Adicionar seu agente
    6. Para instruções detalhadas, veja Agentes a bordo

Obtendo ajuda

Se você encontrar problemas não abordados nesta seção de solução de problemas, explore estes recursos:

Microsoft Agent 365 SDK repositórios

Mais suporte

Próximas etapas

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

  • Implante e publique agentes: Aprenda como implantar seu agente no Azure Web App e publicá-lo no Microsoft Admin Center, tornando-o disponível para sua organização descobrir e criar instâncias de agentes no Microsoft 365.
  • Last updated on