Partilhar via

Agentes de teste usando o Microsoft Agent 365 SDK

Importante

É necessário fazer parte do programa de pré-visualização Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier liga-o diretamente às mais recentes inovações de IA da Microsoft. As pré-visualizações da Frontier estão sujeitas aos termos de pré-visualização existentes dos seus contratos com clientes. Como estas funcionalidades ainda estão em desenvolvimento, a sua disponibilidade e capacidades podem mudar ao longo do tempo.

Teste o seu agente localmente usando o Agents Playground antes da implementação. Este guia aborda a configuração do seu ambiente de desenvolvimento, a autenticação e a validação da funcionalidade do seu agente com a ferramenta de testes Agents Playground.

Quando o seu agente estiver a trabalhar localmente, pode implementá-lo e publicá-lo para testar em aplicações Microsoft 365 como o Teams.

Pré-requisitos

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

Pré-requisitos comuns

Pré-requisitos específicos da língua

Configurar o ambiente de teste do agente

Esta secçã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 o seu ambiente de testes de agentes segue um fluxo de trabalho sequencial:

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

  2. Configuração do LLM - Obter chaves API e configurar as definições OpenAI ou Azure OpenAI

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

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

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

Depois de completar estes passos, está pronto para começar a testar o seu agente no Agents Playground.

Passo 5: Configurar o seu ambiente do

Configure o seu ficheiro de configuração:

cp .env.template .env

Nota

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

Passo 2: Configuração do LLM

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

Adicione ao seu .env ficheiro:

# 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 LLM em Python

Variável Description Obrigatório Exemplo
OPENAI_API_KEY Chave API para serviço OpenAI Para OpenAI sk-proj-...
AZURE_OPENAI_API_KEY API key for Azure OpenAI service Para o Azure OpenAI: execute a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI service endpoint URL Para o Azure OpenAI: execute https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nome da implementação em Azure OpenAI Para o Azure OpenAI: execute gpt-4
AZURE_OPENAI_API_VERSION Versão API para Azure OpenAI Para o Azure OpenAI: execute 2024-02-15-preview

Passo 3: Configurar valores de autenticação para a autenticação da identidade do agente

Use o comando CLI a365 config display do A365 para obter as credenciais do seu projeto de agente.

a365 config display -g

Este comando mostra a configuração do blueprint do seu agente. Defina os seguintes valores:

valor Descrição
agentBlueprintId O ID de cliente do seu agente
agentBlueprintClientSecret O segredo do cliente do seu agente
tenantId O seu ID de inquilino do Microsoft Entra ID.

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

Adicione as seguintes definições ao seu .env ficheiro, substituindo os valores provisórios pelas suas 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 Obrigatório Exemplo
USE_AGENTIC_AUTH Ativar o modo de autenticação agente Sim true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID do cliente blueprint do agente a365 config display -g Sim 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Secreto do cliente blueprint do agente a365 config display -g Sim abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Inquilino do Microsoft Entra ID. Sim adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Nota

Para .NET, também garantir USE_AGENTIC_AUTH=true que está definido ( launchSettings.json ver Passo 4: Referência de variáveis de ambiente)

Passo 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 - Definições obrigatórias para autenticação agente
  • Configuração do endpoint MCP - Especificar o endpoint da plataforma Agent 365
  • Variáveis de observabilidade - Permitir registo e rastreio distribuído
  • Configuração do servidor de aplicação agente - Configure a porta onde o seu servidor agente corre

Variáveis de autenticação

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

Adicione ao seu .env ficheiro:

# 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 Obrigatório
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Tipo de manipulador de autenticação Sim
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Escopos de autenticação para o Microsoft Graph Sim
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nome alternativo da ligação do blueprint Sim
CONNECTIONSMAP_0_SERVICEURL Padrão de URL de serviço para mapeamento de ligação Sim
CONNECTIONSMAP_0_CONNECTION Nome da ligação para mapeamento Sim

Verificar a configuração do ponto final

