Migrar del SDK de Agentes de OpenAI a la API de Agentes: ¿Qué cambia realmente a nivel arquitectónico?

Migrar del SDK de Agentes de OpenAI a la API de Agentes no es un simple cambio de nombre en las importaciones. El límite arquitectónico central cambia: el SDK ejecuta el bucle del agente dentro de tu aplicación, mientras que la API de Agentes ejecuta un harness de Codex gestionado y una sesión duradera del lado de OpenAI. Por lo tanto, la pregunta de la migración no es "¿Qué clases se asignan a qué endpoints?" sino "¿Qué responsabilidades de tiempo de ejecución cruzan el límite, cuáles permanecen en nuestra aplicación y cuáles necesitan ser rediseñadas?"

La migración es de un bucle propiedad de la aplicación a un harness gestionado

En el SDK de Agentes, una ejecución es un turno a nivel de aplicación. El runner del SDK llama al modelo, inspecciona la salida, ejecuta herramientas, sigue los handoffs y continúa hasta alcanzar un punto de parada. Tu proceso aloja ese bucle y, por lo tanto, es dueño de su ciclo de vida.

En la API de Agentes, OpenAI ejecuta el harness. Una sesión es una instancia duradera de una configuración de agente que acepta tareas, produce eventos, puede pausarse para acciones requeridas y puede continuar a lo largo del tiempo. OpenAI gestiona las sesiones, la orquestación, la compactación de contexto y la recuperación; tu aplicación envía trabajo, maneja herramientas de función, recibe eventos y opcionalmente gestiona un entorno de ejecución autoalojado.

Ese cambio de propiedad es la migración. Todo lo demás — sintaxis de la API, esquemas de herramientas, manejo de eventos, IDs de sesión — se deriva de ello.

El Mapa de Migración de Límites de Tiempo de Ejecución

Qué puede migrar conceptualmente sin cambiar la propiedad

Varios conceptos de la aplicación sobreviven la migración sin problemas aunque su representación cambie. Los modelos, las instrucciones, las definiciones de funciones con esquema JSON, el acceso a MCP, las descripciones de herramientas y los requisitos de salida estructurada siguen siendo aspectos de la configuración del agente.

El modelo de configuración de la API de Agentes de OpenAI define explícitamente un agente a través del modelo, las instrucciones, las herramientas, el razonamiento y el comportamiento de salida. Las herramientas de función siguen siendo código de la aplicación: el harness solicita una llamada a función y tu manejador devuelve el resultado. OpenAI también señala que las implementaciones de funciones usadas con la API de Respuestas pueden reutilizarse con el flujo de sesión de la API de Agentes.

Qué no debe migrarse uno a uno

El patrón de migración peligroso es recrear cada abstracción de tiempo de ejecución del SDK dentro de la API de Agentes. Eso puede dejarte pagando por un harness gestionado mientras sigues operando un harness en la sombra en tu aplicación.

Paso 1 — Separar el estado del dominio del estado de la sesión del agente

Antes de tocar las llamadas a la API, clasifica el estado que tu aplicación SDK mantiene actualmente. Parte del estado existe solo para mantener la conversación del agente en marcha. Otro estado es la verdad del negocio: permisos de usuario, estado del proyecto, datos de pedidos, aprobación de flujos de trabajo, registros de clientes, versiones de documentos, estado de políticas o configuración de la aplicación.

La segunda categoría no debería volverse dependiente de una sesión de la API de Agentes. Una sesión duradera es una continuidad útil para el agente; no es un reemplazo de la fuente de verdad de tu producto. Si la sesión desaparece, expira, se reconstruye o cambia de implementación, tu aplicación debe seguir sabiendo qué es verdadero.

Paso 2 — Convertir la mentalidad de ejecutor en una mentalidad de sesión y eventos

