Responses API es la base actual de OpenAI para construir aplicaciones y agentes conectados a herramientas. Aprende a manejar estado, Conversations, tools, MCP y flujos agentic.
Arquitectura de Responses API para conectar modelos de OpenAI con tools, contexto y agentes.
OpenAI Responses API con tools, estado de conversación y agentes de inteligencia artificial
OpenAI Responses API: guía completa de tools, estado y agentes
Aprende cómo utilizar la API que concentra el nuevo stack agentic de OpenAI: conversaciones persistentes, herramientas, function calling, MCP, ejecución de código y agentes capaces de completar tareas de varios pasos.
OpenAI Responses API se ha convertido en una de las piezas centrales para construir aplicaciones de inteligencia artificial que necesitan algo más que generar texto. Con una misma arquitectura, un modelo puede recibir información, mantener contexto, buscar datos, llamar funciones y utilizar herramientas para completar una tarea.
Por ello, esto cambia la forma de desarrollar productos con IA. En lugar de crear múltiples capas solamente para conectar un modelo con búsquedas, archivos, APIs externas o acciones, Responses API ofrece una interfaz unificada sobre la que pueden construirse asistentes, automatizaciones y agentes.
Además, no es necesario utilizar todas sus capacidades desde el primer día. Una aplicación puede empezar con una Response sencilla y, posteriormente, incorporar estado, búsqueda web, File Search, functions, MCP o una capa de orquestación con Agents SDK.
Capacidades principales de Responses API
Qué es OpenAI Responses API
Responses API es un endpoint diseñado para generar respuestas utilizando modelos de OpenAI mientras permite incorporar contexto, herramientas y diferentes tipos de input dentro de la misma interacción.
Por ejemplo, una Response puede recibir una pregunta del usuario y decidir que necesita buscar información en Internet. También puede consultar archivos, llamar una función de tu backend o interactuar con un servicio conectado mediante MCP.
El desarrollador continúa definiendo qué herramientas están disponibles. Por tanto, el modelo no obtiene acceso automático a todos los sistemas de una empresa. Solamente puede trabajar con las capacidades que tu aplicación le expone.
texto · imagen · archivo
RESPONSES API
o llamada a tool
Modelo
Interpreta la petición, razona sobre el contexto disponible y determina qué respuesta o acción necesita ejecutar.
Estado
Permite construir experiencias de varios turnos utilizando Conversations, respuestas anteriores o contexto administrado por tu aplicación.
Tools
Extienden al modelo para buscar, consultar información, ejecutar código o interactuar con sistemas externos.
Cómo crear tu primera Response
En primer lugar, la implementación básica es mucho más sencilla de lo que puede parecer. Inicializas el cliente de OpenAI, seleccionas un modelo y envías un input.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6",
input="Explica qué es una API en términos sencillos."
)
print(response.output_text)
El helper response.output_text permite obtener directamente
el texto combinado de la respuesta sin recorrer manualmente todos los
objetos contenidos en output.
Sin embargo, una Response puede contener más que texto. Cuando utilizas herramientas, el array de salida puede incluir llamadas a funciones, resultados de búsquedas, outputs de código y otros tipos de items.
Agregar instrucciones a la Response
Además, puedes establecer instrucciones separadas del mensaje enviado por el usuario. Esto resulta útil para definir comportamiento, tono y restricciones generales.
response = client.responses.create(
model="gpt-5.6",
instructions=(
"Eres un asistente técnico. "
"Responde en español y utiliza ejemplos breves."
),
input="¿Qué diferencia existe entre REST y GraphQL?"
)
print(response.output_text)Cómo funciona el estado en Responses API
En primer lugar, una aplicación conversacional necesita decidir qué información de los turnos anteriores seguirá disponible. Responses API ofrece varias estrategias y cada una tiene ventajas diferentes.
Para aplicaciones con conversaciones persistentes, puedes utilizar
Conversations. Para flujos sencillos, también puedes encadenar
una Response con la anterior mediante previous_response_id.
Finalmente, una aplicación puede conservar el historial completamente
en su propia infraestructura.
| Estrategia | Ideal para | Cómo funciona |
|---|---|---|
| Conversation | Chats persistentes | Mantiene items de entrada y salida asociados a una conversación. |
| previous_response_id | Flujos encadenados | Una nueva Response continúa a partir de la Response anterior. |
| Estado propio | Control máximo | Tu backend almacena y vuelve a enviar el contexto que considere necesario. |
Opción 1: utilizar una Conversation
Por ejemplo, una Conversation puede actuar como contenedor persistente del intercambio. Tu aplicación guarda el identificador correspondiente a cada usuario o sesión.
conversation = client.conversations.create(
metadata={
"customer_id": "cliente_841"
}
)
response = client.responses.create(
model="gpt-5.6",
conversation=conversation.id,
input="Hola, mi nombre es José."
)
print(response.output_text)
En las siguientes peticiones, puedes utilizar el mismo
conversation.id. Los items asociados a esa conversación
pueden formar parte automáticamente del contexto de nuevas Responses.
ID 841
conversation_id
Conversation
Continuidad con previous_response_id o estado propio
Opción 2: utilizar previous_response_id
Por otra parte, para un flujo más sencillo, puedes enlazar la siguiente petición con la Response anterior. De esta manera no necesitas crear primero un objeto Conversation.
first = client.responses.create(
model="gpt-5.6",
input="Mi empresa vende cursos de marketing."
)
second = client.responses.create(
model="gpt-5.6",
previous_response_id=first.id,
input="¿Qué tipo de chatbot podría crear para mis alumnos?"
)
print(second.output_text)Son dos mecanismos diferentes para administrar continuidad. Elige una estrategia según la arquitectura de tu aplicación.
Opción 3: administrar el historial tú mismo
Finalmente, algunas empresas prefieren que toda la conversación permanezca en su propia base de datos. En ese caso, tu backend puede decidir exactamente qué mensajes o resúmenes enviará en cada petición.
Ventaja
Obtienes un control muy granular sobre almacenamiento, retención, recuperación y selección del contexto.
Desventaja
Necesitas construir más infraestructura para resumir, truncar, recuperar y reenviar el historial correctamente.
Tools de OpenAI Responses API
En primer lugar, una de las diferencias más importantes entre una aplicación tradicional con un modelo y una aplicación agentic es la capacidad de utilizar herramientas.
Además, el modelo puede analizar la petición y decidir que necesita una tool antes de generar una respuesta final. Algunas herramientas son ejecutadas dentro de la plataforma de OpenAI. En cambio, otras regresan el control a tu aplicación para que tu backend realice una operación.
Web Search
Permite obtener información reciente de Internet cuando la tarea requiere datos que no deberían depender únicamente del conocimiento del modelo.
File Search
Busca información relevante dentro de documentos y vector stores vinculados a tu aplicación.
Functions
El modelo puede generar argumentos estructurados para ejecutar funciones definidas en tu propio backend.
Code Interpreter
Ejecuta Python para cálculos, transformación de datos y análisis cuando el modelo necesita procesamiento programático.
Shell
Algunos modelos pueden trabajar con un entorno de comandos para ejecutar tareas más amplias dentro de un sandbox controlado.
Computer Use
Permite construir agentes capaces de interactuar con interfaces visuales y aplicaciones mediante acciones controladas.
MCP
Conecta servidores y servicios externos mediante Model Context Protocol sin construir una integración distinta para cada herramienta.
Image Generation
Determinados modelos pueden utilizar generación de imágenes dentro de un flujo iniciado desde Responses API.
Skills
Los modelos compatibles pueden utilizar lógica reutilizable para ejecutar workflows especializados de una forma más consistente.
Ejemplos de Web Search y File Search
Ejemplo de Web Search
Por ejemplo, Web Search resulta útil para asistentes de investigación, monitoreo, análisis de mercado y cualquier producto que necesite información reciente.
response = client.responses.create(
model="gpt-5.6",
tools=[
{
"type": "web_search"
}
],
input=(
"Busca información reciente sobre agentes de IA "
"y resume los cambios más importantes."
)
)
print(response.output_text)Ejemplo de File Search
Asimismo, si tus respuestas deben basarse en manuales, contratos, documentación, políticas internas o conocimiento empresarial, File Search puede ser una alternativa a insertar documentos completos en cada prompt.
response = client.responses.create(
model="gpt-5.6",
tools=[
{
"type": "file_search",
"vector_store_ids": [
"vs_empresa_123"
]
}
],
input=(
"Busca en nuestra documentación cuál es "
"la política para cancelar una suscripción."
)
)
print(response.output_text)Function calling: conectar Responses API con tu negocio
En primer lugar, las funciones permiten que el modelo solicite una acción a tu backend. Esto es especialmente importante para CRM, ecommerce, reservas, soporte y automatización empresarial.
De hecho, el modelo no ejecuta mágicamente tu función. Primero genera una llamada estructurada. Después, tu servidor valida los argumentos, comprueba los permisos y ejecuta la operación real.
“Consulta mi pedido”
consultar_pedido()
ejecuta la acción
tools = [
{
"type": "function",
"name": "consultar_pedido",
"description": (
"Consulta el estado de un pedido "
"utilizando su identificador."
),
"parameters": {
"type": "object",
"properties": {
"pedido_id": {
"type": "string"
}
},
"required": [
"pedido_id"
],
"additionalProperties": False
},
"strict": True
}
]
response = client.responses.create(
model="gpt-5.6",
tools=tools,
input="¿Dónde está mi pedido PED-1284?"
)
Si el modelo decide llamar a consultar_pedido, tu aplicación
recibe el nombre de la función y sus argumentos. Entonces puede consultar
Shopify, WooCommerce, HighLevel, un ERP o cualquier backend propio.
El modelo puede decidir
- Qué función necesita
- Qué argumentos debe proporcionar
- Cuándo una tool no es necesaria
- Cómo utilizar el resultado para responder
Tu backend debe decidir
- Si el usuario tiene permiso
- Si los argumentos son válidos
- Si una acción requiere confirmación
- Qué información puede regresar al modelo
Cómo utilizar MCP con Responses API
En términos generales, Model Context Protocol permite exponer herramientas y datos mediante una interfaz estandarizada. En lugar de escribir una integración diferente para cada agente, un servidor MCP puede publicar un conjunto de tools que diferentes clientes compatibles pueden descubrir y utilizar.
Dentro de Responses API, MCP es especialmente interesante porque amplía el número de sistemas con los que un agente puede trabajar. Por ejemplo, un servidor podría exponer herramientas para consultar un CRM, buscar documentos o realizar acciones dentro de una plataforma empresarial.
Responses API
MCP
Base de datos · App
Cuándo MCP tiene más sentido
Muchas herramientas
Cuando un sistema expone varias acciones y quieres evitar mantener integraciones independientes para cada agente.
Varios clientes IA
Cuando quieres reutilizar el mismo conjunto de herramientas desde diferentes aplicaciones compatibles con MCP.
Arquitectura modular
Cuando quieres separar claramente la capa de IA de los servicios y sistemas internos de una empresa.
Limita las herramientas disponibles, aplica autenticación, registra acciones y solicita confirmaciones cuando una operación pueda modificar información importante.
Cómo convertir Responses API en un agente
En primer lugar, un chatbot normalmente recibe una pregunta y devuelve una respuesta. Sin embargo, un agente puede ir más lejos: analiza un objetivo, utiliza herramientas, observa los resultados y continúa trabajando hasta completar la tarea.
Responses API ofrece muchas de las primitives necesarias para ese ciclo. Sin embargo, cuando el workflow empieza a crecer, puede ser conveniente utilizar Agents SDK para estructurar la orquestación.
Responses API
Ideal cuando quieres controlar directamente las Responses, tools y estado desde tu propio backend.
Agents SDK
Útil cuando necesitas estructurar agentes, herramientas, handoffs y workflows más complejos.
Realtime API
Pensada para experiencias de baja latencia, especialmente aplicaciones de voz y comunicación en tiempo real.
El loop básico de un agente
Recibe un objetivo
El usuario no tiene que decir exactamente cómo completar la tarea. Puede expresar el resultado que quiere conseguir.
Analiza el contexto
El modelo interpreta instrucciones, conversación previa, archivos y herramientas disponibles.
Selecciona una herramienta
Puede buscar en la web, consultar archivos, ejecutar una función, trabajar con código o utilizar MCP.
Observa el resultado
La información regresada por la tool vuelve al contexto del agente para decidir el siguiente paso.
Continúa o termina
Si la tarea está resuelta, entrega el resultado. Si todavía necesita más información o acciones, inicia otro ciclo.
Ejemplo práctico de un agente empresarial
por su pedido
intención + contexto
+ políticas
El agente podría consultar el pedido, revisar la política de devoluciones mediante File Search y preparar una respuesta personalizada. Sin embargo, una devolución de dinero debería pasar por reglas de negocio y autorización, no depender exclusivamente de la decisión del modelo.
Streaming y tareas de larga duración
Por otra parte, no todas las Responses necesitan ejecutarse de la misma forma. Para una interfaz de chat, normalmente quieres mostrar texto conforme se genera. Para una investigación extensa o un workflow agentic, quizá prefieras ejecutar el trabajo como una tarea más larga.
Streaming
Con streaming, tu aplicación recibe eventos mientras la Response continúa generándose. Esto reduce la percepción de espera en interfaces donde el usuario está mirando directamente la respuesta.
stream = client.responses.create(
model="gpt-5.6",
input="Explica cómo funciona un agente de IA.",
stream=True
)
for event in stream:
print(event)Background mode
Responses API también dispone de ejecución en background para trabajos que pueden tardar más tiempo. Esto resulta útil en tareas de investigación, generación de artefactos y procesos agentic donde no quieres mantener una petición HTTP tradicional abierta durante toda la ejecución.
response = client.responses.create(
model="gpt-5.6",
background=True,
input=(
"Analiza este conjunto de información "
"y prepara un informe detallado."
)
)
print(response.id)
print(response.status)Cómo controlar el uso de herramientas
En la práctica, una buena arquitectura agentic no entrega todas las herramientas al modelo sin restricciones. Responses API permite definir qué tools existen y también controlar cómo pueden seleccionarse.
auto
El modelo decide si necesita utilizar una tool o si puede generar directamente una respuesta.
required
La ejecución debe utilizar al menos una herramienta antes de finalizar.
none
Desactiva tool calling para esa petición y obliga al modelo a responder sin utilizar las herramientas expuestas.
Además, puedes limitar el número total de llamadas a herramientas integradas mediante parámetros de control. Esto ayuda a evitar loops costosos y proporciona límites claros para algunos tipos de workflows.
Arquitectura recomendada para Responses API en producción
En primer lugar, la API no debería conectarse directamente desde una aplicación web pública utilizando tu clave privada. Por ello, lo recomendable es colocar un backend entre el usuario y OpenAI.
Auth + reglas
Tools + contexto
Tu aplicación debería controlar
- Usuarios y autenticación
- Roles y permisos
- Datos críticos
- Acceso a herramientas
- Confirmaciones
- Logs de acciones
- Rate limits internos
- Relación con Conversations
OpenAI puede encargarse de
- Interpretar lenguaje natural
- Razonar sobre la solicitud
- Seleccionar herramientas
- Generar argumentos estructurados
- Buscar información
- Analizar archivos
- Generar la respuesta final
- Orquestar tools alojadas compatibles
Ejemplo de arquitectura con Supabase
React / WordPress
usuario · permisos · datos
modelo + tools
En este patrón, Supabase puede almacenar usuarios, Conversations, configuraciones y datos de negocio. Responses API recibe únicamente el contexto necesario para ejecutar cada interacción.
Qué modelo utilizar con Responses API
En términos generales, Responses API es la capa de ejecución, mientras que el modelo determina gran parte de la inteligencia, coste y latencia. Por eso, no siempre tiene sentido utilizar el modelo más potente para todos los casos.
| Modelo | Enfoque | Cuándo utilizarlo |
|---|---|---|
| GPT-5.6 Sol | Máxima capacidad | Razonamiento complejo, desarrollo, análisis y agentes de alto valor. |
| GPT-5.6 Terra | Equilibrio | Aplicaciones donde buscas buena capacidad con un coste inferior. |
| GPT-5.6 Luna | Alto volumen | Tareas repetitivas, clasificación y procesos sensibles al coste. |
Cómo controlar el coste de Responses API
En primer lugar, el coste de una aplicación agentic no depende solamente del número de mensajes. Además, también puede crecer por el tamaño del contexto, los tokens generados y el uso de herramientas.
Por ello, una arquitectura eficiente debe controlar qué información se envía, cuánto historial se mantiene y cuántas llamadas a tools puede generar una tarea.
Reduce contexto
No envíes miles de mensajes si solamente unas pocas piezas de información siguen siendo relevantes.
Usa el modelo correcto
Una operación sencilla no siempre necesita el modelo de mayor capacidad.
Limita tools
Ofrece únicamente las herramientas necesarias para el workflow actual.
Prompt caching
Por ejemplo, en aplicaciones con instrucciones o contexto repetitivo, Prompt Caching puede reducir el procesamiento duplicado. Además, la familia GPT-5.6 dispone de opciones específicas de caché que pueden aprovecharse cuando existe una parte común entre muchas peticiones.
Limitar tokens de salida
Asimismo, si una tarea debería producir una respuesta breve, establecer un límite de output puede impedir generaciones innecesariamente extensas.
response = client.responses.create(
model="gpt-5.6",
max_output_tokens=500,
input=(
"Resume este reporte en no más de "
"cinco puntos principales."
)
)Ejemplo completo de una aplicación sencilla
A continuación, el siguiente ejemplo reúne varias ideas de esta guía. Una función recibe un ID interno de usuario, obtiene o crea una Conversation y utiliza Responses API para generar la respuesta.
from openai import OpenAI
client = OpenAI()
# Sustituye esto por una base de datos real.
conversation_ids = {}
def get_conversation(user_id: str) -> str:
existing = conversation_ids.get(user_id)
if existing:
return existing
conversation = client.conversations.create(
metadata={
"user_id": user_id
}
)
conversation_ids[user_id] = conversation.id
return conversation.id
def ask_agent(
user_id: str,
message: str
) -> str:
conversation_id = get_conversation(user_id)
response = client.responses.create(
model="gpt-5.6",
conversation=conversation_id,
instructions=(
"Eres un asistente empresarial. "
"Responde con claridad. "
"No inventes datos del usuario."
),
input=message
)
return response.output_text
reply = ask_agent(
user_id="cliente_841",
message="¿Puedes ayudarme con mi pedido?"
)
print(reply)En una implementación real, la relación entre usuario y Conversation debe guardarse en una base de datos persistente. Además, deberías incorporar autenticación, logs, manejo de errores, observabilidad y límites de uso.
Cuándo conviene utilizar Responses API
Es una buena opción si necesitas
- Chats con contexto persistente
- Agentes conectados a herramientas
- Function calling
- File Search
- Web Search
- MCP
- Automatizaciones de varios pasos
- Structured Outputs
Puede ser demasiado si solamente necesitas
- Una generación de texto aislada
- Un flujo sin herramientas
- Una función local extremadamente simple
- Un proceso que ya funciona con otra API y no obtiene beneficios del cambio
Aun así, para nuevas integraciones de OpenAI, Responses API ofrece una base especialmente flexible porque permite empezar de manera sencilla y agregar herramientas más adelante sin rediseñar toda la arquitectura.
Errores comunes al construir con Responses API
Dar demasiadas herramientas al modelo
Si un agente solamente necesita consultar pedidos, no hace falta exponerle también herramientas de administración, pagos y borrado.
Confundir contexto con base de datos
Por ejemplo, una Conversation ayuda con continuidad, pero tu aplicación todavía necesita una base de datos para usuarios, permisos y datos críticos.
No validar function calls
En cambio, nunca ejecutes una acción únicamente porque el modelo produjo argumentos con formato correcto.
Utilizar siempre el modelo más caro
Clasificar un mensaje y resolver una investigación compleja son tareas diferentes. Evalúa modelos distintos según el workflow.
No registrar lo que hacen los agentes
Finalmente, un sistema de producción necesita logs de tools, errores, tiempos de ejecución y acciones importantes.
La arquitectura más útil para empresas
En la práctica, la mayor oportunidad de Responses API aparece cuando deja de utilizarse únicamente como chatbot y se convierte en una capa de inteligencia conectada a sistemas reales.
Por ejemplo, una empresa puede permitir que un agente consulte contactos de su CRM, revise políticas almacenadas en documentos, analice información reciente y prepare una acción. Sin embargo, el backend sigue validando qué puede ejecutar y con qué permisos.
Checklist para implementar Responses API
- Define exactamente qué tarea debe resolver la aplicación
- Selecciona el modelo según calidad, coste y latencia
- Decide si utilizarás Conversation, previous_response_id o estado propio
- Expón únicamente las tools necesarias
- Valida todas las funciones ejecutadas por tu backend
- Configura autenticación y permisos
- Registra llamadas a herramientas y errores
- Establece límites de tokens y tool calls cuando sea necesario
- Implementa pruebas con casos reales
- Evalúa coste por conversación o tarea completada
- Utiliza streaming cuando mejore la experiencia
- Considera background mode para trabajos largos
- Implementa confirmaciones antes de acciones sensibles
Preguntas frecuentes sobre OpenAI Responses API
¿Qué es OpenAI Responses API?
En términos generales, es una API de OpenAI diseñada para generar respuestas utilizando modelos y combinarlas con herramientas, contexto conversacional, function calling y otros componentes necesarios para construir aplicaciones agentic.
¿Responses API sirve solamente para agentes?
No. De hecho, también puede utilizarse para una petición sencilla de texto. Además, las herramientas y el estado son opcionales y pueden agregarse únicamente cuando la aplicación los necesite.
¿Cómo mantiene memoria Responses API?
Por ejemplo, puedes utilizar una Conversation persistente, encadenar Responses mediante previous_response_id o gestionar el historial desde tu propia aplicación.
¿Puedo usar GPT-5.6 con Responses API?
Sí. Además, GPT-5.6 está disponible mediante Responses API y soporta diferentes capacidades de tools según el modelo concreto de la familia seleccionado.
¿Responses API puede buscar en Internet?
Sí. Asimismo, los modelos compatibles pueden utilizar Web Search como herramienta dentro de una Response.
¿Puede consultar mis documentos?
Sí. De hecho, File Search permite buscar contenido dentro de recursos y vector stores configurados para tu aplicación.
Tools, CRM, Agents SDK y tareas largas
¿Puede conectarse a mi CRM?
Sí. Por otra parte, puedes crear funciones propias o conectar herramientas mediante MCP. Sin embargo, tu backend debe conservar el control de autenticación y permisos.
¿Cuál es la diferencia entre Responses API y Agents SDK?
En este caso, Responses API es la primitive de ejecución sobre la que puedes trabajar directamente con modelos y tools. En cambio, Agents SDK añade una capa de orquestación para construir workflows agentic más estructurados.
¿Responses API permite streaming?
Sí. Además, puedes recibir eventos mientras la Response continúa generándose, algo especialmente útil en chats y experiencias interactivas.
¿Se pueden ejecutar tareas largas?
Sí. Asimismo, Background mode permite iniciar Responses que necesitan más tiempo y consultar posteriormente su progreso o resultado.
¿MCP reemplaza function calling?
No necesariamente. Por un lado, Function calling es excelente para funciones controladas directamente por tu backend. Por otro lado, MCP resulta especialmente útil para exponer conjuntos de herramientas mediante un protocolo estandarizado.
Conclusión
Finalmente, OpenAI Responses API ofrece una base flexible para construir desde una simple generación de texto hasta agentes conectados a múltiples herramientas. Su ventaja principal consiste en que puedes incorporar estado, búsqueda, archivos, funciones y MCP sin necesitar una arquitectura completamente diferente para cada capacidad.
Sin embargo, un buen agente no depende únicamente del modelo. También necesita una arquitectura clara para identidad, permisos, datos, tools, observabilidad y control de costes.
Por eso, la mejor forma de comenzar suele ser pequeña: crea primero una Response sencilla, agrega estado cuando necesites conversaciones persistentes y habilita herramientas únicamente cuando exista un caso de uso concreto.
Después, si el workflow crece hasta convertirse en un verdadero agente, puedes incorporar Agents SDK, MCP, sandboxes y otras capacidades sin abandonar Responses API como una de las bases principales del sistema.
Fuentes oficiales sobre Responses API
Fuentes oficiales consultadas
¿Quieres crear una aplicación o agente con Responses API?
En Zadrig Technology podemos desarrollar aplicaciones conectadas a OpenAI, bases de datos, CRM, MCP, ecommerce y automatizaciones para que un agente no solamente responda preguntas, sino que pueda trabajar con procesos reales de tu empresa.
Hablar con Zadrig Technology →
