Adicionar e gerir ferramentas

Importante

É necessário fazer parte do programa de pré-visualização Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier liga-o diretamente às mais recentes inovações de IA da Microsoft. As pré-visualizações da Frontier estão sujeitas aos termos de pré-visualização existentes dos seus contratos com clientes. Como estas funcionalidades ainda estão em desenvolvimento, a sua disponibilidade e capacidades podem mudar ao longo do tempo.

O módulo de Ferramentas permite aos programadores descobrir, configurar e integrar servidores do Protocolo de Contexto de Modelo (MCP) em fluxos de trabalho de agentes de IA. Os servidores MCP expõem capacidades externas como ferramentas que os agentes de IA podem invocar. Para uma visão geral dos servidores de ferramentas disponíveis, consulte servidores de ferramentas do Agente 365.

Descrição geral

A integração das ferramentas Agent 365 segue um fluxo de trabalho em quatro etapas:

1. Configurar servidores MCP - Usar a CLI do Agente 365 para descobrir e adicionar servidores MCP
2. Gerar manifesto - CLI cria ToolingManifest.json com configurações de servidor
3. Integra no código - Carrega ferramentas de manifestos e registos com o teu orquestrador
4. Invocar ferramentas - O agente chama ferramentas durante a execução para realizar operações

Pré-requisitos

Antes de configurar servidores MCP, certifique-se de que tem:

• CLI do Agente 365 instalado e configurado
• .NET 8.0 SDK ou superior - Download
• Privilégios de Administrador Global no seu tenant Microsoft 365

Configuração da identidade do agente

Se estiver a usar autenticação agente, complete o processo de registo do agente para criar a identidade do seu agente antes de configurar os servidores MCP. Isto cria o ID da aplicação agente e o utilizador agente que permitem ao seu agente autenticar-se e aceder às ferramentas MCP.

Configurar principal do serviço

Execute este script de configuração ONE-TIME para criar o Service Principal para as Ferramentas do Agente 365 no seu inquilino.

Importante

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

1. Descarregue o script New-Agent365ToolsServicePrincipalProdPublic.ps1

2. Abre o PowerShell como Administrador e navega até ao diretório de scripts

3. Executar o script:

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Se solicitado, inicie sessão com as suas credenciais para o .

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

Configurar o servidor DHCP

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

Descubra os servidores disponíveis

Liste todos os servidores MCP que podem ser configurados:

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

Servidores configurados por listas

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 da CLI, consulte o comando a365 develop.

Compreender o manifesto das ferramentas

Quando executas a365 develop add-mcp-servers, a CLI gera um ToolingManifest.json ficheiro contendo a configuração de todos os servidores MCP. O tempo de execução do agente usa este manifesto para perceber quais os servidores disponíveis e como autenticar-se com eles.

Estrutura do manifesto

Exemplo:

{
  "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 a apresentar do utilizador
mcpServerUniqueName	O identificador único 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). Este valor é recuperado do catálogo do servidor MCP quando executa o add-mcp-servers comando.
público	O URI do ID Microsoft Entra que identifica o recurso API alvo. Este valor também é recuperado do catálogo de servidores MCP.

Nota

Os scope valores e audience são automaticamente preenchidos pela CLI do Agente 365 quando adicionas 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.

Integre ferramentas no seu agente

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

Servidores de ferramentas de listas (Opcional)

Sugestão

Este passo é opcional. Use 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.

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

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

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

Python

# 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	Descrição	Valor esperado	Obrigatório/Opcional
agentic_app_id	str	O identificador único para a instância da aplicação agente	String válida de ID de aplicação de agente	Obrigatório
auth_token	str	Token portador para autenticação com o gateway do servidor MCP	Token portador OAuth válido	Obrigatório

Pacote: microsoft-agents-a365-tooling

JavaScript

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

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

**Parâmetros:

Parâmetro	Type	Descrição	Valor esperado	Obrigatório/Opcional
agentInstanceId	string	O identificador único para a instância do agente	Cadeia válida de ID de instância do agente	Obrigatório
authToken	string	Token portador para autenticação com o gateway do servidor MCP	Token portador OAuth válido	Obrigatório

Pacote: Microsoft.Agents.A365.Tooling

.NET

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

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

**Parâmetros:

Parâmetro	Type	Descrição	Valor esperado	Obrigatório/Opcional
agentInstanceId	string	O identificador único para a instância do agente	Cadeia válida de ID de instância do agente	Obrigatório
authToken	string	Token portador para autenticação com o gateway do servidor MCP	Token portador OAuth válido	Obrigatório

Pacote: Microsoft.Agents.A365.Tooling

Regista ferramentas com o teu orquestrador

Use o método de extensão específico do framework para registar todos os servidores MCP com o seu framework 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 junto do teu orquestrador
• Configurar automaticamente os detalhes da autenticação e da ligação
• Disponibilize ferramentas imediatamente para o seu agente invocar

Escolha a extensão do Orchestrator

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

Python

• microsoft-agents-a365-tooling: Funcionalidade principal das ferramentas
• microsoft-agents-a365-tooling-extensions-agentframework: Integração com o 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

JavaScript

• @microsoft/agents-a365-tooling: Funcionalidade principal das ferramentas
• @microsoft/agents-a365-tooling-extensions-claude: Integração com Claude
• @microsoft/agents-a365-tooling-extensions-openai: Integração com OpenAI
• @microsoft/agents-a365-tooling-extensions-langchain: Integração com LangChain

.NET

