Cree una capa de compatibilidad de API de Responses en una puerta de enlace API de AI

No implementes /v1/responses traduciendo cada solicitud a /v1/chat/completions y esperando que la forma se acerque lo suficiente. Ese adaptador puede devolver texto, pero puede perder silenciosamente las partes que interesan a los desarrolladores: elementos de respuesta, estado del lado del servidor, llamadas a herramientas, continuidad del razonamiento, eventos del ciclo de vida de la transmisión, semántica de cancelación y atribución de uso a nivel de elemento.

El objetivo práctico es una capa de compatibilidad que trate la API de Responses como un protocolo más rico. Mantenga la compatibilidad con Finalizaciones de chat para los clientes existentes, pero cree Respuestas como su propia superficie de puerta de enlace con su propio modelo de estado, normalizador de flujo, libro de llamadas de herramientas, matriz de capacidades y reglas de respaldo.

¿Qué es un hecho, qué es una política y qué es una predicción?

Datos: OpenAI describe la API de Responses como capacidades unificadoras que anteriormente estaban divididas entre Finalizaciones de Chat y Asistentes, incluida la compatibilidad con herramientas como la búsqueda web, la búsqueda de archivos y el uso de computadoras. La API expone campos como previous_response_id, transmisión, selección de herramientas y herramientas integradas. La documentación del SDK muestra que previous_response_id puede proporcionar continuidad de la conversación, mientras que las instrucciones anteriores no se llevan a cabo automáticamente y deben reenviarse cuando aún deberían aplicarse. La referencia de transmisión de OpenAI incluye ciclos de vida de respuesta distintos y eventos de salida en lugar de solo deltas de tokens.

Recomendaciones: una puerta de enlace debe preservar esta semántica en lugar de aplanarla de forma predeterminada. Debería rechazar o degradar explícitamente las solicitudes cuando un proveedor de destino no pueda soportar el comportamiento requerido.

Predicción: más cargas de trabajo de agentes dependerán de la estructura del elemento de respuesta, los seguimientos de ejecución de herramientas y el contexto de razonamiento con estado. Las puertas de enlace que modelan esos conceptos ahora serán más fáciles de ampliar que las puertas de enlace que tratan las Respuestas como un punto final cosmético.

Defina un contrato de compatibilidad independiente para las Respuestas

El primer error de implementación es asumir que la compatibilidad con OpenAI significa un esquema universal de solicitud y respuesta. En la práctica, /v1/chat/completions y /v1/responses deberían ser contratos de compatibilidad separados.

Mantenga una capa compartida de autenticación, facturación, cuota y enrutamiento, pero separe la capa de protocolo:

• Superficie de finalización del chat: mensajes, opciones, deltas, llamadas de herramientas en formato de chat, comportamiento del cliente heredado.
• Superficie de respuestas: elementos de entrada, elementos de salida, ID de respuesta, referencias de respuestas anteriores, eventos de herramientas más completos, eventos de secuencia del ciclo de vida, campos relacionados con el razonamiento y estado de respuesta final.

Esta división es importante para las pruebas de conformidad. Un adaptador de proveedor que pase las pruebas de chat aún puede fallar las pruebas de Respuestas porque no puede conservar previous_response_id, el orden de los elementos, la estructura de rechazo, los metadatos de las herramientas alojadas o los nombres de los eventos de transmisión.

Un contrato de compatibilidad mínima debería responder:

• ¿Qué campos de solicitud se aceptan, rechazan, transforman o ignoran?
• ¿Qué tipos de elementos de respuesta se conservan?
• ¿Qué tipos de herramientas son compatibles por proveedor y modelo?
• ¿Puede el proveedor mantener el estado de la conversación o debe mantenerlo la puerta de enlace?
• ¿Qué sucede cuando se solicita store=false?
• ¿Qué eventos de transmisión están garantizados?
• ¿Cómo se registran las cancelaciones, el tiempo de espera y el uso parcial?

