McpToolRegistrationService Classe

Serviço para gerenciar ferramentas e servidores MCP para um agente

Construtor

McpToolRegistrationService()

Parâmetros

Nome Description
logger
Valor padrão: None

Métodos

__init__

Inicialize o Serviço de Registro da Ferramenta MCP para OpenAI.
__new__
add_tool_servers_to_agent

Adicione novos servidores MCP ao agente criando uma nova instância do Agente.

Observação: devido às limitações do SDK do OpenAI Agents, os servidores MCP devem ser definidos durante a criação do Agente. Se novos servidores forem encontrados, esse método criará uma nova instância do Agente com todos os servidores MCP (existentes + novos) inicializados corretamente.
cleanup_all_servers

Limpar todos os servidores MCP conectados
send_chat_history

Extraia o histórico de chat de uma Sessão OpenAI e envie-o para a plataforma MCP.

Esse método extrai mensagens de um objeto OpenAI Session usando get_items() e as envia para a plataforma MCP para proteção contra ameaças em tempo real.
send_chat_history_messages

Envie mensagens de histórico de chat do OpenAI para a plataforma MCP para proteção contra ameaças.

Esse método aceita uma lista de mensagens TResponseInputItem do OpenAI, as converte no formato ChatHistoryMessage e as envia para a plataforma MCP.

Note

Mesmo se as mensagens estiverem vazias ou todas as mensagens forem filtradas durante a conversão,

a solicitação ainda será enviada para a plataforma MCP. Isso garante que o usuário

a mensagem de turn_context.activity.text é registrada corretamente para

proteção contra ameaças em tempo real.

__init__

Inicialize o Serviço de Registro da Ferramenta MCP para OpenAI.

__init__(logger: Logger | None = None)

Parâmetros

Nome Description
logger
Logger | None

Instância do agente para operações de registro em log.

Valor padrão: None

__new__ 

__new__(**kwargs)

add_tool_servers_to_agent

Adicione novos servidores MCP ao agente criando uma nova instância do Agente.

Observação: devido às limitações do SDK do OpenAI Agents, os servidores MCP devem ser definidos durante a criação do Agente. Se novos servidores forem encontrados, esse método criará uma nova instância do Agente com todos os servidores MCP (existentes + novos) inicializados corretamente.

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

Parâmetros

Nome Description
agent
Obrigatório
<xref:agents.agent.Agent>

O agente existente ao qual adicionar servidores
auth
Obrigatório
Authorization

Manipulador de autorização para troca de token.
auth_handler_name
Obrigatório
str

Nome do manipulador de autorização.
context
Obrigatório
TurnContext

Transforme o contexto da operação atual.
auth_token
str | None

Token de autenticação para acessar os servidores MCP.

Valor padrão: None

Retornos

Tipo Description
<xref:agents.agent.Agent>

Nova instância do Agente com todos os servidores MCP ou agente original se nenhum novo servidor

cleanup_all_servers

Limpar todos os servidores MCP conectados

async cleanup_all_servers() -> None

Retornos

Tipo Description
None

send_chat_history

Extraia o histórico de chat de uma Sessão OpenAI e envie-o para a plataforma MCP.

Esse método extrai mensagens de um objeto OpenAI Session usando get_items() e as envia para a plataforma MCP para proteção contra ameaças em tempo real.

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

Parâmetros

Nome Description
turn_context
Obrigatório
TurnContext

TurnContext do SDK de Agentes que contém informações de conversa. Deve ter uma atividade válida com conversation.id, activity.id e activity.text.
session
Obrigatório
<xref:agents.memory.session.Session>

Instância de Sessão OpenAI da qual extrair mensagens. Deve dar suporte ao método get_items() que retorna uma lista de TResponseInputItem.
limit
int | None

Número máximo opcional de itens a serem recuperados da sessão. Se Nenhum, recuperará todos os itens.

Valor padrão: None
options
ToolOptions | None

ToolOptions opcionais para personalização. Se não for fornecido, usará opções padrão com orchestrator_name="OpenAI".

Valor padrão: None

Retornos

Tipo Description
OperationResult

OperationResult indicando êxito ou falha. Com êxito, retorna OperationResult.success(). Em caso de falha, retorna OperationResult.failed() com detalhes de erro.

Exceções

Tipo Description
ValueError

Se turn_context for Nenhum ou sessão for None.

Exemplos


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

Envie mensagens de histórico de chat do OpenAI para a plataforma MCP para proteção contra ameaças.

Esse método aceita uma lista de mensagens TResponseInputItem do OpenAI, as converte no formato ChatHistoryMessage e as envia para a plataforma MCP.

Note

Mesmo se as mensagens estiverem vazias ou todas as mensagens forem filtradas durante a conversão,

a solicitação ainda será enviada para a plataforma MCP. Isso garante que o usuário

a mensagem de turn_context.activity.text é registrada corretamente para

proteção contra ameaças em tempo real.

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

Parâmetros

Nome Description
turn_context
Obrigatório
TurnContext

TurnContext do SDK de Agentes que contém informações de conversa. Deve ter uma atividade válida com conversation.id, activity.id e activity.text.
messages
Obrigatório
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_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.ItemReference>]

Lista de mensagens do OpenAI TResponseInputItem a serem enviadas. Dá suporte a UserMessage, AssistantMessage, SystemMessage e outros tipos de mensagem OpenAI. Pode estar vazio – a solicitação ainda será enviada para registrar a mensagem de usuário de turn_context.activity.text.
options
ToolOptions | None

ToolOptions opcionais para personalização. Se não for fornecido, usará opções padrão com orchestrator_name="OpenAI".

Valor padrão: None

Retornos

Tipo Description
OperationResult

OperationResult indicando êxito ou falha. Com êxito, retorna OperationResult.success(). Em caso de falha, retorna OperationResult.failed() com detalhes de erro.

Exceções

Tipo Description
ValueError

Se turn_context for Nenhum ou mensagens for Nenhum.

Exemplos


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