Adicionar e gerir ferramentas

O módulo de Ferramentas ajuda os programadores a descobrir, configurar e integrar servidores do Model Context Protocol (MCP) nos fluxos de trabalho dos agentes de IA. Os servidores MCP expõem capacidades externas como ferramentas que os agentes de IA podem invocar. Para uma descrição geral dos servidores de ferramentas disponíveis, consulte Servidores de ferramentas do Agent 365.

Demonstra o fluxo de pedidos e respostas

Descrição geral

A integração de Ferramentas do Agent 365 segue o seguinte fluxo de trabalho:

  1. Configurar servidores MCP - Utilize a CLI do Agent 365 para descobrir e adicionar servidores MCP
  2. Gerar manifesto - A CLI cria um ToolingManifest.json na pasta do seu projeto com as configurações dos servidores.
  3. Aplicar permissões ao esquema - Um Administrador Global concede permissões OAuth2 ao esquema de agente ao executar a365 setup all (primeira configuração) ou a365 setup permissions mcp (caso o esquema já exista). Em qualquer caso, o comando lê ToolingManifest.json e requer o consentimento do administrador. Este passo é sempre separado da adição de servidores ao manifesto.
  4. Integrar no código – Carregar o manifesto e registar as ferramentas com o orquestrador.
  5. Invocar ferramentas - O agente invoca ferramentas durante a execução para realizar operações.

Pré-requisitos

Antes de configurar os servidores MCP, garanta que dispõe de:

  • CLI do Agent 365 instalada e configurada
  • .NET 8.0 SDK ou superior - Transferir
  • Privilégios de Administrador Global no seu inquilino do Microsoft 365

Configuração da identidade do agente

Se estiver a utilizar autenticação por meios de agentes, conclua o processo de registo de agentes para criar a identidade do seu agente antes de configurar os servidores MCP. Este processo cria o ID de agente do Entra e o utilizador do agente que permitem ao seu agente autenticar-se e aceder às ferramentas MCP.

Configuração da autenticação OBO

Se utilizar a autenticação On-Behalf-Of (OBO) em vez da autenticação por meio de agentes, o agente pode aceder às ferramentas MCP através das permissões de utilizador delegadas, sem uma identidade de utilizador do agente. No fluxo OBO, o agente troca o token delegado do utilizador para executar ações em nome do utilizador.

Para mais informações sobre o funcionamento do 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.

Configurar principal do serviço

Execute este script de configuração única para criar o principal de serviço para as Ferramentas do Agent 365 no seu inquilino.

Importante

Esta operação única por inquilino requer privilégios de Administrador Global.

  1. Transfira o script New-Agent365ToolsServicePrincipalProdPublic.ps1.

  2. Abra o PowerShell como Administrador e aceda ao diretório do script.

  3. Execute o script.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Inicie sessão utilizando as suas credenciais Azure, quando pedido.

Após a conclusão, o seu inquilino está pronto para o desenvolvimento de agentes e a configuração dos servidores MCP.

Configurar servidores MCP

Utilize a CLI do Agent 365 para descobrir, adicionar e gerir servidores MCP para o seu agente. Para obter uma lista completa dos servidores MCP disponíveis e das suas capacidades, consulte o catálogo de servidores MCP.

Descobrir os servidores disponíveis

Liste todos os servidores MCP que pode configurar:

a365 develop list-available

Adicionar servidores MCP

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

a365 develop add-mcp-servers mcp_MailTools

Importante

Este comando só atualiza ToolingManifest.json na sua pasta de projeto — não concede permissões ao esquema. A forma como as permissões são aplicadas depende de onde se encontra no processo de configuração:

  • Antes da configuração inicial: execute a365 develop add-mcp-servers primeiro, depois prossiga com a365 setup all. O comando setup all inclui o passo de permissões MCP como parte da criação do esquema.
  • Após a criação do esquema: um Administrador Global deve executar a365 setup permissions mcp separadamente. O a365.config.json do administrador deve ter o deploymentProjectPath a apontar para a pasta do projeto que contém o ToolingManifest.json atualizado. Até que este passo seja concluído, as novas permissões do servidor MCP não são visíveis no esquema.

Listar servidores configurados

Ver servidores MCP configurados atualmente:

a365 develop list-configured

Remover servidores MCP

Remova um servidor MCP da sua configuração:

a365 develop remove-mcp-servers mcp_MailTools

Para obter a referência completa da CLI, consulte comando a365 develop.

Utilizar o servidor de ferramentas simulado para testes

Para testes e desenvolvimento, utilize o servidor de ferramentas simulado da CLI do Agent 365 em vez de se ligar a servidores MCP reais. O servidor simulado simula as interações com o servidor MCP, para que possa testar o seu agente localmente sem dependências externas, como autenticação.

