McpToolServerConfigurationService 類別

提供 MCP 工具伺服器組態管理服務。

此服務處理來自多個來源的 MCP（模型情境協定）工具伺服器的發現與配置：

  • 開發：本地 ToolingManifest.json 檔案
  • 生產環境：遠端工具閘道端點

建構函式

McpToolServerConfigurationService()

參數

名稱 Description
logger
預設值: None

方法

__init__

初始化 MCP 工具伺服器設定服務。
__new__
list_tool_servers

取得為該代理配置的 MCP 伺服器清單。

當 authorization、 auth_handler_name、 turn_context 全部提供時，發現後會為每台伺服器取得每台受眾的 OAuth 代幣：

  • V1 伺服器（無 audience 欄位）共用 ATG 令牌（單一交換機）。
  • V2 伺服器各自獲得一個屬於其受眾 GUID 的令牌。
send_chat_history

將聊天紀錄傳送至 MCP 平台，以提供即時威脅防護。

Note

即使chat_history_messages是空的，請求仍會被送往

MCP 平台。 這確保使用者訊息來自 turn_context.activity.text

已正確註冊以提供即時威脅防護。

__init__

初始化 MCP 工具伺服器設定服務。

__init__(logger: Logger | None = None)

參數

名稱 Description
logger
Logger | None

用於日誌作業的記錄器實例。 若為 N，則建立新的記錄器。

預設值: None

__new__ 

__new__(**kwargs)

list_tool_servers

取得為該代理配置的 MCP 伺服器清單。

當 authorization、 auth_handler_name、 turn_context 全部提供時，發現後會為每台伺服器取得每台受眾的 OAuth 代幣：

  • V1 伺服器（無 audience 欄位）共用 ATG 令牌（單一交換機）。
  • V2 伺服器各自獲得一個屬於其受眾 GUID 的令牌。
async list_tool_servers(agentic_app_id: str, auth_token: str | None = None, options: ToolOptions | None = None, authorization: Authorization | None = None, auth_handler_name: str | None = None, turn_context: TurnContext | None = None) -> List[MCPServerConfig]

參數

名稱 Description
agentic_app_id
必要
str

代理人的代理應用程式 ID。
auth_token
str | None

用於閘道偵測的認證令牌。

預設值: None
options
ToolOptions | None

包含可選參數的 ToolOptions 實例。

預設值: None
authorization
Authorization | None

可選的授權上下文用於每受眾的令牌交換。

預設值: None
auth_handler_name
str | None

可選的認證處理名稱，搭配 authorization。

預設值: None
turn_context
TurnContext | None

可選的 TurnContext 搭配 authorization使用。

預設值: None

傳回

類型 Description
List[MCPServerConfig]

回傳已設定的 MCP 伺服器清單，每台在提供認證上下文時都會附加標 Authorization 頭。

例外狀況

類型 Description
ValueError

若所需參數為無效或為空。
Exception

如果與工具閘道溝通出錯，或是逐受眾的代幣交換失敗。

send_chat_history

將聊天紀錄傳送至 MCP 平台，以提供即時威脅防護。

Note

即使chat_history_messages是空的，請求仍會被送往

MCP 平台。 這確保使用者訊息來自 turn_context.activity.text

已正確註冊以提供即時威脅防護。

async send_chat_history(turn_context: TurnContext, chat_history_messages: List[ChatHistoryMessage], options: ToolOptions | None = None) -> OperationResult

參數

名稱 Description
turn_context
必要
TurnContext

來自 Agents SDK 的 TurnContext，包含對話資訊。 必須有有效的活動，包含 conversation.id、activity.id 和 activity.text。
chat_history_messages
必要
List[ChatHistoryMessage]

代表聊天歷史的 ChatHistoryMessage 物件列表。 可能是空的——空列表仍會向 MCP 平台發送請求，聊天紀錄為空。
options
ToolOptions | None

包含可選參數的 ToolOptions 實例。

預設值: None

傳回

類型 Description
<xref:OperationResult>

一個表示成功或失敗的操作結果。 成功後，回傳 OperationResult.success（）。 失敗時，回傳 OperationResult.failed（） 並附有錯誤細節。

例外狀況

類型 Description
ValueError

如果 turn_context 為 None，chat_history_messages 為 None，turn_context.activity 為 None，或任何必填欄位（conversation.id、activity.id、activity.text）缺失或為空。

範例


>>> from datetime import datetime, timezone
>>> from microsoft_agents_a365.tooling.models import ChatHistoryMessage
>>>
>>> history = [
...     ChatHistoryMessage("msg-1", "user", "Hello", datetime.now(timezone.utc)),
...     ChatHistoryMessage("msg-2", "assistant", "Hi!", datetime.now(timezone.utc))
... ]
>>>
>>> service = McpToolServerConfigurationService()
>>> result = await service.send_chat_history(turn_context, history)
>>> if result.succeeded:
...     print("Chat history sent successfully")