Responses API frente a Chat Completions para agentes: cómo elegir un contrato

Para cargas de trabajo de agentes, la Responses API es la mejor opción predeterminada: le proporciona el estado de la conversación en el lado del servidor mediante previous_response_id, elementos de salida tipados en lugar de un único bloque de mensajes y eventos de streaming semánticos. Estas características reducen la gestión que, de otro modo, tendría que realizar su capa de orquestación. Chat Completions sigue siendo una opción válida cuando desea un control total sobre el historial de mensajes o si está integrando herramientas creadas en torno al formato de mensajes de chat de OpenAI, pero para agentes que realizan llamadas a herramientas en múltiples turnos, Responses es la opción más directa.

Ambos endpoints están documentados en las páginas de referencia de modelos actuales para GPT-5.6 y GPT-5.5, y el contrato compartido de solicitud/respuesta para Responses se especifica en la referencia de creación de Responses.

Puntos clave

• Chat Completions es gestionado por el llamador: usted envía la matriz messages completa en cada solicitud y reconstruye el historial usted mismo.
• Responses cuenta con asistencia del servidor: usted envía input además de instructions opcionales, y puede encadenar turnos con previous_response_id en lugar de reenviar el historial.
• La llamada a herramientas difiere estructuralmente: Chat Completions anida las llamadas bajo choices[0].message.tool_calls; Responses las emite como elementos tipados en una matriz output plana.
• Los resultados de las herramientas se emparejan mediante tool_call_id (Chat) frente a call_id en un elemento function_call_output (Responses).
• El streaming se basa en deltas de fragmentos en Chat Completions frente a eventos semánticos con nombre en Responses.
• El soporte de herramientas alojadas (búsqueda web, intérprete de código, búsqueda de archivos, etc.) depende del modelo en ambas API; consulte la página del modelo antes de asumir su disponibilidad.

Comparación a nivel de campo

Aspecto	Chat Completions	Responses
Endpoint	POST /v1/chat/completions	POST /v1/responses
Entrada principal	messages: [] (matriz completa en cada llamada)	input (cadena o matriz de elementos)
Guía estilo sistema	messages[0].role = "system"	Campo instructions de nivel superior
Continuación de múltiples turnos	El llamador reenvía todo el historial de messages	previous_response_id hace referencia al turno anterior en el servidor
Forma de salida	choices[0].message (objeto de mensaje único)	output: [], una matriz de elementos tipados (mensaje, function_call, etc.)
Ubicación de la llamada a herramienta	choices[0].message.tool_calls[]	Elementos en output con type: "function_call"
Envío de resultado de herramienta	Nuevo mensaje con role: "tool", tool_call_id	Elemento con type: "function_call_output", call_id
Streaming	Fragmentos chunk.choices[0].delta	Eventos con nombre (response.output_text.delta, response.completed, etc.)

previous_response_id: qué hace realmente

En Chat Completions, la memoria de la conversación es responsabilidad exclusiva suya. Cada solicitud debe incluir el historial completo de mensajes y el servidor no tiene noción de un turno anterior. En cambio, la Responses API devuelve un id en cada objeto de respuesta. Si su aplicación persiste ese id y lo pasa de vuelta como previous_response_id en la siguiente llamada, el servidor reconstruye el estado de la conversación anterior por su parte. Solo necesita enviar el nuevo input para el turno actual más (opcionalmente) instructions nuevas. Esto traslada la gestión del estado de su capa de aplicación a la infraestructura de OpenAI, lo cual es importante para los agentes que realizan muchas llamadas a herramientas secuenciales, ya que evita volver a serializar y transmitir un historial creciente en cada salto.

La contrapartida es que su aplicación aún necesita persistir el id en algún lugar duradero (un almacén de sesiones, una fila de base de datos) entre turnos; la API no le ofrece retención infinita ni búsqueda sobre respuestas pasadas, simplemente le permite hacer referencia a la inmediatamente anterior como punto de continuación.

Ejemplos de solicitudes actuales (gpt-5.6)

Chat Completions: usted es dueño del historial completo:

{
  "model": "gpt-5.6",
  "messages": [
    { "role": "system", "content": "You are a support agent." },
    { "role": "user", "content": "Check order #4471 status." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
      }
    }
  ]
}

Responses: primer turno con instructions e input:

{
  "model": "gpt-5.6",
  "instructions": "You are a support agent.",
  "input": "Check order #4471 status.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
    }
  ]
}

Responses: turno de seguimiento, no se reenvía el historial:

