Ir al contenido principal
Español— Elegir un idioma
Menú

Agents SDK: Instalación y tu primer agente

Lección 4 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Agents SDK: Instalación y tu primer agente
  2. Requisitos previos
  3. Instalación
  4. Tu primer agente
  5. Ejecución asíncrona
  6. Ejecución con streaming
  7. Estructura del proyecto del agente
  8. Puntos clave

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_KEY como una variable de entorno
  • Usa Runner.run_sync() para desarrollo y Runner.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