新增和管理工具

Tooling 模組可協助開發人員探索、設定及整合 Model Context Protocol (MCP) 伺服器至 AI Agent 工作流程中。 MCP 伺服器會以工具的形式公開外部功能,供 AI Agent 呼叫。如需可用工具伺服器的概觀,請參閱 Agent 365 工具伺服器。

示範要求和回應流程

概觀

Agent 365 Tooling 整合作業遵循下列工作流程：

設定 MCP 伺服器 - 使用 Agent 365 CLI 探索並新增 MCP 伺服器
產生資訊清單 - CLI 會在您的專案資料夾中建立包含伺服器設定的 ToolingManifest.json。
將權限套用至藍圖 - 全域管理員可透過執行 a365 setup all (首次設定) 或 a365 setup permissions mcp (若藍圖已存在),將 OAuth2 權限授予 Agent 藍圖。無論哪種方式,此指令都會讀取 ToolingManifest.json,並需要系統管理員同意。此步驟一律與將伺服器新增至資訊清單分開執行。
整合至程式碼 - 載入資訊清單,並向您的協調器註冊工具。
呼叫工具 - Agent 會在執行期間呼叫工具以執行作業。

先決條件

設定 MCP 伺服器之前,請確認您已具備下列項目：

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

Agent 身分識別設定

如果您使用 Agent 型驗證,請先完成 Agent 註冊程序,建立您的 Agent 身分識別,再設定 MCP 伺服器。此程序會建立 Entra Agent 識別碼和 Agent 使用者,讓您的 Agent 能夠驗證並存取 MCP 工具。

OBO 驗證設定

如果您使用 On-Behalf-Of (OBO) 驗證而非 Agent 型驗證,您的 Agent 可以使用委派的使用者權限存取 MCP 工具,而不需要 Agent 使用者身分識別。在 OBO 流程中,Agent 會交換使用者的委派權杖,以代表使用者執行動作。

如需 OBO 流程運作方式的詳細資訊,請參閱驗證流程。如需完整的實作範例,請參閱 Microsoft 365 Agents SDK 中的 OBO 授權範例。

設定服務主體

執行此一次性設定指令碼,在您的租用戶中為 Agent 365 Tools 建立服務主體。

重要

此每租用戶一次性作業需要全域管理員權限。

下載 New-Agent365ToolsServicePrincipalProdPublic.ps1 指令碼。
以系統管理員身分開啟 PowerShell,並前往指令碼目錄。

執行指令碼。

.\New-Agent365ToolsServicePrincipalProdPublic.ps1

出現提示時,使用您的 Azure 認證登入。

完成後,您的租用戶即可用於 Agent 開發和 MCP 伺服器設定。

設定 MCP 伺服器

使用 Agent 365 CLI 為您的 Agent 探索、新增及管理 MCP 伺服器。如需可用 MCP 伺服器及其功能的完整清單,請參閱 MCP 伺服器目錄。

探索可用的伺服器

列出您可以設定的所有 MCP 伺服器：

a365 develop list-available

新增 MCP 伺服器

將一或多個 MCP 伺服器新增至您的 Agent 設定：

a365 develop add-mcp-servers mcp_MailTools

重要

此指令只會更新您專案資料夾中的 ToolingManifest.json - 不會授予藍圖任何權限。權限的套用方式,取決於您在設定程序中的所在階段：

初始設定之前：請先執行 a365 develop add-mcp-servers,再繼續執行 a365 setup all。 setup all 指令會將 MCP 權限步驟納入藍圖建立程序的一部分。
藍圖已存在之後：全域管理員必須另外執行 a365 setup permissions mcp。系統管理員的 a365.config.json 中,deploymentProjectPath 必須指向包含更新後 ToolingManifest.json 的專案資料夾。在此步驟完成之前,新的 MCP 伺服器權限不會顯示在藍圖中。

列出已設定的伺服器

檢視目前已設定的 MCP 伺服器：

a365 develop list-configured

移除 MCP 伺服器

從您的設定中移除 MCP 伺服器：

a365 develop remove-mcp-servers mcp_MailTools

如需完整的 CLI 參考資料,請參閱 a365 develop 指令。

