Testar agentes utilizando o SDK do Microsoft Agent 365

Antes da implementação, teste o seu agente localmente utilizando o Ambiente de Demonstração de Agentes. Este guia aborda a configuração do seu ambiente de desenvolvimento, a configuração da autenticação e a validação da funcionalidade do seu agente utilizando a ferramenta de testes Ambiente de Demonstração de Agentes.

Assim que o seu agente estiver a funcionar localmente, siga o Ciclo de Vida do Desenvolvimento do Agent 365 para o testar em aplicações do Microsoft 365, como Teams, Word e Outlook.

Pré-requisitos

Antes de começar a testar o seu agente, certifique-se de que tem os seguintes pré-requisitos instalados:

Pré-requisitos comuns

Pré-requisitos específicos da linguagem

Configurar o ambiente de teste do agente

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

Configure o seu ambiente de teste de agentes seguindo este fluxo de trabalho sequencial:

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

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

  3. Configurar autenticação - Configure a autenticação por meio de agentes.

  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 do agente

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

Passo 1: Configurar o seu ambiente

Configure o seu ficheiro de configuração:

cp .env.template .env

Nota

Para templates de configuração que apresentam os campos obrigatórios, consulte os exemplos do SDK do Microsoft Agent 365.

Passo 2: Configuração do LLM

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

Adicione ao seu ficheiro .env:

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

Variável Descrição Obrigatório Exemplo
OPENAI_API_KEY Chave de API para o serviço OpenAI Para OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Chave de API para o serviço Azure OpenAI Para Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL do ponto final do serviço Azure OpenAI Para Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nome da implementação no Azure OpenAI Para Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Versão da API para Azure OpenAI Para Azure OpenAI 2024-02-15-preview

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

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

Autenticação por meio de agentes

Abra a365.generated.config.json no seu diretório de trabalho para obter as credenciais do esquema do agente. Copie os seguintes valores:

valor Descrição
agentBlueprintId ID de cliente do agente
agentBlueprintClientSecret Segredo do cliente do agente
tenantId ID do inquilino do Microsoft Entra

Utilize estes valores para configurar a autenticação por meio de agentes no seu agente:

Adicione as seguintes definições ao seu ficheiro .env, substituindo os valores do marcador de posição 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 Descrição Obrigatório Exemplo
USE_AGENTIC_AUTH Ativar o modo de autenticação por meio de agentes Sim true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID de cliente do esquema do agente a partir de a365.generated.config.json Sim 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Segredo do cliente do esquema do agente a partir de a365.generated.config.json Sim abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID ID do inquilino do Microsoft Entra a partir de a365.generated.config.json Sim 22223333-cccc-4444-dddd-5555eeee6666

Autenticação OBO

Ao utilizar a autenticação On-Behalf-Of (OBO), o seu agente pode aceder às ferramentas do servidor MCP utilizando permissões de utilizador delegadas, sem necessitar de uma identidade de utilizador do agente. Neste fluxo, o agente recebe um token delegado do utilizador e troca-o para executar ações em nome do utilizador.

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

  • O agente não tem uma identidade de utilizador do agente.
  • É necessário aceder a recursos com permissões específicas do utilizador.
  • Pretende que o agente atue em nome do utilizador autenticado.

Para mais informações sobre como funciona o fluxo OBO, consulte Fluxos de autenticação. Para obter um exemplo completo de implementação, consulte o Exemplo de autorização OBO no SDK de Agentes do Microsoft 365.

Autenticação de token de portador

Para cenários iniciais de desenvolvimento e teste, quando a autenticação de produção não está configurada, utilize a autenticação de token de portador para testar o seu agente. Este método utiliza autenticação interativa do browser para obter um token de acesso delegado. Ao utilizar este token, o seu agente pode chamar as ferramentas do Servidor MCP utilizando as permissões do utilizador. Esta abordagem simula como um utilizador de agente acede a recursos em produção sem necessitar de uma instância real de agente.

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

a365 develop add-permissions

Em seguida, utilize a365 develop get-token para obter e configurar os tokens de portador:

a365 develop get-token