• Microsoft.Agents.A365.Tooling: Funcionalidade principal das ferramentas
• Microsoft.Agents.A365.Tooling.Extensions.AgentFramework: Integração com o Agent Framework
• Microsoft.Agents.A365.Tooling.Extensions.AzureAIFoundry: Azure AI Foundry integration
• Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel: Integração com o Semantic Kernel

Nota

A autenticação é configurada automaticamente pelo CLI do Agente 365 quando 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 . Os métodos de extensão usam automaticamente estes valores para configurar a autenticação – não é necessária configuração manual.

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

Exemplo de Implementação

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

Python

Python com OpenAI

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

Adicionar instrução de importação.

Adicione as importações 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

Use o add_tool_servers_to_agent método para registar todas as ferramentas MCP configuradas junto do seu agente OpenAI. Este método lida com cenários de autenticação tanto agentica como não agente:

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 considerar.

Parâmetros	Descrições
agent	A instância do agente OpenAI para registar ferramentas.
agentic_app_id	O identificador único do agente (ID da aplicação agente).
auth	O contexto de autorização para o utilizador.
context	A conversa atual muda o contexto do SDK dos Agentes. Fornece identidade do utilizador, metadados de conversa e contexto de autenticação para o registo 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 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 add_tool_servers_to_agent método automaticamente:

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

JavaScript

JavaScript com LangChain

Este exemplo mostra como integrar ferramentas MCP com LangChain numa aplicação JavaScript/TypeScript.

Adicionar instrução de importação.

Adicione as importações necessárias para aceder ao módulo de Ferramentas e às extensões LangChain:

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

2. Inicializar serviços de ferramentas

Crie uma instância do serviço de registo de ferramentas:

const toolService = new McpToolRegistrationService();

3. Registar ferramentas MCP com o agente LangChain

Use o addToolServersToAgent método para registar todas as ferramentas MCP configuradas junto do seu agente LangChain. Este método lida com cenários de autenticação tanto agentica como não agente:

// 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);
}

Parâmetros do método

A tabela seguinte descreve os parâmetros a utilizar com o addToolServersToAgent método.

Parâmetros	Descrições
agent	A instância LangChain ReactAgent para registar ferramentas.
agentUserId	O identificador exclusivo para o mosaico. Pode ser uma cadeia vazia ('') se não usar autenticação agente.
authorization	O contexto de autorização para o utilizador.
turnContext	A conversa atual muda o contexto do SDK dos Agentes. Fornece identidade do utilizador, metadados de conversa e contexto de autenticação para o registo seguro de ferramentas.
authToken	(Opcional) Token portador para cenários de autenticação não agente.

4. Chamada durante a inicialização

Ligue ao addToolServersToAgent método durante a inicialização para registar as ferramentas MCP junto do seu agente.

O addToolServersToAgent método automaticamente:

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

.NET

.NET com Kernel Semântico

Este exemplo mostra como integrar ferramentas MCP com o Kernel Semântico numa aplicação .NET.

Adicionar instrução de importação.

Adicione os namespaces necessários para aceder ao módulo de Ferramentas e às extensões do Kernel Semântico:

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

2. Serviços de registo com injeção de dependências

Adicione os serviços de ferramentas ao seu contentor de injeção de dependências para que possam ser injetados nas suas classes:

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

3. Adicionar declaração privada de campo

Declare um campo privado para guardar a referência do serviço de registo de ferramentas:

private readonly IMcpToolRegistrationService _toolsService;

4. Ferramentas MCP de registos com Kernel Semântico

Use o método de AddToolServersToAgentAsync extensão para registar todas as ferramentas MCP configuradas com a sua instância do Kernel Semântico. Este método lida com cenários de autenticação tanto agentica como não agente:

// 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);
}

Nota

Estão disponíveis várias sobrecargas de métodos. A versão simplificada utiliza a configuração de autenticação por defeito, enquanto a versão explícita permite a especificação personalizada do handler de autenticação.

Parâmetros do método

A tabela que se segue descreve os parâmetros a considerar.

Parâmetros	Descrições
kernel	A instância Semantic Kernel para registar ferramentas. O Kernel orquestra serviços de IA, plugins e execução de funções.
userAuthorization	O contexto de autorização para o utilizador
authHandlerName	Nome do handler de autenticação para uso com o Sistema de Autorização de Utilizador
turnContext	A conversa atual muda de contexto (uma mensagem do utilizador e ciclo de resposta do agente) a partir do SDK dos Agentes. Fornece identidade do utilizador, metadados de conversa e contexto de autenticação para o registo seguro de ferramentas.
authToken	(Opcional) Token portador para cenários de autenticação não agentivos

O AddToolServersToAgentAsync método automaticamente:

• Carrega todos os servidores MCP a partir da ToolingManifest.json
• Regista as suas ferramentas com o Kernel Semântico
• Configura a autenticação com base na configuração do manifesto
• Disponibiliza as ferramentas para o seu agente invocar

Para exemplos completos funcionais, consulte o repositório Agent 365 Samples.

Testar e monitorizar

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. Segue o guia de testes para configurar o teu ambiente e foca-te principalmente na secção de invocações de ferramentas de Teste para validar que as tuas ferramentas MCP estão a funcionar como esperado.

Adicionar observabilidade

Adicione observabilidade ao seu agente para monitorizar e rastrear as invocações da ferramenta MCP do seu agente, adicionar capacidades de observabilidade para acompanhar desempenho, depurar problemas e compreender padrões de utilização de ferramentas. Saiba mais sobre a implementação do rastreio e monitorização