Agentes OpenAI do SDK do mecanismo do agente

Construindo um agente

Para começar a partir de um projeto de trabalho, execute agentengine create e escolha a variante OpenAI Agents SDK do agente Olá, Mundo ouHuman-in-the-Loop(--template hello-world-agent-openai ou --template insurance-agent-openai).

from agents import Agent, ModelSettingsfrom agent_engine_sdk_openai_agents import App
app = App(app_name="support")

@app.tool()def lookup_order(order_id: str) -> str:    """Look up an order."""    ...

@app.entrypointdef build() -> Agent:    return Agent(        name="support",        instructions="Help with orders.",        model=app.llm("gpt-4.1", settings=ModelSettings(temperature=0)),        tools=app.tools(),    )

Usar o modelo gerado por app.llm(...) e as ferramentas geradas por app.tools(); qualquer outra coisa falha na curva antes de qualquer modelo ou ferramenta funcionar. Passe um agents.Model configurado para app.llm para usar um cliente OpenAI personalizado. Os parâmetros da ferramenta devem ser valores JSON que podem ser passados por nome (nenhum parâmetro somente posicional ou *args, e nenhum nomeado tool_call_id), porque as ferramentas remotas recebem seus argumentos como valores JSON nomeados. Definir o tempo limite de uma ferramenta com @app.tool(timeout=...); um timeout_seconds nativo em uma ferramenta emitida falha na curva. Um resultado de ferramenta que não seja string, incluindo modelos aninhados, classes de dados, enums e data/hora, chega ao modelo como texto JSON. O texto é canônico, portanto, um lance repetido envia ao modelo o mesmo texto: as chaves são classificadas e um flutuador de número inteiro como 164.0 é escrito 164. Um número inteiro além de 2**53 no resultado de uma ferramenta falha na chamada e em seus argumentos falha na vez, porque o registro durável não pode mantê-lo exatamente; passar um valor como uma string.

Cada invocação executa um Runner nativo e o confirma no Mecanismo de Orquestração antes de retornar o resultado. Uma ferramenta que aumenta é relatada ao modelo como o SDK do OpenAI Agents faz por padrão, com o texto do default_tool_error_function do SDK instalado, e a vez continua. Lançamentos anteriores a 0.23 incluem a mensagem de erro da ferramenta nesse texto; versões posteriores enviam uma mensagem fixa sem ele. O Mecanismo de Orquestração registra a falha, de modo que uma jogada repetida envia ao modelo o mesmo texto. Uma chamada que a plataforma interrompe ou falha, em vez disso, falha na vez com o erro que seu caminho da ferramenta relata: uma negação de política, uma chamada cancelada ou interrompida pelo usuário ou uma falha da plataforma, como o mecanismo de orquestração que não reconhece o resultado de uma ferramenta. Uma falha de plataforma nunca é relatada ao modelo como uma ferramenta com falha, pois a ferramenta pode já ter sido executada. Nestes casos, nada é confirmado. Uma exceção permanece: quando o Mecanismo de Orquestração não consegue acessar o Pod de Ferramentas de uma ferramenta remota, ele registra a falha como da própria ferramenta, para que o modelo seja informado de que a ferramenta falhou. Quando o modelo chama várias ferramentas de uma só vez, elas são executadas simultaneamente. Cada chamada mantém a atividade do Mecanismo de Orquestração de seu ID de chamada, e seus resultados chegam ao modelo na ordem em que o modelo fez as chamadas, o que terminar primeiro. Se um deles aguardar a aprovação, as chamadas executadas antes da espera manterão suas saídas à frente das chamadas aprovadas, pois o SDK as registra. Quando uma chamada falha na vez, ela falha quando as chamadas que ainda estão sendo executadas ao lado dela terminam. Ganchos de agente, prompts hospedados, instruções dinâmicas e um tool_use_behavior personalizado ainda não são permitidos. As grades de proteção de entrada e saída do próprio agente são executadas conforme descrito em Grades de entrada e saída. As políticas de proteção de um projeto se aplicam a cada modelo e chamada de ferramenta; consulte as políticas da Guardrail.

Ferramentas de MCP

