Reemplazando OpenAI en el OpenAI Agents SDK con Tu Modelo Local Ajustado

Actualizado 2026-05-10 — Refleja OpenAI Agents SDK v0.17.0 (7 de mayo de 2026), que actualizó el modelo predeterminado de RealtimeAgent a gpt-realtime-2. Fija a una versión específica del SDK en producción en lugar de seguir el predeterminado móvil — el patrón de cambio de abajo no cambia de cualquier forma.

El OpenAI Agents SDK es uno de los frameworks de agentes más limpios enviados en 2026. Es el sucesor de calidad de producción de Swarm, con llamadas a herramientas de primera clase, handoffs entre agentes, salidas estructuradas y un sistema de tracing que ha establecido el estándar para el resto del ecosistema. A pesar del nombre en la caja, no es solo de OpenAI. El SDK acepta cualquier endpoint HTTP compatible con OpenAI como modelo de respaldo, lo que significa que la experiencia de desarrollador viaja contigo cuando intercambias el modelo.

Ese detalle es el punto entero de esta guía. Puedes construir un agente contra el SDK, prototiparlo contra un modelo de OpenAI hospedado, y luego apuntar el mismo código a un modelo de 7B ajustado ejecutándose localmente en Ollama. El código del agente no cambia. Las trazas no cambian. La factura sí cambia, aproximadamente en un orden de magnitud o más, dependiendo del tráfico.

Por qué importa esto

Las aplicaciones agénticas queman tokens de una manera que los chatbots no. Un turno de chat típico es una o dos llamadas al modelo. Una tarea agéntica típica son cinco a treinta llamadas al modelo, porque el agente piensa, elige herramientas, lee la salida de la herramienta, decide qué hacer a continuación, y así sucesivamente. La factura de tokens escala con el bucle, no con el turno visible al usuario.

La forma económica que produce esto es inusual. Un producto agéntico con 1K activos mensuales ejecutándose en APIs en la nube de línea base a menudo solo paga unos $120 al mes en inferencia. Los fundadores miran ese número y asumen que la economía unitaria está bien. No lo está. A 40K MAU, el mismo producto está pagando $3,000 al mes o más, a menudo más cerca de $6,000 una vez que tienes en cuenta los reintentos, los contextos más largos y los flujos complejos. La línea de coste sube aproximadamente linealmente con los usuarios, mientras que los ingresos por usuario suben en ningún lugar tan rápido.

Un modelo local ajustado arregla la curva. El coste es fijo: una instancia GPU para el camino del backend, una descarga única del modelo para el camino en el dispositivo. Añade otros 100K usuarios y la factura es la misma.

La configuración: un agente de triaje de soporte al cliente

Construiremos un agente de triaje que clasifica las solicitudes de soporte entrantes, busca al cliente, crea un ticket si es apropiado, y escala a un humano si la solicitud es de alta severidad. Tiene tres herramientas y un alcance claro, lo que lo convierte en un buen candidato para fine-tuning.

Comienza con un proyecto Python fresco e instala el OpenAI Agents SDK.

pip install openai-agents

Aquí está el agente. Es intencionalmente corto — unas 25 líneas de código significativo — porque el SDK está bien diseñado.

from agents import Agent, Runner, function_tool
from pydantic import BaseModel

class TriageDecision(BaseModel):
    category: str
    severity: int
    ticket_id: str | None = None
    escalated: bool = False

@function_tool
def lookup_customer(email: str) -> dict:
    """Look up customer details by email address."""
    return crm.get_customer(email)

@function_tool
def create_ticket(customer_id: str, summary: str, severity: int) -> str:
    """Create a support ticket. Returns the ticket ID."""
    return tickets.create(customer_id, summary, severity)

@function_tool
def escalate(customer_id: str, reason: str) -> bool:
    """Escalate to a human agent for high-severity issues."""
    return on_call.page(customer_id, reason)

triage_agent = Agent(
    name="Support Triage",
    instructions="Triage inbound support requests. Look up the customer, "
                 "create a ticket, and escalate severity 4 or 5 issues.",
    tools=[lookup_customer, create_ticket, escalate],
    output_type=TriageDecision,
)

result = Runner.run_sync(
    triage_agent,
    "alice@example.com says her production database is unreachable and customers are seeing errors."
)
print(result.final_output)

Por defecto esto se ejecuta contra un modelo hospedado de OpenAI, con el nombre de modelo que tengas configurado en OPENAI_API_KEY y los predeterminados del SDK. Verás que el agente llama a lookup_customer, luego a create_ticket, luego a escalate porque la severidad es alta, y emite un TriageDecision validado. El flujo toma unos segundos y produce un objeto estructurado que puedes enrutar hacia tu sistema de soporte.

