El OpenAI Agents SDK es una biblioteca de Python diseñada para simplificar el desarrollo de agentes de IA impulsados por los modelos de lenguaje de OpenAI. Equipa a los desarrolladores con herramientas para crear agentes específicos para tareas, integrar funcionalidades externas, gestionar la delegación de tareas entre agentes, aplicar la validación de entrada/salida y supervisar los flujos de ejecución. Esta guía ofrece un recorrido técnico detallado sobre la instalación, configuración y aprovechamiento eficaz del SDK, garantizando un mínimo de 2000 palabras con un enfoque en la precisión y la aplicación práctica.
Introducción
El OpenAI Agents SDK proporciona un marco estructurado para construir sistemas multiagente donde cada agente está adaptado para realizar tareas específicas. Estos agentes pueden interactuar con los usuarios, ejecutar acciones a través de herramientas integradas y colaborar pasando tareas a otros agentes. Los componentes clave del SDK incluyen:
- Agentes: Instancias de modelos de lenguaje configurados con instrucciones y roles específicos.
- Herramientas: Funciones o servicios (por ejemplo, búsqueda web, código Python personalizado) que amplían las capacidades del agente.
- Traspasos: Mecanismos que permiten a los agentes delegar tareas a otros agentes sin problemas.
- Barandillas: Capas de validación para garantizar que las entradas y salidas cumplen los criterios definidos.
- Seguimiento: Registros de ejecución para la depuración y el análisis del rendimiento.

Esta guía está diseñada para desarrolladores con una comprensión básica de Python y las interacciones de la API, proporcionando explicaciones detalladas, ejemplos de código y mejores prácticas para crear un recurso robusto y completo.
Instalación y configuración
Una configuración adecuada es fundamental para utilizar el OpenAI Agents SDK de forma eficaz. Esta sección cubre los requisitos previos, la configuración del entorno, la instalación y la verificación.
Requisitos previos
Antes de continuar, asegúrate de lo siguiente:
- Python 3.8+: Verifica tu versión de Python con
python --version
. Instala desde python.org si es necesario.

- Clave de la API de OpenAI: Obtén tu clave de platform.openai.com en la configuración de tu cuenta. Esta clave autentica las solicitudes a los servidores de OpenAI.

