Phase 14 - Lesson 16

OpenAI Agents SDK: Handoffs, Guardrails, Tracing

O OpenAI Agents SDK é o framework multiagente leve construído sobre a Responses API. Cinco primitivos: Agent, Handoff, Guardrail, Session, Tracing. Handoffs são ferramentas chamadas transfer_to_<agent>. Guardrails são acionados na entrada ou na saída. Tracing está ativado por padrão.

Tipo: Aprender + Construir Linguagens: Python (stdlib) Pré-requisitos: Fase 14 · 01 (Loop de Agente), Fase 14 · 06 (Uso de Ferramentas) Tempo: ~75 minutos

Objetivos de Aprendizado

• Nomear os cinco primitivos do OpenAI Agents SDK.
• Explicar handoffs: por que eles são modelados como ferramentas, qual o formato do nome que o modelo vê e como o contexto é transferido.
• Distinguir guardrails de entrada, guardrails de saída e guardrails de ferramenta; explicar run_in_parallel vs modo de bloqueio.
• Implementar um runtime da stdlib com handoffs + guardrails + rastreamento no estilo span.

O Problema

Agentes que não conseguem delegar de forma limpa acabam colocando tudo em um único prompt. Agentes sem guardrails enviam informações de identificação pessoal (PII), saídas que violam políticas ou entram em loop infinito. O SDK da OpenAI codifica os três primitivos que tornam o trabalho multiagente tratável.

O Conceito

Cinco primitivos

1. Agent. LLM + instruções + ferramentas + handoffs.
2. Handoff. Delegação para outro agente. Representado para o modelo como uma ferramenta chamada transfer_to_<agent_name>.
3. Guardrail. Validação na entrada (apenas no primeiro agente), na saída (apenas no último agente) ou na invocação de ferramenta (por ferramenta de função).
4. Session. Histórico de conversa automático entre interações.
5. Tracing. Spans integrados para gerações de LLM, chamadas de ferramentas, handoffs e guardrails.

Handoffs como ferramentas

O modelo vê transfer_to_billing_agent em sua lista de ferramentas. Chamá-lo sinaliza ao runtime para:

1. Copiar o contexto da conversa (ou colapsá-lo via beta do nest_handoff_history).
2. Inicializar o agente de destino com suas instruções.
3. Continuar a execução com o agente de destino.

Este é o padrão supervisor (Lição 13 / Lição 28) transformado em produto.

Guardrails

Três tipos:

• Input guardrails. Executam na entrada do primeiro agente. Rejeitam solicitações inseguras ou fora do escopo antes de qualquer chamada de LLM.
• Output guardrails. Executam na saída do último agente. Capturam vazamentos de PII, violações de políticas e respostas malformadas.
• Tool guardrails. Executam por ferramenta de função. Validam argumentos, verificam permissões e auditam a execução.

Modos:

• Parallel (padrão). O LLM do guardrail executa ao lado do LLM principal. Menor latência de cauda. Se for acionado, o trabalho do LLM principal é descartado (desperdício de tokens).
• Blocking (run_in_parallel=False). O LLM do guardrail executa primeiro. Se for acionado, nenhum token é desperdiçado na chamada principal.

Os tripwires geram InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered.

Tracing

Ativado por padrão. Cada geração de LLM, chamada de ferramenta, handoff e guardrail emite um span. OPENAI_AGENTS_DISABLE_TRACING=1 desativa o recurso. add_trace_processor(processor) envia spans para seu próprio backend junto com o da OpenAI.

Sessions

A Session armazena o histórico da conversa em um backend (SQLite, Redis, personalizado). Runner.run(agent, input, session=session) carrega e anexa automaticamente.

Onde este padrão falha

• Handoff drift. O Agente A passa para o Agente B, que passa de volta para o Agente A. Adicione um contador de saltos.
• Guardrail bypass. Os guardrails de ferramenta só são acionados em ferramentas de função; ferramentas nativas (leitor de arquivos, busca na web) precisam de uma política separada.
• Over-tracing. Conteúdo sensível nos spans. Combine com as regras de captura de conteúdo do OTel GenAI (Lição 23) — armazene externamente e referencie por ID.

Construa

O arquivo code/main.py implementa a estrutura do SDK na stdlib:

• Agent, FunctionTool, Handoff (como uma ferramenta de função com semântica de transferência).
• Runner com guardrails de entrada/saída/ferramenta, despacho de handoff e contador de saltos.
• Um emissor simples de span para mostrar o formato do trace.
• Um agente de triagem que passa a tarefa para faturamento ou suporte com base na consulta do usuário; o guardrail é acionado em uma das entradas.

Execute-o:

python3 code/main.py

O trace mostra dois handoffs bem-sucedidos, um acionamento de guardrail de entrada e uma árvore de spans espelhando o que o SDK real emite.

Use

• OpenAI Agents SDK para produtos focados em OpenAI.
• Claude Agent SDK (Lição 17) para produtos focados em Claude.
• LangGraph (Lição 13) quando você deseja um estado explícito e retomada durável.
• Custom quando você precisa de controle exato (voz, multi-provedor, implantações federadas).

Envie para Produção

O arquivo outputs/skill-agents-sdk-scaffold.md estrutura um aplicativo do Agents SDK com um agente de triagem, handoffs, guardrails de entrada/saída/ferramenta, armazenamento de sessão e um processador de trace.

Exercícios

1. Adicione um contador de saltos para o handoff: recuse após N transferências. Rastreie o comportamento.
2. Implemente nest_handoff_history como uma opção — colapse mensagens anteriores em um único resumo antes de transferir.
3. Escreva um guardrail de saída bloqueante. Compare a latência em prompts que o acionariam em relação aos que passam.
4. Conecte o add_trace_processor a um registrador JSON. Qual formato ele emite por span?
5. Leia a documentação do SDK. Porte o seu protótipo da stdlib para openai-agents-python. O que você modelou de forma incorreta?

Termos-Chave

Leituras Adicionais

• OpenAI Agents SDK docs — primitivos, handoffs, guardrails, tracing
• Claude Agent SDK overview — equivalente na versão Claude
• Anthropic, Building Effective Agents — quando realmente utilizar handoffs
• OpenTelemetry GenAI semantic conventions — o padrão para o qual os spans do Agents SDK são mapeados