Las aplicaciones SDK a menudo piensan en términos de llamar a run y recibir un resultado. La API de Agentes piensa en términos de una sesión duradera cuyos turnos pueden ejecutarse de forma asíncrona. Un mensaje a una sesión inactiva inicia el trabajo; un mensaje durante un turno activo puede dirigirlo. El progreso llega a través de streaming o webhooks.

Esto afecta la arquitectura de la aplicación. El trabajo de producción de larga duración no debería depender de que una sola solicitud HTTP permanezca activa. Tu producto necesita identificadores de sesión estables, persistencia del ciclo de vida, verificación de webhooks, manejadores idempotentes y una forma de reconciliar el estado actual de la sesión después de reinicios del proceso.

Paso 3 — Rediseñar las herramientas de función en torno a las acciones requeridas

Las herramientas de función siguen siendo una frontera importante de la aplicación. Defines la función y su esquema JSON en la configuración del agente. Cuando el harness necesita la función, la sesión puede entrar en un estado de acción requerida. Tu aplicación recupera la acción requerida, ejecuta la lógica de negocio y devuelve el resultado.

Eso significa que la implementación de la función debería ser segura de reanudar. Un webhook puede entregarse mientras otro trabajador está procesando. Puede ocurrir un fallo de red después del efecto secundario externo pero antes de que se devuelva el resultado. Por lo tanto, la migración es un buen momento para agregar IDs de llamada, claves de idempotencia, autorización explícita, políticas de tiempo de espera y registros de auditoría a las herramientas consecuentes.

Paso 4 — Decidir dónde debe ocurrir la ejecución

La API de Agentes separa el harness gestionado del entorno de ejecución. Un agente puede operar sin un entorno dedicado, en un sandbox alojado por OpenAI, o a través de un entorno autoalojado conectado a la sesión.

Esto crea una decisión de migración que las aplicaciones SDK quizás nunca hayan tomado explícitamente: ¿qué código debería ejecutarse como una función de aplicación, qué código pertenece a un sandbox y qué cargas de trabajo requieren infraestructura que tú controlas?

Paso 5 — Reemplazar la recuperación implícita con manejo explícito del ciclo de vida

El harness gestionado proporciona recuperación a nivel de sesión, pero tu aplicación sigue siendo dueña de cada dependencia externa a su alrededor. Los entornos autoalojados necesitan aprovisionamiento, reconexión y apagado. Los manejadores de funciones pueden fallar. Los webhooks pueden reintentarse. El estado del lado del producto puede cambiar mientras un agente está inactivo.

Por lo tanto, la migración necesita dos modelos de recuperación: recuperación del tiempo de ejecución del agente y recuperación de la operación de negocio. La primera es cada vez más gestionada por la API de Agentes. La segunda sigue siendo tu responsabilidad.

Paso 6 — Reconstruir la observabilidad en torno al nuevo límite de traza

Las sesiones de Agents API exponen eventos, historial guardado, turnos, llamadas a herramientas, subagentes y uso de tokens. OpenAI también proporciona registros de sesión en la plataforma y exportación de trazas.

No descartes la observabilidad de tu aplicación porque las trazas de la plataforma hayan mejorado. Los registros de producto aún necesitan conectar la sesión del agente con la identidad del usuario, la decisión de autorización, el objeto de dominio, el efecto secundario de la herramienta, el registro de aprobación y el resultado final aceptado. La traza de producción útil es la unión entre la evidencia del tiempo de ejecución del agente y la evidencia del tiempo de ejecución del negocio.

Paso 7 — Preservar las evaluaciones antes de cambiar el tiempo de ejecución

Una migración puede parecer exitosa porque el nuevo sistema aún produce respuestas plausibles mientras cambia silenciosamente la elección de herramientas, la continuidad de la sesión, el comportamiento de transferencia, la latencia o la recuperación de fallos. Construye la línea base de comportamiento antes de cambiar los tiempos de ejecución.

