添加和管理标记

重要提示

你需要是边境预览计划的一部分，才能提前访问 Microsoft Agent 365。边界将你直接与Microsoft最新的 AI 创新联系起来。边境预览版受客户协议现有预览条款的约束。由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

工具模块帮助开发者发现、配置并集成模型上下文协议（MCP）服务器到AI代理的工作流程中。 MCP 服务器将外部功能公开为 AI 代理可以调用的工具。有关可用工具服务器的概述，请参阅代理 365 工具服务器。

演示请求和响应流

概述

代理 365 工具集成遵循四步工作流：

配置 MCP 服务器 - 使用代理 365 CLI 发现和添加 MCP 服务器
生成清单 - CLI 使用服务器配置创建ToolingManifest.json
集成到代码 - 加载清单并向业务流程协调程序注册工具
调用工具 - 代理在执行过程中调用工具以执行作

先决条件

在配置备份服务之前，请确保具备以下先决条件：：

已安装并配置代理 365 CLI
.NET 8.0 SDK 或更高版本 - 下载
Microsoft 365 租户的全局管理员

代理标识设置

如果使用代理身份验证，请在配置 MCP 服务器之前完成代理注册过程以创建代理标识。该过程创建代理应用ID和代理用户，使代理能够认证并访问MCP工具。

OBO认证设置

如果你使用 On-Behalf-Of（OBO）认证代替代理认证，代理可以通过委派用户权限访问 MCP 工具，而无需代理用户身份。在OBO流程中，代理交换用户委托的令牌，以代表用户执行作。

有关OBO流程的工作方式，请参见认证流程。完整实现示例请参见 Microsoft 365 Agents SDK 中的 OBO 授权示例。

设置服务主体

运行这个一次性设置脚本，在租户中创建Agent 365 Tools的服务主体。

重要提示

每个租户一次性作需要全局管理员权限。

下载 New-Agent365ToolsServicePrincipalProdPublic.ps1 剧本。
以管理员身份打开PowerShell，进入脚本目录。

运行脚本。

.\New-Agent365ToolsServicePrincipalProdPublic.ps1

当提示时使用你的Azure凭证登录。

完成后，租户已准备好进行代理开发和 MCP 服务器配置。

配置 MCP 服务器

使用代理 365 CLI 发现、添加和管理代理的 MCP 服务器。有关可用 MCP 服务器及其功能的完整列表，请参阅 MCP 服务器目录。

发现可用的计数器

列出所有可配置的MCP服务器：

a365 develop list-available

添加 MCP 服务器

将一个或多个 MCP 服务器添加到代理配置：

a365 develop add-mcp-servers mcp_MailTools

列出配置的服务器

查看当前配置的 MCP 服务器：

a365 develop list-configured

管控 MCP 服务器

从配置中删除 MCP 服务器：

a365 develop remove-mcp-servers mcp_MailTools

完整的CLI参考，请参见 a365 develop命令。

使用模拟工具服务器进行测试

在测试和开发时，使用Agent 365的CLI模拟工具服务器，而不是连接到实际的MCP服务器。模拟服务器模拟MCP服务器交互，因此你可以在本地测试代理，无需外部依赖如认证。

模拟服务器为本地开发和测试提供了以下优势：

离线开发：测试您的代理时不连接互联网或外部依赖。
持续测试：在测试边缘案例时获得可预测的响应。
调试：实时查看所有请求和响应
快速迭代：无需等待外部 API 调用或搭建复杂的测试环境。

通过使用命令a365 develop start-mock-tooling-server启动模拟模具服务器。

学习如何搭建和配置模型工具服务器。

备注

接下来关于配置清单和将工具集成到代理中的部分，无论你使用模拟工具服务器还是实际的MCP服务器，工作方式都是一样的。设置环境 MCP_PLATFORM_ENDPOINT 变量指向模拟服务器（例如： http://localhost:5309），而不是生产端点。

了解工具清单