Si ya tienes una puerta de enlace API AI, trata la compatibilidad con Respuestas como una expansión del protocolo, no como un alias de ruta.

Utilizar un modelo de elemento de respuesta canónico

La API de Responses devuelve más de un mensaje de asistente. Puede representar diferentes elementos de salida y eventos. Su puerta de enlace necesita un modelo canónico interno antes de asignarse a cualquier proveedor.

Un esquema práctico de elemento interno puede comenzar así:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "diez_123",
  "key_id": "key_456",
  "model_alias": "agente predeterminado",
  "proveedor": "openai",
  "artículos": [
    {
      "item_id": "item_1",
      "tipo": "texto",
      "rol": "asistente",
      "contenido": [{ "tipo": "output_text", "texto": "..." }],
      "estado": "completado"
    },
    {
      "item_id": "item_2",
      "tipo": "llamada_función",
      "call_id": "call_abc",
      "nombre": "lookup_order",
      "arguments_json": "{\"order_id\":\"123\"}",
      "estado": "completado"
    }
  ],
  "uso": {
    "tokens de entrada": 0,
    "tokens_salida": 0,
    "tokens_razonamiento": nulo,
    "unidades_herramientas": []
  },
  "estado": "completado"
}

Incluya tipos de elementos incluso antes de que cada proveedor pueda producirlos. Las categorías útiles incluyen:

• Salida de texto
• Rechazos
• Llamadas a funciones
• Salidas de funciones enviadas por la aplicación
• Resúmenes de razonamiento o metadatos relacionados con el razonamiento cuando estén disponibles
• Referencias de archivos
• Búsqueda web, búsqueda de archivos, uso de computadoras u otros eventos de herramientas alojadas
• Metadatos de facturación y uso final

El punto no es exponer un esquema propietario a los usuarios. El objetivo es evitar que el portal deseche información antes de que pueda auditarla, facturarla, transmitirla, reproducirla o transformarla.

Crear un libro de contabilidad estatal propiedad de la puerta de enlace

previous_response_id es el campo que más expone la diferencia entre el proxy de chat sin estado y la compatibilidad de Respuestas. Si un cliente hace referencia a una respuesta anterior, la puerta de enlace debe saber qué significa ese ID, si el inquilino puede usarlo y si el proveedor puede continuar a partir de él.

Cree un libro de estado con clave por inquilino e ID de respuesta:

{
  "gateway_response_id": "gw_resp_789",
  "provider_response_id": "resp_provider_789",
  "previous_gateway_response_id": "gw_resp_456",
  "tenant_id": "diez_123",
  "user_id": "usuario_999",
  "key_id": "key_456",
  "modelo": "gpt-...",
  "proveedor": "openai",
  "store_mode": "proveedor|puerta de enlace|ninguno",
  "retention_policy": "estándar|cero_retención|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "creado_at": "...",
  "expires_at": "...",
  "eliminado_at": nulo
}

Regla importante: no emule automáticamente previous_response_id reproduciendo el historial de chat completo a menos que el inquilino haya permitido explícitamente ese comportamiento de retención y costos. La repetición puede aumentar el costo del token, cambiar la postura de privacidad y alterar el comportamiento del modelo. Es más seguro devolver un error de capacidad claro que enviar silenciosamente contenido de conversación almacenado que la aplicación no esperaba que usted retuviera o reutilizara.

Modos de manejo de estados

• Estado del proveedor: el proveedor ascendente almacena suficiente contexto y la puerta de enlace asigna los ID de respuesta de la puerta de enlace a los ID de respuesta del proveedor.
• Estado de la puerta de enlace: la puerta de enlace almacena los elementos anteriores necesarios y reconstruye el contexto cuando está permitido.
• Sin estado: la solicitud utiliza store=false o la política del inquilino prohíbe la retención. previous_response_id debe rechazarse a menos que el proveedor pueda cumplir con la solicitud sin retención de puerta de enlace y la política lo permita.