La línea base debe incluir tareas representativas, llamadas a herramientas esperadas, acciones prohibidas, puntos de aprobación, continuidad de estado, escenarios de recuperación y criterios de aceptación de la salida final. Ejecuta las arquitecturas antigua y nueva contra los mismos casos siempre que sea posible.

La prueba de migración

Qué medir durante la migración

Cuándo no migrar todavía

Una aplicación existente de Agents SDK no se convierte en mala arquitectura simplemente porque la dirección de la plataforma cambió. OpenAI continúa con el mantenimiento, las correcciones de seguridad, las correcciones de errores críticos y el trabajo de compatibilidad. Si la aplicación es estable, está bien evaluada y no tiene un requisito de hoja de ruta bloqueado, una migración inmediata del tiempo de ejecución puede no estar justificada.

• Una capacidad requerida del SDK aún no está disponible en la Agents API.
• La migración interrumpiría un período crítico de producción sin entregar valor a corto plazo.
• La aplicación depende de semánticas de orquestación personalizadas que no han sido validadas en el arnés gestionado.
• La portabilidad del proveedor es un requisito estricto y la abstracción actual del SDK es materialmente valiosa.
• Tu equipo aún no ha separado el estado de negocio del estado del tiempo de ejecución del agente, lo que hace insegura la transición.
• El comportamiento de la nueva Agents API no ha sido probado contra cargas de trabajo de producción representativas.

Cuándo la migración se vuelve estratégicamente importante

La migración se vuelve más convincente cuando los requisitos del producto se alinean con el arnés gestionado: trabajo duradero de larga duración, compactación y recuperación de contexto gestionadas por la plataforma, capacidades más nuevas del tiempo de ejecución del agente, ejecución en sandbox, gestión de ciclo de vida alojada más rica, o el deseo de reducir la cantidad de código de orquestación que opera tu aplicación.

La señal más fuerte no es "el SDK antiguo está completo en funciones". Es "nuestra hoja de ruta ahora depende de capacidades cuyo hogar natural es el tiempo de ejecución gestionado de Agents API".

Qué cambiaría esta respuesta

La estrategia de migración cambiaría si OpenAI publica herramientas de migración automatizadas, introduce capas de compatibilidad explícitas, cambia la semántica de sesión de la API de Agents, amplía o reduce el soporte de entornos autoalojados, o cambia la política de soporte del SDK de Agents.

También cambiaría si cambian los requisitos de tu producto. Un asistente simple de solicitud-respuesta puede que no necesite en absoluto un arnés gestionado duradero. Un agente de codificación, investigación u operaciones de larga duración puede beneficiarse mucho más del modelo de propiedad de la API de Agents.

Limitaciones

No existe un mapa universal uno a uno de migración de SDK a API porque las aplicaciones usan el SDK de Agents de manera diferente. Algunas dependen en gran medida de sesiones y traspasos; otras lo usan como un ejecutor ligero en torno a herramientas de función. La migración correcta depende de qué responsabilidades asume realmente tu aplicación hoy.

La API de Agents también está en beta pública, por lo que los detalles de implementación pueden evolucionar. Trata los principios de propiedad de este artículo como más duraderos que cualquier forma de endpoint individual.

Conclusión

Migrar del SDK de Agents a la API de Agents se entiende mejor como mover el límite del tiempo de ejecución del agente. El arnés gestionado asume más del bucle, la continuidad de sesión, la compactación y la recuperación. Tu aplicación debería volverse más explícita sobre las responsabilidades que siguen siendo tuyas: verdad del dominio, autorización, efectos secundarios de funciones, artefactos, auditabilidad y ciclo de vida del producto.

Si una migración deja toda la maquinaria de orquestación antigua en su lugar y simplemente reemplaza las llamadas al SDK con llamadas a la API de Agents, probablemente ha perdido la oportunidad arquitectónica. El objetivo no es reproducir el tiempo de ejecución antiguo sobre el nuevo. El objetivo es decidir qué responsabilidades del tiempo de ejecución ya no pertenecen a tu aplicación.