运行 a365 develop add-mcp-servers时，CLI 会生成一个 ToolingManifest.json 文件，其中包含所有 MCP 服务器的配置。代理运行时使用此清单来了解哪些服务器可用以及如何对其进行身份验证。

清单结构

示例: ToolingManifest.json

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

清单参数

每个 MCP 服务器条目都包含：

参数设置	描述
mcpServerName	服务器的显示名称。
mcpServerUniqueName	执行实例的唯一标识符
作用域	访问 MCP 服务器功能所需的 OAuth 范围（例如： `McpServers.Mail.All` 邮件作）。该 `add-mcp-servers` 命令从MCP服务器目录中检索该值。
audience	标识目标 API 资源的Microsoft Entra ID URI。该 `add-mcp-servers` 命令从MCP服务器目录中检索该值。

备注

Agent 365 CLI在添加MCP服务器时会自动填充 scope 和 audience 值。这些值来自 MCP 服务器目录，并定义访问每个 MCP 服务器所需的权限。

将自定义工具集成到代理中

生成工具清单后，将配置的 MCP 服务器集成到代理代码中。本部分介绍可选的检查步骤和所需的集成步骤。

列表工具服务器（可选）

小费

此步骤是可选的。在将可用工具添加到业务流程协调程序之前，使用工具服务器配置服务检查工具清单中的可用工具服务器。

使用工具服务器配置服务从工具清单中发现代理可用的工具服务器。此方法允许你：

从文件中查询所有已配置的MCP服务器 ToolingManifest.json 。
检索服务器元数据和功能。
注册前请确认服务器可用性。

列出工具服务器的方法在核心工具包中可用：

# 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)

参数：

参数	类型	描述	预期的值	必需/可选
`agentic_app_id`	str	应用程序实例的唯一标识符	有效的代理应用程序 ID 字符串	需要
`auth_token`	str	使用 MCP 服务器网关进行身份验证的持有者令牌	有效的 OAuth 持有者令牌	需要

包： microsoft-agents-a365-tooling

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

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

参数：

参数	类型	描述	预期的值	必需/可选
`agentInstanceId`	字符串	执行实例的唯一标识符	有效的代理实例 ID 字符串	需要
`authToken`	字符串	使用 MCP 服务器网关进行身份验证的持有者令牌	有效的 OAuth 持有者令牌	需要

包： Microsoft.Agents.A365.Tooling

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

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

参数：

参数	类型	描述	预期的值	必需/可选
`agentInstanceId`	字符串	执行实例的唯一标识符	有效的代理实例 ID 字符串	需要
`authToken`	字符串	使用 MCP 服务器网关进行身份验证的持有者令牌	有效的 OAuth 持有者令牌	需要

包： Microsoft.Agents.A365.Tooling

向业务流程协调程序注册工具

使用特定于框架的扩展方法向业务流程框架注册所有 MCP 服务器：

.NET。
add_tool_servers_to_agent (Python)、
Node.js：

这些方法：

将配置 MCP 服务器中的所有工具注册到业务流程协调程序
自动设置身份验证和连接详细信息
使工具立即可供代理调用

选择业务流程协调程序扩展

代理 365 工具模块为不同的业务流程框架提供专用扩展包：

microsoft-agents-a365-tooling：核心工具功能
microsoft-agents-a365-tooling-extensions-agentframework：Agent Framework 集成
microsoft-agents-a365-tooling-extensions-azureaifoundry：Azure AI Foundry 集成
microsoft-agents-a365-tooling-extensions-openai：OpenAI 集成
microsoft-agents-a365-tooling-extensions-semantickernel：语义内核集成

备注

运行 a365 develop add-mcp-servers时代理 365 CLI 会自动配置身份验证。 MCP服务器目录检索OAuth范围和受众值，并将其包含在 ToolingManifest.json. 扩展方法自动使用这些值来设置身份验证 - 无需手动配置。

有关详细的实现示例，请参阅代理 365 示例。

