Guía de Referencia de OpenAI Agents SDK
El SDK de Agentes de OpenAI es un marco Python pequeño y opinativo para construir aplicaciones agénticas. Expone cuatro primitivos centrales — Agentes (un LLM más instrucciones y herramientas), Herramientas (funciones Python o herramientas alojadas), Handoffs (delegar una ejecución a otro agente) y Guardrails (validar entradas y salidas) — con Sesiones para memoria y Tracing integrados. Es flexible en cuanto al proveedor pero funciona de inmediato con modelos de OpenAI.
Instalación
| Paso | Comando |
|---|
| Instalar | pip install openai-agents |
| Con uv | uv add openai-agents |
| Establecer la clave | export OPENAI_API_KEY="sk-..." |
| Extras de voz | pip install "openai-agents[voice]" |
| Verificar | python -c "import agents; print(agents.__version__)" |
Agente 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)
| Llamada | Descripción |
|---|
Runner.run_sync(agent, input) | Ejecutar de forma síncrona |
await Runner.run(agent, input) | Ejecutar de forma asíncrona |
Runner.run_streamed(agent, input) | Transmitir eventos conforme suceden |
result.final_output | La respuesta final del agente |
result.new_items | Elementos de ejecución estructurados (mensajes, llamadas de herramientas, handoffs) |
Herramientas
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])
| Concepto | Descripción |
|---|
@function_tool | Convertir una función Python tipada en una herramienta (esquema generado automáticamente a partir de la firma/docstring) |
| Herramientas alojadas | Integradas como búsqueda web y búsqueda de archivos |
tool_use_behavior | Controlar si la salida de la herramienta termina el turno |
| Agentes como herramientas | agent.as_tool(...) expone un agente como una herramienta callable de otro |
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, ...)
)
Los handoffs transfieren la conversación completa al agente receptor dentro de una única ejecución; los guardrails de entrada se aplican al primer agente y los guardrails de salida al agente que produce la salida 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 | Se ejecuta | Propósito |
|---|
@input_guardrail | Antes del agente | Validar/filtrar entrada del usuario |
@output_guardrail | Después de la salida final | Validar la respuesta del agente |
| Guardrails de herramienta | Alrededor de cada llamada de herramienta | Verificar entradas/salidas de herramientas individuales |
| Tripwire | Al activarse | Lanza una excepción para detener la ejecución |
Sesiones (Memoria)
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
| Sesión | Uso |
|---|
SQLiteSession | Memoria de conversación local/persistente |
| Sesión en memoria | Contexto efímero dentro de un proceso |
| Sesión personalizada | Implementar el protocolo de sesión para tu propio almacén |
Tracing
| Característica | Descripción |
|---|
| Trazas automáticas | Cada Runner.run registra llamadas de modelo, llamadas de herramientas, handoffs, resultados de guardrails y tiempos |
| Panel de control | Las trazas aparecen bajo tu proyecto en la plataforma de OpenAI |
trace(...) | Agrupar múltiples ejecuciones en una única traza de flujo de trabajo |
| Procesadores externos | Exportar spans a herramientas de observabilidad de terceros |
Flujos de Trabajo Comunes
# Streaming tokens to a 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