Liste um servidor MCP remoto em mcp.servers em agent.yaml, com as mesmas chaves que todo framework do Agent Engine usa. Suas ferramentas são descobertas quando o agente inicia e app.tools() as retorna ao lado das funções registradas, denominadas <server>__<tool>:

mcp:  servers:    atlas:      url: https://mcp.example.com/mcp      allowed_tools: [find]      auth:        type: bearer_env        token_env: ATLAS_MCP_TOKEN

auth nomeia a variável de ambiente que contém o token; o token em si pertence aos segredos do espaço de trabalho ou em .env para desenvolvimento local.

Uma chamada para uma dessas ferramentas é uma atividade de ferramenta do Mecanismo de Orquestramento como qualquer outra e é executada no Pod de Ferramentas, que contém as credenciais e o acesso à rede do servidor. allowed_tools limita quais das ferramentas do servidor o agente obtém. Uma chamada com falha ou um resultado de erro de MCP é relatado ao modelo como qualquer ferramenta com falha. Um resultado estruturado contendo um número inteiro igual ou superior a 2**53, que um registro durável não consegue manter exatamente, falha na vez; faça com que o servidor retorne esse valor como uma string.

Um servidor que não pode ser acessado quando o agente inicia impede que ele seja iniciado; timeout_seconds limita cada solicitação dessa descoberta, pois limita uma chamada.

Somente o tempo de execução do agente lista as ferramentas do servidor, quando ele é iniciado; o Pod de Ferramenta encontra o servidor para uma chamada de agent.yaml quando a chamada chega. O Pod de Ferramenta também executa o ponto de entrada, para registrar os modelos do agente, e lá app.tools() retorna apenas as funções registradas. Passe as ferramentas MCP para um agente sem procurá-las por nome, por exemplo [tool for tool in app.tools() if tool.name.startswith("atlas__")], para que o ponto de entrada seja baseado em ambos.

O próprio Agent.mcp_servers do SDK é recusado: o SDK chamaria o servidor do processo do agente, fora do Pod da Ferramenta. needs_approval em uma ferramenta MCP ainda não é suportado.

Transferências

Use o próprio handoffs=[...] do SDK, com outros agentes ou agents.handoff(...). O tempo de execução lê todo o gráfico do agente que o ponto de entrada retorna antes de cada vez e mantém todos os agente acessíveis nas mesmas regras do primeiro: seu modelo vem de app.llm(...) (dê a cada modelo de agente seu próprio llm_id) e suas ferramentas de app.tools(), a partir do qual cada agente pode selecionar o seu próprio nome. Os nomes dos agentes devem ser exclusivos.

Uma transferência altera o agente ativo; a vez permanece uma execução. O estado comprometido registra o agente ativo , portanto, o próximo turno, também após uma reinicialização, começa com o agente que encerrou o último. Uma aprovação solicitada por um agente transferido é suspensa e retomada nesse agente.

agents.handoff(...) may override the tool name and description. Agents may hand off to each other in a cycle. An input_filter, nest_handoff_history, an on_handoff callback, an input_type, a callable is_enabled, and a hand-built Handoff fail the turn before any model or tool work. So does a handoff on any agent whose tool name matches another handoff's or one of that agent's tools: the SDK would otherwise keep one and drop the other.

Agentes como ferramentas

Use the SDK's own Agent.as_tool(...) and put the result in another agent's tools. The nested agent follows the same rules as every other agent in the graph. Each call runs the nested agent as its own operation: its model and tool calls are Orchestration Engine activities under a path named after the tool, and repeated or concurrent calls to the same agent tool stay distinct, in the order the model made them.

O modelo do agente de chamada vê apenas a resposta da ferramenta e somente a conversa de chamada é confirmada; uma tentativa de substituição reproduz a execução aninhada de suas atividades registradas. O fluxo do chamador carrega o texto do agente aninhado entre os eventos subagent_start e subagent_end, marcado com o nome da ferramenta e a ID da chamada, além da resposta do agente de chamada. Uma execução aninhada que falha falha na curva.

Uma ferramenta que um agente aninhado usa pode precisar de aprovação, e o mesmo pode acontecer com a própria ferramenta do agente . A vez é suspensa como em qualquer outra aprovação e a espera é registrada no caminho do agente aninhado. Por um lado, as esperas do agente de chamada e dos agentes aninhados são respondidas juntas. As IDs de chamada de ferramenta devem ser exclusivas em um gráfico. Um agente aninhado que para para uma aprovação não envia subagent_end; o fluxo retomado o abre novamente com subagent_start antes do resto do texto e não envia novamente o texto que o chamador viu antes da espera.