Recuerde también que es posible que el cliente deba reenviar las instrucciones anteriores cuando deban continuar aplicándose. La puerta de enlace no debe inventar instrucciones ocultas para compensar a menos que ese comportamiento sea parte de una política explícita del inquilino.

Validar herramientas antes del envío

Responses hace que el uso de herramientas sea más central. Una capa de compatibilidad debe manejar dos categorías amplias:

• Herramientas de aplicación: definiciones de funciones proporcionadas por el cliente, ejecutadas fuera del proveedor del modelo, con resultados enviados a la API.
• Herramientas del proveedor alojadas: búsqueda web, búsqueda de archivos, uso de computadoras, ejecución de código, conexión a tierra o herramientas similares ejecutadas por el proveedor o la infraestructura controlada por la puerta de enlace.

Al ingresar, valide los esquemas de herramientas antes del enrutamiento:

• Rechazar pronto el esquema JSON no válido.
• Imponer el tamaño máximo del esquema y la profundidad de anidamiento.
• Compruebe los nombres de las herramientas para comprobar la compatibilidad del proveedor.
• Aplicar ámbitos de inquilino, clave, usuario y entorno.
• Requerir puertas de aprobación para herramientas que escriben datos, gastan dinero, acceden a sistemas confidenciales o llaman a conectores externos.

Para llamar a la función de la aplicación, se requiere una identificación de llamada estable. El modelo emite una llamada de función con call_id; la aplicación envía el resultado de la herramienta que hace referencia a ese ID; la puerta de enlace registra ambos en el mismo seguimiento. Sin esa clave de unión, los registros de auditoría y los reintentos se vuelven ambiguos.

Para herramientas alojadas, reserve el presupuesto antes del envío y liquide el costo después. Las herramientas alojadas pueden agregar cargos fuera de la contabilidad de tokens ordinaria, así que conecte el libro mayor de la herramienta a la facturación unificada de API de IA en lugar de ocultar esos costos dentro de un total de llamadas de modelo genérico.

Normalizar la transmisión como eventos, no como texto simbólico

Un proxy de chat a menudo puede salirse con la suya reenviando deltas de tokens. Una puerta de enlace de Responses no puede hacerlo. La secuencia tiene un significado de ciclo de vida: una respuesta puede comenzar, los elementos de salida pueden comenzar y completarse, el texto puede llegar en deltas, las llamadas a herramientas se pueden ensamblar de forma incremental, el uso puede llegar al final o durante la secuencia, y la respuesta puede fallar o cancelarse.

Defina un esquema de eventos de puerta de enlace y luego asigne cada flujo de proveedor a él:

evento: respuesta_iniciada
datos: { "response_id": "gw_resp_123", "status": "in_progress" }

evento: salida_item_starteddatos: { "item_id": "item_1", "tipo": "texto" }

evento: texto_delta
datos: { "item_id": "item_1", "delta": "Hola" }

evento: herramienta_call_delta
datos: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

evento: use_delta
datos: { "output_tokens": 12 }

evento: completado
datos: { "response_id": "gw_resp_123", "usage": { ... } }

Eventos normalizados recomendados:

• respuesta_iniciada
• output_item_started
• output_item_completed
• text_delta
• rechazo_delta
• tool_call_delta
• tool_result_received
• usage_delta
• completado
• cancelado
• falló

Cuando el cliente se desconecta, propaga la cancelación en sentido ascendente si el proveedor lo admite. Registre el estado de respuesta parcial de cualquier manera. Si el proveedor luego devuelve el uso final a través de una devolución de llamada retrasada o un fragmento final, concilie el libro mayor. La compatibilidad de streaming tiene que ver tanto con la contabilidad y el ciclo de vida como con la latencia.

Crear una matriz de capacidades del proveedor

El enrutamiento multimodelo es útil solo cuando la puerta de enlace comprende qué se puede enrutar de manera segura. Agregue capacidades específicas de Responses a su catálogo de modelos:

