Agents SDK: Instalación y tu primer agente
En esta página
Agents SDK: Instalación y tu primer agente
Vamos a programar. Instalarás el SDK oficial de Agents de OpenAI, crearás un agente funcional en Python y explorarás los tres modos de ejecución que utilizarás a lo largo de este curso.
Requisitos previos
Solo necesitas tres cosas: Python 3.10+ instalado en tu máquina, una cuenta de OpenAI con una clave de API activa y un editor de código. Recomendamos VS Code, pero cualquier editor con resaltado de sintaxis para Python funciona perfectamente.
Instalación
El paquete se llama openai-agents. Ten cuidado: instalar solo openai te proporciona el cliente clásico de la API, no el SDK de Agents.
pip install openai-agents
Este paquete instala automáticamente las dependencias necesarias, incluido el SDK de Python de OpenAI. A continuación, configura tu clave de API como una variable de entorno. El SDK la lee automáticamente, por lo que no se requiere configuración adicional.
export OPENAI_API_KEY="sk-proj-your-api-key"
Este comando desaparece cuando cierras el terminal y, desde luego, no querrás codificar tu clave directamente en tus archivos de origen. Para una configuración adecuada del proyecto, utiliza un archivo .env con python-dotenv y añade ese archivo a tu .gitignore antes de tu primera confirmación (commit).
pip install python-dotenv
# .env
OPENAI_API_KEY=sk-proj-your-api-key
Tu primer agente
Crea un archivo llamado my_first_agent.py:
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant. Respond in English concisely.",
model="gpt-5.6-terra",
)
result = Runner.run_sync(agent, "Explain what an AI agent is in three sentences.")
print(result.final_output)
Ejecútalo:
python my_first_agent.py
Acabas de crear y ejecutar tu primer agente. Es sencillo: sin herramientas, sin barreras de seguridad, pero constituye la base de todo lo demás. El resto de este curso simplemente se construye sobre estos dos objetos: Agent y Runner.
Ejecución asíncrona
run_sync bloquea el hilo actual hasta que llega la respuesta. Esto está bien para un script de prueba, pero es inaceptable para un servidor web que gestiona cientos de solicitudes simultáneas. En producción, utilizarás el modo asíncrono.
import asyncio
from agents import Agent, Runner
agent = Agent(
name="Async Assistant",
instructions="You are a helpful assistant. Respond in English.",
model="gpt-5.6-terra",
)
async def main():
result = await Runner.run(agent, "What are the advantages of Python for AI?")
print(result.final_output)
asyncio.run(main())
Runner.run() es la versión asíncrona; Runner.run_sync() es un contenedor síncrono que la llama por ti. Cuando utilices FastAPI o cualquier otro framework asíncrono, usa siempre Runner.run().
Ejecución con streaming
Existe un tercer modo, esencial siempre que haya un humano esperando frente a la pantalla. El streaming muestra la respuesta a medida que se genera, token a token.
import asyncio
from agents import Agent, Runner
agent = Agent(
name="Streaming Assistant",
instructions="You are a helpful assistant. Respond in English.",
model="gpt-5.6-terra",
)
async def main():
result = Runner.run_streamed(agent, "Tell a short story about AI.")
async for event in result.stream_events():
if event.type == "raw_response_event":
if hasattr(event.data, "delta") and event.data.delta:
print(event.data.delta, end="", flush=True)
print() # New line at the end
asyncio.run(main())
El bucle async for consume un flujo de eventos. Aquí, filtramos los eventos de respuesta cruda del modelo e imprimimos solo los fragmentos de texto. El streaming es crítico para la experiencia de usuario: nadie quiere mirar una pantalla en blanco durante 10 segundos.
Estructura del proyecto del agente
Un agente de producción no cabe en un único archivo. Separa desde el principio las definiciones de tus agentes, las herramientas y las pruebas, o tu main.py se volverá rápidamente ilegible.
my-agent-project/
├── .env # API key
├── requirements.txt # Dependencies
├── agents/
│ ├── __init__.py
│ ├── assistant.py # Agent definition
│ └── tools.py # Tool definitions
├── main.py # Entry point
└── tests/
└── test_agent.py # Tests
# requirements.txt
openai-agents>=0.1.0
python-dotenv>=1.0.0
Puntos clave
- Instala el SDK con
pip install openai-agents - Configura
OPENAI_API_KEYcomo una variable de entorno - Usa
Runner.run_sync()para desarrollo yRunner.run()para producción asíncrona - Usa
Runner.run_streamed()para streaming en tiempo real - Estructura tu proyecto con carpetas separadas para agentes, herramientas y pruebas