max_turns, custom_output_extractor e entrada estruturada são suportados. Uma tentativa de substituição chama o extrator e o input_builder de uma entrada estruturada novamente, então ambos devem retornar o mesmo valor para a mesma entrada e não ter efeitos colaterais; OE falha na vez quando uma chamada de modelo reproduzida difere da gravada.

Um chamada de respostaon_stream, hooks, um run_config, um session, ids de continuação do provedor, um needs_approval ou is_enabled chamável, grades de proteção de ferramentas, grades de proteção de entrada ou saída no agente aninhado ou em um agente manual off, um timeout_seconds nativo e um agente que pode se alcançar por meio de sua própria ferramenta de agente falham na curva antes que qualquer modelo ou ferramenta funcione.

Aprovações

Registre uma ferramenta com @app.tool(needs_approval=True) para que uma pessoa aprove cada chamada. O argumento é o próprio function_tool(needs_approval=...) do SDK, passado para o FunctionTool que app.tools() retorna; definir needs_approval nessa ferramenta retornada também funciona. Quando o modelo chama uma ferramenta que precisa de aprovação, a vez suspende: a invocação retorna status: suspended com uma interrupção por chamada aguardando aprovação, na ordem em que o modelo fez as chamadas, cada uma nomeando a ferramenta e seus argumentos. As chamadas na mesma resposta que não precisam de aprovação são executadas primeiro. Retome por meio do endpoint de invocação normal na mesma sessão, com resume_map respondendo a cada ID de interrupção de uma só vez:

{"resume_map": {"<interrupt id>": {"confirmed": true}}}

interrupts lista cada aprovação pendente. suspend_payload carrega apenas o valor do primeiro, para chamadores que leem uma única carga útil.

{"confirmed": false, "rejection_message": "..."} rejeita a chamada; o modelo vê a mensagem de descarte em vez de um resultado de ferramenta, como no reject(..., rejection_message=...) do próprio SDK. Sem um rejection_message, o modelo vê o texto de exclusão padrão do SDK; um vazio é recusado. Uma aprovação não carrega nenhuma mensagem. O Mecanismo de orquestração registra a espera e sua resposta. A retomada reproduz a vez das chamadas de modelo registradas, aplica a resposta por meio do próprio RunStatedo SDK e executa apenas o restante, portanto, uma ferramenta nunca é executada antes de sua aprovação, a saída de prefixo não é repetida e uma reinicialização enquanto espera não perde nada. Uma retomada que deixa qualquer interrupção sem resposta é recusada; needs_approval deve ser True ou False, não é um callable.

Grades de proteção de entrada e saída

Declare as proteções em um agente como documentos do SDK, com input_guardrails e output_guardrails:

from agents import Agent, GuardrailFunctionOutput, Runner, input_guardrail

@app.entrypointdef build() -> Agent:    judge = Agent(        name="topic judge",        instructions="Answer yes if the message is about an order, else no.",        model=app.llm("gpt-4.1-mini", llm_id="judge"),    )
    @input_guardrail    async def on_topic(context, agent, input) -> GuardrailFunctionOutput:        verdict = await Runner.run(judge, input, context=context.context)        return GuardrailFunctionOutput(            output_info=None,            tripwire_triggered=verdict.final_output.strip().lower() != "yes",        )
    return Agent(        name="support",        model=app.llm("gpt-4.1"),        tools=app.tools(),        input_guardrails=[on_topic],    )

A guardrail that trips fails the turn as a policy denial: the execution ends with error_code policy_denied and the platform's own message for that class. The denial's reason names the guardrail and leaves out its output_info; it is in the runtime's log and in the metadata of the live stream's error event, not in the stored execution. The turn commits nothing, so the conversation continues from the turn before it. Tools the turn already ran are not undone.

Como a negação nomeia a proteção, cada proteção precisa de um nome. Um declarado com @input_guardrail ou @output_guardrail, ou construído a partir de uma função, usa o da função; um construído a partir de um functools.partial ou de um objeto que pode ser chamado não tem nenhum, então passe name=. Uma proteção sem nome é recusada antes de qualquer chamada de modelo.