A configuração do endpoint MCP (Model Context Protocol) é obrigatória para especificar a que endpoint da plataforma Agent 365 o seu agente deve ligar-se. Quando gera o manifesto de ferramentas que define os servidores de ferramentas para o seu agente, deve especificar o endpoint da plataforma MCP. Este endpoint determina a que ambiente (pré-produção, teste ou produção) os servidores da ferramenta MCP se ligam para capacidades de integração com o Microsoft 365.

Adicione ao seu .env ficheiro:

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

Importante: Se MCP_PLATFORM_ENDPOINT não for especificado, por defeito passa para o endpoint de produção.

Variáveis de observabilidade

Configure estas variáveis necessárias para permitir o registo e o rastreio distribuído para o seu agente. Saiba mais sobre características de observabilidade e melhores práticas

Nota

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

Variável Descrição Predefinição Exemplo
ENABLE_A365_OBSERVABILITY Ativar/desativar a observabilidade false true
ENABLE_A365_OBSERVABILITY_EXPORTER Rastreios de exportação para serviço de observabilidade false true
OBSERVABILITY_SERVICE_NAME Nome do serviço para rastreio Nome do agente my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Espaço de Nomes do Service Bus agent365-samples my-company-agents

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

Configura a porta onde o teu servidor de aplicação agente corre. Isto é opcional e aplica-se a agentes Python e JavaScript.

Adicione ao seu .env ficheiro:

# Server Configuration
PORT=3978
Variável Description Necessário Predefinição Exemplo
PORT Número de porta onde o servidor agente corre Não 3978 3978

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

Depois de configurado o ambiente, precisa de instalar as dependências necessárias e iniciar localmente o servidor de aplicações agente para testes.

Instalar dependências:

uv pip install -e .

Este comando lê as dependências de pacotes definidas em pyproject.toml e instala-as a partir do PyPI. Ao criar uma aplicação de agente do zero, precisa de criar um pyproject.toml ficheiro para definir as suas dependências. Os agentes de amostra do repositório de amostras já têm estes pacotes definidos. Podes adicioná-los ou atualizá-los conforme necessário.

Iniciar o servidor de aplicações agente

python <main.py>

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

Ou usar UV:

uv run python <main.py>

O seu servidor de agentes deve agora estar a correr e pronto para receber pedidos do Agents Playground ou das aplicações Microsoft 365.

Agente de teste no Agents Playground

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

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

agentsplayground

Isto abre um navegador web com a interface do Agents Playground. A ferramenta apresenta uma interface de chat onde pode enviar mensagens ao seu agente.

Testes Básicos

Comece por verificar se o seu agente está devidamente configurado. Envie uma mensagem ao agente:

What can you do?

O agente deve responder com as instruções com que está configurado, com base no prompt do sistema e nas capacidades do seu agente. Isto confirma que:

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

Invocações de ferramentas de teste

Depois de configurar os servidores das suas ferramentas MCP em toolingManifest.json (ver Ferramentas para instruções de configuração), as invocações de ferramentas de teste com exemplos como estes:

Primeiro, verifique quais as ferramentas disponíveis:

List all tools I have access to

Depois testa 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 email através do servidor Mail MCP e confirma que a mensagem foi enviada.

Ferramentas de calendário

List my calendar events for today

Resposta esperada: O agente irá recuperar e exibir os seus eventos do calendário para o dia atual.

Ferramentas SharePoint

List all SharePoint sites I have access to

Resposta esperada: O agente consulta o SharePoint e devolve uma lista dos sites a que tem acesso.

Pode ver as invocações da ferramenta em:

  • A janela de chat – veja a resposta do agente e quaisquer chamadas de ferramenta
  • O painel de Registos - consulte informações detalhadas sobre atividades, incluindo parâmetros e respostas da ferramenta

Teste com atividades de notificação

Durante o desenvolvimento local, pode testar cenários de notificação simulando atividades personalizadas no Agents Playground. Isto permite-lhe verificar o tratamento das notificações pelo seu agente antes de o implementar em produção.

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

As notificações requerem tanto uma configuração adequada de ferramentas como uma configuração de notificações para funcionar corretamente. Pode testar cenários como notificações por email ou comentários no Word usando a funcionalidade de atividade personalizada.