Hasta aquí esto es uso del OpenAI Agents SDK estándar. Ahora cambiamos el modelo.

El cambio: apunta el SDK a tu modelo local

El OpenAI Agents SDK expone un cliente AsyncOpenAI a través de OpenAIChatCompletionsModel y OpenAIResponsesModel. Ambos aceptan un base_url. Esa es toda la costura. Apunta el cliente a cualquier endpoint compatible con OpenAI y el SDK lo usa para completaciones, llamadas a herramientas y salidas estructuradas de la misma forma que lo haría con la API hospedada.

Para desarrollo local, Ollama es el camino de menor resistencia. Expone un endpoint compatible con OpenAI en http://localhost:11434/v1 listo para usar.

Aquí está el cambio. Este es el único cambio requerido para mover el agente del modelo hospedado de OpenAI a uno local ajustado.

from openai import AsyncOpenAI
from agents import set_default_openai_client, set_default_openai_api

client = AsyncOpenAI(base_url="http://localhost:11434/v1", api_key="not-needed")
set_default_openai_client(client)
set_default_openai_api("chat_completions")

triage_agent = Agent(
    name="Support Triage",
    model="ertas-triage-7b",
    instructions="...",
    tools=[lookup_customer, create_ticket, escalate],
    output_type=TriageDecision,
)

Cinco líneas. La llamada Runner.run_sync, las definiciones de herramientas, el esquema de salida estructurada — todos sin cambios. El agente ahora se ejecuta enteramente contra un modelo en tu portátil o tu propia instancia GPU.

Por qué importa el fine-tuning aquí

Puedes detenerte después del cambio si solo te importa el coste. Pero no deberías, porque un modelo open-weight 7B genérico no es realmente lo suficientemente bueno para este tipo de agente. Los números suelen ser decepcionantes de una forma específica: el modelo elige la herramienta correcta la mayor parte del tiempo, rellena los nombres de parámetros correctos la mayor parte del tiempo, y acierta con los valores de los parámetros la mayor parte del tiempo, y "la mayor parte del tiempo" multiplicado a través de un bucle de 5 llamadas es una tasa de éxito de extremo a extremo del 60%.

Rangos representativos para un agente de estilo triaje como el de arriba, extraídos de los sub-puntajes públicos de BFCL v4 y de los resultados típicos post-fine-tune que Studio reporta contra conjuntos de evaluación reservados:

• Llama 3.1 8B genérico: precisión de nombre de herramienta y nombre de parámetro en los 80 bajos a medios en conjuntos de herramientas amplios, precisión de valor de parámetro ligeramente menor. Completación de tarea de extremo a extremo en los 70 una vez que esas tasas de error se acumulan a través de un bucle de 5 llamadas.
• Qwen3-7B / Qwen3-8B genérico: 80 bajos a medios en las tres sub-métricas en conjuntos de herramientas amplios. Completación de extremo a extremo en los 70 altos.
• Modelo 7B–8B ajustado por Ertas entrenado en 400–600 ejemplos representativos: típicamente supera el 95% en cada sub-métrica para la superficie de herramientas entrenada. Completación de extremo a extremo en los 90 medios una vez que los esquemas son estables.

Tus propios números se situarán en algún lugar de esas bandas dependiendo del conteo de herramientas, complejidad del esquema y calidad del dataset. La brecha del fine-tuning es la diferencia entre un prototipo divertido y un sistema de producción. Una tasa de completación del 95% está en el mismo rango que un modelo frontier hospedado en este tipo de tarea agéntica acotada. Una tasa de completación del 79% no lo está.

La forma de los datos de entrenamiento que te lleva ahí es directa. Quieres alrededor de 500 ejemplos cubriendo las combinaciones de herramientas que el agente realmente usa en producción: llamadas de una sola herramienta (los casos simples), secuencias multi-herramienta (los casos realistas), casos límite de validación (cuando el modelo necesita reconocer información incompleta y preguntar de vuelta), y rechazos (cuando el modelo necesita reconocer solicitudes fuera de alcance). El módulo Data Craft de Studio genera el grueso de estos a partir de una plantilla de prompt estructurada — escribes 30 a 50 ejemplos semilla a mano, el resto viene de un pase de generación guiada que valida cada ejemplo contra tus esquemas de herramientas antes de que aterrice en el dataset.

Un fine-tune QLoRA de una base de 7B en 500 ejemplos se completa en menos de una hora en el nivel estándar de GPU. La suite de evaluación de Studio reporta las tres métricas de precisión de arriba contra un conjunto de validación reservado, y marca las combinaciones específicas de herramienta/parámetro donde el modelo aún es débil para que puedas dirigir el dataset hacia las brechas y ejecutar entrenamiento incremental.