Três coisas diferem do próprio Runner do SDK:

• As proteções de entrada terminam antes da primeira chamada de modelo. O padrão do SDK, run_in_parallel=True, inicia-os ao lado da chamada de modelo, que é então feita e paga, independentemente de um guard-rail disparar ou não. Aqui run_in_parallel não tem efeito.

• As grades de proteção de um agente são executadas uma de cada vez, na ordem em que o agente as lista, e as grades de proteção após uma viagem não são executadas. O SDK os inicia juntos.

• Um agente com grades de proteção de saída não transmite seu texto. O SDK transmite uma resposta antes que os guardas de saída a vejam e retém apenas o valor final da execução. Aqui, o chamador recebe a resposta inteira, no resultado da vez, assim que as grades de proteção passarem. Os agentes sem proteção de saída transmitem como antes.

Como no SDK, as guardas de entrada pertencem ao agente que inicia a conversa até agora com a nova mensagem; as guardrails de saída pertencem ao agente que dá a resposta final da vez. Depois de uma transferência, o agente entregue a ele inicia os seguintes retornos, para que suas proteções de entrada os verifiquem.

A replacement attempt runs the turn again from its start, guardrails included, and a turn that waits for an approval runs them again when it resumes. A guardrail must therefore return the same verdict for the same input and change nothing outside the process. A guardrail that asks a model does so through an agent whose model comes from app.llm(...), called while the entrypoint builds the app, as judge is above: the judge's model call is then an Orchestration Engine activity under the project's policies, and a replay returns its recorded response instead of asking again. The run needs context=context.context, which carries the turn. A judge with a plain model name has no provider credentials in the runtime and fails the turn. Tools, approvals, and handoffs in a judge agent are not qualified. A project policy that holds a judge's response for review fails the turn: only an agent of the app's graph can wait for a reviewer. A guardrail that calls an outside service directly is not supported: the call would be made again on every replay, outside the platform's network policy.

As grades de proteção de ferramentas e as grades de proteção em um agente usado como ferramenta ainda não são permitidas.

Políticas de guardrail

As políticas de proteção de um projeto são aplicadas pelo Mecanismo de Orquestração em cada modelo e chamada de ferramenta, incluindo as de um agente usado como ferramenta, e não precisam de código de aplicação . Uma política que registra, edita ou bloqueia alterações apenas o que a chamada retorna.

Uma política que exige a revisão de uma resposta de modelo suspende a vez como uma aprovação: a resposta é retida e a invocação retorna status: suspended com uma interrupção cujo valor nomeia a revisão em guardrail_review. Ele espera ao lado de qualquer aprovação de ferramenta do mesmo lado e um resume_map responde juntos:

{"resume_map": {"<interrupt id>": {"decision": "approve", "reviewer_notes": "checked"}}}

A aprovação libera a resposta retida, incluindo as chamadas de ferramentas, sem outra chamada do fornecedor. Negar falha na curva e não libera nada. O Mecanismo de Orquestração mantém a resposta e registra a decisão; o adaptador nunca vê o texto retido antes de ser aprovado.

Para interromper o Runner, o adaptador fornece a cada agente uma ferramenta chamada agent_engine_guardrail_review, que nenhum modelo é oferecido. A parada não é conteúdo de conversa, portanto, nem uma chamada de modelo posterior nem o histórico comprometido a carregam. O resultado do próprio executor para uma execução ainda o lista, então um custom_output_extractor de um agente usado como ferramenta vê a chamada e sua saída vazia entre os itens dessa execução quando uma resposta desse agente foi revisada; eles nomeiam a revisão, nunca a resposta realizada. Cada avaliação ocupa um dos max_turns da execução. Uma ferramenta ou transferência com esse nome, ou uma resposta de modelo que a chama, falha na curva.

Memória

Com memory: true em agent.yaml, as ferramentas leem e escrevem na memória de longo prazo do projeto por meio de app.memory, a mesma máscara que os aplicativos LangGraph e ADK usam:

@app.tool()def remember_preference(preference: str) -> str:    """Remember how the customer likes to be contacted."""    result = app.memory.save_semantic(text=preference, label="contact_preference")    return "saved" if result.acknowledged else "not saved"

