# OpenAI Agents SDK: Guia Definitivo para Agentes Leves

> Domine o OpenAI Agents SDK — o framework minimalista que substitui o Swarm com handoffs, guardrails e tracing nativo para agentes multi-agent em Python.

Source: https://agentify.ia.br/blog/openai-agents-sdk/

> **TL;DR** — O OpenAI Agents SDK é o sucessor de produção do Swarm: quatro primitivos (Agent, Runner, Handoffs, Guardrails), tracing embutido, suporte a MCP, e zero boilerplate para colocar múltiplos agentes conversando entre si. Se você já roda modelos OpenAI e precisa de delegação limpa entre especialistas, esse SDK é a menor distância entre a sua ideia e um sistema multi-agent funcionando. Instalou, definiu agentes, rodou. Sem grafos, sem YAML, sem cerimônia.

---

## Overview

### De Swarm a produção: a história de um experimento que vingou

Em outubro de 2024 a OpenAI soltou o Swarm — um repositório educacional, quase um brinquedo, que mostrava como orquestrar múltiplos agentes LLM em menos de 100 linhas de Python. A premissa era audaciosa na simplicidade: agentes são funções stateless que se passam o bastão. Sem grafos, sem DAGs, sem banco de estado. Só handoffs.

O problema? O Swarm carregava um disclaimer gigante: “experimental, educational, not production-ready”. E não mentia. Faltava tratamento de erro, tracing, guardrails, persistência de sessão — tudo que você precisa quando sai do Jupyter notebook e vai pra produção.