Paso 1: Configurar un entorno virtual
Un entorno virtual aísla las dependencias del proyecto, evitando conflictos con otros proyectos de Python. Para crear y activar uno:
- Linux/macOS:
python -m venv agents_env
source agents_env/bin/activate
- Windows:
python -m venv agents_env
agents_env\Scripts\activate
Una vez activado, el símbolo del sistema de tu terminal debería reflejar el entorno (por ejemplo, (agents_env)
). Este paso es una buena práctica para el desarrollo de Python, garantizando un espacio de trabajo limpio.
Paso 2: Instalar el SDK
Con el entorno virtual activo, instala el SDK utilizando pip:
pip install openai-agents
Este comando obtiene la última versión del SDK y sus dependencias de PyPI. Para confirmar la instalación, ejecuta:
pip show openai-agents-python
Esto muestra los metadatos, incluyendo el número de versión, confirmando que el paquete está instalado.
Paso 3: Configurar la clave de la API
El SDK requiere una clave de la API de OpenAI para funcionar. Establécela como una variable de entorno para evitar incrustarla en tu código, lo que mejora la seguridad:
- Linux/macOS:
export OPENAI_API_KEY='your-api-key'
- Windows:
set OPENAI_API_KEY='your-api-key'
Para que esto sea persistente entre sesiones, añade el comando a tu archivo de configuración de shell (por ejemplo, .bashrc
o .zshrc
en sistemas Unix). Alternativamente, puedes establecerlo programáticamente en Python, aunque esto es menos seguro:
import os
os.environ["OPENAI_API_KEY"] = "your-api-key"
Paso 4: Verificar la instalación
Prueba la configuración con un agente mínimo para asegurarte de que todo funciona:
from agents import Agent, Runner
agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output) # Expected output: "Setup successful"
Si esto imprime "Setup successful", tu instalación es funcional. Los problemas comunes incluyen:
- Clave de la API no válida: Comprueba la clave y asegúrate de que no haya espacios adicionales o errores tipográficos.
- Errores de red: Verifica tu conexión a Internet y el estado del servidor de OpenAI.
Creación de agentes
Los agentes son los bloques de construcción fundamentales del SDK, cada uno definido por un rol y un comportamiento únicos.
Inicialización del agente
La clase Agent
se utiliza para instanciar agentes. Los parámetros clave incluyen:
name
: Un identificador de cadena (por ejemplo, "MathAgent").instructions
: Una cadena que especifica el propósito del agente (por ejemplo, "Resolver problemas de matemáticas").model
: El modelo de OpenAI a utilizar (por defecto:gpt-4
).temperature
: Un flotante entre 0 y 1 que controla la aleatoriedad de la salida (por defecto: 0.7).
Ejemplo: Agente básico
Aquí tienes un agente simple para la aritmética:
from agents import Agent, Runner
agent = Agent(
name="MathAgent",
instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output) # Output: "20"
El método Runner.run_sync
ejecuta el agente de forma síncrona, devolviendo un objeto de resultado con el atributo final_output
.
Configuración avanzada
Personaliza los agentes para necesidades específicas ajustando los parámetros:
agent = Agent(
name="CreativeWriter",
instructions="Write a short story based on the prompt.",
model="gpt-4",
temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output) # Output: A creative story
- Model:
gpt-4
ofrece un razonamiento superior, mientras quegpt-3.5-turbo
es más rápido y barato para tareas más sencillas. - Temperature: Los valores más bajos (por ejemplo, 0.2) producen salidas predecibles; los valores más altos (por ejemplo, 0.9) aumentan la creatividad.
Ejemplo de múltiples agentes
Crea agentes distintos para diferentes tareas:
support_agent = Agent(
name="SupportBot",
instructions="Answer technical support questions."
)
code_agent = Agent(
name="CodeHelper",
instructions="Generate Python code snippets."
)
support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output) # Output: Installation instructions
print(code_result.final_output) # Output: "def add(a, b): return a + b"
Esto demuestra la flexibilidad del SDK para manejar diversos roles.
Integración de herramientas
Las herramientas mejoran los agentes permitiéndoles realizar acciones externas. El SDK admite herramientas alojadas, herramientas de función personalizadas y herramientas basadas en agentes.
Uso de herramientas alojadas
Las herramientas alojadas, como web_search
, están preconstruidas y listas para usar:
from agents import Agent, Runner, web_search
agent = Agent(
name="ResearchAgent",
instructions="Answer questions using web search.",
tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output) # Output: "The capital of France is Paris."
El agente invoca automáticamente web_search
para obtener datos en tiempo real.
Creación de herramientas de función personalizadas
Define herramientas personalizadas con el decorador @function_tool
. Las herramientas deben aceptar y devolver cadenas.
Ejemplo: Herramienta de obtención de datos
from agents import Agent, Runner, function_tool
@function_tool
def fetch_data(id: str) -> str:
"""Return data for the given ID."""
# Simulated database lookup
return f"Data for ID {id}: active"
agent = Agent(
name="DataAgent",
instructions="Retrieve data using the tool.",
tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output) # Output: "Data for ID 123: active"
Integración de API externas
Las herramientas pueden conectarse a servicios externos. Aquí tienes un ejemplo de herramienta meteorológica:
import requests
from agents import function_tool, Agent, Runner
@function_tool
def get_weather(city: str) -> str:
"""Get the current weather for a city."""
api_key = "your-weather-api-key" # Replace with a real key
url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
response = requests.get(url)
if response.status_code == 200:
data = response.json()
return f"The weather in {city} is {data['current']['condition']['text']}."
return "Weather data unavailable."
agent = Agent(
name="WeatherAgent",
instructions="Provide weather updates using the tool.",
tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output) # Output: "The weather in Tokyo is Sunny." (example)
Regístrate para obtener una clave de API gratuita en weatherapi.com para probar esto.

