McpToolRegistrationService 類別

管理代理的 MCP 工具與伺服器的服務

建構函式

McpToolRegistrationService()

參數

名稱 Description
logger
預設值: None

方法

__init__

初始化 OpenAI 的 MCP 工具註冊服務。
__new__
add_tool_servers_to_agent

透過建立新的代理實例，新增 MCP 伺服器到代理程式。

注意：由於 OpenAI Agents SDK 的限制，MCP 伺服器必須在建立代理時設定。 若發現新伺服器，此方法會建立一個新的代理實例，所有 MCP 伺服器（現有 + 新伺服器）均已正確初始化。
cleanup_all_servers

清理所有連接的 MCP 伺服器
send_chat_history

從 OpenAI 會話中擷取聊天歷史並傳送到 MCP 平台。

此方法利用 get_items（） 從 OpenAI 會話物件擷取訊息，並傳送至 MCP 平台以進行即時威脅防護。
send_chat_history_messages

將 OpenAI 聊天記錄訊息發送到 MCP 平台以進行威脅防護。

此方法接受 OpenAI TResponseInputItem 訊息清單，將其轉換為 ChatHistoryMessage 格式，並傳送至 MCP 平台。

Note

即使訊息為空或所有訊息在轉換過程中都被過濾，

請求仍會送達 MCP 平台。 這確保使用者

來自 turn_context.activity.text 的訊息已正確註冊為

即時威脅防護。

__init__

初始化 OpenAI 的 MCP 工具註冊服務。

__init__(logger: Logger | None = None)

參數

名稱 Description
logger
Logger | None

用於日誌作業的記錄器實例。

預設值: None

__new__ 

__new__(**kwargs)

add_tool_servers_to_agent

透過建立新的代理實例，新增 MCP 伺服器到代理程式。

注意：由於 OpenAI Agents SDK 的限制，MCP 伺服器必須在建立代理時設定。 若發現新伺服器，此方法會建立一個新的代理實例，所有 MCP 伺服器（現有 + 新伺服器）均已正確初始化。

async add_tool_servers_to_agent(agent: Agent, auth: Authorization, auth_handler_name: str, context: TurnContext, auth_token: str | None = None) -> Agent

參數

名稱 Description
agent
必要
<xref:agents.agent.Agent>

現有代理程式，用來新增伺服器
auth
必要
Authorization

用於代幣交換的授權處理程序。
auth_handler_name
必要
str

授權處理者的名字。
context
必要
TurnContext

請說明當前行動的背景。
auth_token
str | None

使用認證令牌來存取 MCP 伺服器。

預設值: None

傳回

類型 Description
<xref:agents.agent.Agent>

新代理實例包含所有 MCP 伺服器，或若無新伺服器則使用原始代理

cleanup_all_servers

清理所有連接的 MCP 伺服器

async cleanup_all_servers() -> None

傳回

類型 Description
None

send_chat_history

從 OpenAI 會話中擷取聊天歷史並傳送到 MCP 平台。

此方法利用 get_items（） 從 OpenAI 會話物件擷取訊息，並傳送至 MCP 平台以進行即時威脅防護。

async send_chat_history(turn_context: TurnContext, session: Session, limit: int | None = None, options: ToolOptions | None = None) -> OperationResult

參數

名稱 Description
turn_context
必要
TurnContext

來自 Agents SDK 的 TurnContext，包含對話資訊。 必須有有效的活動，包含 conversation.id、activity.id 和 activity.text。
session
必要
<xref:agents.memory.session.Session>

OpenAI 會話實例用來擷取訊息。 必須支援 get_items（） 方法，該方法會回傳 TResponseInputItem 的清單。
limit
int | None

可選地設定從遊戲中取回的物品數量上限。 若無，則取回所有物品。

預設值: None
options
ToolOptions | None

可選工具選項可自訂。 若未提供，則使用預設選項，orchestrator_name=“OpenAI”。

預設值: None

傳回

類型 Description
OperationResult

OperationResult 表示成功或失敗。 成功後，回傳 OperationResult.success（）。 失敗時，回傳 OperationResult.failed（） 並附有錯誤細節。

例外狀況

類型 Description
ValueError

如果turn_context是無，或是會話是無。

範例


>>> from agents import Agent, Runner
>>> from microsoft_agents_a365.tooling.extensions.openai import (
...     McpToolRegistrationService
... )
>>>
>>> service = McpToolRegistrationService()
>>> agent = Agent(name="my-agent", model="gpt-4")
>>>
>>> # In your agent handler:
>>> async with Runner.run(agent, messages) as result:
...     session = result.session
...     op_result = await service.send_chat_history(
...         turn_context, session
...     )
...     if op_result.succeeded:
...         print("Chat history sent successfully")

send_chat_history_messages

將 OpenAI 聊天記錄訊息發送到 MCP 平台以進行威脅防護。

此方法接受 OpenAI TResponseInputItem 訊息清單，將其轉換為 ChatHistoryMessage 格式，並傳送至 MCP 平台。

Note

即使訊息為空或所有訊息在轉換過程中都被過濾，

請求仍會送達 MCP 平台。 這確保使用者

來自 turn_context.activity.text 的訊息已正確註冊為

即時威脅防護。