O servidor fictício oferece os seguintes benefícios para desenvolvimento e testes locais:

  • Desenvolvimento offline: Teste o seu agente sem conectividade Internet ou dependências externas.
  • Testes consistentes: Receba respostas previsíveis para testar casos extremos.
  • Depuração: Ver todos os pedidos e respostas em tempo real
  • Iteração rápida: não é necessário aguardar chamadas de API externas ou configurar ambientes de teste complexos.

Inicie o servidor simulado utilizando o comando a365 develop start-mock-tooling-server.

Aprenda a configurar o servidor de ferramentas simulado.

Nota

As secções seguintes para configurar manifestos e integrar ferramentas no seu agente funcionam da mesma forma, quer esteja a utilizar o servidor de ferramentas simulado ou servidores MCP reais. Defina a variável de ambiente MCP_PLATFORM_ENDPOINT para apontar para o servidor simulado (por exemplo: http://localhost:5309) em vez do ponto final de produção.

Compreender o manifesto de ferramentas

Ao executar a365 develop add-mcp-servers, a CLI gera um ficheiro ToolingManifest.json com a configuração de todos os servidores MCP. O runtime do agente utiliza este manifesto para compreender quais servidores estão disponíveis e como se autenticar com eles.

Estrutura do manifesto

Exemplo ToolingManifest.json:

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

Parâmetros do manifesto

Cada entrada de servidor MCP contém:

Parâmetro Description
mcpServerName O nome a apresentar do servidor MCP.
mcpServerUniqueName O identificador exclusivo para a instância do servidor MCP.
âmbito O âmbito OAuth necessário para aceder às capacidades do servidor MCP (por exemplo: McpServers.Mail.All para operações de correio). O comando add-mcp-servers obtém este valor do catálogo de servidores MCP.
audiência O URI do Microsoft Entra ID que identifica o recurso da API de destino. O comando add-mcp-servers obtém este valor do catálogo de servidores MCP.

Nota

A CLI do Agent 365 preenche automaticamente os valores scope e audience ao adicionar um servidor MCP. Estes valores provêm do catálogo de servidores MCP e definem as permissões necessárias para aceder a cada servidor MCP.

Integrar ferramentas no seu agente

Depois de gerar o manifesto de ferramentas, integre os servidores MCP configurados no código do seu agente. Esta secção cobre o passo opcional de inspeção e os passos obrigatórios de integração.

Listar servidores de ferramentas (opcional)

Sugestão

Este passo é opcional. Utilize o serviço de configuração do servidor de ferramentas para inspecionar os servidores de ferramentas disponíveis a partir do manifesto de ferramentas antes de os adicionar ao seu orquestrador.

Utilize o serviço de configuração de servidores de ferramentas para descobrir quais servidores de ferramentas estão disponíveis para o seu agente a partir do manifesto de ferramentas. Este método permite-lhe:

  • Consultar todos os servidores MCP configurados do ficheiro ToolingManifest.json.
  • Obter metadados e capacidades do servidor.
  • Verifique a disponibilidade do servidor antes do registo.

O método para listar os 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 Tipo Descrição Valor Esperado Obrigatório/Opcional
agentic_app_id str O identificador exclusivo para a instância da aplicação de agente Cadeia de ID de aplicação de agente válida Obrigatório
auth_token str Token de portador para autenticação através do gateway do servidor MCP Token de portador OAuth válido Obrigatório

Pacote: Microsoft_agents_a365.tooling

Registar as ferramentas com o seu orquestrador

Utilize o método de extensão específico da arquitetura para registar todos os servidores MCP na sua arquitetura de orquestração:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Estes métodos:

  • Registe todas as ferramentas dos servidores MCP configurados no seu orquestrador
  • Configure automaticamente os detalhes de autenticação e de ligação
  • Disponibilize imediatamente as ferramentas para serem invocadas pelo seu agente

Escolher a extensão do seu orquestrador

O módulo de Ferramentas do Agent 365 fornece pacotes de extensão dedicados para diferentes arquiteturas de orquestração.

Nota

Ao executar a365 develop add-mcp-servers, a CLI obtém automaticamente os âmbitos OAuth e os valores da audiência do catálogo do servidor MCP e escreve-os em ToolingManifest.json. Os métodos de extensão utilizam estes valores para configurar a autenticação em runtime — nenhuma configuração manual é necessária no código do seu agente. No entanto, um Administrador Global deve ainda assim conceder essas permissões ao esquema do agente antes que o agente possa utilizá-las em produção: via a365 setup all (primeira configuração) ou a365 setup permissions mcp (se o esquema já existir).

Para obter exemplos detalhados de implementação, consulte os Exemplos do Agent 365.

Exemplos de implementação

Os exemplos seguintes mostram como integrar as Ferramentas do Agent 365 com diferentes arquiteturas de orquestração.

Python com OpenAI

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

1. Adicionar instruções de importação

Adicione as instruções de importação necessárias para aceder ao módulo de Ferramentas e às 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 registo de ferramentas:

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

3. Registar ferramentas MCP com o agente OpenAI

Utilize o método add_tool_servers_to_agent para registar todas as ferramentas MCP configuradas no seu agente OpenAI. Este método lida com cenários de autenticação tanto por meio de agentes como não por meio de agentes.

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 do método

A tabela que se segue descreve os parâmetros a utilizar com add_tool_servers_to_agent.

Parâmetro Description
agent A instância de agente OpenAI com a qual registar ferramentas.
agentic_app_id O identificador exclusivo do agente (ID da aplicação de agente).
auth O contexto de autorização para o utilizador.
context O contexto do turno da conversa atual pelo SDK de Agentes. Fornece identidade do utilizador, metadados de conversa e contexto de autenticação para o registo seguro de ferramentas.
auth_token (Opcional) Token de portador para cenários de autenticação não por meio de agentes.

4. Chamada durante a inicialização

Certifique-se de que chama 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 método add_tool_servers_to_agent automaticamente:

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

Para obter exemplos completos, consulte o repositório de Exemplos do Agent 365.

Outras formas de aceder aos servidores MCP do Agent 365

Além do SDK do Agent 365, pode aceder aos servidores MCP do Agent 365 através de outras experiências de desenvolvimento:

  • Visual Studio Code - Ligue-se diretamente a servidores MCP para fluxos de trabalho de desenvolvimento personalizados.
  • Microsoft Copilot Studio - Integre servidores MCP em fluxos conversacionais utilizando uma experiência low-code.
  • Azure AI Foundry - Utilize servidores MCP com suporte completo ao SDK e capacidades avançadas de orquestração.

Para uma descrição geral completa dos servidores MCP disponíveis e das opções de integração nestas plataformas, consulte Descrição geral dos servidores de ferramentas do Agent 365.

Traga o seu próprio (BYO) Servidor MCP

A funcionalidade Traga o seu Próprio (BYO) servidor MCP permite-lhe registar os seus próprios servidores MCP externos no Microsoft Agent 365, para que possam ser governados, aprovados e monitorizados centralmente no centro de administração do Microsoft 365. Encaminha estes servidores através do gateway de ferramentas do Agent 365, dando aos administradores controlo sobre a aprovação, o acesso e as políticas, ao mesmo tempo que permite às equipas de segurança monitorizar a utilização através de telemetria. Como programador, pode registar o seu servidor MCP utilizando a CLI do Agent 365 e, em seguida, solicitar ao administrador que reveja e aprove o registo e conceda as permissões. O servidor aprovado pode então ser utilizado em ferramentas de cliente suportadas, com monitorização contínua a garantir a conformidade e a visibilidade em todas as integrações.

Para obter instruções completas, consulte Traga o seu próprio (BYO) servidor MCP.

Teste o seu agente

Depois de integrar as ferramentas MCP no 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 o seu ambiente. Em seguida, concentre-se principalmente na secção Testar invocações de ferramentas para validar que as ferramentas MCP estão a funcionar conforme o esperado. Consulte o servidor de ferramentas simulado para testar a ligação ao servidor MCP e as invocações de ferramentas sem necessidade de gerir autenticação.

Adicionar observabilidade

Implemente observabilidade no agente para monitorizar e rastrear as invocações das ferramentas MCP. Ao adicionar capacidades de observabilidade, pode monitorizar o desempenho, depurar problemas e compreender padrões de utilização das ferramentas. Saiba mais sobre como implementar o rastreio e monitorização.

Resolução de Problemas

Esta secção lista problemas comuns quando configura e utiliza servidores e ferramentas MCP.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, 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 servidores MCP e ferramentas

Sintomas:

  • Falhas nas chamadas de ferramentas.
  • Erros: "Servidor MCP não encontrado"
  • Erros de permissão negada ao chamar ferramentas.

Causa raiz:

  • O servidor MCP não está configurado.
  • Permissões em falta.
  • O principal do serviço não está configurado.
  • Confusão entre servidores simulados e de produção.

Soluções: experimente as seguintes soluções para resolver o problema.

  • Verifique se os servidores MCP estão configurados

    Liste os servidores configurados e adicione os que faltam.

    # List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

  • Verifique se o principal de serviço existe

    Assegure-se de que o principal de serviço necessário é criado para as ferramentas.

    # Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Para desenvolvimento e teste iniciais, utilize servidores simulados

    Utilize o servidor de ferramentas simulado para o desenvolvimento e testes locais iniciais, caso pretenda testar o resto do seu agente sem os componentes das ferramentas de produção.

    # Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309

    Saiba mais sobre o servidor de ferramentas simulado.

  • Verificar permissões no centro de administração

    Confirme se o seu agente tem as permissões MCP necessárias.

    • Valide se as permissões da API do esquema do seu agente no portal do Azure mostram todas as permissões do servidor MCP.

    Verificação:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on