Compartilhar via

Adicionar e gerenciar marcas

Importante

Você precisa fazer parte do programa de versão preliminar do Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. As versões preliminares da Frontier estão sujeitas aos termos de versão preliminar existentes dos contratos de cliente. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

O módulo Ferramentas permite que desenvolvedores descubram, configurem e integrem servidores do Protocolo de Contexto de Modelo (MCP) em fluxos de trabalho de agentes de IA. Servidores MCP expõem capacidades externas como ferramentas que agentes de IA podem invocar. Para uma visão geral dos servidores de ferramentas disponíveis, veja Servidores de ferramentas do Agente 365.

Demonstra o fluxo de solicitação e resposta

Visão geral

A integração do Agent 365 Tooling segue um fluxo de trabalho de quatro etapas:

  1. Configure servidores MCP - Use a CLI do Agente 365 para descobrir e adicionar servidores MCP
  2. Gerar manifesto - CLI criada ToolingManifest.json com configurações de servidor
  3. Integre ao código - Carregue ferramentas de manifestos e registradores com seu orquestrador
  4. Invoque ferramentas - O agente chama ferramentas durante a execução para realizar operações

Pré-requisitos

Antes de configurar o serviço de backup, verifique se você tem:

  • CLI do Agente 365 instalado e configurado
  • .NET 8.0 SDK ou superior - Download
  • Administrador global do locatário do Microsoft 365

Configuração da identidade do agente

Se você estiver usando autenticação agente, complete o processo de registro do agente para criar sua identidade antes de configurar os servidores MCP. Isso cria o ID do aplicativo agente e o usuário agente que permitem que seu agente se autentique e acesse as ferramentas MCP.

Configurar entidade de serviço

Execute este script de configuração ONE-TIME para criar o Principal de Serviço para as Ferramentas do Agente 365 no seu locatário.

Importante

Esta é uma operação ÚNICA por tenant que requer privilégios de Administrador Global.

  1. Baixe o script New-Agent365ToolsServicePrincipalProdPublic.ps1

  2. Abra o PowerShell como Administrador e navegue até o diretório em que você salvou os scripts do PowerShell.

  3. Executar o script:

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Entre com suas credenciais do Azure, se solicitado.

Após a conclusão, seu tenant está pronto para desenvolvimento de agentes e configuração do servidor MCP.

Configurar servidores MCP

Use a CLI do Agent 365 para descobrir, adicionar e gerenciar servidores MCP para seu agente. Para uma lista completa dos servidores MCP disponíveis e suas capacidades, veja o catálogo de servidores MCP.

Descubra os contadores disponíveis

Liste todos os servidores MCP que podem ser configurados:

a365 develop list-available

Adicionar um servidor de MCP

Adicione um ou mais servidores MCP à configuração do seu agente:

a365 develop add-mcp-servers mcp_MailTools

Servidores configurados por lista

Veja servidores MCP atualmente configurados:

a365 develop list-configured

Remover servidores MCP

Remova um servidor MCP da sua configuração:

a365 develop remove-mcp-servers mcp_MailTools

Para referência completa à CLI, veja o comando a365 develop.

Entenda o manifesto de ferramentas

Quando você executa a365 develop add-mcp-servers, a CLI gera um ToolingManifest.json arquivo contendo a configuração de todos os servidores MCP. O runtime do agente usa esse manifesto para entender quais servidores estão disponíveis e como autenticar com eles.

Estrutura manifesta

Exemplo: ToolingManifest.json

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Parâmetros manifestos

Cada entrada do servidor MCP contém:

Parâmetros Descrições
mcpNomeServidor O nome de exibição completo do servidor.
mcpServerUniqueName O identificador exclusivo da instância de execução
escopo O escopo OAuth necessário para acessar as capacidades do servidor MCP (por exemplo: McpServers.Mail.All para operações de e-mail). Esse valor é recuperado do catálogo do servidor MCP quando você executa o add-mcp-servers comando.
Público-alvo O URI do ID Microsoft Entra que identifica o recurso de API alvo. Esse valor também é recuperado do catálogo do servidor MCP.

Observação

Os scope valores e audience são automaticamente preenchidos pela CLI do Agente 365 quando você adiciona um servidor MCP. Esses valores vêm do catálogo de servidores MCP e definem as permissões necessárias para acessar cada servidor MCP.

Integre ferramentas personalizadas ao seu agente

Após gerar o manifesto de ferramentas, integre os servidores MCP configurados ao código do seu agente. Esta seção cobre a etapa opcional de inspeção e as etapas necessárias de integração.

Servidores de ferramentas de listas (Opcional)

Gorjeta

Esta etapa é opcional. Use o serviço de configuração do servidor de ferramentas para inspecionar os servidores de ferramentas disponíveis no manifesto de ferramentas antes de adicioná-los ao seu orquestrador.