Em março de 2025, a OpenAI arquivou o repositório do Swarm e redirecionou todo mundo pro [OpenAI Agents SDK](https://github.com/openai/openai-agents-python). Mesma filosofia minimalista, mesma API enxuta — mas agora com a robustez que faltava. O README do Swarm é explícito: “Swarm is now replaced by the OpenAI Agents SDK, which is a production-ready evolution of Swarm.”

E em abril de 2026 veio a evolução seguinte: sandbox agents, manifests para workspaces, integração com provedores de sandbox (E2B, Modal, Cloudflare, Vercel), memory configurável e skills nativas. O SDK deixou de ser “só um loop de agente” e virou um harness completo para agentes que mexem em arquivos, rodam comandos e trabalham em tarefas longas.

### Filosofia: minimalismo com opinião

O Agents SDK ocupa um ponto muito específico no stack. Não é uma API de modelo (isso é o Responses API). Não é uma plataforma managed (isso era o Agent Builder, que foi descontinuado). É um **runtime de agente** — uma biblioteca que gerencia o loop do agente, despacha tools, executa handoffs, roda guardrails e coleta traces.

A filosofia de design pode ser resumida em três princípios:

- **Poucos primitivos, bem compostos** — Agent, Runner, Handoffs, Guardrails. Você aprende em uma tarde.

- **O LLM decide** — o modelo escolhe quando usar tools e quando fazer handoff. O SDK não impõe fluxo.

- **Convenção sobre configuração** — tracing é automático, schemas são inferidos via Pydantic, tools se registram com um decorator.

Isso é radicalmente diferente do approach do [LangGraph](/blog/agent-frameworks-vs-coding-agents), que modela workflows como grafos dirigidos com nós e arestas explícitas. Aqui não existe grafo. Existe um agente que pode delegar pra outro. Ponto.

A pergunta que fica: quando essa simplicidade é suficiente — e quando vira limitação? Vamos descobrir.

---

## Tutorial

### Instalação

Python 3.9+ e um `pip install`:

```
pip install openai-agents
```

Pronto. Sem extra dependencies pesadas, sem compilação de extensões C. O pacote é leve de propósito — a OpenAI quer que você importe, use e não pense na infraestrutura.

Configure sua API key:

```
export OPENAI_API_KEY="sk-..."
```

### Primeiro agente: o clássico “Hello World”

```
from agents import Agent, Runner

agente = Agent(
 name="Assistente Geral",
 instructions="Você é um assistente técnico. Responda de forma concisa e direta.",
 model="gpt-4o-mini",
)

resultado = Runner.run_sync(agente, "O que é o Model Context Protocol?")
print(resultado.final_output)
```

Três linhas de setup, uma de execução. O `Runner.run_sync()` faz todo o trabalho pesado: monta o prompt com as instructions, chama o modelo, verifica se há tool calls, executa tools se necessário, e repete até ter uma resposta final.

A versão assíncrona é `await Runner.run()` — mesma interface, mas sem bloquear a event loop.

### Adicionando uma tool

Tools são funções Python decoradas:

```
from agents import Agent, Runner, function_tool

@function_tool
def buscar_clima(cidade: str) -> str:
 """Retorna a previsão do tempo para uma cidade."""
 # Em produção, chamaria uma API de clima
 return f"Em {cidade}: 22°C, parcialmente nublado."

agente = Agent(
 name="Agente Clima",
 instructions="Você ajuda usuários com informações de clima. Use a tool buscar_clima.",
 tools=[buscar_clima],
 model="gpt-4o-mini",
)

resultado = Runner.run_sync(agente, "Qual o clima em São Paulo?")
print(resultado.final_output)
```

O SDK usa `inspect` do Python pra extrair a assinatura da função e `pydantic` pra gerar o schema JSON automaticamente. Você não precisa declarar schemas manualmente — é a type hint que define tudo.

### Handoff entre dois agentes

Aqui é onde a coisa fica interessante. Vamos criar um sistema de triagem que delega para um especialista:

```
from agents import Agent, Runner

# Agente especialista em billing
agente_billing = Agent(
 name="Especialista Financeiro",
 instructions="""Você é especialista em questões financeiras.
 Ajuda com cobranças, faturas, reembolsos e métodos de pagamento.
 Seja direto e resolva o problema.""",
 model="gpt-4o-mini",
)

# Agente especialista em suporte técnico
agente_suporte = Agent(
 name="Suporte Técnico",
 instructions="""Você é especialista em suporte técnico.
 Ajuda com bugs, configurações, integrações e problemas de performance.""",
 model="gpt-4o-mini",
)

# Agente de triagem — decide pra quem delegar
agente_triagem = Agent(
 name="Triagem",
 instructions="""Você é o agente de triagem. Analise a mensagem do usuário e:
- Se for sobre cobrança, fatura ou pagamento → delegue para Especialista Financeiro
- Se for sobre bug, erro ou configuração → delegue para Suporte Técnico
- Se for genérico, responda você mesmo.""",
 handoffs=[agente_billing, agente_suporte],
 model="gpt-4o-mini",
)

# O usuário fala com triagem, que delega automaticamente
resultado = Runner.run_sync(
 agente_triagem,
 "Fui cobrado duas vezes na minha assinatura esse mês."
)
print(resultado.final_output)
```

O que acontece por baixo dos panos: o modelo do `agente_triagem` recebe a mensagem, identifica que é um problema financeiro, e emite um sinal de handoff para o `agente_billing`. O Runner intercepta esse sinal, transfere o controle, e o `agente_billing` recebe o contexto da conversa e responde. Tudo dentro de uma única chamada `Runner.run_sync()`.

Não precisou definir grafos, arestas, condições de roteamento explícitas. O LLM decidiu. Essa é a filosofia do SDK: **confia no modelo pra rotear, e valida com guardrails**.

---

## Deep Dive

### Agent — o descritor leve

Um `Agent` no SDK não é um processo rodando, não é um container, não é um servidor. É um **descritor**: um objeto Python que diz “esse agente tem essas instructions, essas tools, esse modelo, esses handoffs disponíveis”. Quem dá vida ao agente é o Runner.

Os parâmetros principais:

 Parâmetro
 O que faz

 name
 Identificador legível (aparece no tracing)

 instructions
 System prompt — a personalidade e regras do agente

 model
 Override de modelo por agente (cada agente pode usar um modelo diferente)

 tools
 Lista de function tools, hosted tools ou MCP servers

 handoffs
 Lista de outros Agents para os quais este pode delegar

 input_guardrails
 Validações que rodam na entrada do usuário

 output_guardrails
 Validações que rodam na saída do agente

 output_type
 Modelo Pydantic para structured output

Detalhe que eu acho elegante: como cada agente pode ter seu próprio `model`, você consegue montar arquiteturas onde o triagem usa um modelo barato e rápido (gpt-4o-mini) e o especialista usa um modelo pesado (gpt-4o ou gpt-5.4) só quando necessário. Economia de tokens na veia.

### Runner — o motor de execução

O Runner é o loop. Ele:

- Chama o LLM com as instructions do agente + histórico da conversa

- Se o LLM retorna tool calls → executa as tools

- Alimenta os resultados de volta ao LLM

- Se o LLM retorna um handoff → transfere controle pro agente-alvo

- Repete até ter output final ou atingir `max_turns`

```
from agents import Runner

# Síncrono
resultado = Runner.run_sync(agente, "mensagem do usuário")

# Assíncrono
resultado = await Runner.run(agente, "mensagem do usuário")

# Com configuração
from agents.run import RunConfig
resultado = await Runner.run(
 agente,
 "mensagem",
 run_config=RunConfig(max_turns=)
)
```

**Gotcha importante:** o default de `max_turns` é 10. Em workflows com múltiplos handoffs e tools, 10 turns acabam rápido. Cada handoff consome um turn, cada tool call + resposta consome dois. Três agentes com duas tools cada pode estourar fácil. Aumente o `max_turns` ou passe `None` pra desabilitar o limite.

### Handoffs — delegação entre agentes

Handoffs são o mecanismo multi-agent do SDK. Conceitualmente: um agente termina seu turno passando o bastão para outro agente. Na prática, funciona assim:

- O agente-fonte tem o agente-alvo na sua lista de `handoffs`

- O LLM do agente-fonte decide (via function calling) fazer o handoff

- O Runner detecta o sinal, reescreve o contexto da conversa, e passa o controle

O ponto-chave é a **reescrita de histórico**. Quando o agente B recebe o handoff do agente A, ele não vê necessariamente toda a conversa anterior. O SDK fornece filtros em `agents.extensions.handoff_filters` pra customizar o que o agente-alvo recebe.

Existem dois padrões de orquestração com handoffs:

**Padrão 1: Router (mais comum)**

```
Usuário → Triagem → [Billing | Suporte | Vendas]
```

**Padrão 2: Agent as Tool**

```
from agents import Agent, Runner, function_tool

agente_pesquisa = Agent(
 name="Pesquisador",
 instructions="Pesquise informações sobre o tema solicitado.",
)

@function_tool
def pesquisar(query: str) -> str:
 """Delega pesquisa para o agente especialista."""
 resultado = Runner.run_sync(agente_pesquisa, query)
 return resultado.final_output

coordenador = Agent(
 name="Coordenador",
 tools=[pesquisar],
 instructions="Coordene tarefas. Use a tool pesquisar quando precisar de dados.",
)
```

Nesse segundo padrão, o agente-filho roda como tool e retorna o resultado para o pai. É handoff implícito — o controle volta pro coordenador depois.

### Guardrails — segurança em camadas

O sistema de guardrails do SDK é uma das funcionalidades que mais brilham. São três escopos:

**Input Guardrails** — rodam na entrada do primeiro agente da cadeia:

```
from agents import input_guardrail, GuardrailFunctionOutput, Agent, Runner
from pydantic import BaseModel

class AnaliseSeguranca(BaseModel):
 is_malicioso: bool
 razao: str

agente_guardrail = Agent(
 name="Analisador de Segurança",
 instructions="Verifique se a mensagem é maliciosa, spam ou off-topic.",
 output_type=AnaliseSeguranca,
 model="gpt-4o-mini", # modelo barato pro guardrail
)

@input_guardrail
async def guardrail_seguranca(ctx, agent, input):
 resultado = await Runner.run(agente_guardrail, input, context=ctx.context)
 return GuardrailFunctionOutput(
 output_info=resultado.final_output,
 tripwire_triggered=resultado.final_output.is_malicioso,
 )

agente_principal = Agent(
 name="Assistente",
 instructions="Ajude o usuário com suas dúvidas.",
 input_guardrails=[guardrail_seguranca],
 model="gpt-4o", # modelo caro, protegido pelo guardrail
)
```

A sacada aqui é econômica: o guardrail roda num modelo barato e bloqueia requests maliciosos antes de atingir o modelo caro. Tripwire disparou? A execução para imediatamente com uma exceção `InputGuardrailTripwireTriggered`.

**Output Guardrails** — rodam na saída do último agente:

```
from agents import output_guardrail, GuardrailFunctionOutput

@output_guardrail
async def guardrail_pii(ctx, agent, output):
 # Verifica se a resposta contém dados sensíveis
 texto = str(output)
 tem_pii = any(p in texto.lower() for p in ["cpf", "cartão de crédito", "senha"])
 return GuardrailFunctionOutput(tripwire_triggered=tem_pii)
```

**Tool Guardrails** — rodam antes/depois de cada chamada de function tool:

```
from agents import function_tool, tool_input_guardrail, ToolGuardrailFunctionOutput

@tool_input_guardrail
def bloquear_segredos(data):
 args = data.context.tool_arguments or "{}"
 if "sk-" in args:
 return ToolGuardrailFunctionOutput.reject_content(
 "Remova segredos antes de chamar esta tool."
 )
 return ToolGuardrailFunctionOutput.allow()

@function_tool(tool_input_guardrails=[bloquear_segredos])
def processar_texto(texto: str) -> str:
 """Processa texto para classificação."""
 return f"Classificado: {len(texto)} caracteres"
```

Existe também a opção de rodar guardrails em **modo bloqueante** (`run_in_parallel=False`) — onde o guardrail termina antes do agente começar, garantindo zero tokens gastos em requests inválidos. Por default rodam em paralelo (melhor latência, mas o agente pode já ter começado quando o guardrail dispara).

### Tracing — observabilidade de graça

Todo `Runner.run()` é automaticamente rastreado. Sem configuração, sem setup adicional. O SDK coleta:

- Gerações LLM (prompt, completion, token counts)

- Tool calls (nome, input, output, duração)

- Handoffs (fonte, alvo, razão)

- Guardrail checks (qual guardrail, resultado, duração)

Os traces vão pro dashboard de Traces da OpenAI por padrão. Quer mandar pro Grafana, Datadog ou outro backend? Implemente um `TraceProcessor` custom:

```
from agents import trace

with trace(workflow_name="Suporte ao Cliente"):
 resultado = Runner.run_sync(agente_triagem, "Preciso de ajuda")
```

Essa é uma funcionalidade que frameworks concorrentes ou não têm, ou cobram à parte (oi, LangSmith). Aqui é grátis desde o primeiro `run()`. Quando você está debugando por que um agente fez um handoff estranho ou por que uma tool falhou, os traces são ouro.

### Context — estado compartilhado

O `RunContextWrapper` permite injetar contexto customizado que todas as tools e guardrails acessam:

```
from dataclasses import dataclass
from agents import Agent, Runner, function_tool, RunContextWrapper

@dataclass
class ContextoApp:
 user_id: str
 plano: str
 saldo: float

@function_tool
def verificar_saldo(ctx: RunContextWrapper[ContextoApp]) -> str:
 """Verifica o saldo do usuário."""
 return f"Saldo atual: R$ {ctx.context.saldo:.2f}"

contexto = ContextoApp(user_id="usr_123", plano="pro", saldo=150.00)
resultado = await Runner.run(agente, "Qual meu saldo?", context=contexto)
```

O context é type-safe via generics. Se você tentar acessar um campo que não existe, o linter pega.

### Sessions — memória persistente

Pra manter conversa entre turns (o agente lembrar o que o usuário disse antes), o SDK oferece sessions plugáveis:

```
from agents import Agent, Runner
from agents.extensions.memory import SQLAlchemySession

session = await SQLAlchemySession.create(
 connection_string="sqlite:///agente.db"
)

agente = Agent(name="Memória", instructions="Lembre preferências do usuário.")

await Runner.run(agente, "Meu nome é João.", session=session)
resultado = await Runner.run(agente, "Qual meu nome?", session=session)
# → "Seu nome é João."
```

Backends disponíveis: SQLite (dev), Redis (multi-processo), PostgreSQL via SQLAlchemy (produção), MongoDB, e até DaprSession pra ambientes cloud-native.

### MCP — ferramentas externas

O SDK tem suporte nativo ao [Model Context Protocol](/blog/ferramentas-tools-e-mcp-servers), permitindo conectar qualquer MCP server como tool do agente:

```
from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
 name="Filesystem",
 params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}
) as server:
 agente = Agent(
 name="File Manager",
 instructions="Gerencie arquivos para o usuário.",
 mcp_servers=[server],
 )
```

Isso abre um universo: databases, APIs, browsers, sistemas de arquivo — qualquer coisa que tenha um MCP server vira tool acessível pros seus agentes.

---

## Spider Chart

Avaliação em 8 eixos (0–100):

```
 Facilidade de Uso

 │
 Documentação │ Ecosystem/Comunidade
 80 ─────────┼───────── 65
 ╱│╲
 Tracing/ ╱ │ ╲ Flexibilidade
 Observ. 90 ──╱──│──╲── 55
 ╱ │ ╲
 Guardrails ╱ │ ╲ Multi-Provider
 85 ───╱─────│─────╲─── 60
 ╱ │ ╲
 ╱ │ ╲
 Multi-Agent │ Maturidade
 75 ─────────┼───────── 80
```

 Eixo
 Nota
 Justificativa

 Facilidade de Uso
 95
 Quatro primitivos, zero boilerplate. Curva de aprendizado mais suave que qualquer concorrente.

 Documentação
 80
 Docs oficiais completas, com exemplos. Falta conteúdo em português e tutoriais avançados.

 Tracing/Observabilidade
 90
 Automático, gratuito, integrado. Difícil bater isso.

 Guardrails
 85
 Três escopos (input, output, tool), tripwire pattern elegante. Falta approval flows sofisticados.

 Multi-Agent
 75
 Handoffs funcionam bem pra padrão router/supervisor. Falta execução paralela nativa.

 Multi-Provider
 60
 Funciona com 100+ modelos via LiteLLM, mas features premium (tracing dashboard, hosted tools) são OpenAI-only.

 Flexibilidade
 55
 Opinado por design. Se seu workflow não é tree-shaped, vai lutar contra o framework.

 Ecosystem/Comunidade
 65
 Crescendo rápido, mas ainda atrás de LangChain/LangGraph em tamanho de comunidade e plugins.

 Maturidade
 80
 Em produção desde 2025. Empresas como Oscar Health já usam em produção. API estabilizando.

---

## Prós e Contras

### O que brilha

- **Zero cerimônia** — Você vai de `pip install` a multi-agent funcionando em 20 minutos. Sério. Sem YAML, sem grafos, sem configuração de infraestrutura.

- **Tracing gratuito e automático** — Não precisa configurar nada. Todo `Runner.run()` gera traces. Compare com LangSmith que cobra planos a partir de $39/mês pra funcionalidades similares.

- **Guardrails como cidadão de primeira classe** — Não é um afterthought ou plugin. O sistema de tripwires é simples, testável e cobre input, output e tools.

- **Economia por design** — Modelo barato no guardrail, modelo barato na triagem, modelo caro só no especialista. O SDK incentiva esse padrão naturalmente.

- **MCP nativo** — Qualquer MCP server é tool. Sem adapters, sem wrappers, sem gambiarras.

- **Sandbox Agents** — A evolução de abril/2026 permite rodar agentes em ambientes isolados com filesystem, shell e persistência. É basicamente o [Codex](/blog/codex-openai) como library.

### Onde dói

- **Sem execução paralela nativa** — Se você precisa de fan-out/fan-in (rodar 3 agentes em paralelo e sintetizar), vai ter que orquestrar com `asyncio.gather()` na mão. LangGraph faz isso out of the box.

- **Human-in-the-loop limitado** — Guardrails conseguem *parar* a execução, mas não *pausar e retomar*. Fluxos de aprovação tipo “agente propõe → humano aprova → agente continua” exigem gambiarra.

- **Vendor lock-in prático** — Sim, suporta outros modelos via LiteLLM. Mas tracing dashboard, hosted tools (WebSearch, FileSearch, CodeInterpreter), e sandbox agents são exclusivos OpenAI. Rodar com Anthropic ou local perde metade das features.

- **Sem TypeScript (ainda)** — O SDK oficial é Python-only. Existe um port comunitário em TS, mas sem garantia de paridade. Se seu stack é Node, vai ter que esperar ou usar alternativas.

- **Handoffs são sequenciais** — Um agente delega pra outro que delega pra outro. É sempre linear. Workflows onde dois agentes precisam dialogar entre si (A → B → A → B) ficam desajeitados.

- **Custos invisíveis** — O SDK abstrai contagem de tokens. Você só descobre quanto gastou depois, nos traces. Não existe budget governor ou custo máximo por run.

---

## Quando usar

O OpenAI Agents SDK é a escolha certa quando:

✅ **Seu stack já é OpenAI** — Se você usa GPT-4o/gpt-5.x e a Responses API, o SDK adiciona orquestração multi-agent sem nova superfície de abstração.

✅ **Seu padrão é router → especialistas** — Triagem que delega pra N especialistas é exatamente o que handoffs fazem bem. Suporte ao cliente com departamentos, pipelines de processamento com etapas especializadas.

✅ **Guardrails e compliance são requisitos** — Se precisa de validação de input/output como requisito regulatório ou de segurança, o SDK entrega isso pronto.

✅ **Prototipagem rápida com caminho pra produção** — Ao contrário do CrewAI (ótimo pra prototipar mas questionável em prod), o Agents SDK é production-ready desde o dia um. Tracing, sessions, error handling — tudo incluído.

✅ **Migração do Assistants API** — O Assistants API será sunset em agosto de 2026. Se você usa, essa é a migração recomendada oficialmente pela OpenAI.

✅ **Agentes que operam em arquivos e código** — Com sandbox agents, seu agente pode inspecionar arquivos, rodar comandos e editar código em ambientes isolados. Pense num [harness de agente de codificação](/blog/harness-e-loop-arquitetura-agentes) encapsulado numa lib.

## Quando NÃO usar

❌ **Workflows com paralelismo complexo** — Se você precisa de fan-out/fan-in, dependency graphs entre tasks, ou múltiplos agentes rodando simultâneamente com estado compartilhado, LangGraph é melhor equipado.

❌ **Diálogos multi-turn entre agentes** — Se seu valor está em agentes que se criticam mutuamente (um escreve, outro revisa, o primeiro corrige), AutoGen modela isso naturalmente com group chat. Handoffs são unidirecionais.

❌ **Stack 100% TypeScript/JavaScript** — Sem SDK oficial em TS, você vai lutar com bindings incompletas. Espere o suporte oficial ou use o Vercel AI SDK como alternativa.

❌ **Orçamento apertado de tokens com controle granular** — O SDK não tem cost governor. Se cada token conta e você precisa de budget caps por agent run, vai ter que instrumentar manualmente.

❌ **Multi-provider como requisito core** — Se amanhã você quer trocar OpenAI por Anthropic sem perder funcionalidade, vai perder tracing dashboard, hosted tools e sandbox. A promessa “provider-agnostic” é parcial.

❌ **Fluxos de aprovação humana sofisticados** — Pra workflows onde um agente propõe uma ação, pausa, um humano revisa no Slack, aprova, e o agente continua — o SDK não tem mecanismo nativo. Precisa de infra custom em volta.

---

## Comparativo rápido com concorrentes

 Agents SDK
 LangGraph
 CrewAI
 AutoGen/MAF

 Curva de aprendizado
 Baixa
 Alta
 Baixa
 Média

 Multi-agent
 Handoffs
 Grafos
 Roles+Tasks
 Group Chat

 Parallelismo
 Manual
 Nativo
 Sequencial
 Via chat

 Guardrails
 Nativo (3 scopes)
 Via callbacks
 —
 Limitado

 Tracing
 Grátis/automático
 LangSmith (pago)
 Limitado
 Third-party

 MCP
 Nativo
 Community
 Via plugins
 Community

 Maturidade
 Alta
 Mais alta
 Crescendo
 Em transição (MAF)

---

## Próximos passos

### Se você quer começar agora

- **`pip install openai-agents`** — instale e rode o quickstart da [documentação oficial](https://openai.github.io/openai-agents-python/quickstart/)

- **Monte um triagem + 2 especialistas** — use o padrão router do tutorial acima como base

- **Adicione guardrails** — comece com um input guardrail simples que bloqueia off-topic

- **Habilite tracing** — já vem ligado, mas explore o dashboard em platform.openai.com/traces

- **Conecte um MCP server** — filesystem ou database, pra experimentar tools externas

### Se quer ir além

- Explore **Sandbox Agents** pra agentes que operam em código — [o post da OpenAI de abril/2026](https://openai.com/en-US/index/the-next-evolution-of-the-agents-sdk/) detalha o modelo de isolamento

- Combine com **sessions em Redis/PostgreSQL** pra agentes stateful em produção

- Implemente um `TraceProcessor` custom pra mandar traces pro [Grafana ou seu stack de observabilidade](/blog/harness-e-loop-arquitetura-agentes)

- Avalie se handoffs atendem ou se você precisa de algo mais sofisticado — se sim, olhe LangGraph

### Leituras complementares aqui no blog

- [Agent Frameworks vs Coding Agents: Qual a diferença?](/blog/agent-frameworks-vs-coding-agents)

- [Harness e Loop: A Arquitetura por Trás dos Agentes](/blog/harness-e-loop-arquitetura-agentes)

- [Ferramentas, Tools e MCP Servers](/blog/ferramentas-tools-e-mcp-servers)

- [Codex da OpenAI: Agente de Código na Nuvem](/blog/codex-openai)

---

## Veredicto

O OpenAI Agents SDK é a resposta certa pra pergunta “qual o menor framework que me dá multi-agent funcional em produção?”. Quatro primitivos. Tracing grátis. Guardrails embutidos. MCP nativo. Sessions plugáveis.

Não é a resposta certa pra tudo — se você precisa de grafos complexos, paralelismo nativo, ou independência total de provider, existem ferramentas melhores. Mas pra 80% dos casos de uso “tenho um sistema que precisa rotear requests entre agentes especializados”, o SDK entrega mais com menos código e menos dependências que qualquer alternativa.

A OpenAI está apostando que minimalismo com opinião ganha de generalismo com complexidade. No ecossistema de agentes de codificação onde todos reclamam de excesso de abstração, talvez eles tenham razão.

---

*Precisa de ajuda implementando agentes em produção? Consultoria personalizada em [ft.ia.br](https://ft.ia.br).*

-->