Cómo construir un AI agent con OpenAI Assistants (ahora la Responses API)
Turn this article into takeaways for your work.
Each assistant summarizes the article only for you and suggests best practices for your work.
La Assistants API de OpenAI permitía a los desarrolladores construir aplicaciones de tipo agent con hilos de conversación persistentes, recuperación de archivos, ejecución de código y llamadas a funciones, sin gestionar todo ese estado a mano. Fue importante y, para las integraciones existentes, todavía funciona hoy. Pero OpenAI anunció su desuso el 26 de agosto de 2025, con una fecha de cierre definitiva el 26 de agosto de 2026, y ha dirigido todo el desarrollo nuevo hacia su Responses API y su Agents SDK. Si va a empezar un proyecto nuevo, constrúyalo allí. Esta guía cubre lo que hacía la Assistants API, qué la reemplaza y cómo construir hoy un agent con las herramientas actuales de OpenAI.
Qué era la Assistants API y por qué desaparece
Lanzada en la conferencia de desarrolladores de OpenAI de 2023, la Assistants API les dio a los desarrolladores cuatro primitivas centrales: un Assistant (el agent configurado, con instrucciones y herramientas), un Thread (una conversación persistente), un Run (una ejecución del assistant sobre un thread) y Run Steps (las acciones individuales realizadas durante una ejecución). Incluía recuperación sobre archivos subidos, un intérprete de código y llamadas a funciones, lo que durante un tiempo la convirtió en la forma más rápida de levantar un agent con estado y uso de herramientas sin construir usted mismo esa infraestructura.
El problema, en palabras de la propia OpenAI, era la complejidad. Cuando la empresa lanzó la Responses API en marzo de 2025, dijo con claridad que planeaba llevar todas las funciones de Assistants a la API más simple y dar de baja la original, y cumplió: el aviso de desuso llegó a los desarrolladores el 26 de agosto de 2025, con la eliminación de la API exactamente un año después. La guía de migración de OpenAI confirma que no se pierde ninguna funcionalidad en el cambio, las funciones se reorganizan, no se eliminan.
Qué la reemplaza: la Responses API y el Agents SDK
La Responses API no es un cambio de nombre, es un modelo genuinamente más simple: usted envía elementos de entrada, recibe elementos de salida directamente, sin consultar repetidamente un objeto Run hasta que cambie su estado. Cuatro conceptos de Assistants se corresponden con cuatro conceptos de Responses.
| Assistants API | Equivalente en la Responses API | Qué cambió |
|---|---|---|
| Assistants | Prompts | La configuración ahora vive en el dashboard con control de versiones integrado, en lugar de gestionarse por completo mediante llamadas a la API |
| Threads | Conversations | Ampliadas para almacenar más que mensajes: llamadas a herramientas, salidas y otros tipos de elementos |
| Runs | Responses | Usted envía la entrada y recibe la salida directamente; no se necesita un ciclo de consulta repetida |
| Run steps | Items | Objetos generalizados que cubren el rango de datos que puede contener una respuesta |
La Responses API también incluye cinco herramientas integradas que usted no tiene que construir: búsqueda web, búsqueda de archivos, intérprete de código, uso del computador y conexiones a servidores MCP remotos. La búsqueda de archivos es el sucesor directo de la función de recuperación de la Assistants API, el mismo patrón de fundamentación en documentos que se explica en RAG para AI agents y, a nivel de patrón, en el patrón de asistente RAG.
Para cualquier cosa más allá de un solo agent, OpenAI también ofrece el Agents SDK, un sucesor listo para producción de su framework experimental anterior "Swarm". Mientras la Responses API le da el bloque de construcción, una llamada de entrada y una respuesta de salida, el Agents SDK le da la orquestación a su alrededor: Agents (un modelo más instrucciones y herramientas), Handoffs (que permiten que un agent delegue una tarea a otro) y Guardrails (que validan lo que entra y lo que sale). El planteamiento de la propia OpenAI es directo: use la Responses API cuando quiera ser dueño del ciclo del agent, y use el Agents SDK cuando quiera que el SDK ejecute ese ciclo por usted. Las novedades de 2026 en el SDK incluyen integración nativa con la Realtime API para agents de voz y compatibilidad de primera clase con servidores de Model Context Protocol, de modo que cualquier herramienta que hable MCP se convierte en una capacidad conectable sin código intermedio personalizado.
El recorrido de construcción
- Decida quién es dueño del ciclo. Para un solo agent bastante simple, llame directamente a la Responses API y gestione en su propio código el ciclo de entrada, salida y llamada a funciones. Para varios agents que se coordinan, o si prefiere no escribir ese ciclo usted mismo, comience con el Agents SDK.
- Escriba las instrucciones del agent. Son los bloques de rol y reglas de cómo construir un AI agent, expresados como un system prompt: de qué se encarga el agent y qué nunca debe hacer.
- Adjunte las herramientas integradas que necesite. Búsqueda de archivos si debe responder a partir de sus propios documentos, búsqueda web si necesita información actual, intérprete de código para cálculos, uso del computador solo si realmente necesita operar una interfaz.
- Conecte herramientas personalizadas de llamada a funciones para sus propios sistemas. Defina un esquema JSON para cada función (nombre, parámetros, descripción); el modelo solicita una llamada con argumentos específicos, el código de su aplicación la ejecuta realmente contra su CRM, base de datos o API, y devuelve el resultado para que el modelo siga razonando. Es la misma mecánica de llamada a herramientas que se explica a fondo en cómo usan herramientas los AI agents.
- Use Conversations para todo lo que deba persistir entre sesiones, el sucesor directo de los Threads de Assistants.
- Agregue Handoffs si el trabajo se divide con claridad entre agents especializados, el mismo patrón de orquestación que se explica en sistemas multi-agent.
- Agregue Guardrails para validar entradas y salidas, y agregue trazabilidad (la integración nativa con Sentry del SDK, o su propio registro) para ver exactamente qué herramientas se ejecutaron y por qué antes de confiarle al agent un volumen real.
- Despliéguelo detrás de su propio backend. Aquí no hay un host visual; usted es dueño del servidor, la autenticación y la lógica de reintentos.
La implementación avanza desde la propiedad del ciclo y las instrucciones hasta las herramientas, el estado persistente, los handoffs, los guardrails y la trazabilidad.
Un ejemplo real: un AI Knowledge Base Agent
Un agent de knowledge base encaja de forma natural con la Responses API, ya que se apoya directamente en la herramienta integrada de búsqueda de archivos en lugar de código de recuperación personalizado.
Un usuario hace una pregunta. Las instrucciones del agent lo restringen a responder únicamente a partir de un conjunto indexado de documentos de la empresa que se subió, conectado mediante la herramienta de búsqueda de archivos. Busca, encuentra los pasajes relevantes y responde con una cita a su documento de origen en lugar de una afirmación sin respaldo. Si la búsqueda de archivos no devuelve una coincidencia confiable, las instrucciones le indican que lo diga explícitamente en lugar de adivinar, y una herramienta personalizada de llamada a funciones le permite escalar la pregunta a una cola humana cuando no puede responder.
Es la misma estructura de reglas y barreras de protección que especifica por completo el plan de construcción del AI Knowledge Base Agent: restringirse a fuentes aprobadas, citar de dónde sale la respuesta y escalar en lugar de adivinar. Construirlo en la Responses API consiste sobre todo en conectar la herramienta de búsqueda de archivos y la función de escalada, y dejar que el propio razonamiento del modelo decida cuándo aplica cada una.
Costos y límites
La API de OpenAI factura por tokens (entrada y salida con precios separados, que varían según el modelo), y cada una de las herramientas integradas tiene su propia medición: la búsqueda web y la búsqueda de archivos cobran por llamada o por volumen de documentos almacenados, y el intérprete de código y el uso del computador cobran por el tiempo de cómputo que ejecutan. Las tarifas cambian con la frecuencia suficiente como para que valga la pena consultar directamente la página de precios de OpenAI en lugar de tratar cualquier cifra de aquí como vigente. Lo que importa para planificar es la forma del costo, basada en el uso y repartida en varios medidores separados, no un precio fijo único, así que lea costo total de propiedad de la AI antes de estimar un agent pesado y siempre activo a partir de la factura de un piloto ligero.
El límite mayor para la mayoría de los equipos no es el costo, sino que este camino no ofrece ningún constructor visual. Todo lo que n8n, Make o Lindy resuelven por usted (alojamiento, reintentos, una interfaz para que personas no técnicas ajusten el agent) es trabajo de su equipo aquí. Esa es la compensación que conviene nombrar con claridad: usted obtiene acceso de primera mano a los modelos y herramientas de OpenAI con la menor abstracción posible entre usted y la API, a cambio de ser dueño de todo el entorno de ejecución. Y si tiene una integración existente con la Assistants API, migrar no es opcional. Debe hacerse antes del 26 de agosto de 2026, usando la correspondencia anterior, o la integración dejará de funcionar por completo.
Cuándo elegir esto frente a otras opciones
| Si usted quiere... | Elija |
|---|---|
| Control total del código directamente sobre los modelos de OpenAI, abstracción mínima, y su equipo ya escribe software | Responses API y Agents SDK de OpenAI |
| El camino más rápido a un agent funcional sin nada de código | Lindy |
| El catálogo de apps prediseñadas más amplio con un constructor visual | Make |
| Self-hosting con un lienzo visual y una salida a código | n8n |
Estas no son elecciones estrictamente excluyentes. n8n, Make y Lindy pueden llamar a los modelos de OpenAI como el motor de razonamiento de un agent construido en su plataforma; usted elige una capa de orquestación, no necesariamente se aleja de los modelos de OpenAI. Construya directamente sobre la Responses API y el Agents SDK cuando su equipo ya entregue código y quiera el menor número de capas entre su aplicación y el modelo. Recurra a una plataforma visual cuando prefiera cambiar parte del control de bajo nivel por una iteración más rápida y un constructor que también puedan tocar personas no técnicas. La urgencia detrás de esa elección es real: Gartner predice que el 40% de las aplicaciones empresariales incluirá AI agents para tareas específicas a finales de 2026, frente a menos del 5% en 2025, justo el tipo de curva de adopción que hace que construir sobre una plataforma que OpenAI está retirando activamente sea hoy la apuesta equivocada.
Datos clave
- OpenAI anunció el desuso de la Assistants API el 26 de agosto de 2025, con una fecha de cierre definitiva el 26 de agosto de 2026. Los proyectos nuevos deben construirse sobre la Responses API.
- La Responses API reemplaza cuatro conceptos de Assistants: los Assistants pasan a ser Prompts, los Threads pasan a ser Conversations, los Runs pasan a ser Responses y los Run steps pasan a ser Items.
- La Responses API incluye cinco herramientas integradas: búsqueda web, búsqueda de archivos, intérprete de código, uso del computador y conexiones a servidores MCP remotos.
- El Agents SDK, un sucesor de producción del framework experimental Swarm de OpenAI, agrega Agents, Handoffs y Guardrails para coordinar a más de un agent.
- Gartner predice que el 40% de las aplicaciones empresariales incluirá AI agents para tareas específicas a finales de 2026, frente a menos del 5% en 2025.
Preguntas frecuentes sobre cómo construir un AI agent con OpenAI Assistants
¿Se puede seguir usando la Assistants API de OpenAI en 2026?
Sí, hasta su fecha de cierre del 26 de agosto de 2026, después de la cual se elimina por completo de la API. Las integraciones existentes siguen funcionando hasta entonces, pero OpenAI ha dirigido todo el desarrollo nuevo hacia la Responses API y el Agents SDK desde que anunció el desuso el 26 de agosto de 2025.
¿Qué reemplaza a la Assistants API?
La Responses API, que unifica y simplifica las mismas capacidades (estado persistente, recuperación, ejecución de código, llamadas a funciones) en un modelo en el que usted envía elementos de entrada y recibe elementos de salida directamente, sin consultar repetidamente un objeto Run. Para coordinar varios agents, el Agents SDK de OpenAI se apoya en la Responses API y agrega handoffs y guardrails.
¿Necesito migrar mi integración existente con la Assistants API?
Sí, antes del 26 de agosto de 2026. La guía de migración de OpenAI hace corresponder cada concepto de Assistants con su equivalente en la Responses API (Assistants con Prompts, Threads con Conversations, Runs con Responses, Run steps con Items) y confirma que no se pierde ninguna funcionalidad, solo se reorganiza.
¿Cuál es la diferencia entre la Responses API y el Agents SDK?
La Responses API es la primitiva subyacente: usted envía una solicitud y obtiene una respuesta, y es dueño del ciclo de llamarla repetidamente, ejecutar las llamadas a funciones y devolver los resultados. El Agents SDK se construye encima de eso y ejecuta el ciclo por usted, agregando handoffs entre varios agents y guardrails de entrada y salida, útil cuando la lógica de un solo agent se vuelve lo bastante compleja como para querer esa estructura.
¿Puedo construir un AI agent sobre los modelos de OpenAI sin escribir código?
No directamente mediante las APIs de OpenAI, ya que no hay un constructor visual. Plataformas como n8n, Make y Lindy pueden llamar a los modelos de OpenAI como el motor de razonamiento de un agent que usted construya de forma visual, que es el camino más accesible si su equipo no quiere escribir ni alojar el código de orquestación.
Siguientes pasos
Si su equipo ya escribe software y quiere el menor número de capas entre su código y los modelos de OpenAI, la Responses API y el Agents SDK son el punto de partida correcto, solo construya allí en lugar de en la API que se está retirando. Si prefiere construir de forma visual, vea cómo construir un AI agent con n8n, cómo construir un AI agent con Make o cómo construir un AI agent con Lindy, según cuánto control frente a velocidad necesite. El resumen de herramientas para desarrolladores y la guía de cómo elegir una plataforma de AI chatbot son buenas siguientes paradas si todavía compara las herramientas propias de OpenAI con una plataforma alojada.