使用模擬工具伺服器進行測試

進行測試和開發時,請使用 Agent 365 CLI 模擬工具伺服器,而非連線至實際的 MCP 伺服器。模擬伺服器會模擬 MCP 伺服器互動,讓您可以在本機測試 Agent,而不需要驗證等外部相依性。

模擬伺服器為本地開發與測試提供以下優點：

離線開發：在沒有網際網路連線或外部相依性的情況下測試您的Agent。
一致性測試：獲得可預測的回覆以測試邊緣案例。
除錯：即時檢視所有請求與回覆
快速迭代：無需等待外部 API呼叫，也不需設定複雜的測試環境。

使用 a365 develop start-mock-tooling-server 指令啟動模擬工具伺服器。

了解如何安裝及設定模擬工具伺服器。

注意

不論您使用模擬工具伺服器或實際的 MCP 伺服器,以下設定資訊清單和將工具整合到 Agent 中的章節,運作方式都相同。請將您的 MCP_PLATFORM_ENDPOINT 環境變數設定為指向模擬伺服器 (例如：http://localhost:5309),而非正式環境端點。

了解工具資訊清單

執行 a365 develop add-mcp-servers 時,CLI 會產生一個 ToolingManifest.json 檔案,其中包含所有 MCP 伺服器的設定。 Agent 執行階段會使用此資訊清單,判斷有哪些伺服器可用,以及如何與其進行驗證。

資訊清單結構

範例：ToolingManifest.json

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

資訊清單參數

每個 MCP 伺服器項目都包含：

參數	描述
mcpServerName	MCP 伺服器的顯示名稱。
mcpServerUniqueName	MCP 伺服器執行個體的唯一識別碼。
範圍 (scope)	存取 MCP 伺服器功能所需的 OAuth 範圍 (例如,郵件作業使用 `McpServers.Mail.All`)。 `add-mcp-servers` 指令會從 MCP 伺服器目錄擷取此值。
audience	用於識別目標 API 資源的 Microsoft Entra ID URI。 `add-mcp-servers` 指令會從 MCP 伺服器目錄擷取此值。

注意

新增 MCP 伺服器時,Agent 365 CLI 會自動填入 scope 和 audience 值。這些值來自 MCP 伺服器目錄,並定義存取每個 MCP 伺服器所需的權限。

將工具整合到您的 Agent 中

產生工具資訊清單後,請將已設定的 MCP 伺服器整合到您的 Agent 程式碼中。本節涵蓋選擇性的檢查步驟,以及必要的整合步驟。

列出工具伺服器 (選擇性)

提示

這個步驟是選擇性的。在將可用的工具伺服器新增至協調器之前,可使用工具伺服器設定服務,從工具資訊清單中檢查這些伺服器。

使用工具伺服器設定服務,從工具資訊清單中探索您的 Agent 可使用哪些工具伺服器。此方法可讓您執行下列作業：

從 ToolingManifest.json 檔案查詢所有已設定的 MCP 伺服器。
擷取伺服器中繼資料和功能。
在註冊之前驗證伺服器可用性。

列出工具伺服器的方法,可在核心工具套件中使用：

# 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`	str	Agent 應用程式執行個體的唯一識別碼	有效的 Agent 應用程式識別碼字串	必要
`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);

參數：

參數	類型	Description	預期的值	必要/選擇性
`agentInstanceId`	字串	Agent 執行個體的唯一識別碼	有效的 Agent 執行個體識別碼字串	必要
`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);

參數：

參數	類型	Description	預期的值	必要/選擇性
`agentInstanceId`	字串	Agent 執行個體的唯一識別碼	有效的 Agent 執行個體識別碼字串	必要
`authToken`	字串	用於透過 MCP 伺服器閘道進行驗證的持有者權杖	有效的 OAuth 持有者權杖	必要

套件：Microsoft.Agents.A365.Tooling.Services

向您的協調器註冊工具

使用架構專屬的擴充方法,向您的協調流程架構註冊所有 MCP 伺服器：

AddToolServersToAgentAsync (.NET)
add_tool_servers_to_agent (Python)
addToolServersToAgent (Node.js)

這些方法會：