{
  "model_alias": "agente predeterminado",
  "rutas": [
    {
      "proveedor": "openai",
      "modelo": "...",
      "supports_responses": verdadero,
      "supports_previous_response_id": verdadero,
      "supports_store_false": verdadero,
      "supports_builtin_web_search": verdadero,
      "supports_function_calling": verdadero,
      "supports_stream_lifecycle_events": verdadero,
      "supports_reasoning_context_continuity": verdadero,
      "max_tool_schema_bytes": 65536
    },
    {
      "proveedor": "proveedor_b",
      "modelo": "...",
      "supports_responses": falso,
      "chat_adapter_available": verdadero,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

El respaldo debe tener en cuenta las pérdidas. Si la solicitud requiere una búsqueda web integrada y el proveedor alternativo no puede realizarla, no responda silenciosamente sin realizar una búsqueda. Si la solicitud depende del contexto de razonamiento preservado y la ruta alternativa no puede preservarlo, devuelva un error de capacidad o una respuesta de degradación que el cliente optó explícitamente.

Una opción de solicitud útil es:

{
  "modelo": "agente predeterminado",
  "entrada": "...",
  "política_de_alternativa": {
    "allow_lossy": falso,
    "pérdidas_permitidas": []
  }
}

Para casos de uso menos sensibles, los inquilinos pueden permitir degradaciones específicas con pérdida:

{
  "política_de_alternativa": {
    "allow_lossy": verdadero,
    "allowed_losses": ["flujo_aplanado", "sin_resumen_de_razonamiento"]
  }
}

La puerta de enlace debe registrar la decisión alternativa de cualquier manera. Esto hace posible la depuración posterior cuando un agente se comporta de manera diferente después de una interrupción del proveedor o un redireccionamiento del modelo.

Uso de atributos a nivel de respuesta y elemento

Las llamadas de respuesta pueden costar más que las completaciones de chat equivalentes porque pueden incluir ejecución de herramientas, contexto más extenso, tokens de razonamiento, búsqueda de archivos, búsqueda web o instrucciones repetidas. Un único recuento agregado de tokens no es suficiente para un panel de análisis de uso de API de IA.

Registrar el uso en dos niveles:

• Nivel de respuesta: inquilino, clave, usuario, modelo, proveedor, latencia, estado final, tokens de entrada, tokens de salida, tokens de razonamiento donde se informaron, costo total y ruta alternativa.
• Nivel de elemento/herramienta: nombre de la herramienta, ID de llamada, unidades de herramientas alojadas, ID de archivos, recuento de consultas de búsqueda si están disponibles, latencia de la herramienta, costo de la herramienta y resultado de la política de aprobación.

Esto permite a los desarrolladores responder preguntas concretas:

• ¿El costo aumentó debido a un estado más prolongado, esfuerzo de razonamiento, llamadas a herramientas o respaldo?
• ¿Qué inquilino o clave API genera cargos por herramientas alojadas?
• ¿Qué respuesta falló después de una llamada a la herramienta pero antes del texto final?
• ¿Qué transmisiones canceladas aún generan uso ascendente?

Manejar la retención cero y la eliminación como comportamiento de primera clase

El estado del lado del servidor es útil, pero cambia las obligaciones de retención de la puerta de enlace. Cree una política en la capa de protocolo en lugar de tratarla como una configuración de registro.

Para cada solicitud de Respuestas, resuelva:

• Política de retención de inquilinos
• Preferencia de tienda a nivel de solicitud
• Compatibilidad de retención de proveedores
• Si se permite la reproducción de la puerta de enlace
• Si se pueden almacenar las entradas y salidas de la herramienta
• Comportamiento de caducidad y eliminación para el estado de respuesta

Si la retención está deshabilitada, es posible que la puerta de enlace aún mantenga metadatos operativos mínimos: marcas de tiempo, ID, estado, recuentos de tokens, costos y decisiones de políticas. Evite almacenar indicaciones sin procesar, resultados completos de herramientas o historial reconstruido a menos que la política lo permita.

Accesorios de conformidad para agregar antes del lanzamiento

No confíe en las pruebas manuales de happy-path. Agregue accesorios que verifiquen el comportamiento del protocolo en rutas directas de OpenAI, rutas adaptadas por el proveedor y escenarios alternativos.

Conjunto de prueba mínimo

• Respuesta básica: el elemento de texto se devuelve con un ID de respuesta y un uso estables.
• Estado de varios turnos: la segunda solicitud hace referencia a previous_response_id; La puerta de enlace valida la propiedad del inquilino y el modo de estado.
• Instrucciones repetidas: verifique que la puerta de enlace no invente silenciosamente las instrucciones omitidas.
• Función de llamada de ida y vuelta: el modelo emite ID de llamada; la aplicación envía el resultado; la respuesta final une ambos registros.
• Política de herramientas alojadas: la herramienta integrada no autorizada se bloquea antes de su envío.
• Orden de transmisión: el inicio de la respuesta, el inicio del elemento, los deltas, la finalización del elemento, el uso y la finalización se emiten en un orden válido.
• Cancelación de transmisión: la desconexión del cliente activa la cancelación ascendente cuando es compatible y registra el uso parcial.
• Rechazo alternativo: el proveedor sin la semántica de respuestas requeridas devuelve un error de capacidad.
• Opción de respaldo con pérdidas: la solicitud con pérdidas permitidas recibe un marcador de degradación explícito.
• Modo de retención cero: la reproducción del estado y la retención de mensajes del lado de la puerta de enlace están bloqueadas.

Secuencia de implementación recomendada

1. Exponer una ruta beta. Agregar /v1/responses sin cambiar el comportamiento de chat existente.
2. Implemente la transferencia primero para los proveedores con soporte nativo de Respuestas. Conserve ID, elementos, transmisiones, uso y errores.
3. Agregue el libro mayor estatal. Asigne los ID de puerta de enlace a los ID de proveedor y aplique la propiedad de los inquilinos.
4. Agregar elementos canónicos. Almacenar metadatos de elementos necesarios para auditoría, facturación y reconstrucción de transmisiones.
5. Añadir control de herramientas. Validar esquemas, aplicar alcances y registrar uniones de llamadas de herramientas.
6. Agregar normalización de transmisión. Convertir transmisiones específicas del proveedor en eventos del ciclo de vida de la puerta de enlace.
7. Añadir enrutamiento basado en capacidades. Permitir solo alternativas seguras de forma predeterminada.
8. Agregue análisis y liquidación de facturación. Token de atributo, razonamiento y uso de herramientas por separado.
9. Publicar notas de compatibilidad. Indique a los desarrolladores qué campos son nativos, emulados, no compatibles o con pérdida.

Conclusión procesable

Una capa de compatibilidad de Responses API debe preservar el significado del protocolo, no simplemente devolver texto plausible. Constrúyalo en torno a cinco objetos duraderos: un modelo de elemento de respuesta canónico, un libro de contabilidad de estado de conversación, un libro de contabilidad de llamadas de herramientas, un normalizador de eventos de transmisión y una matriz de capacidades de proveedor.

El valor predeterminado más seguro es la compatibilidad estricta: si una ruta no puede preservar el estado requerido, las herramientas, el contexto de razonamiento, los eventos de transmisión o el comportamiento de retención, devolverá un error de capacidad claro. Agregue respaldo con pérdida de suscripción solo cuando los desarrolladores comprendan qué se eliminará. Ese enfoque puede parecer menos conveniente que el aplanamiento automático, pero previene el peor modo de falla: una aplicación que parece compatible pero pierde silenciosamente la semántica que la hizo usar la API de Respuestas en primer lugar.

Lectura relacionada

• manejo de cancelación y contabilidad de tokens de transmisión