Adicionar e gerenciar ferramentas

O módulo de Ferramentas ajuda os desenvolvedores a descobrir, configurar e integrar servidores do Model Context Protocol (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.

Visão geral

A integração das ferramentas do Agent 365 segue este fluxo de trabalho:

1. Configure servidores MCP - Use o CLI do Agent 365 para descobrir e adicionar servidores MCP
2. Gerar manifesto – a CLI cria ToolingManifest.json em sua pasta de projeto com configurações de servidor.
3. Aplicar permissões ao blueprint – um Administrador Global concede permissões OAuth2 ao blueprint do agente executando a365 setup all (configuração pela primeira vez) ou a365 setup permissions mcp (se o blueprint já existir). De qualquer forma, o comando lê ToolingManifest.json e requer consentimento do administrador. Essa etapa é sempre separada da adição de servidores ao manifesto.
4. Integrar ao código – Carregar o manifesto e registrar ferramentas no orquestrador.
5. Invocar ferramentas – o agente chama ferramentas durante a execução para executar operações.

Pré-requisitos

Antes de configurar os servidores MCP, certifique-se de que você possui:

• CLI do Agente 365 instalado e configurado
• .NET SDK 8.0 ou superior - Download
• Privilégios de Administrador Global em seu locatário 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. Esse processo cria o ID do aplicativo agente e o usuário agente, que permitem que seu agente autentique e acesse as ferramentas MCP.

Configuração de autenticação OBO

Se você usar autenticação On-Behalf-Of (OBO) em vez da autenticação agente, seu agente pode acessar as ferramentas MCP usando permissões de usuário delegadas sem uma identidade agente. No fluxo OBO, o agente troca o token delegado pelo usuário para realizar ações em nome do usuário.

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

Configurar entidade de serviço

Execute este script de configuração única para criar o principal de serviço para o Agent 365 Tools no seu tenant.

1. Baixe o New-Agent365ToolsServicePrincipalProdPublic.ps1 script.

2. Abra o PowerShell como Administrador e vá para o diretório de scripts.

3. Executar o script.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Entre usando suas credenciais de Azure quando 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 servidores disponíveis

Liste todos os servidores MCP que você pode configurar:

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

Listar servidores configurados

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 a referência completa da CLI, veja o comando a365 develop.

Use o servidor de ferramentas simuladas para testar

Para testes e desenvolvimento, use o servidor de ferramentas simuladas CLI do Agent 365 em vez de conectar aos servidores MCP reais. O servidor simulado simula interações com servidores MCP, então você pode testar seu agente localmente sem dependências externas como autenticação.

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

• Desenvolvimento offline: Teste seu agente sem conectividade à internet ou dependências externas.
• Testes consistentes: Receba respostas previsíveis para testar casos extremos.
• Depuração: Visualize todas as solicitações e respostas em tempo real
• Iteração rápida: Não precisa esperar por chamadas de API externas ou configurar ambientes de teste complexos.

Inicie o servidor de ferramentas simuladas usando o a365 develop start-mock-tooling-server comando.

Aprenda a configurar e a fazer a configuração do servidor de ferramentas de simulação.

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:

Integre ferramentas 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)

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

• Consulte todos os servidores MCP configurados a partir do ToolingManifest.json arquivo.
• Recupere metadados e capacidades do servidor.
• Verifique a disponibilidade do servidor antes do registro.

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)

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

Registre ferramentas no 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:

• AddToolServersToAgentAsync (.NET)
• add_tool_servers_to_agent (Python)
• addToolServersToAgent (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 de orquestrador

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

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

Exemplo de implementação

Os exemplos a seguir mostram como integrar as Ferramentas Agent 365 com diferentes frameworks de orquestração.

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

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

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}")

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

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

const toolService = new McpToolRegistrationService();

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

private readonly IMcpToolRegistrationService _toolsService;

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

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

Outras formas de acessar servidores MCP do Agent 365

Além do SDK Agent 365, você pode acessar servidores MCP do Agent 365 por meio de outras experiências de desenvolvimento:

• Visual Studio Code – conecte-se diretamente aos servidores MCP para fluxos de trabalho de desenvolvimento personalizados.
• Microsoft Copilot Studio – integrar servidores MCP em fluxos de conversa usando uma experiência de baixo código.
• Azure AI Foundry – use servidores MCP com suporte completo do SDK e recursos avançados de orquestração.

Para uma visão geral completa dos servidores MCP disponíveis e das opções de integração entre essas plataformas, veja a visão geral dos servidores de ferramentas do Agente 365.

Testar o seu agente

Após 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 seu ambiente. Depois, foque principalmente na seção de invocações de ferramentas de Teste para validar que suas ferramentas MCP estão funcionando como esperado. Além disso, confira o servidor de ferramentas simuladas para testar a conexão do servidor MCP e as invocações de ferramentas sem precisar de autenticação.

Adicionar observabilidade

Adicione observabilidade ao seu agente para monitorar e rastrear as invocações da ferramenta MCP do seu agente. Ao adicionar capacidades de observabilidade, você pode acompanhar desempenho, depurar problemas e entender padrões de uso de ferramentas. Saiba mais sobre como implementar rastreamento e monitoramento.

Resolução de problemas

Esta seção lista problemas comuns quando você configura e utiliza servidores e ferramentas MCP.

Problemas com servidores MCP e ferramentas

Sintomas:

• Falhas de chamadas de ferramenta.
• Erros "Servidor MCP não encontrado".
• Erros de permissão negada ao utilizar ferramentas.

Causa raiz:

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

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

• Verifique se os servidores MCP estão configurados

  Liste 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

  Garanta que o principal de serviço necessário seja criado para o conjunto de ferramentas.

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

• Para desenvolvimento e testes iniciais, use servidores simulados

  Use o servidor de ferramentas simuladas para desenvolvimento local inicial e testes se quiser testar o restante do seu agente sem componentes de ferramentas de produção.

  # Start mock tooling server
  a365 develop start-mock-tooling-server
  
  # Update your .env
  MCP_PLATFORM_ENDPOINT=http://localhost:5309
  

  Aprenda sobre o servidor de simulação de ferramentas.

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

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

  • Valide se as permissões da API de blueprint do 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