Para enviar atividades personalizadas:

  1. Inicie o seu Agente e o Agents Playground
  2. No Agents Playground, navegue para simular uma>atividade personalizada
  3. Copiar o conversationId da atividade (o ID da conversa muda cada vez que o Agents Playground é reiniciado)
  4. Cole o JSON da sua atividade personalizada e atualize o personal-chat-id campo com o ID da conversa que copiou. Consulte o exemplo da notificação por email
  5. Selecione Adicionar atividade.
  6. Veja o resultado tanto na conversa de chat como no painel de registo

Notificação por e-mail

Isto simula um email enviado ao agente. Substitua os valores provisórios pelos dados reais do seu agente:

{
  "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": []
}

Ver registos de observabilidade

Para visualizar registos de observabilidade durante o desenvolvimento local, instrumente o 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 configurado, aparecem trilhos em tempo real na consola que mostram:

  • Rastreios de invocação de agentes
  • Detalhes de execução
  • Chamadas de inferência LLM
  • Mensagens de entrada e saída
  • Utilização do token
  • Tempo de resposta
  • Informação de erro

Estes registos ajudam-no a depurar problemas, compreender o comportamento dos agentes e otimizar o desempenho.

Resolução de problemas

Esta secção apresenta soluções para problemas comuns que possa encontrar ao testar o seu agente localmente.

Questões de ligação e ambiente

Estes problemas relacionam-se com a conectividade de rede, conflitos de portas e problemas na configuração do ambiente que podem impedir o seu agente de comunicar corretamente.

Problemas de ligação ao Agents Playground

Sintoma: O Agents Playground não consegue ligar-se ao seu agente

### Solução:

  • Verifica se o teu servidor de agentes está a funcionar
  • Verifique se os números de porta correspondem entre o seu agente e o Agents Playground
  • Certifique-se de que não existem regras de firewall a bloquear o acesso ao contentor de Blobs.
  • Tenta reiniciar tanto o Agente como o Agents Playground

Versão desatualizada de Agents Playground

Sintoma: Erros inesperados ou funcionalidades em falta no Agents Playground

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

winget uninstall agentsplayground
winget install agentsplayground

Conflitos portuários

Sintoma: A porta a indicar erro já está em uso

### Solução:

  • Pare qualquer outra situação do seu agente
  • Muda a porta na tua configuração
  • Elimine quaisquer processos que usem a porta:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Não posso adicionar o DeveloperMCPServer

Sintoma: Erro ao tentar adicionar o DeveloperMCPServer no VS Code

Solução: Fecha e reabre o Visual Studio Code, depois tenta adicionar o servidor novamente.

Problemas de autenticação

Estes problemas surgem quando o seu agente não consegue autenticar-se corretamente com os serviços Microsoft 365 ou quando as credenciais estão expiradas ou mal configuradas.

Token de portador expirado

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

Solução: As fichas portadoras expiram após aproximadamente 1 hora. Adquira um novo token e atualize a sua configuração.

Erros de autenticação agente em Python

Sintoma: Token de instância agente por erro

Solução: Verifique a ALT_BLUEPRINT_NAME definição no seu .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Problemas conhecidos e notificações

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

Emails não recebidos

Sintoma: O agente indica que o email foi enviado, mas não o recebes

### Solução:

  • Verifique na pasta de spam/lixo.
  • A entrega de emails pode atrasar alguns minutos – espere até 5 minutos
  • Verifique se o endereço de e-mail está correto.
  • Verifique os registos dos agentes para eventuais erros durante o envio de emails

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. Esta funcionalidade está a ser desenvolvida.

Obter ajuda

Se encontrar problemas não abordados nesta secção de resolução de problemas, explore estes recursos:

Microsoft Agent 365 SDK repositories

Mais apoio

Próximos passos

Agora que testou com sucesso o seu agente localmente, está pronto para o implementar no Azure e publicá-lo no Microsoft 365:

  • Implemente e publique agentes: Saiba como implementar o seu agente na Azure Web App e publicá-lo no Microsoft Admin Center, tornando-o disponível para a sua organização descobrir e contratar no Microsoft 365.
  • Last updated on