实现示例

以下示例展示了如何将 Agent 365 工具与不同的编排框架集成。

使用 OpenAI 的 Python

此示例演示如何在 Python 应用程序中将 MCP 工具与 OpenAI 集成。

添加 Import 语句。

添加所需的导入以访问工具模块和 OpenAI 扩展：

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

2. 初始化工具服务

创建配置和工具注册服务的实例：

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

3. 向 OpenAI 代理注册 MCP 工具

使用此方法 add_tool_servers_to_agent 向 OpenAI 代理注册所有配置的 MCP 工具。此方法同时处理代理身份验证和非AGENTIC 身份验证方案：

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

方法参数

下表描述了与 add_tool_servers_to_agent 一起使用的参数。

参数设置	描述
`agent`	要注册工具的 OpenAI 代理实例。
`agentic_app_id`	代理的唯一标识符（代理应用 ID）。
`auth`	用户的授权上下文。
`context`	代理 SDK 中的当前聊天轮次上下文。提供用于安全工具注册的用户标识、对话元数据和身份验证上下文。
`auth_token`	（可选）非AGENTIC 身份验证方案的持有者令牌。

4. 初始化期间调用

在运行代理之前，请确保在初始化期间调用安装方法：

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

该方法 add_tool_servers_to_agent 自动：

从 ToolingManifest.json 文件加载所有MCP服务器。
将工具注册给OpenAI代理。
根据清单配置设置认证。
为你的代理人提供可用的工具。

使用 LangChain 的 JavaScript

本示例展示了如何在JavaScript或TypeScript应用中将MCP工具与LangChain集成。

添加 Import 语句。

添加所需的导入以访问工具模块和 LangChain 扩展：

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

2. 初始化工具服务

创建工具注册服务的实例：

const toolService = new McpToolRegistrationService();

3. 向 LangChain 代理注册 MCP 工具

使用此方法 addToolServersToAgent 向 LangChain 代理注册所有配置的 MCP 工具。此方法同时处理代理身份验证和非AGENTIC 身份验证方案：

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

方法参数

下表描述了与 addToolServersToAgent 一起使用的参数。

参数设置	描述
`agent`	要注册工具的 LangChain ReactAgent 实例。
`agentUserId`	用户的唯一标识符。如果你没有使用代理认证，请使用空字符串（`''`）。
`authorization`	用户的授权上下文。
`turnContext`	代理 SDK 中的当前聊天轮次上下文。提供用于安全工具注册的用户标识、对话元数据和身份验证上下文。
`authToken`	（可选）非AGENTIC 身份验证方案的持有者令牌。

4. 初始化期间调用

addToolServersToAgent在初始化期间调用该方法，以向代理注册 MCP 工具。

该方法 addToolServersToAgent 自动：

从 ToolingManifest.json 文件加载所有MCP服务器。
向LangChain代理登记工具。
根据清单配置设置认证。
为你的代理人提供可用的工具。

具有语义内核的 .NET

此示例演示如何在 .NET 应用程序中将 MCP 工具与语义内核集成。

添加 Import 语句。

添加所需的命名空间以访问工具模块和语义内核扩展：

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

在依赖项注入术语中，服务：

将工具服务添加到你的依赖注入容器中，这样你可以将它们注入到你的类中：

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

3. 添加专用字段声明

声明用于保存工具注册服务引用的专用字段：

private readonly IMcpToolRegistrationService _toolsService;

4. 将 MCP 工具注册到语义内核

使用 AddToolServersToAgentAsync 扩展方法向语义内核实例注册所有配置的 MCP 工具。此方法同时处理代理身份验证和非AGENTIC 身份验证方案：

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

备注

提供了多个方法重载。简化的版本使用默认身份验证配置，而显式版本允许自定义身份验证处理程序规范。

方法参数

下表描述了与 AddToolServersToAgentAsync 一起使用的参数。

