新增與管理工具

重要

你需要參加 Frontier 預覽計畫，才能搶 先取得 Microsoft Agent 365 的使用權。 Frontier 直接連結你與 Microsoft 最新的 AI 創新。 Frontier 預覽受限於您現有的客戶協議預覽條款。由於這些功能仍在開發中，其可用性與功能可能會隨時間改變。

工具模組讓開發者能夠發現、配置並整合模型情境協定（MCP）伺服器到人工智慧代理的工作流程中。 MCP 伺服器將外部能力暴露為 AI 代理可調用的工具。欲了解可用工具伺服器的概覽，請參見 Agent 365 工具伺服器。

展示請求與回應流程

概觀

Agent 365 工具整合遵循四步驟工作流程：

設定 MCP 伺服器 - 使用 Agent 365 CLI 來發現並新增 MCP 伺服器
產生清單 - CLI 與伺服器設定一起建立ToolingManifest.json
整合進程式碼 - 用你的 orchestrator 載入清單並註冊工具
呼叫工具 - 代理在執行時呼叫工具以執行操作

先決條件

在配置 MCP 伺服器前，請確保你具備：

Agent 365 CLI 已安裝並設定
.NET 8.0 SDK 或更高版本 - 下載
您的 Microsoft 365 租戶中的全域管理員權限

代理身份設定

如果你使用代理認證，請先完成代理註冊流程，建立代理身份，再設定 MCP 伺服器。這會建立代理式應用程式 ID 與代理使用者，使代理能驗證並存取 MCP 工具。

設定服務主體

執行這個一次性設定腳本，在你的租戶中建立 Agent 365 工具的服務主體。

重要

這是每個租戶一次性操作，需要全域管理員權限。

下載 New-Agent365ToolsServicePrincipalProdPublic.ps1 腳本
以系統管理員身分開啟 PowerShell，然後瀏覽至您儲存 PowerShell 指令碼的目錄。

執行指令碼：

.\New-Agent365ToolsServicePrincipalProdPublic.ps1

如果系統提示，請使用您的 Azure 認證登入。

完成後，租戶即可進行代理程式開發及 MCP 伺服器配置。

配置 MCP 伺服器

使用 Agent 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 指令。

了解工具清單

當你執行 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"
    }
  ]
}

manifest 參數

每個 MCP 伺服器項目包含：

參數	Description
mcpServerName	伺服器的顯示名稱。
mcpServerUniqueName	執行的執行個體之唯一識別碼
範圍 (scope)	存取 MCP 伺服器功能所需的 OAuth 範圍（例如： `McpServers.Mail.All` 郵件操作）。這個值會在執行 `add-mcp-servers` 指令時從 MCP 伺服器目錄中取得。
目標對象	用來識別目標 API 資源的 Microsoft Entra ID URI。此值同樣可從 MCP 伺服器目錄中取得。

注意

scope當你新增 MCP 伺服器時，Agent 365 CLI 會自動填入 and 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)

參數：

參數	類型	Description	預期的值	必要/選用
`agentic_app_id`	字串	代理應用程式實例的唯一識別碼	有效代理應用程式 ID 字串	必要
`auth_token`	字串	用於與 MCP 伺服器閘道認證的持有憑證	有效的 OAuth 持有人令牌	必要

Package： 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);

參數：

參數	類型	Description	預期的值	必要/選用
`agentInstanceId`	string	執行的執行個體之唯一識別碼	有效代理實例 ID 字串	必要
`authToken`	string	用於與 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);

參數：

參數	類型	Description	預期的值	必要/選用
`agentInstanceId`	string	執行的執行個體之唯一識別碼	有效代理實例 ID 字串	必要
`authToken`	string	用於與 MCP 伺服器閘道認證的持有憑證	有效的 OAuth 持有人令牌	必要

套件： Microsoft.Agents.A365.Tooling

向你的管線器註冊工具

使用框架專屬的擴充方法，將所有 MCP 伺服器註冊到你的編排框架中：

.NET
Python
Node.js：

這些方法會：

用你的編排器註冊所有已設定的 MCP 伺服器上的工具
自動設定驗證與連線細節
立即提供工具供代理人調用

選擇你的編排器擴充

Agent 365 工具模組提供針對不同協調框架的專用擴充套件：

Microsoft-agents-a365-tooling：核心工具功能
microsoft-agents-a365-tooling-extensions-agentframework：代理框架整合
Microsoft-agents-a365-tooling-extensions-azureaifoundry： Azure AI Foundry integration
Microsoft-agents-a365-tooling-extensions-openai： OpenAI 整合
microsoft-agents-a365-tooling-extensions-semantickernel： Semantic Kernel integration

