Cheatsheet do SDK de Agents OpenAI
O SDK de Agents OpenAI é um pequeno framework Python opinado para construir aplicativos agentic. Ele expõe quatro primitivas principais — Agents (um LLM mais instruções e ferramentas), Tools (funções Python ou ferramentas hospedadas), Handoffs (delegando uma execução a outro agente), e Guardrails (validando entradas e saídas) — com Sessions para memória e Tracing built-in. Ele é flexível em relação ao provedor, mas funciona pronto com modelos OpenAI.
Instalação
| Passo | Comando |
|---|
| Instalar | pip install openai-agents |
| Com uv | uv add openai-agents |
| Defina a chave | export OPENAI_API_KEY="sk-..." |
| Extras de voz | pip install "openai-agents[voice]" |
| Verificar | python -c "import agents; print(agents.__version__)" |
Agent Mínimo
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a concise, helpful assistant.",
)
result = Runner.run_sync(agent, "Summarize the Unix philosophy in one line.")
print(result.final_output)
| Chamada | Descrição |
|---|
Runner.run_sync(agent, input) | Executa sincronicamente |
await Runner.run(agent, input) | Executa assincronicamente |
Runner.run_streamed(agent, input) | Transmite eventos conforme ocorrem |
result.final_output | A resposta final do agente |
result.new_items | Itens de execução estruturados (mensagens, chamadas de ferramentas, handoffs) |
Ferramentas
from agents import Agent, function_tool
@function_tool
def get_weather(city: str) -> str:
"""Return the weather for a city."""
return f"Sunny in {city}"
agent = Agent(name="Weather", tools=[get_weather])
| Conceito | Descrição |
|---|
@function_tool | Transforma uma função Python tipada em uma ferramenta (esquema auto-gerado a partir da assinatura/docstring) |
| Ferramentas hospedadas | Built-ins como web search e file search |
tool_use_behavior | Controla se a saída da ferramenta encerra o turno |
| Agents como ferramentas | agent.as_tool(...) expõe um agente como ferramenta chamável de outro |
Handoffs
from agents import Agent, handoff
billing = Agent(name="Billing", instructions="Handle billing questions.")
triage = Agent(
name="Triage",
instructions="Route the user to the right specialist.",
handoffs=[billing], # or handoff(billing, ...)
)
Handoffs transferem a conversa completa para o agente receptor dentro de uma única execução; guardrails de entrada se aplicam ao primeiro agente e guardrails de saída ao agente que produz a saída final.
Guardrails
from agents import Agent, input_guardrail, GuardrailFunctionOutput
@input_guardrail
async def no_secrets(ctx, agent, user_input):
tripped = "password" in user_input.lower()
return GuardrailFunctionOutput(output_info={}, tripwire_triggered=tripped)
agent = Agent(name="Safe", input_guardrails=[no_secrets])
| Tipo | Executa | Propósito |
|---|
@input_guardrail | Antes do agente | Valida/tela a entrada do usuário |
@output_guardrail | Após a saída final | Valida a resposta do agente |
| Guardrails de ferramenta | Em torno de cada chamada de ferramenta | Verifica entradas/saídas de ferramentas individuais |
| Tripwire | Na ativação | Levanta uma exceção para interromper a execução |
Sessions (Memória)
from agents import Agent, Runner, SQLiteSession
session = SQLiteSession("user-123", "conversations.db")
Runner.run_sync(agent, "My name is Nick.", session=session)
Runner.run_sync(agent, "What's my name?", session=session) # remembers
| Session | Uso |
|---|
SQLiteSession | Memória de conversação local/persistente |
| Session em memória | Contexto efêmero dentro de um processo |
| Session personalizada | Implemente o protocolo de session para seu próprio armazenamento |
Tracing
| Feature | Descrição |
|---|
| Traces automáticos | Cada Runner.run registra chamadas de modelo, chamadas de ferramentas, handoffs, resultados de guardrail e timing |
| Dashboard | Traces aparecem sob seu projeto na plataforma OpenAI |
trace(...) | Agrupa múltiplas execuções em um trace de fluxo de trabalho |
| Processadores externos | Exporte spans para ferramentas de observabilidade de terceiros |
Fluxos de Trabalho Comuns
# Transmitindo tokens para uma UI
import asyncio
from agents import Agent, Runner
async def main():
agent = Agent(name="Writer", instructions="Write vividly.")
streamed = Runner.run_streamed(agent, "Describe a thunderstorm.")
async for event in streamed.stream_events():
print(event)
asyncio.run(main())
Recursos