Paridad de tracing

El OpenAI Agents SDK tiene un sistema de tracing que captura cada llamada al modelo, cada invocación de herramienta y cada handoff en una traza unificada. Puedes ver las trazas en el panel de OpenAI, o enviarlas a Logfire, Datadog o cualquier backend OTLP.

La cosa que importa operativamente: el sistema de tracing funciona idénticamente ya sea que el modelo de respaldo sea el endpoint hospedado de OpenAI o tu modelo local servido por Ollama. Cada llamada al modelo, cada llamada a herramienta, cada reintento aparece en la misma UI de trazas con la misma estructura. Puedes desarrollar el agente contra el modelo hospedado de OpenAI donde la iteración es más rápida, enviar la versión de producción contra tu modelo local ajustado, e inspeccionar trazas de ambos en el mismo panel.

Esto es más importante de lo que parece. Una de las razones por las que los equipos de agentes permanecen en APIs hospedadas más tiempo del que deberían es que la observabilidad es tan buena contra modelos hospedados — las trazas son limpias, el panel funciona, el equipo tiene memoria muscular para él. El instinto de cambiar el modelo se mata por la suposición de que la capa de observabilidad se va con él. Con el OpenAI Agents SDK, no se va. La UI de trazas es parte del SDK, no parte del servicio del modelo hospedado.

Patrones de despliegue en producción

Tres patrones de despliegue cubren la mayoría de los casos que llegan a través de productos agénticos reales.

Patrón backend: vLLM detrás de un endpoint privado. Para agentes que se ejecutan en tus servidores y llaman a tu propia infraestructura, el despliegue correcto es vLLM sirviendo el modelo ajustado en una sola instancia GPU, con el OpenAI Agents SDK apuntado al endpoint vLLM en lugar de al de OpenAI. El servidor compatible con OpenAI de vLLM admite llamadas a herramientas, salidas estructuradas y batching lo suficientemente bien para tráfico de producción. Una sola instancia A10 maneja unos cuantos cientos de flujos agénticos concurrentes dependiendo de la longitud del contexto. El flujo de exportación de Studio produce tanto un binario GGUF (para Ollama y llama.cpp) como el checkpoint safetensors original (para vLLM y TGI), así que no tienes que elegir en tiempo de entrenamiento.

Patrón en el dispositivo: envía el modelo dentro de la aplicación. Para aplicaciones móviles y de escritorio donde ejecutar el agente en el dispositivo del usuario es factible, el Ertas Deployment CLI envía el modelo ajustado como un binario GGUF a proyectos de iOS, Android, Flutter o React Native con los enlaces móviles de llama.cpp. El modelo desplegado expone la misma interfaz compatible con OpenAI localmente en el dispositivo. El código Python o TypeScript del OpenAI Agents SDK (típicamente ejecutándose en un backend que controlas) apunta al endpoint local del dispositivo cuando la arquitectura lo requiere, o haces puente a un runtime nativo a través de una capa RPC delgada. Los documentos de Ertas cubren ambos caminos.

Patrón híbrido: camino rápido local, camino complejo API. Para agentes donde la distribución de carga de trabajo es desigual — la mayoría de las tareas son rutinarias, unas pocas son exóticas — la respuesta correcta es enrutar. El camino rápido ejecuta el modelo local ajustado. El camino lento o inusual cae al modelo frontier hospedado. El OpenAI Agents SDK hace esto limpiamente: define dos instancias Agent con diferentes configuraciones de model, escribe un agente enrutador de nivel superior que hace handoff basado en clasificación, y tienes una arquitectura que paga precios de API hospedada solo para las llamadas que realmente lo necesitan. En la práctica esto colapsa el 80 al 95% del coste de tokens mientras preserva el comportamiento del modelo frontier en los casos genuinamente difíciles.

La composición

El OpenAI Agents SDK es la mejor experiencia de desarrollador en su clase para código de agentes Python y TypeScript en 2026. El modelo ajustado entrenado por Ertas es el mejor modelo económico en su clase para cargas de trabajo agénticas en producción. No fueron diseñados el uno para el otro, y eso es precisamente por qué se componen tan bien — el diseño agnóstico al modelo del SDK significa que no necesita saber nada sobre tu modelo, y tu modelo ajustado no necesita saber nada sobre el SDK. La interfaz HTTP compatible con OpenAI es el contrato, y mientras ambos lados lo honren, el resto es tubería.

Para un equipo que ha prototipado contra OpenAI y ahora está mirando la curva de costes, la migración es inusualmente indolora. Cinco líneas de configuración. Un fine-tune en Studio. Mismo código, mismas trazas, mismo flujo de agente. Diferente factura.