{
  "model": "gpt-5.6",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

Ciclo de vida de la llamada a función

Chat Completions:

1. El modelo devuelve choices[0].message.tool_calls, cada uno con un id y el nombre/argumentos de la función.
2. Usted ejecuta la función localmente.
3. Usted añade el mensaje del asistente (con tool_calls) a su matriz messages, luego añade un nuevo mensaje: { "role": "tool", "tool_call_id": "<id>", "content": "<result>" }.
4. Usted reenvía toda la matriz messages actualizada para continuar.

Responses:

1. La matriz output contiene un elemento con type: "function_call", incluyendo un call_id, name y arguments.
2. Usted ejecuta la función localmente.
3. Usted envía una nueva solicitud con previous_response_id configurado al id de la respuesta anterior, e input conteniendo un elemento con type: "function_call_output", coincidiendo con el call_id y el resultado.
4. El servidor ya ha retenido el contexto de la llamada a función, por lo que no reenvía turnos anteriores.

La diferencia estructural entre elementos de salida tipados planos y un mensaje único con una matriz anidada tiende a simplificar la lógica de análisis en Responses, ya que puede iterar sobre output y cambiar según el type en lugar de profundizar en los campos opcionales de un mensaje.

Lista de verificación para la decisión

• ¿Está creando un agente de múltiples turnos con llamadas a herramientas? Use Responses por defecto; previous_response_id elimina la gestión del historial.
• ¿Necesita un control exacto sobre lo que hay en el historial (redacción, resumen personalizado, inyección de mensajes no estándar)? Chat Completions le da ese control explícitamente, ya que usted mismo ensambla los messages.
• ¿Está migrando una integración de Chat Completions existente? Evalúe el costo de refactorización frente al ahorro en la gestión de estado; para llamadas de corta duración y un solo turno, el beneficio es menor.
• ¿Depende de herramientas alojadas (búsqueda, intérprete de código, herramientas de archivos)? Verifique el soporte en la página del modelo específico antes de comprometerse, ya que la disponibilidad varía según el modelo y el endpoint.
• ¿Necesita streaming con semántica de eventos de grano fino (p. ej., distinguir deltas de texto de deltas de llamadas a herramientas sin inspeccionar la forma del delta)? Los eventos con nombre de Responses son más explícitos que los fragmentos delta genéricos de Chat Completions.
• ¿Trabaja dentro de un framework o SDK existente construido en torno a mensajes de chat? Confirme la madurez de su soporte para Responses antes de cambiar de contrato a mitad del proyecto.

Agentes multiproveedor y traducción de contratos

Los agentes rara vez permanecen en un solo proveedor por mucho tiempo. Un agente de codificación podría dirigirse a Claude Sonnet 5 o Kimi K2.7 Code para el trabajo de implementación, recurrir a DeepSeek V4 Flash o Gemini 3.5 Flash para borradores económicos, y ocasionalmente llamar a GLM-5.2 o Qwen3.7 Plus para el control de costos de modelos de pesos abiertos. Ninguno de estos proveedores expone necesariamente el contrato de Chat Completions o Responses de OpenAI de forma nativa.

Aquí es donde una capa de enrutamiento demuestra su valor. La documentación de TokenLab en docs.tokenlab.sh describe una única superficie de API y clave utilizada para llegar a múltiples proveedores de modelos, lo que elimina la necesidad de escribir manualmente una integración de cliente separada por contrato de proveedor. Nuestro artículo relacionado sobre alias de encabezado para compatibilidad de contratos cubre cómo se pueden asignar los encabezados de solicitud para que el código escrito contra una forma de contrato pueda llegar a modelos que no la hablan de forma nativa. Si está creando un chatbot o agente que necesita llamar a más de una familia de modelos, nuestra guía sobre creación de un chatbot de IA con una sola clave API detalla la configuración en términos más concretos.

Para obtener la lista completa y actual de modelos accesibles a través de TokenLab, incluyendo las opciones de vanguardia, codificación y enrutamiento de bajo costo mencionadas anteriormente, consulte nuestra página de modelos. Confirme la disponibilidad actual y cualquier nota específica del contrato allí antes de finalizar su arquitectura, ya que las líneas de modelos cambian con más frecuencia que los contratos de API.

Limitaciones

Este artículo no repite la referencia exacta de la API a nivel de campo de OpenAI para ninguno de los contratos, porque esos detalles tienen versiones y pueden cambiar. No trate el ejemplo de forma de solicitud anterior como código listo para producción. Tampoco hemos cubierto en profundidad el contrato nativo de cada proveedor; Claude, Gemini, DeepSeek y GLM publican sus propias referencias de API, y ninguno de ellos está obligado a coincidir con las formas de Chat Completions o Responses de OpenAI. Si su agente necesita garantías sobre el orden de las llamadas a herramientas, formatos de eventos de streaming o comportamiento de procesamiento por lotes, verifique esos detalles específicos en la documentación actual del proveedor nombrado, no en este artículo.

Preguntas frecuentes

¿Es la Responses API un reemplazo para Chat Completions? La documentación de inicio rápido de OpenAI posiciona a la Responses API como la ruta actual para el nuevo desarrollo, incluidos los casos de uso de agentes, mientras que Chat Completions sigue siendo parte de su superficie de API documentada. Si Chat Completions está en desuso, retirado o simplemente es legado en un momento dado es algo que debe confirmar directamente en la documentación actual de OpenAI, ya que el estado del soporte puede cambiar.

¿Otros proveedores como Claude, Gemini o DeepSeek usan los mismos contratos? No de forma nativa. Cada proveedor define su propia forma de solicitud y respuesta. Si necesita ejecutar un agente a través de modelos de OpenAI y proveedores como Claude Sonnet 5 o DeepSeek V4 Pro, planifique una capa de traducción en lugar de asumir un contrato compartido.

¿Cambiar de contrato altera la calidad de salida del modelo? No. El contrato es el transporte y la estructura de la solicitud y la respuesta, no el modelo en sí. La calidad de la salida se rige por el modelo que llame (por ejemplo, GPT-5.5 frente a Claude Sonnet 5), no por si utilizó Chat Completions o la Responses API para llamarlo.

Si está evaluando qué contrato y qué modelos se ajustan a su agente, comience con una pequeña compilación de prueba contra los endpoints documentados de TokenLab y compare directamente la sobrecarga de orquestación. Comience en docs.tokenlab.sh para ejecutar esa comparación contra su propia carga de trabajo.