async send_chat_history_messages(turn_context: TurnContext, messages: List[EasyInputMessageParam | Message | ResponseOutputMessageParam | ResponseFileSearchToolCallParam | ResponseComputerToolCallParam | ComputerCallOutput | ResponseFunctionWebSearchParam | ResponseFunctionToolCallParam | FunctionCallOutput | ToolSearchCall | ResponseToolSearchOutputItemParamParam | AdditionalTools | ResponseConfigurationUpdateItemParamParam | ResponseReasoningItemParam | ResponseCompactionItemParamParam | ImageGenerationCall | ResponseCodeInterpreterToolCallParam | LocalShellCall | LocalShellCallOutput | ShellCall | ShellCallOutput | ApplyPatchCall | ApplyPatchCallOutput | McpListTools | McpApprovalRequest | McpApprovalResponse | McpCall | ResponseCustomToolCallOutputParam | ResponseCustomToolCallParam | CompactionTrigger | ItemReference | Program | ProgramOutput], options: ToolOptions | None = None) -> OperationResult

參數

名稱 Description
turn_context
必要
TurnContext

來自 Agents SDK 的 TurnContext，包含對話資訊。 必須有有效的活動，包含 conversation.id、activity.id 和 activity.text。
messages
必要
List[<xref:openai.types.responses.easy_input_message_param.EasyInputMessageParam> | <xref:openai.types.responses.response_input_item_param.Message> | <xref:openai.types.responses.response_output_message_param.ResponseOutputMessageParam> | <xref:openai.types.responses.response_file_search_tool_call_param.ResponseFileSearchToolCallParam> | <xref:openai.types.responses.response_computer_tool_call_param.ResponseComputerToolCallParam> | <xref:openai.types.responses.response_input_item_param.ComputerCallOutput> | <xref:openai.types.responses.response_function_web_search_param.ResponseFunctionWebSearchParam> | <xref:openai.types.responses.response_function_tool_call_param.ResponseFunctionToolCallParam> | <xref:openai.types.responses.response_input_item_param.FunctionCallOutput> | <xref:openai.types.responses.response_input_item_param.ToolSearchCall> | <xref:openai.types.responses.response_tool_search_output_item_param_param.ResponseToolSearchOutputItemParamParam> | <xref:openai.types.responses.response_input_item_param.AdditionalTools> | <xref:openai.types.responses.response_configuration_update_item_param_param.ResponseConfigurationUpdateItemParamParam> | <xref:openai.types.responses.response_reasoning_item_param.ResponseReasoningItemParam> | <xref:openai.types.responses.response_compaction_item_param_param.ResponseCompactionItemParamParam> | <xref:openai.types.responses.response_input_item_param.ImageGenerationCall> | <xref:openai.types.responses.response_code_interpreter_tool_call_param.ResponseCodeInterpreterToolCallParam> | <xref:openai.types.responses.response_input_item_param.LocalShellCall> | <xref:openai.types.responses.response_input_item_param.LocalShellCallOutput> | <xref:openai.types.responses.response_input_item_param.ShellCall> | <xref:openai.types.responses.response_input_item_param.ShellCallOutput> | <xref:openai.types.responses.response_input_item_param.ApplyPatchCall> | <xref:openai.types.responses.response_input_item_param.ApplyPatchCallOutput> | <xref:openai.types.responses.response_input_item_param.McpListTools> | <xref:openai.types.responses.response_input_item_param.McpApprovalRequest> | <xref:openai.types.responses.response_input_item_param.McpApprovalResponse> | <xref:openai.types.responses.response_input_item_param.McpCall> | <xref:openai.types.responses.response_custom_tool_call_output_param.ResponseCustomToolCallOutputParam> | <xref:openai.types.responses.response_custom_tool_call_param.ResponseCustomToolCallParam> | <xref:openai.types.responses.response_input_item_param.CompactionTrigger> | <xref:openai.types.responses.response_input_item_param.ItemReference> | <xref:openai.types.responses.response_input_item_param.Program> | <xref:openai.types.responses.response_input_item_param.ProgramOutput>]

OpenAI TResponseInputItem 訊息清單。 支援 UserMessage、AssistantMessage、SystemMessage 及其他 OpenAI 訊息類型。 可以是空的——請求仍會被發送，以註冊來自 turn_context.activity.text 的使用者訊息。
options
ToolOptions | None

可選工具選項可自訂。 若未提供，則使用預設選項，orchestrator_name=“OpenAI”。

預設值: None

傳回

類型 Description
OperationResult

OperationResult 表示成功或失敗。 成功後，回傳 OperationResult.success（）。 失敗時，回傳 OperationResult.failed（） 並附有錯誤細節。

例外狀況

類型 Description
ValueError

如果turn_context是 None 或訊息是 None。

範例


>>> from microsoft_agents_a365.tooling.extensions.openai import (
...     McpToolRegistrationService
... )
>>>
>>> service = McpToolRegistrationService()
>>> messages = [
...     {"role": "user", "content": "Hello"},
...     {"role": "assistant", "content": "Hi there!"},
... ]
>>>
>>> result = await service.send_chat_history_messages(
...     turn_context, messages
... )
>>> if result.succeeded:
...     print("Chat history sent successfully")