参数设置	描述
`kernel`	要注册工具的语义内核实例。内核协调 AI 服务、插件和函数执行。
`userAuthorization`	用户的授权上下文。
`authHandlerName`	用于用户授权系统的认证处理程序名称。
`turnContext`	代理 SDK 中的当前会话轮次上下文（一个用户消息和代理响应周期）。提供用于安全工具注册的用户标识、对话元数据和身份验证上下文。
`authToken`	（可选）非AGENTIC 身份验证方案的持有者令牌。

该方法 AddToolServersToAgentAsync 自动：

从 ToolingManifest.json 文件加载所有MCP服务器。
将工具注册到语义内核。
根据清单配置设置认证。
为你的代理人提供可用的工具。

有关完整的工作示例，请参阅 Agent 365 示例存储库。

访问Agent 365 MCP服务器的其他方式

除了 Agent 365 SDK，您还可以通过其他开发体验访问 Agent 365 MCP 服务器：

Visual Studio Code - 直接连接到 MCP 服务器，实现自定义开发流程。
Microsoft Copilot Studio - 利用低代码体验将MCP服务器集成到对话流程中。
Azure AI Foundry - 使用具备完整SDK支持和高级编排功能的MCP服务器。

有关这些平台间可用MCP服务器及集成选项的完整概述，请参见 Agent 365工具服务器概述。

测试您的智能体

将MCP工具集成到代理中后，测试工具调用，确保它们能正常工作并处理不同场景。按照测试指南搭建环境。然后，主要关注测试工具调用部分，以验证你的MCP工具是否按预期工作。另外，可以试试模拟工具服务器，测试MCP服务器连接和工具调用，无需处理认证。

SDK 可观测性

为你的代理添加可观察性，以监控和追踪代理的MCP工具调用。通过增加可观测性功能，你可以跟踪性能、调试问题并理解工具使用模式。了解更多关于实施追踪和监控的信息。

Troubleshooting

本节列出了配置和使用 MCP 服务器及工具时常见的问题。

小费

Agent 365 故障排除指南包含高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

MCP 服务器与工具问题

症状：

工具呼叫故障。
“找不到MCP服务器”错误。
调用工具时出现许可被拒错误。

根本原因：

MCP服务器没有配置。
缺少权限。
服务负责人没有被安排好。
模拟服务器和生产服务器之间的混淆。

解决方案： 尝试以下解决方案来解决问题。

核实MCP服务器的配置

列出已配置的服务器，并添加缺失的服务器。

# List configured servers
a365 develop list-configured

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

存在校验服务主体

确保为工具制作创建所需的服务主体。

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

在早期开发和测试中，使用模拟服务器

如果你想测试代理的其他部分而不使用生产工具组件，可以用模拟工具服务器进行早期本地开发和测试。
```
# Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309
```
了解一下模拟模具服务器。
在管理中心验证权限

确认你的代理人拥有必要的MCP权限。
- 验证你的 Azure 门户中的代理蓝图 API 权限是否显示了所有 MCP 服务器权限。
验证：
```
# Test a tool call in Agents Playground
# Should execute without permission errors
```

反馈

此页面是否有帮助？

Last updated on 2026-02-11

通过

添加和管理标记

概述

先决条件

代理标识设置

OBO认证设置

设置服务主体

配置 MCP 服务器

发现可用的计数器

添加 MCP 服务器

列出配置的服务器

管控 MCP 服务器

使用模拟工具服务器进行测试

了解工具清单

清单结构

清单参数

将自定义工具集成到代理中

列表工具服务器（可选）

向业务流程协调程序注册工具

选择业务流程协调程序扩展

实现示例

使用 OpenAI 的 Python

添加 Import 语句。

2. 初始化工具服务

3. 向 OpenAI 代理注册 MCP 工具

方法参数

4. 初始化期间调用

访问Agent 365 MCP服务器的其他方式

测试您的智能体

SDK 可观测性

Troubleshooting

MCP 服务器与工具问题

反馈

其他资源