Adicionar e gerenciar ferramentas

O módulo de ferramentas ajuda os desenvolvedores a descobrir, configurar e integrar servidores MCP (Protocolo de Contexto do Modelo) em fluxos de trabalho de agentes de IA. Os servidores MCP disponibilizam recursos externos como ferramentas que podem ser invocados por agentes de IA. Para obter uma visão geral dos servidores de ferramentas disponíveis, consulte Servidores de ferramentas do Agent 365.

Visão geral

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

1. Configurar servidores MCP – use a CLI do Agent 365 para descobrir e adicionar servidores MCP
2. Gerar manifesto – a CLI cria ToolingManifest.json na sua pasta de projeto com as configurações do servidor.
3. Aplicar permissões ao blueprint – um Administrador Global concede permissões OAuth2 ao blueprint do agente executando a365 setup all (configuração inicial) 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 independente 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 realizar operações.

Pré-requisitos

Antes de configurar servidores MCP, verifique se você tem:

• CLI do Agent 365 instalada e configurada
• SDK do .NET 8.0 ou superior – Baixar
• Privilégios de Administrador Global no seu locatário do Microsoft 365

Privilégios da identidade do agente

Se você estiver usando autenticação de agentes, conclua o processo de registro do agente para criar a identidade do seu agente antes de configurar os servidores MCP. Esse processo cria a ID do agente do Entra e o usuário do agente, permitindo que seu agente se autentique e acesse as ferramentas MCP.

Configuração de autenticação em nome do usuário

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

Para obter mais informações sobre como o fluxo OBO funciona, 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 entidade de serviço

Execute este script de configuração única para criar a entidade de serviço para as Ferramentas do Agent 365 no seu locatário.

1. Baixe o script New-Agent365ToolsServicePrincipalProdPublic.ps1.

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

3. Execute o script.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Entre com as suas credenciais do Azure quando solicitado.

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

Configurar servidores MCP

Use o CLI do Agent 365 para descobrir, adicionar e gerenciar servidores MCP para seu agente. Para obter uma lista completa dos servidores MCP disponíveis e seus recursos, consulte o Catálogo de servidores MCP.

Descobrir servidores disponíveis

Liste todos os servidores MCP que você 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

Listar servidores configurados

Exiba os 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 obter a referência completa da CLI, consulte comando a365 develop.

Usar o servidor de ferramentas de simulação para testes

Para testes e desenvolvimento, use o servidor de ferramentas de simulação da CLI do Agent 365 em vez de se conectar aos servidores MCP de produção. O servidor de simulação reproduz as interações com servidores MCP, permitindo que você teste 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 é preciso esperar por chamadas de API externas nem configurar ambientes de teste complexos.

Inicie o servidor de ferramentas de simulação usando o comando a365 develop start-mock-tooling-server.

Saiba como instalar e configurar o servidor de ferramentas de simulação.

Entender o manifesto de ferramentas

Quando você executa a365 develop add-mcp-servers, a CLI gera um arquivo ToolingManifest.json 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 do manifesto

Exemplo de 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 do servidor MCP contém:

Integrar ferramentas ao seu agente

Depois de 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.

Listar servidores de ferramentas (opcional)

Use o serviço de configuração do servidor de ferramentas para verificar 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 no arquivo ToolingManifest.json.
• Recupere metadados e recursos do servidor.
• Verifique a disponibilidade do servidor antes do registro.

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

# 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 da estrutura para registrar todos os servidores MCP com a sua estrutura 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
• Configurar automaticamente os detalhes da autenticação e da conexão
• Torne as ferramentas imediatamente disponíveis para o seu agente invocar

Escolha a extensão do seu orquestrador

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

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

Exemplos de implementação

Os exemplos a seguir mostram como integrar as Ferramentas do Agent 365 com diferentes estruturas 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 obter exemplos completos e funcionais, consulte o Repositório de exemplos do Agent 365.

Outras formas de acessar servidores MCP do Agent 365

Além do SDK do 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 personalizados de desenvolvimento.
• Microsoft Copilot Studio – integre servidores MCP em fluxos de conversa usando uma experiência low-code.
• Fábrica de IA do Azure – use servidores MCP com suporte completo a SDK e recursos avançados de orquestração.

Para obter uma visão completa dos servidores MCP disponíveis e das opções de integração nessas plataformas, consulte Visão geral dos servidores MCP do Agent 365.

Traga seu próprio (BYO) servidor MCP

O recurso Traga seu próprio (BYO) servidor MCP permite que você registre seus próprios servidores MCP externos no Microsoft Agent 365, para que possam ser controlados, aprovados e monitorados de forma centralizada no Centro de administração do Microsoft 365. Ele roteia esses servidores pelo gateway de ferramentas do Agent 365, dando aos administradores controle sobre aprovação, acesso e políticas, enquanto permite que as equipes de segurança acompanhem o uso por meio de telemetria. Como desenvolvedor, você pode registrar seu servidor MCP usando a CLI do Agent 365. Após o registro, seu administrador pode revisar, aprovar e conceder permissões. O servidor aprovado pode então ser usado em ferramentas de cliente com suporte, com monitoramento contínuo garantindo conformidade e visibilidade em todas as integrações.

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

Testar o seu agente

Depois que integrar as ferramentas MCP ao seu agente, teste as invocações das ferramentas para garantir que elas funcionem corretamente e lidem com diferentes cenários. Siga o guia de testes para configurar seu ambiente. Em seguida, concentre-se principalmente na seção Testar as invocações de ferramentas para validar que suas ferramentas MCP estejam funcionando como esperado. Além disso, confira o servidor de ferramentas de simulação para testar a conexão com o servidor MCP e as invocações de ferramentas sem lidar com autenticação.

Adicionar observabilidade

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

Solução de Problemas

Esta seção lista problemas comuns ao configurar e usar servidores e ferramentas MCP.

Problemas com servidores e ferramentas MCP

Sintomas:

• Falhas de chamadas da ferramenta.
• 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 ausentes.
• A entidade de serviço não está configurada.
• Confusão entre servidores de simulação e de produção.

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

• Verificar se os servidores MCP estão configurados

  Liste os servidores configurados e adicione os que estão ausentes.

  # 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 a entidade de serviço existe

  Garanta que a entidade de serviço necessária seja criada para a ferramenta.

  # 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 de simulação

  Use o servidor de ferramentas de simulação para desenvolvimento e testes locais iniciais se você quiser testar o restante do seu agente sem as 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 de simulação.

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

  Certifique-se de que o agente tenha as permissões MCP necessárias.

  • 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