OpenAI Agents API vs Agents SDK: diferencias y elección
Agents API vs Agents SDK vs Responses: diferencias en la aplicación
| Decisión | Agents API | Agents SDK | Responses API directa |
|---|---|---|---|
| ¿Quién ejecuta la orquestación? | Servicio gestionado de OpenAI | Tu aplicación con el SDK | Tu aplicación o motor existente |
| ¿Dónde se representa el trabajo que continúa? | Sesiones gestionadas vinculadas a tareas de negocio | Integración de sesiones y estado elegida | Registro del flujo de trabajo y funciones de estado de la API utilizadas |
| ¿Cómo funcionan las herramientas de negocio? | Los handlers de la aplicación siguen ejecutando funciones | Herramientas SDK integradas con el código propio | Tu dispatcher ejecuta el trabajo que corresponde al cliente |
| ¿Principal contrapartida? | Menos operación del runtime, frontera externa | Control del runtime y responsabilidad de despliegue | Composición directa y responsabilidad explícita del flujo |
| ¿Qué sobrevive a cambiar el runtime? | Solo lo mantenido portable fuera del servicio | Registros de negocio y adaptadores independientes | Registros y contratos del flujo conservados |
La última fila es una recomendación arquitectónica. Ninguna etiqueta garantiza portabilidad. La implementación de una herramienta puede reutilizarse mientras sus llamadas pendientes, aprobaciones y formato de resultado necesitan adaptación.
¿Agents API reemplazará LangGraph o tu framework actual?
Depende de la función del framework en el producto. Si mantiene principalmente un bucle genérico de modelo y herramientas, un runtime gestionado puede sustituir buena parte del trabajo. Si codifica rutas de negocio, aprobaciones, plazos y estado de dominio duradero, esas responsabilidades siguen necesitando un propietario.
Un flujo de documentos de seguros puede extraer información, esperar a un revisor autorizado y enviar el resultado aprobado a otro sistema. El razonamiento puede cambiar de runtime sin cambiar quién aprueba. Reemplazar todo el flujo porque una etapa ahora se gestiona externamente mezcla política de negocio con infraestructura.
Clasifica cada componente como regla de negocio, mecanismo de ejecución o adaptador. Después identifica qué mecanismos puede sustituir realmente el servicio. Es una estimación de migración más útil que comparar líneas de dos ejemplos iniciales.
También cabe un híbrido: conserva un flujo externo determinista y delega una investigación acotada a Agents API. Define para esa etapa una única entrada, la evidencia esperada y una condición de retorno. Evita que el flujo externo y el runtime interno decidan por separado repetir la misma escritura en un sistema externo.
Esto no afirma que todos los frameworks mencionados carezcan de servicios gestionados ni que uno haya quedado obsoleto. Evalúa responsabilidades de tu implementación, no una clasificación universal de marcas.
Sesiones, memoria y aprobaciones no son el mismo estado
RunState serializado. La diferencia es quién despliega y opera el mecanismo, no la existencia de memoria o aprobaciones.Para un asistente de revisión de reembolsos, separa tres registros:
| Registro | Contenido de ejemplo | Por qué no basta la conversación |
|---|---|---|
| Contexto de trabajo | Evidencia y explicación candidata | Ayuda a razonar, pero no es el registro de autorización |
| Estado de ejecución | Ejecución actual, llamada pendiente, referencia de continuación | Identifica dónde reanudar |
| Estado de negocio | Cliente, importe propuesto, revisor e identificador final de transacción | Acredita qué se permitió y qué ocurrió |
Son registros conceptuales propuestos, no tres tablas obligatorias ni un esquema OpenAI. Permiten comprobar si una acción sigue autorizada antes de ejecutarla tras reanudar. Si el cliente cancela mientras espera aprobación, no debe reaparecer el permiso anterior.
Vincula sesiones gestionadas al trabajo de negocio. Con el SDK, decide dónde guardar las sesiones y las ejecuciones pausadas, y cómo las recuperará un worker. Con Responses, define la continuación equivalente en tu workflow. Prueba un reinicio de proceso durante la aprobación; una demo en memoria no demuestra recuperación.
¿Un sandbox privado equivale a autoalojar todo el agente?
Traza el camino real de los datos. En una investigación de base de datos, distingue consulta, filas devueltas, resultado enviado al modelo y traza guardada. Tener la base en una VPC no garantiza que sus resultados nunca salgan.
¿Y si necesitas elegir entre varios modelos?
Separa la interfaz del modelo de la interfaz del runtime. Un gateway con varios modelos facilita la selección, pero no hace iguales todos los ciclos de sesión ni protocolos de herramientas.
Evalúa primero runtimes con el mismo modelo, herramientas, datos y criterios cuando sea posible. Después compara modelos dentro de la arquitectura elegida. Si un candidato requiere otro modelo o configuración, denomina el resultado comparación de sistemas completos; no atribuyas toda mejora al runtime.
En rutas SDK, verifica mensajes de entrada, argumentos y resultados de herramientas, salida estructurada, streaming, uso y errores del adaptador. Una respuesta de texto no demuestra compatibilidad con agentes intensivos en herramientas. La flexibilidad de proveedores del SDK no implica que la API gestionada admita cualquier modelo de gateway.
La frontera útil para un fallback suele ser una tarea de negocio nueva: envíala a una alternativa verificada con un registro de ejecución nuevo. Mover una sesión en curso requiere conversión de estado y política de reproducción explícitas; cambiar la URL base no sustituye ese diseño.
Elegir por carga, incluso si conviene mantener lo actual
| Carga y situación | Primer candidato | Motivo | Qué haría cambiar la elección |
|---|---|---|---|
| Equipo pequeño, investigaciones variables, poca orquestación | Agents API | Operar el runtime sería una carga nueva importante | Datos incompatibles o ausencia de mejora de calidad/operación |
| Producto con aprobaciones propias y workers | Agents SDK | Ejecución próxima a controles existentes | Operar workers y estado cuesta más que el control obtenido |
| Motor fiable con pocos pasos fijos de modelo | Responses directa | Reutiliza la máquina de estados | Hace falta un bucle adaptativo que no se puede mantener económicamente |
| Muchos archivos y cómputo interno especializado | SDK o API gestionada con entorno propio | Evaluar ambos sobre la infraestructura real | No se satisface conexión, aislamiento o recuperación |
| Varias investigaciones independientes | Orquestación gestionada o SDK | El paralelismo puede acortar la ruta crítica | Síntesis, duplicación o verificación anulan la ventaja |
Probar la recuperación donde puede duplicarse una acción
Usa un escenario de tickets no productivo. La tarea investiga y crea exactamente un ticket tras aprobarse. Interrumpe al cliente después de que el destino acepte el ticket, pero antes de guardar el resultado de la herramienta en la aplicación. Es una propuesta de inyección de fallo, no un defecto reportado del proveedor.
Aprueba el escenario solo si la aplicación sabe si existe el ticket, evita duplicarlo y reanuda o termina en estado conocido. Si hay ambigüedad, envíala a revisión. Reintentar a ciegas puede empeorar la fiabilidad real aunque la demo parezca resistente.
Comparar costo por resultado aceptado, no solo tokens
Divide cargos directos por resultados aceptados y registra ingeniería aparte. Incluye fallos, herramientas, entornos y rescates. Un runtime puede reducir esfuerzo operativo y aumentar gasto API, o al revés; muestra ese intercambio.
La migración tiene punto de equilibrio. Supón $1,200 de integración y validación estimados internamente, y después un ahorro verificado de $0.04 por tarea aceptada en operación estable. Recuperar la inversión exige 30,000 tareas aceptadas, antes de diferencias operativas recurrentes. Son hipótesis: sustitúyelas por tus datos. Si no alcanzarás ese volumen, el pequeño ahorro unitario puede no justificar migrar.
Compara tiempos equivalentes: primer progreso, artefacto aceptado y revisión humana. No enfrentes primer token de streaming con informe plenamente validado. Mide preparación y limpieza de entornos además de procesamiento para detectar arranques en frío o esperas dominantes.
Exportar trazas ayuda al diagnóstico, pero no basta para auditar
Una traza y un resultado de negocio aceptado responden a preguntas diferentes. Relaciona trabajo, traza, llamada y ticket destino. Un revisor ajeno al test debe poder explicar por qué se creó el ticket y si estaba autorizado. Exportar más spans no cierra por sí solo una brecha de evidencia.
Mantén observaciones de modelos/herramientas separadas de cargos hasta conciliarlas. Una captura del panel no prueba la economía unitaria final; una llamada registrada no demuestra que el cambio se haya confirmado en destino.
Migración con una frontera real para volver atrás
- Congela la referencia. Guarda tareas, versiones de herramientas, criterios y resultados. Incluye tarea larga, entrada ambigua, pausa de aprobación y fallo externo.
- Haz pruebas emparejadas. Mismo modelo y presupuesto cuando sea posible; registra diferencias. Conserva varios intentos de las tareas cuyos resultados varían e informa del tamaño de la muestra, no solo de la mejor salida.
- Prueba en sombra y solo lectura. El agente paralelo no debe enviar mensajes ni duplicar escrituras. Aplica los mismos criterios de aceptación.
- Introduce tareas nuevas gradualmente. Asigna runtime al iniciar el trabajo y mantén ese propietario durante su ciclo. No dividas una tarea activa entre controladores desincronizados.
- Revierte deliberadamente. Devuelve trabajos nuevos a la referencia. Deja terminar los activos o concilia efectos y artefactos antes de reemplazarlos. Preserva la evidencia de transición.
Fija umbrales antes de ver resultados. La calidad debe cumplir los requisitos existentes; escrituras no autorizadas y efectos duplicados bloquean el despliegue. Presupuestos de costo y latencia dependen del negocio. No existe un «95 % listo para producción» universal que los sustituya.
Ejemplo: conservar soporte y sustituir solo la investigación
Una aplicación SDK recibe una incidencia, reúne evidencia de cuenta, espera aprobación y crea un ticket. Una primera migración útil reemplaza únicamente la investigación. La tarea gestionada devuelve borrador y referencias; la aplicación conserva aprobación y creación. Es un diseño propuesto, no una migración probada.
| Componente actual | ¿Conservar o adaptar? | Trabajo concreto |
|---|---|---|
| Identidad, permisos y esquema del ticket | Conservar contrato de negocio | Proporcionar mismos registros autorizados y campos obligatorios |
| Runner SDK de investigación | Sustituir en el piloto | Iniciar sesión gestionada y asociarla al trabajo existente |
| Herramientas | Reutilizar contratos compatibles, adaptar despacho | Convertir argumentos y resultados, conservar las comprobaciones de permisos y registrar fallos |
Aprobación pendiente y RunState guardado | Mantener propietario de tareas activas | Terminar o conciliar ejecución antigua; no tratar su estado serializado como una importación a una sesión gestionada |
| Progreso y resultado en pantalla | Adaptar correspondencias | Diferenciar investigación, borrador pendiente y ticket realmente creado |
| Trazas y facturación | Añadir referencias | Relacionar ejecución con tarea, aceptación y registro de costos |
El primer piloto puede terminar en «borrador listo para revisión». No es necesario trasladar todo simultáneamente. Si mejora la investigación pero empeora recuperar una aprobación, conserva esa ruta en la aplicación y reduce el alcance de la migración.
RunState serializado incluye trabajo pendiente y decisiones, pero deserializarlo no autentica a quien lo envió. Guárdalo bajo control de la aplicación, comprueba que el revisor esté autorizado para la acción pendiente y coordina la reanudación para no consumir dos veces una aprobación. Ese trabajo continúa aunque cambie el runtime de investigación.Preguntas frecuentes
¿Agents API vuelve obsoletos los frameworks?
Puede sustituir mecánica genérica, pero reglas de negocio, aprobaciones y estado del dominio siguen necesitando propietario. Evalúa componentes, no nombres.
¿Agents SDK carece de estado?
No. Documenta sesiones e implementaciones persistentes. Tu aplicación sigue operando despliegue y almacenamiento.
¿Puedo mantener aprobación humana con SDK?
Sí: documenta interrupciones y estado reanudable. Prueba reinicios y cambios de autorización en tu despliegue, no solo una demo en memoria.
¿El cómputo propio hace Agents API compatible con ZDR?
No, según la documentación actual. Revisa también todos los flujos de datos en alternativas SDK; la orquestación local no garantiza las condiciones de retención de datos.
¿Basta cambiar la URL base para cambiar runtime?
No lo asumas. Herramientas reutilizables no evitan adaptar y probar sesiones, llamadas pendientes, estado y resultados.
¿Qué opción es más barata?
Mide el mismo resultado aceptado incluyendo fallos y rescates, más migración y operación. La aritmética anterior es hipotética, no declara un ganador.
¿Se pueden exportar trazas de Agents API?
La documentación oficial describe OTLP JSON. Prepara su conexión con monitorización y consulta el lanzamiento EvoLink para conocer la integración disponible.
¿Puedo usarlo mediante EvoLink hoy?
Fuentes y alcance
Las afirmaciones técnicas enlazan documentación primaria. HN y Reddit solo identifican preguntas API/SDK y frameworks. Cargas, cálculos y recomendaciones son propuestas editoriales, no un benchmark controlado, ahorro universal ni compatibilidad de gateway en producción.
