Integrando OpenResponses en tu Gateway

Lidiar con flujos de trabajo basados en agentes usando APIs diseñadas solo para chat suele ser frustrante. A menudo te encuentras forzando estructuras de datos que no encajan o intentando descifrar eventos de streaming que carecen de un contexto semántico claro para tus herramientas.

Para solucionar esto, te recomiendo adoptar el estándar OpenResponses. Implementar el endpoint /v1/responses te permite manejar entradas basadas en ítems y eventos detallados, lo que facilita la orquestación de agentes sin romper la compatibilidad con lo que ya tienes funcionando en tu Gateway.

Requisitos previos

• Especificación de OpenResponses (OpenAPI y sitio oficial).
• Node.js para la ejecución del Gateway.
• Esquemas Zod para validación (aislados en src/gateway/open-responses.schema.ts).
• Configuración de acceso al Gateway.

Inicio rápido

Para poner en marcha el endpoint /v1/responses en menos de 5 minutos, sigue estos pasos. Te sugiero mantener el soporte de Chat Completions activo mientras realizas la transición.

1. Modifica la configuración de tu Gateway para habilitar el nuevo endpoint:

gateway:
  http:
    endpoints:
      responses:
        enabled: true
      chatCompletions:
        enabled: true

2. Realiza una petición de prueba con curl para validar que el streaming semántico funciona correctamente:

curl -X POST http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "OpenResponses-Version: latest" \
  -d '{
    "model": "gpt-4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{ "type": "text", "text": "Hola, ¿cuál es tu función?" }]
      }
    ],
    "stream": true
  }'

3. Verifica que la secuencia de eventos SSE siga este orden obligatorio:

• response.created
• response.output_item.added
• response.content_part.added
• response.output_text.delta (repetido según el contenido)
• response.output_text.done
• response.content_part.done
• response.completed
• [DONE]

Solución de problemas

• Error invalid_request_error: El Gateway rechazará la petición si envías partes de contenido que incluyan imágenes o archivos, ya que no están soportados en esta fase.
• Uso de tokens en cero: El objeto usage devolverá valores en cero temporalmente hasta que la contabilidad de tokens esté conectada al nuevo endpoint.
• Advertencias en el inicio: Si ves un aviso sobre el estado “legacy” de Chat Completions, es normal. El Gateway emite esto para recordarte que el soporte de OpenAI se desactivará en el futuro.
• Fallo en la validación: Asegúrate de que los ítems de entrada usen roles permitidos como system, developer, user o assistant.

Si tienes dudas sobre la implementación de los esquemas Zod o la configuración de los endpoints, utiliza el AI Setup Assistant.

Próximos pasos

• OpenAI Chat Completions Legacy
• OpenResponses OpenAPI Specification