Preguntas frecuentes

Glosario

Fuentes primarias y lecturas adicionales

Migrar del SDK de Agentes de OpenAI a la API de Agentes no es un simple cambio de nombre de importación. El límite arquitectónico central cambia: el SDK ejecuta el bucle del agente dentro de tu aplicación, mientras que la API de Agentes ejecuta un arnés de Codex gestionado y una sesión duradera del lado de OpenAI. Por lo tanto, la pregunta de migración no es "¿Qué clases se asignan a qué endpoints?" sino "¿Qué responsabilidades de tiempo de ejecución cruzan el límite, cuáles permanecen en nuestra aplicación y cuáles necesitan ser rediseñadas?"

La migración es de un bucle propiedad de la aplicación a un arnés gestionado

En el SDK de Agentes, una ejecución es un turno a nivel de aplicación. El ejecutor del SDK llama al modelo, inspecciona la salida, ejecuta herramientas, sigue los traspasos y continúa hasta alcanzar un punto de parada. Tu proceso aloja ese bucle y por lo tanto posee su ciclo de vida.

En la API de Agentes, OpenAI ejecuta el arnés. Una sesión es una instancia duradera de una configuración de agente que acepta tareas, produce eventos, puede pausarse para acciones requeridas y puede continuar a lo largo del tiempo. OpenAI gestiona sesiones, orquestación, compactación de contexto y recuperación; tu aplicación envía trabajo, maneja herramientas de función, recibe eventos y opcionalmente gestiona un entorno de ejecución autoalojado.

Ese cambio de propiedad es la migración. Todo lo demás — sintaxis de API, esquemas de herramientas, manejo de eventos, IDs de sesión — se deriva de ello.

El Mapa de Migración de Límites de Tiempo de Ejecución

Qué puede migrar conceptualmente sin cambiar la propiedad

Varios conceptos de la aplicación sobreviven a la migración limpiamente aunque su representación cambie. Modelos, instrucciones, definiciones de funciones con esquema JSON, acceso MCP, descripciones de herramientas y requisitos de salida estructurada siguen siendo preocupaciones de configuración del agente.

El modelo de configuración de la API de Agentes de OpenAI define explícitamente un agente a través del modelo, instrucciones, herramientas, razonamiento y comportamiento de salida. Las herramientas de función siguen siendo código de la aplicación: el arnés solicita una llamada a función, y tu manejador devuelve el resultado. OpenAI también señala que las implementaciones de funciones utilizadas con la API de Respuestas pueden reutilizarse con el flujo de sesión de la API de Agentes.

Qué no debería migrarse uno a uno

El patrón de migración peligroso es recrear cada abstracción de tiempo de ejecución del SDK dentro de la API de Agentes. Eso puede dejarte pagando por un arnés gestionado mientras sigues operando un arnés en la sombra en tu aplicación.

Paso 1 — Separar el estado de dominio del estado de sesión del agente

Antes de tocar las llamadas a la API, clasifica el estado que tu aplicación del SDK transporta actualmente. Parte del estado existe solo para mantener la conversación del agente en marcha. Otro estado es verdad de negocio: permisos de usuario, estado del proyecto, datos de pedidos, aprobación de flujos de trabajo, registros de clientes, versiones de documentos, estado de políticas o configuración de la aplicación.

La segunda categoría no debería volverse dependiente de una sesión de la API de Agentes. Una sesión duradera es una continuidad útil para el agente; no es un reemplazo de la fuente de verdad de tu producto. Si la sesión desaparece, expira, se reconstruye o cambia de implementación, tu aplicación debe seguir sabiendo qué es verdadero.

Paso 2 — Convertir la mentalidad de runner en una mentalidad de sesión y eventos

