¿Cómo usar el SDK de Agentes de OpenAI?

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 que gpt-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.