As chamadas feitas enquanto uma solicitação está em execução usam o usuário dessa solicitação. Uma escrita é ativa, e não uma atividade durável: se uma chamada de ferramenta for repetida após uma falha, sua escrita será executada novamente, portanto, prefira gravações que sejam seguras para repetir.

Estado durável

Cada volta confirmada armazena a lista de entrada completa do Corredor na propriedade de estado __agent_engine_openai_agents__ , juntamente com o aplicativo e a sessão à qual ele pertence e o nome do agente que encerrou a curva. O próximo passo continua dessa lista com esse agente. As mensagens confirmadas são uma projeção de campo explícito para leitores de histórico; eles não são lidos de volta.

Um leitor do histórico do mecanismo de orquestração vê essa projeção: mensagens de usuário e assistente, cada chamada de ferramenta e cada saída. Uma transferência e uma chamada para um agente usado como uma ferramenta aparecem como chamadas comuns com suas saídas. A própria conversa de um agente aninhado não está confirmada, portanto, não está no histórico; seu modelo e chamadas de ferramentas estão nos registros de atividades da execução.

Os itens suportados são mensagens de texto, chamadas de função e saídas de função de texto. As chamadas que uma resposta do modelo fez se reúnem, seguidas por exatamente uma saída por chamada antes de qualquer outra coisa. Qualquer outro item, qualquer estado que pertença a um aplicativo ou sessão diferente e um agente ativo que o aplicativo não tenha mais falha na curva antes do início do novo modelo ou ferramenta.

Sessões e ramificações

O estado comprometido do Mecanismo de Orquestração é o único armazenamento de conversas. O adaptador faz com que a Runner chame a si mesma com esse estado como entrada, para que os objetos Session do SDK não sejam usados e a continuação hospedada pelo provedor (previous_response_id, uma ID de conversa ou um prompt hospedado, se passado para o Corredor, para Agent.as_tool, ou em um modelo registrado extra_body ou extra_args) falha antes de qualquer modelo funcionar.

Uma ramificação é uma nova sessão que começa a partir do estado confirmado de outra sessão. Seu primeiro turno continua com a conversa da fonte e o agente ativo , confirma em sua própria sessão e não compartilha nada com a fonte posteriormente; as aprovações funcionam nele como em qualquer caminho. Uma conversa pode ser ramificada no final de uma volta concluída, porque o adaptador confirma uma vez por volta. A plataforma ramifica apenas a partir de uma etapa confirmada, portanto, uma espera por uma aprovação não oferece nada para ramificar até que ela seja concluída.

Criar uma ramificação é uma operação de plataforma, não de SDK. O adaptador não adiciona API de ramificação, e a ramificação de sessão do próprio SDK (AdvancedSQLiteSession.create_branch_from_turn) não está disponível, portanto, um aplicativo não pode ramificar sua própria conversa; a API de branch da plataforma faz.

Chamadas de modelo

Cada chamada de modelo que o Runner nativo faz se torna uma atividade LLM do Mecanismo de Orquestração. O modelo do agente responde a partir da atividade registrada e o próprio modelo é executado no Pod de Ferramentas. Uma tentativa de substituição reproduz a resposta registrada e fornece Runner itens de saída idênticos.

Somente as configurações por chamada que a plataforma carrega ultrapassam esse limite: max_tokens, top_p, frequency_penalty, presence_penalty, timeout, parallel_tool_calls, reasoning.effort, verbosity e um tool_choice nomeado . As configurações do fornecedor, como temperature, pertencem ao modelo que você registra e o Pod da Ferramenta as aplica. Um modelo registrado não pode carregar um campo tool_choice ou timeout (definidos no agente), ou extra_body / extra_args campos que fazem o provedor continuar uma conversa armazenada (previous_response_id, conversation, conversation_id , prompt) ou que substituem o que o adaptador cria para cada chamada (como tools, input, instructions ou o formato de saída) ou esse conjunto reasoning, reasoning_effort ou verbosity como campos brutos (use ModelSettings.reasoning e ModelSettings.verbosity). O rastreamento nativo, a continuação hospedada pelo fornecedor e as sequências de parada falham antes que a chamada seja enviada.