Las aplicaciones del SDK a menudo piensan en términos de llamar a run y recibir un resultado. La API de Agentes piensa en términos de una sesión duradera cuyos turnos pueden ejecutarse de forma asíncrona. Un mensaje a una sesión inactiva inicia trabajo; un mensaje durante un turno activo puede dirigirlo. El progreso llega a través de streaming o webhooks.

Esto afecta la arquitectura de la aplicación. El trabajo de producción de larga duración no debería depender de que una solicitud HTTP permanezca viva. Tu producto necesita identificadores de sesión estables, persistencia del ciclo de vida, verificación de webhooks, manejadores idempotentes y una forma de reconciliar el estado actual de la sesión después de reinicios del proceso.

Paso 3 — Rediseñar las herramientas de función en torno a las acciones requeridas

Las herramientas de función siguen siendo una frontera importante de la aplicación. Defines la función y su esquema JSON en la configuración del agente. Cuando el arnés necesita la función, la sesión puede entrar en un estado de acción requerida. Tu aplicación recupera la acción requerida, ejecuta la lógica de negocio y devuelve el resultado.

Eso significa que la implementación de la función debería ser segura de reanudar. Un webhook puede entregarse mientras otro worker está procesando. Un fallo de red puede ocurrir después del efecto secundario externo pero antes de que se devuelva el resultado. Por lo tanto, la migración es un buen momento para agregar IDs de llamada, claves de idempotencia, autorización explícita, políticas de tiempo de espera y registros de auditoría a las herramientas consecuentes.

Paso 4 — Decidir dónde debería ocurrir la ejecución

La API de Agentes separa el arnés gestionado del entorno de ejecución. Un agente puede operar sin un entorno dedicado, en un sandbox alojado por OpenAI, o a través de un entorno autoalojado conectado a la sesión.

Esto crea una decisión de migración que las aplicaciones del SDK quizás nunca hayan tomado explícitamente: qué código debería ejecutarse como una función de aplicación, qué código pertenece a un sandbox y qué cargas de trabajo requieren infraestructura que tú controles.

Paso 5 — Reemplazar la recuperación implícita con manejo explícito del ciclo de vida

El harness gestionado proporciona recuperación a nivel de sesión, pero tu aplicación sigue siendo responsable de cada dependencia externa a su alrededor. Los entornos autoalojados necesitan aprovisionamiento, reconexión y apagado. Los manejadores de funciones pueden fallar. Los webhooks pueden reintentarse. El estado del lado del producto puede cambiar mientras un agente está inactivo.

Por lo tanto, la migración necesita dos modelos de recuperación: recuperación del tiempo de ejecución del agente y recuperación de la operación de negocio. La primera está cada vez más gestionada por la Agents API. La segunda sigue siendo tu responsabilidad.

Paso 6 — Reconstruir la observabilidad en torno al nuevo límite de traza

Las sesiones de la Agents API exponen eventos, historial guardado, turnos, llamadas a herramientas, subagentes y uso de tokens. OpenAI también proporciona registros de sesión en la plataforma y exportación de trazas.

No descartes la observabilidad de tu aplicación porque las trazas de la plataforma hayan mejorado. Los registros del producto todavía necesitan conectar la sesión del agente con la identidad del usuario, la decisión de autorización, el objeto de dominio, el efecto secundario de la herramienta, el registro de aprobación y el resultado final aceptado. La traza de producción útil es la unión entre la evidencia del tiempo de ejecución del agente y la evidencia del tiempo de ejecución del negocio.

Paso 7 — Preservar las evaluaciones antes de cambiar el tiempo de ejecución

Una migración puede parecer exitosa porque el nuevo sistema sigue produciendo respuestas plausibles mientras cambia silenciosamente la elección de herramientas, la continuidad de la sesión, el comportamiento de traspaso, la latencia o la recuperación de fallos. Construye la línea base de comportamiento antes de cambiar los tiempos de ejecución.