向您的協調器註冊所有已設定 MCP 伺服器的工具
自動設定驗證和連線詳細資料
讓工具立即可供您的 Agent 呼叫

選擇您的協調器擴充功能

Agent 365 Tooling 模組會為不同的協調流程架構,提供專用的擴充套件：

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 時,CLI 會自動從 MCP 伺服器目錄擷取 OAuth 範圍和目標對象值,並寫入 ToolingManifest.json。擴充方法會使用這些值在執行階段設定驗證 - 您的 Agent 程式碼不需要任何手動設定。不過,在您的 Agent 可在正式環境中使用這些權限之前,全域管理員仍必須將這些權限授予 Agent 藍圖：透過 a365 setup all (首次設定) 或 a365 setup permissions mcp (若藍圖已存在)。

如需詳細的實作範例,請參閱 Agent 365 Samples。

實作範例

以下範例說明如何將 Agent 365 Tooling 與不同的協調流程架構整合。

搭配 OpenAI 使用 Python

此範例說明如何在 Python 應用程式中,將 MCP 工具與 OpenAI 整合。

1. 新增匯入陳述式

新增必要的匯入項目,以存取 Tooling 模組和 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 Agent 註冊 MCP 工具

使用 add_tool_servers_to_agent 方法,向您的 OpenAI Agent 註冊所有已設定的 MCP 工具。此方法可處理 Agent 型和非 Agent 型驗證案例：

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 Agent 執行個體。
`agentic_app_id`	Agent 的唯一識別碼 (Agent 應用程式識別碼)。
`auth`	使用者的授權內容。
`context`	來自 Agents SDK 的目前交談回合內容。提供使用者身分識別、交談中繼資料和驗證內容,以進行安全的工具註冊。
`auth_token`	(選擇性) 用於非 Agent 型驗證案例的持有者權杖。

4. 在初始化期間呼叫

請確認您在執行 Agent 之前,已在初始化期間呼叫設定方法：

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

add_tool_servers_to_agent 方法會自動執行下列作業：

從 ToolingManifest.json 檔案載入所有 MCP 伺服器。
向 OpenAI Agent 註冊其工具。
根據資訊清單設定來設定驗證。
讓您的 Agent 可以呼叫這些工具。

搭配 LangChain 使用 JavaScript

此範例說明如何在 JavaScript 或 TypeScript 應用程式中,將 MCP 工具與 LangChain 整合。

1. 新增匯入陳述式

新增必要的匯入項目,以存取 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 Agent 註冊 MCP 工具

使用 addToolServersToAgent 方法,向您的 LangChain Agent 註冊所有已設定的 MCP 工具。此方法可處理 Agent 型和非 Agent 型驗證案例：

// 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`	Agent 使用者的唯一識別碼。如果您未使用 Agent 型驗證,請使用空字串 (`''`)。
`authorization`	使用者的授權內容。
`turnContext`	來自 Agents SDK 的目前交談回合內容。提供使用者身分識別、交談中繼資料和驗證內容,以進行安全的工具註冊。
`authToken`	(選擇性) 用於非 Agent 型驗證案例的持有者權杖。

4. 在初始化期間呼叫

在初始化期間呼叫 addToolServersToAgent 方法,向您的 Agent 註冊 MCP 工具。

addToolServersToAgent 方法會自動執行下列作業：

從 ToolingManifest.json 檔案載入所有 MCP 伺服器。
向 LangChain Agent 註冊其工具。
根據資訊清單設定來設定驗證。
讓您的 Agent 可以呼叫這些工具。

搭配語意核心使用 .NET

此範例說明如何在 .NET 應用程式中,將 MCP 工具與語意核心整合。

1. 新增匯入陳述式

新增必要的命名空間,以存取 Tooling 模組和語意核心擴充功能：

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

2. 使用相依性插入註冊服務

將工具服務新增至您的相依性插入容器,以便將其插入您的類別中：

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

3. 新增私用欄位宣告

宣告私用欄位,以保留工具註冊服務參考：

private readonly IMcpToolRegistrationService _toolsService;

4. 向語意核心註冊 MCP 工具