Use o serviço de configuração do servidor de ferramentas para descobrir quais servidores de ferramentas estão disponíveis para seu agente a partir do manifesto de ferramentas. Esse método permite que você:

  • Consultar todos os servidores MCP configurados a partir do ToolingManifest.json
  • Recuperar metadados e capacidades do servidor
  • Verifique a disponibilidade do servidor antes do cadastro

O método para listar servidores de ferramentas está disponível nos pacotes principais de ferramentas:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Parâmetros:

Parâmetro Type Description Valor Esperado Obrigatório/Opcional
agentic_app_id str Identificador exclusivo da instância de um aplicativo String de ID de aplicação de agente válida Obrigatória
auth_token str Token de portador para autenticação com o gateway do servidor MCP Token portador OAuth válido Obrigatória

Pacote: microsoft-agents-a365-tooling

Registre ferramentas com seu orquestrador

Use o método de extensão específico do framework para registrar todos os servidores MCP com seu framework de orquestração:

  • .NET
  • Python:
  • Node.js

Estes métodos:

  • Registre todas as ferramentas dos servidores MCP configurados com seu orquestrador
  • Configure automaticamente os detalhes da autenticação e da conexão
  • Disponibilize ferramentas imediatamente para seu agente usar

Escolha sua extensão Orchestrator

O módulo Agent 365 Tooling fornece pacotes de extensão dedicados para diferentes frameworks de orquestração:

  • microsoft-agents-a365-tooling: Funcionalidade central das ferramentas
  • microsoft-agents-a365-tooling-extensions-agentframework: Integração com Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry integration
  • microsoft-agents-a365-tooling-extensions-openAI: Integração com OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel: Integração com o Kernel Semântico

Observação

A autenticação é configurada automaticamente pelo CLI do Agente 365 quando você executa a365 develop add-mcp-servers. Os escopos OAuth e valores de audiência são recuperados do catálogo de servidores MCP e incluídos no ToolingManifest.jsonarquivo de . Os métodos de extensão usam automaticamente esses valores para configurar a autenticação – não é necessária configuração manual.

Para exemplos detalhados de implementação, veja os Amostras do Agente 365.

Exemplo de implementação

Os exemplos a seguir demonstram como integrar as Ferramentas do Agente 365 com diferentes frameworks de orquestração.

Python com OpenAI

Este exemplo mostra como integrar ferramentas MCP com OpenAI em uma aplicação Python.

Adicione instruções de importação.

Adicione as importações necessárias para acessar o módulo de Ferramentas e as extensões OpenAI:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Inicializar serviços de ferramentas

Crie instâncias dos serviços de configuração e registro de ferramentas:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. Registrar ferramentas MCP com o agente OpenAI

Use o add_tool_servers_to_agent método para registrar todas as ferramentas MCP configuradas com seu agente OpenAI. Esse método lida com cenários de autenticação tanto agentica quanto não agentica:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Parâmetros de método

A tabela a seguir descreve os parâmetros usados com add_tool_servers_to_agent.

Parâmetros Descrições
agent A instância do agente OpenAI para registrar ferramentas.
agentic_app_id O identificador único do agente (ID do aplicativo agente).
auth O contexto de autorização para o usuário.
context A conversa atual vira contexto do SDK Agent. Fornece identidade do usuário, metadados de conversa e contexto de autenticação para registro seguro de ferramentas.
auth_token (Opcional) Token portador para cenários de autenticação não agente.

4. Chamada durante a inicialização

Certifique-se de chamar o método de configuração durante a inicialização antes de executar o agente:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

O add_tool_servers_to_agent método automaticamente:

  • Carrega todos os servidores MCP do ToolingManifest.json
  • Registra suas ferramentas com o agente OpenAI
  • Configura a autenticação com base na configuração do manifesto
  • Disponibiliza as ferramentas para seu agente invocar

Para exemplos completos e funcionando, veja o repositório de Amostras do Agente 365.

Testar e monitorar.

Testar o seu agente

Após integrar as ferramentas MCP ao seu agente, teste as invocações das ferramentas para garantir que funcionam corretamente e lidam com diferentes cenários. Siga o guia de testes para configurar seu ambiente e então foque principalmente na seção de invocações de ferramentas de Teste para validar que suas ferramentas MCP estão funcionando como esperado.

Observabilidade do KMS

Adicione observabilidade ao seu agente para monitorar e rastrear as invocações da ferramenta MCP do seu agente, adicionar capacidades de observabilidade para acompanhar desempenho, depurar problemas e entender padrões de uso de ferramentas. Saiba mais sobre a implementação de rastreamento e monitoramento

  • Last updated on