La línea base debe incluir tareas representativas, llamadas a herramientas esperadas, acciones prohibidas, puntos de aprobación, continuidad del estado, escenarios de recuperación y criterios de aceptación del resultado final. Ejecuta las arquitecturas antigua y nueva contra los mismos casos siempre que sea posible.

La prueba de verificación de la migración

Qué medir durante la migración

Cuándo no migrar todavía

Una aplicación existente del Agents SDK no se convierte en mala arquitectura simplemente porque la dirección de la plataforma cambió. OpenAI continúa con el mantenimiento, las correcciones de seguridad, las correcciones de errores críticos y el trabajo de compatibilidad. Si la aplicación es estable, está bien evaluada y no tiene un requisito de hoja de ruta bloqueado, una migración inmediata del tiempo de ejecución puede no estar justificada.

• Una capacidad requerida del SDK aún no está disponible en la Agents API.
• La migración interrumpiría un período crítico de producción sin entregar valor a corto plazo.
• La aplicación depende de semánticas de orquestación personalizadas que no han sido validadas en el harness gestionado.
• La portabilidad del proveedor es un requisito estricto y la abstracción actual del SDK es materialmente valiosa.
• Tu equipo aún no ha separado el estado de negocio del estado del tiempo de ejecución del agente, lo que hace inseguro el cambio.
• El comportamiento de la nueva Agents API no ha sido probado contra cargas de trabajo de producción representativas.

Cuándo la migración se vuelve estratégicamente importante

La migración resulta más convincente cuando los requisitos del producto se alinean con el harness gestionado: trabajo duradero de larga duración, compactación y recuperación de contexto gestionadas por la plataforma, capacidades más recientes del runtime de agentes, ejecución en sandbox, gestión de ciclo de vida alojada más completa, o el deseo de reducir la cantidad de código de orquestación que opera tu aplicación.

La señal más fuerte no es "el SDK antiguo está completo en funciones". Es "nuestra hoja de ruta ahora depende de capacidades cuyo hogar natural es el runtime gestionado de la Agents API".

¿Qué cambiaría esta respuesta?

La estrategia de migración cambiaría si OpenAI publica herramientas de migración automatizadas, introduce capas de compatibilidad explícitas, cambia la semántica de sesión de la Agents API, amplía o reduce el soporte de entornos autoalojados, o cambia la política de soporte del Agents SDK.

También cambiaría si cambian los requisitos de tu producto. Un asistente simple de solicitud-respuesta puede que no necesite un harness gestionado duradero en absoluto. Un agente de codificación, investigación u operaciones de larga duración puede beneficiarse mucho más del modelo de propiedad de la Agents API.

Limitaciones

No existe un mapa universal uno a uno de migración de SDK a API porque las aplicaciones usan el Agents SDK de manera diferente. Algunas dependen en gran medida de sesiones y handoffs; otras lo usan como un runner ligero alrededor de herramientas de función. La migración correcta depende de qué responsabilidades asume realmente tu aplicación hoy.

La Agents API también está en beta pública, por lo que los detalles de implementación pueden evolucionar. Trata los principios de propiedad de este artículo como más duraderos que cualquier forma de endpoint individual.

Conclusión

Migrar del Agents SDK a la Agents API se entiende mejor como mover la frontera del runtime de agentes. El harness gestionado asume más del bucle, la continuidad de sesión, la compactación y la recuperación. Tu aplicación debería volverse más explícita sobre las responsabilidades que siguen siendo tuyas: verdad de dominio, autorización, efectos secundarios de funciones, artefactos, auditabilidad y ciclo de vida del producto.

Si una migración deja toda la maquinaria de orquestación antigua en su lugar y simplemente reemplaza las llamadas al SDK con llamadas a la Agents API, probablemente ha perdido la oportunidad arquitectónica. El objetivo no es reproducir el runtime antiguo sobre el nuevo. El objetivo es decidir qué responsabilidades del runtime ya no pertenecen a tu aplicación.

Preguntas frecuentes

Glosario

Fuentes primarias y lecturas adicionales