注意

當你執行 a365 develop add-mcp-servers. 時，Agent 365 CLI 會自動設定認證。 OAuth 範圍與受眾值會從 MCP 伺服器目錄中取得並包含於 ToolingManifest.json. 擴充方法會自動使用這些值來設定認證——不需要手動設定。

欲了解詳細實作範例，請參閱 Agent 365 範例。

實作範例

以下範例展示了如何將 Agent 365 工具整合到不同的協調框架中。

Python 與 OpenAI 合作

這個範例展示了如何在 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. 將 MCP 工具註冊為 OpenAI 代理

使用該 add_tool_servers_to_agent 方法將所有已設定的 MCP 工具註冊給你的 OpenAI 代理。此方法可處理代理認證與非代理認證兩種情境：

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 中使用的參數。

參數	Description
`agent`	OpenAI 代理實例用來註冊工具。
`agentic_app_id`	代理人的唯一識別碼（代理應用程式 ID）。
`auth`	使用者的授權上下文。
`context`	目前的對話從 Agents SDK 的背景轉向。提供使用者身份、對話中繼資料及驗證上下文，以保障工具註冊的安全。
`auth_token`	（可選）非代理認證情境下的持有憑證。

4. 初始化時的呼叫

在執行代理程式前，請在初始化時呼叫設定方法：

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

該方法自動：add_tool_servers_to_agent

從ToolingManifest.json載入所有 MCP 伺服器
將工具註冊給 OpenAI 代理
根據清單設定來建立認證
讓你的代理人可以使用這些工具

JavaScript 與 LangChain

這個範例展示了如何在 JavaScript/TypeScript 應用程式中整合 MCP 工具與 LangChain。

新增 import 陳述式。

新增所需匯入以存取 Tooling 模組與 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 方法將所有已設定的 MCP 工具註冊給你的 LangChain 代理程式。此方法可處理代理認證與非代理認證兩種情境：

// 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 參數。

參數	Description
`agent`	用來註冊工具的 LangChain ReactAgent 實例。
`agentUserId`	圖格的唯一識別碼。若不使用代理認證，則可為空字串（`''`）。
`authorization`	使用者的授權上下文。
`turnContext`	目前的對話從 Agents SDK 的背景轉向。提供使用者身份、對話中繼資料及驗證上下文，以保障工具註冊的安全。
`authToken`	（可選）非代理認證情境下的持有憑證。

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 extension 方法將所有已設定的 MCP 工具註冊到你的語意核心實例。此方法可處理代理認證與非代理認證兩種情境：

// 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 中使用的參數。

參數	Description
`kernel`	用於註冊工具的語意核心實例。核心負責協調 AI 服務、外掛及函式執行。
`userAuthorization`	使用者的授權上下文
`authHandlerName`	用於使用者授權系統的認證處理程式名稱
`turnContext`	目前的對話轉向上下文（一個使用者訊息與代理回應週期）來自代理 SDK。提供使用者身份、對話中繼資料及驗證上下文，以保障工具註冊的安全。
`authToken`	（可選）非代理認證情境下的持有憑證

該方法自動：AddToolServersToAgentAsync

從ToolingManifest.json載入所有 MCP 伺服器
將工具註冊給語意核心
根據清單設定來建立認證
讓你的代理人可以使用這些工具

完整工作範例請參閱 Agent 365 樣本庫。

測試與監視

測試您的 Agent

將 MCP 工具整合進代理程式後，測試工具調用，確保它們能正常運作並處理不同情境。依照測試指南設定環境，然後主要專注於測試工具調用部分，以驗證你的 MCP 工具是否如預期運作。

KMS 可檢視性

為代理加入可觀察性，以監控並追蹤代理的 MCP 工具調用，新增可觀察功能以追蹤效能、除錯問題及理解工具使用模式。了解更多關於追蹤與監控的實施

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-08

共用方式為

新增與管理工具

概觀

先決條件

代理身份設定

設定服務主體

配置 MCP 伺服器

探索可用的計數器

新增 MCP 伺服器

列出已配置伺服器

移除 MCP 伺服器

了解工具清單

顯現結構

manifest 參數

將自訂工具整合到代理程式中

列表工具伺服器（可選）

向你的管線器註冊工具

選擇你的編排器擴充

實作範例

Python 與 OpenAI 合作

新增 import 陳述式。

2. 初始化工具服務

3. 將 MCP 工具註冊為 OpenAI 代理

方法參數

4. 初始化時的呼叫

測試與監視

測試您的 Agent

KMS 可檢視性

意見反應

其他資源