Combinación de múltiples herramientas
Los agentes pueden utilizar múltiples herramientas simultáneamente:
@function_tool
def log_entry(text: str) -> str:
"""Log a message."""
return f"Logged: {text}"
agent = Agent(
name="MultiToolAgent",
instructions="Use tools to search and log.",
tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output) # Output includes search results and log confirmation
Traspasos de agentes
Los traspasos permiten a los agentes delegar tareas, permitiendo flujos de trabajo complejos.
Configuración de traspasos
Define un agente primario con acceso a agentes secundarios a través del parámetro handoffs
:
from agents import Agent, Runner
english_agent = Agent(
name="EnglishHelper",
instructions="Respond in English only."
)
spanish_agent = Agent(
name="SpanishHelper",
instructions="Respond in Spanish only."
)
triage_agent = Agent(
name="LanguageRouter",
instructions="Detect the language and hand off to the appropriate agent.",
handoffs=[english_agent, spanish_agent]
)
result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output) # Output: "¡Bien, gracias!" (or similar)
El triage_agent
analiza la entrada y delega al agente específico del idioma apropiado.
Lógica de traspaso
La decisión de traspaso se basa en las instrucciones del agente primario. Por ejemplo:
- "Si la entrada contiene palabras en español, traspasa a SpanishHelper."
- "Para las entradas en inglés, utiliza EnglishHelper."
Prueba con una entrada en inglés:
result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output) # Output: "I'm good, thanks!"
Traspasos anidados
Para flujos de trabajo más profundos, los agentes pueden traspasar a otros agentes con traspasos:
analysis_agent = Agent(
name="AnalysisBot",
instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
name="ReportBot",
instructions="Generate a report from analysis."
)
main_agent = Agent(
name="WorkflowManager",
instructions="Start with analysis.",
handoffs=[analysis_agent, report_agent]
)
result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output) # Output: A generated report
Implementación de barandillas
Las barandillas aplican restricciones a las entradas y salidas utilizando modelos Pydantic.
Definición de una barandilla
Crea un modelo para validar la estructura de salida:
from pydantic import BaseModel
from agents import Agent, Runner
class QuestionCheck(BaseModel):
is_question: bool
reason: str
guard_agent = Agent(
name="QuestionGuard",
instructions="Determine if the input is a question.",
output_type=QuestionCheck
)
result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output) # Output: {"is_question": true, "reason": "Ends with a question mark"}
Integración del flujo de trabajo
Utiliza barandillas para filtrar las entradas:
task_agent = Agent(
name="TaskProcessor",
instructions="Process questions only.",
handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output) # Output indicates it’s not a question
Seguimiento y depuración
El seguimiento registra los detalles de la ejecución del agente, accesibles a través del Panel de control de OpenAI.
Habilitación del seguimiento
El seguimiento es automático. Cada ejecución genera un seguimiento con:
- Datos de entrada/salida
- Llamadas a herramientas
- Eventos de traspaso
- Errores
Ejemplo de depuración
Si un agente falla, revisa el seguimiento para identificar:
- Parámetros de herramienta incorrectos
- Enrutamiento incorrecto del traspaso
- Errores de la API
Mejores prácticas
Optimización del rendimiento
- Elección del modelo: Utiliza
gpt-3.5-turbo
para la velocidad,gpt-4
para el razonamiento complejo. - Temperatura: 0.2 para la precisión, 0.9 para la creatividad.
- Ejecución asíncrona: Utiliza
Runner.run_async
para tareas paralelas.
Manejo de errores
- Herramientas: Devuelve mensajes de error claros (por ejemplo, "ID no válido").
- Traspasos: Incluye un agente de reserva para los fallos.
Diseño del flujo de trabajo
- Modularidad: Divide las tareas entre los agentes.
- Claridad: Escribe instrucciones inequívocas.
- Validación: Aplica barandillas en las etapas clave.
Conclusión
El OpenAI Agents SDK permite a los desarrolladores construir sistemas de IA sofisticados con agentes especializados, herramientas integradas y flujos de trabajo colaborativos. Esta guía proporciona una base técnica para aprovechar todo su potencial, completa con ejemplos y mejores prácticas.
Entonces, ¿qué sigue? ¡Empieza a experimentar! Juega con diferentes instrucciones, herramientas y flujos de trabajo. Y si te encuentras con algún problema, herramientas como Apidog pueden ayudarte con las pruebas de la API, consíguela gratis.