使用 AddToolServersToAgentAsync 擴充方法,向您的語意核心執行個體註冊所有已設定的 MCP 工具。此方法可處理 Agent 型和非 Agent 型驗證案例：

// 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`	要向其註冊工具的語意核心執行個體。 Kernel 會協調 AI 服務、外掛程式和函式執行。
`userAuthorization`	使用者的授權內容。
`authHandlerName`	用於 UserAuthorization 系統的驗證處理常式名稱。
`turnContext`	來自 Agents SDK 的目前交談回合內容 (一次使用者訊息和 Agent 回應的循環)。提供使用者身分識別、交談中繼資料和驗證內容,以進行安全的工具註冊。
`authToken`	(選擇性) 用於非 Agent 型驗證案例的持有者權杖。

AddToolServersToAgentAsync 方法會自動執行下列作業：

從 ToolingManifest.json 檔案載入所有 MCP 伺服器。
向語意核心註冊其工具。
根據資訊清單設定來設定驗證。
讓您的 Agent 可以呼叫這些工具。

如需完整的可運作範例,請參閱 Agent 365 Samples 存放庫。

其他存取 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 工具伺服器概觀。

自備 (BYO) MCP 伺服器

自備 (BYO) MCP 伺服器功能可讓您向 Microsoft Agent 365 註冊自己的外部 MCP 伺服器,以便在 Microsoft 365 系統管理中心集中治理、核准和監視這些伺服器。這項功能會透過 Agent 365 工具閘道,將這些伺服器路由傳送,讓管理員可以控制核准、存取和原則,同時讓安全性小組能透過遙測資料追蹤使用情形。身為開發人員,您可以使用 Agent 365 CLI 註冊您的 MCP 伺服器,然後請管理員審查並核准註冊,並授予權限。核准的伺服器即可在支援的用戶端工具中使用,並透過持續監視確保所有整合作業的合規性和可見度。

如需完整指示,請參閱自備 (BYO) MCP 伺服器。

測試您的 Agent

將 MCP 工具整合到 Agent 之後,請測試工具呼叫,確保其能正確運作並處理不同的案例。請遵循測試指南設定您的環境。接著,請主要著重於測試工具呼叫一節,驗證您的 MCP 工具是否如預期般運作。此外,您也可以查看模擬工具伺服器,在不處理驗證的情況下測試 MCP 伺服器連線和工具呼叫。

新增可觀察性

為您的 Agent 新增可觀察性,以監視及追蹤 Agent 的 MCP 工具呼叫。透過新增可觀察性功能,您可以追蹤效能、偵錯問題,並了解工具使用模式。深入了解如何實作追蹤和監視。

疑難排解

本節列出設定和使用 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

在早期開發和測試階段,使用模擬伺服器

如果您想在不使用正式環境工具元件的情況下測試 Agent 的其餘部分,請在早期的本機開發和測試階段使用模擬工具伺服器。
```
# Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309
```
深入了解模擬工具伺服器。
在系統管理中心中驗證權限

確認您的 Agent 具備必要的 MCP 權限。
- 驗證 Azure 入口網站中您 Agent 藍圖的 API 權限,是否顯示所有 MCP 伺服器權限。
驗證：
```
# Test a tool call in Agents Playground
# Should execute without permission errors
```

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-30

新增和管理工具

概觀

先決條件

Agent 身分識別設定

OBO 驗證設定

設定服務主體

設定 MCP 伺服器

探索可用的伺服器

新增 MCP 伺服器

列出已設定的伺服器

移除 MCP 伺服器

使用模擬工具伺服器進行測試

了解工具資訊清單

資訊清單結構

資訊清單參數

將工具整合到您的 Agent 中

列出工具伺服器 (選擇性)

向您的協調器註冊工具

選擇您的協調器擴充功能

實作範例

搭配 OpenAI 使用 Python

1. 新增匯入陳述式

2. 初始化工具服務

3. 向 OpenAI Agent 註冊 MCP 工具

方法參數

4. 在初始化期間呼叫

其他存取 Agent 365 MCP 伺服器的方式

自備 (BYO) MCP 伺服器

測試您的 Agent

新增可觀察性

疑難排解​​

MCP 伺服器和工具問題

意見反應

其他資源

疑難排解