O comando get-token automaticamente:

  • Lê ToolingManifest.json para detetar todos os servidores MCP configurados.
  • Adquire um token por audiência – os servidores MCP dedicados recebem um token limitado ao respetivo ID da aplicação específico; os servidores ATG partilhados recebem um token limitado ao ID da aplicação partilhado do Agent Tools Gateway (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • Escreve tokens nos ficheiros de configuração do seu projeto:
    • Tokens por servidor: BEARER_TOKEN_<SERVER_NAME> (por exemplo, BEARER_TOKEN_MCP_MAILTOOLS)
    • Token ATG partilhado: BEARER_TOKEN

Antes de executar get-token, adicione entradas de marcador de posição ao ficheiro de configuração do seu projeto:

  • .NET: Adicione "BEARER_TOKEN": "" e/ou "BEARER_TOKEN_<SERVER_NAME>": "" a environmentVariables em cada perfil em Properties/launchSettings.json. O comando só atualiza os perfis que já têm estas chaves definidas.
  • Python/Node.js: Crie um ficheiro .env com BEARER_TOKEN= e/ou BEARER_TOKEN_<SERVER_NAME>= antes de executar. Se o ficheiro estiver em falta, o comando ignora a gravação e apresenta orientações.

Nota

Se executar a365 develop get-token --app-id <id> sem um ficheiro a365.config.json, os tokens não são guardados automaticamente. Copie e cole-os manualmente no ficheiro Properties/launchSettings.json (para .NET) ou no ficheiro .env (para Python/Node.js).

Os tokens de portador expiram ao fim de cerca de uma hora Utilize a365 develop get-token para atualizar os tokens expirados.

Passo 4: Referência das variáveis de ambiente

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

Variáveis de autenticação

Configure as definições do processador de autenticação necessárias para que a autenticação por meio de agentes funcione corretamente.

Adicione ao seu ficheiro .env:

# 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 Descrição Obrigatório
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Tipo de processador de autenticação Sim
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Âmbitos de autenticação para o Microsoft Graph Sim
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nome alternativo da ligação do esquema Sim
CONNECTIONSMAP_0_SERVICEURL Padrão do URL de serviço para mapeamento de ligações Sim
CONNECTIONSMAP_0_CONNECTION Nome da ligação para mapeamento Sim

Variáveis do token de portador (apenas para desenvolvimento local)

Variável Descrição Obrigatório
BEARER_TOKEN Token de portador partilhado para servidores ATG MCP partilhados. O comando a365 develop get-token escreve automaticamente este token. Para desenvolvimento local ATG partilhado
BEARER_TOKEN_<SERVER_NAME> Token de portador por servidor. O SDK deriva o nome convertendo para maiúsculas o mcpServerName do ToolingManifest.json (por exemplo, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). O comando a365 develop get-token escreve automaticamente este token. Para desenvolvimento local por servidor
SKIP_TOOLING_ON_ERRORS Defina como true para recorrer ao LLM básico caso as ferramentas MCP falhem ao carregar. Só é respeitado quando ASPNETCORE_ENVIRONMENT ou ENVIRONMENT está definido como Development. Não

Importante

Os tokens de portador são apenas para desenvolvimento local. Nunca defina BEARER_TOKEN ou BEARER_TOKEN_<SERVER_NAME> em implementações de produção.

Configuração do ponto final MCP

Especifique o ponto final da plataforma Agent 365 ao qual o seu agente se liga. Quando gerar o manifesto de ferramentas que define os servidores de ferramentas para o seu agente, especifique o ponto final da plataforma MCP. Este ponto final determina a que ambiente (pré-produção, teste ou produção) os servidores MCP se ligam para capacidades de integração com o Microsoft 365.

Adicione ao seu ficheiro .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variável Descrição Necessário Predefinição Exemplo
MCP_PLATFORM_ENDPOINT URL do ponto final da plataforma MCP (pré-produção, teste ou produção) Não Ponto final de produção

Importante: Se não especificar MCP_PLATFORM_ENDPOINT, a aplicação utiliza o ponto final de produção.

Nota

Se estiver a utilizar o servidor de ferramentas simulado da CLI, defina o ponto final como http://localhost:<port> utilizando o número da porta que utilizou. A porta predefinida é 5309.

Variáveis de observabilidade

Configure estas variáveis obrigatórias para ativar o registo e o rastreio distribuído do seu agente. Para obter a lista completa de variáveis de ambiente, opções de configuração e exemplos de código, consulte Observabilidade do agente.

Nota

A configuração de observabilidade é idêntica em todas as linguagens. Consulte a Configuração para obter detalhes.

Variável Descrição Predefinição Exemplo
ENABLE_A365_OBSERVABILITY_EXPORTER Exporta rastreios para o serviço de observabilidade. Quando false, exporta os spans para a consola em vez disso. false true
A365_OBSERVABILITY_LOG_LEVEL Nível de registo interno para o SDK de observabilidade. Útil para depurar problemas de exportação durante os testes. none info, warn, error, debug

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

Configure a porta onde o servidor da aplicação do agente é executado. Esta definição é opcional e aplica-se a agentes Python e JavaScript.

Adicione ao seu ficheiro .env:

# Server Configuration
PORT=3978
Variável Descrição Necessário Predefinição Exemplo
PORT Número da porta onde o servidor do agente é executado Não 3978 3978

Instalar dependências e iniciar o servidor da aplicação do agente

Depois de configurar o ambiente, instale as dependências necessárias e inicie o servidor da aplicação do agente localmente para efeitos de teste.

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 de raiz, crie um ficheiro pyproject.toml para definir as suas dependências. Os agentes de exemplo do repositório de exemplos já têm estes pacotes definidos. Pode adicioná‑los ou atualizá‑los conforme necessário.

Iniciar o servidor da aplicação do agente

python <main.py>

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

Ou utilize uv:

uv run python <main.py>

O servidor do seu agente está agora em execução e pronto para receber pedidos do Agents Playground ou das aplicações Microsoft 365.

Testar o agente no Agents Playground

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

Configurar o Agents Playground para autenticação por meio de agentes

Nota

Esta configuração só é necessária quando se utiliza a autenticação por meio de agentes. Caso utilize a autenticação por token de portador, pode ignorar esta secção e avançar diretamente para Teste básico.

Quando utilizar a autenticação por meio de agentes, configure o ficheiro YAML do Agents Playground com os detalhes do seu agente:

  1. Configurar o ficheiro de configuração: Crie ou atualize o ficheiro .m365agentsplayground.yml na pasta onde executa o Agents Playground. Para instruções detalhadas de configuração, consulte Personalizar o contexto do Teams.

  2. Atualizar a configuração do bot: Adicione os seguintes detalhes do bot ao seu ficheiro .m365agentsplayground.yml, substituindo os marcadores de posição 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 Obrigatório
    id O endereço de e-mail do utilizador de agente no formato agentusername@tenant.onmicrosoft.com Sim
    name Nome a apresentar para o utilizador de agente Sim
    role Deve ser definido como agenticUser para a autenticação por meio de agentes Sim
    agenticUserId O ID de Objeto de utilizador de agente. Localize este valor no centro de administração Microsoft Entra, na página de perfil do utilizador de agente. Sim
    agenticAppId O ID de Agente do utilizador de agente. Localize este valor no centro de administração Microsoft Entra, na página de perfil do utilizador de agente. Sim

Abra um novo terminal (PowerShell no Windows) e inicie a aplicação Agents Playground:

agentsplayground

Este comando abre um browser com a interface do Agents Playground. A ferramenta apresenta uma interface de chat onde pode enviar mensagens ao seu agente.

Teste básico

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

What can you do?

O agente responde de acordo com as instruções com que foi configurado, com base no pedido do sistema e nas capacidades do seu agente. Esta resposta confirma que:

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

Testar invocações de ferramentas

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

Primeiro, verifique que 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 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 obtém e apresenta os seus eventos do calendário para o dia atual.

Ferramentas do SharePoint

List all SharePoint sites I have access to

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

Pode ver as invocações das ferramentas:

  • Na janela de chat – veja a resposta do agente e quaisquer chamadas de ferramenta.
  • No painel de Registo - veja informações detalhadas de atividade, incluindo parâmetros e respostas das ferramentas.

Testar com atividades de notificação

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

Captura de ecrã que mostra a interface do Agents Playground com o menu Simular uma Atividade expandido, apresentando opções de Acionar Atividade de Notificação, incluindo Enviar e-mail e Mencionar no Word.

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

Testar notificações por e-mail

Para testar o processamento das notificações por e-mail:

  1. Inicie o seu agente e o Agents Playground.
  2. No Agents Playground, aceda a Simular uma Atividade>Acionar uma Atividade de Notificação.
  3. Selecione Enviar e-mail.
  4. Na caixa de 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ção por chat como no painel de registo.

O agente recebe uma notificação por e-mail simulada e processa-a de acordo com a sua lógica de processamento de notificações. Para detalhes sobre a estrutura do payload de notificação por e-mail, consulte Payload de notificação por e-mail.

Testar notificações de menção no Word

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

  1. Inicie o seu agente e o Agents Playground.
  2. No Agents Playground, aceda a Simular uma Atividade>Acionar uma Atividade de Notificação.
  3. Selecione Mencionar no Word.
  4. Na caixa de diálogo do 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ção por chat como no painel de registo.

O agente recebe uma notificação simulada de menção no Word e responde de acordo com a lógica de processamento de notificações. Para detalhes sobre a estrutura do payload de notificação de comentários do Word, consulte Payload de notificação de comentários do documento.

Testar os eventos de instalação e desinstalação do agente

Quando o Agents Playground se liga ao seu agente, envia automaticamente uma atividade InstallationUpdate com a ação add. Se implementar um processador de instalação, a mensagem de boas-vindas do seu agente é apresentada no chat imediatamente após a ligação ser estabelecida.

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

  1. Inicie o servidor do agente.
  2. Abra o Agents Playground. O ambiente de demonstração liga-se ao seu agente e aciona automaticamente o evento de instalação.
  3. Verifique se a mensagem de boas-vindas é apresentada na conversação por chat.

Captura de ecrã que mostra a interface do Agents Playground com a mensagem de boas-vindas do agente:

Para detalhes sobre a implementação do processador, consulte Gerir eventos de instalação e desinstalação do agente.

Ver registos de observabilidade

Para ver os registos de observabilidade durante o desenvolvimento local, instrumente o seu agente com código de observabilidade (consulte Observabilidade para obter exemplos de código) e configure as variáveis de ambiente conforme descrito em Variáveis de observabilidade. Para obter instruções de validação passo a passo e a saída esperada do registo, consulte Validar localmente. Concluída a configuração, são apresentados na consola rastreios em tempo real que mostram:

  • Rastreios de invocação do agente
  • Detalhes da execução da ferramenta
  • Chamadas de inferência do LLM
  • Mensagens de entrada e de saída
  • Utilização de tokens
  • Tempos de resposta
  • informações de erros

Estes registos ajudam a depurar problemas, compreender o comportamento do agente e otimizar o desempenho. Antes de publicar, utilize Validar para publicação na loja para confirmar que todos os atributos necessários estão presentes.

Passos seguintes

Após testar o agente localmente, implemente-o no Azure e publique-o no Microsoft 365.

Para testar o seu agente nas aplicações Microsoft 365 como Teams, Word e Outlook, consulte o Ciclo de Vida do Desenvolvimento do Agent 365.

Resolução de Problemas

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

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de nível elevado, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

Problemas de ligação e de ambiente

Estes problemas estão relacionados com a conectividade de rede, conflitos de portas e problemas de configuração do ambiente que impedem o seu agente de comunicar corretamente.

Problemas de ligação do Agents Playground

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

Soluções:

  • Verifique se o seu servidor de agente está em execução.
  • Verifique se os números das portas correspondem entre o agente e o Agents Playground.
  • Certifique-se de que não existem regras da firewall a bloquear as ligações locais.
  • Tente reiniciar tanto o agente como o Agents Playground.

Versão desatualizada do 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 das portas

Sintoma: Erro que indica que a porta já está a ser utilizada.

Solução:

  • Pare quaisquer outras instâncias do seu agente.
  • Altere a porta na sua configuração.
  • Encerre quaisquer processos que estejam a utilizar a porta.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Não é possível adicionar DeveloperMCPServer

Sintoma: Erro ao tentar adicionar DeveloperMCPServer no Visual Studio Code.

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

Problemas de autenticação e de tokens

Estes problemas ocorrem quando o agente não consegue autenticar-se corretamente com os serviços do Microsoft 365 ou quando as credenciais expiram ou estão configuradas incorretamente.

Sintomas:

  • Erros 401 Não Autorizado
  • Mensagens "Token de portador expirado"
  • Falhas de autenticação por meio de agentes

Causa raiz:

  • Os tokens expiram ao fim de cerca de uma hora
  • Configuração de autenticação incorreta
  • Credenciais em falta ou inválidas

Soluções:

  • Para expiração do token de portador

    Atualize o token e as variáveis do ambiente.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Para falhas do token de portador por servidor

    Verifique se o seu ficheiro de configuração tem entradas de marcadores de posição para cada servidor (BEARER_TOKEN_<SERVER_NAME>) e, em seguida, volte a executar a365 develop get-token para as preencher. O SDK deriva o nome da variável convertendo para maiúsculas o mcpServerName em ToolingManifest.json e substituindo hífens por carateres de sublinhado (por exemplo, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Para erros de autenticação por meio de agentes (Python)

    Verifique o ficheiro .env:

    # 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 em falta

    Verifique se as credenciais necessárias estão presentes antes de testar.

    Certifique-se de que .env ou appsettings.json contém:

    • Segredos e chaves de API
    • ID do Inquilino
    • ID de Cliente
    • ID de esquema (se utilizar autenticação por meio de agentes)

    Verificação:

    Teste com um pedido simples no Agents Playground. Deve receber uma resposta sem erros 401.

  • Problemas de ferramentas e notificações

    Estes problemas dizem respeito a questões relacionadas 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 não o recebe

Soluções:

  • Verifique a sua pasta de Lixo ou Spam.
  • A entrega de e-mails pode demorar alguns minutos. Aguarde até cinco minutos.
  • Verifique se o endereço de e-mail do destinatário está correto.
  • Verifique os registos do agente para detetar possíveis erros durante o envio de e-mails.

As respostas aos comentários do Word não estão a funcionar

Problema conhecido: O serviço de notificações atualmente não consegue responder diretamente aos comentários do Word. Esta funcionalidade está em desenvolvimento.

As mensagens não chegam ao agente

Sintoma: A aplicação do seu agente não recebe mensagens enviadas ao agente no Teams.

Causas possíveis:

  • O Portal do Programador não está configurado com o esquema do agente.
  • Problemas da Aplicação Web do Azure (falhas de implementação, a aplicação não está em execução, erros de configuração).
  • A instância do agente não foi criada corretamente no Teams.

Soluções:

  • Verificar a configuração do Portal do Programador:

    Certifique-se de que conclui a configuração do esquema do agente no Portal do Programador. Saiba como configurar o esquema do agente no Portal do Programador.

  • Verificar o estado de funcionamento da Aplicação Web do Azure:

    Se implementar o seu agente no Azure, verifique se a Aplicação Web está a ser executada corretamente:

    1. Aceda ao portal do Azure.
    2. Aceda ao recurso da sua Aplicação Web.
    3. Verifique Descrição geral>Estado (deve mostrar "Em Execução").
    4. Verifique Fluxo de registos em Monitorização para detetar erros de runtime.
    5. Reveja os registos do Centro de Implementação para verificar se a implementação foi concluída com êxito.
    6. Verifique se Configuração>Definiçõ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 que cria a instância de agente corretamente no Microsoft Teams:

    1. Abrir Microsoft Teams.
    2. Aceda a Aplicações e procure o seu agente.
    3. Verifique se o agente é apresentado nos resultados de pesquisa.
    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 no seu agente.
    6. Para instruções detalhadas, consulte Integrar agentes.

Resolver problemas dos registos de observabilidade

Se os registos de observabilidade do seu agente não forem apresentados como esperado, consulte Resolução de problemas no guia de observabilidade.

  • Last updated on