OpenAI Responses API

introducción openai responses api es el provider de inteligencia artificial más avanzado disponible en asisteclick para construir chatbots inteligentes combina los modelos más recientes de openai (familia gpt 5) con herramientas integradas como búsqueda web, ejecución de código, generación de imágenes y análisis de documentos, todo en una sola configuración ¿por qué elegir responses api? modelos de última generación acceso a gpt 5, gpt 5 mini, gpt 5 nano y toda la familia gpt 4 1 herramientas builtin web search, code interpreter e image generation se activan automáticamente, sin configuración adicional soporte multimodal el bot puede recibir y procesar imágenes, documentos, archivos csv/excel y audio structured output respuestas en formato json validado, que permiten extraer variables, detectar intenciones y clasificar conversaciones de forma confiable contexto conversacional automático el historial se mantiene automáticamente entre mensajes, sin necesidad de reenviarlo cada vez nota importante openai assistants api será deprecada el 26 de agosto de 2026 se recomienda configurar nuevos bots directamente con responses api si ya tenés un bot con assistants, consultá la docid al final de este tutorial 1\ cómo configurar un bot con responses api paso 1 crear un nuevo bot o skill llm desde el panel de administración, creá un nuevo bot o abrí la configuración de un skill llm existente paso 2 seleccionar el provider en el selector de provider , elegí "openai responses api (beta)" paso 3 ingresar tu api key de openai pegá tu api key de openai en el campo api key podés verificar que la conexión sea correcta haciendo clic en el botón de verificación (ícono de enchufe) usá el ícono del ojo para mostrar/ocultar la key el botón de enchufe verifica la conexión con openai paso 4 seleccionar el modelo elegí el modelo que mejor se ajuste a tu caso de uso los modelos disponibles para responses api son gpt 5 2 gpt 5 gpt 5 mini (recomendado para la mayoría de casos) gpt 5 nano gpt 4 1 gpt 4 1 mini paso 5 escribir el system prompt (instrucciones) en el campo de instrucciones , describí el comportamiento del bot su personalidad, qué información maneja, cómo debe responder, y qué debe hacer cuando no sabe algo ejemplo de system prompt sos el asistente virtual de tiendaonline tu rol es ayudar a los clientes con consultas sobre productos, envíos y devoluciones reglas \ respondé siempre en español \ sé amable y profesional \ si no sabés la respuesta, ofrecé transferir a un agente humano \ usá la información del knowledge base para responder sobre productos paso 6 configurar knowledge base (opcional) si querés que el bot responda en base a documentos específicos (catálogos, manuales, faqs), configurá un knowledge base subí los archivos en la sección de knowledge base selecciona los knowledge bases que quieras vincular a este bot el sistema realizará un proceso de incorporación de la kb al bot de manera automática en cualquier momentos podés "resetear" toda la base de conocimientos activa del bot de la siguiente manera hacé clic en el botón regenerar (ícono de recarga junto al selector de provider) esto creará un vector store en openai que el bot usará para buscar información relevante paso 7 grabar bot hacé clic en grabar bot para guardar la configuración y activar el bot 2\ modelos disponibles y costos modelo input (usd/1m tokens) output (usd/1m tokens) ideal para gpt 5 2 $1 75 $14 00 máxima capacidad coding, ciencia, razonamiento complejo gpt 5 $1 25 $10 00 flagship general, reducción significativa de alucinaciones gpt 5 mini $0 25 $2 00 recomendado mejor relación costo/rendimiento gpt 5 nano $0 05 $0 40 alto volumen, respuestas ultra rápidas gpt 4 1 $2 00 $8 00 contexto ultra largo (1 millón de tokens) gpt 4 1 mini $0 40 $1 60 contexto largo, económico ¿qué modelo elegir? caso de uso modelo recomendado por qué alto volumen / respuestas simples gpt 5 nano el más económico ($0 05/1m input), ideal para faqs y respuestas cortas uso general / mejor balance gpt 5 mini excelente calidad a un precio accesible, cubre el 90% de los casos máxima calidad gpt 5 o gpt 5 2 para consultas complejas que requieren razonamiento profundo documentos muy largos gpt 4 1 o gpt 4 1 mini ventana de contexto de 1 millón de tokens para procesar documentos extensos 3\ herramientas builtin (tools) responses api incluye herramientas integradas que se activan automáticamente no necesitás configurar nada extra el bot decide cuándo usarlas según la consulta del cliente 3 1 web search (siempre activa) el bot puede buscar información actualizada en internet cuando lo necesita casos de uso el cliente pregunta por precios actuales, disponibilidad o novedades consultas sobre temas que cambian frecuentemente verificación de datos en tiempo real ejemplo cliente "¿cuál es el tipo de cambio del dólar hoy?" bot (busca en internet y responde con el dato actualizado) 3 2 code interpreter (siempre activo) ejecuta código python en tiempo real dentro de un entorno seguro de openai casos de uso análisis de datos el cliente sube un csv o excel y el bot lo procesa cálculos complejos presupuestos, conversiones, estadísticas generación de gráficos y visualizaciones ejemplo cliente (sube un archivo excel con ventas) bot "analicé tu archivo las ventas totales del mes fueron $45,230 el producto más vendido fue " 3 3 image generation (siempre activa) genera imágenes a partir de descripciones de texto usando dall e / gpt image 1 casos de uso el cliente pide que le generen una imagen, logo o diseño visualizaciones creativas para propuestas ejemplo cliente "generame una imagen de un logo moderno para una cafetería" bot (genera y envía la imagen) 3 4 file search / knowledge base (activa cuando hay kb configurada) busca información dentro de los documentos cargados en el knowledge base usando rag (retrieval augmented generation) requisitos tener archivos subidos en el knowledge base del bot haber hecho clic en regenerar para crear el vector store casos de uso consultas sobre catálogos de productos preguntas frecuentes basadas en documentos internos manuales técnicos o políticas de la empresa 3 5 function calling / ai tools (activa cuando hay tools configurados) ejecuta herramientas personalizadas definidas en el playbook para conectar el bot con sistemas externos casos de uso consultar el estado de un pedido en tu sistema crear un ticket en tu crm buscar disponibilidad en tu calendario cualquier integración con apis externas nota los ai tools se configuran en la sección de herramientas del playbook y funcionan de la misma manera que en otros providers responses api soporta schema estricto para validación de parámetros 4\ soporte multimodal el bot puede recibir y procesar múltiples tipos de archivos enviados por los clientes, sin importar el canal (web, whatsapp, telegram, facebook, etc ) tipo formatos soportados cómo lo procesa imágenes jpg, png, gif, webp análisis visual directo (el modelo "ve" la imagen) documentos pdf, doc, docx, pptx, txt se suben a openai como archivos adjuntos para análisis hojas de cálculo xls, xlsx se suben a openai para procesamiento con code interpreter csv csv se envía como texto inline para análisis directo audio mp3, wav, ogg, aac, amr transcripción automática vía whisper, luego se procesa el texto ¿cómo funciona el audio? cuando un cliente envía un mensaje de voz o audio el audio se descarga automáticamente se transcribe usando openai whisper la transcripción se envía al modelo como texto el bot responde en base al contenido del audio esto funciona en todos los canales que soportan audio, incluyendo whatsapp (notas de voz) y telegram 5\ variables en el system prompt (custom assignments) las variables permiten que el bot extraiga información estructurada de la conversación de forma automática se configuran en la sección custom assignments del skill llm modo estructurado (array) definí cada variable con su nombre y descripción, una por línea nombre cliente nombre completo del cliente monto compra monto en dólares que desea gastar producto interes producto por el cual consulta motivo contacto razón principal del contacto el bot extraerá estos valores a medida que el cliente los mencione en la conversación el resultado es un json con cada variable y su valor \[ {"nombre cliente" "juan pérez"}, {"monto compra" "500"}, {"producto interes" "laptop"}, {"motivo contacto" "compra nueva"} ] modo texto libre si preferís dar instrucciones en lenguaje natural extrae el nombre del cliente, su email y número de teléfono de la conversación si menciona un producto específico, extrae también el nombre del producto el bot retornará pares {key, value} genéricos con los datos extraídos ¿cómo se usan las variables? las variables extraídas se guardan automáticamente en la memoria del playbook podés usarlas en otros skills del mismo playbook con la sintaxis {{nombre variable}} notas privadas /private el cliente {{nombre cliente}} consultó por {{producto interes}} mensajes de derivación o cierre 6\ tags personalizados (custom tags) los tags permiten que el bot clasifique automáticamente las conversaciones agregando o quitando etiquetas cómo configurarlos en la sección custom tags del skill llm, definí los tags y cuándo deben aplicarse venta agregar si el cliente muestra intención de compra soporte agregar si el cliente reporta un problema urgente agregar si el cliente expresa urgencia o frustración resuelto agregar si la consulta fue resuelta satisfactoriamente acciones posibles para cada tag, el bot puede ejecutar dos acciones add agregar el tag a la conversación remove quitar el tag de la conversación casos de uso segmentar conversaciones por tipo (venta, soporte, reclamo) marcar intenciones del cliente para seguimiento priorizar tickets automáticamente alimentar reportes y métricas 7\ comando /private notas privadas el bot puede generar notas internas que no se envían al cliente estas notas se insertan como eventos privados en el ticket, visibles solo para los agentes cómo funciona cuando el bot genera una respuesta que comienza con /private , el texto que sigue se guarda como nota privada en lugar de enviarse al cliente ejemplo en el system prompt después de cada interacción, generá una nota privada con el resumen formato /private resumen el cliente {{nombre cliente}} consultó por {{producto interes}} estado {{motivo contacto}} soporte de variables las notas privadas soportan variables de memoria con la sintaxis {{variable}} las variables se reemplazan automáticamente con los valores almacenados en la memoria del playbook casos de uso logging interno registrar información relevante para el equipo resumen de conversación generar un brief automático cuando se transfiere a un agente alertas internas marcar situaciones que requieren atención especial datos extraídos documentar los datos que el bot capturó durante la conversación 8\ mensajes de seguimiento (follow up) cuando la respuesta de openai tarda más de lo habitual (por ejemplo, al usar web search, code interpreter o file search), el bot envía mensajes de espera automáticos para mantener al cliente informado tiempos de envío tiempo transcurrido acción 20 segundos envía primer mensaje de espera 50 segundos envía segundo mensaje de seguimiento 100 segundos envía tercer mensaje 140 segundos envía cuarto mensaje características 3 idiomas disponibles español, inglés y portugués (20 frases por idioma) selección aleatoria las frases se eligen al azar de un pool para no repetirse multi canal se envían por el mismo canal que usa el cliente (web, whatsapp, telegram, etc ) cancelación automática los mensajes programados se cancelan cuando llega la respuesta de openai detección de idioma el idioma se selecciona según la configuración del playbook ejemplos de mensajes (español) "un momento por favor " "estoy procesando tu consulta " "ya casi tengo tu respuesta " "estoy buscando la mejor respuesta " 9\ timeout extendido a 3 minutos responses api tiene un timeout de 180 segundos (3 minutos) , significativamente mayor que los 30 60 segundos típicos de otros providers ¿por qué un timeout más largo? las herramientas builtin pueden requerir tiempo adicional code interpreter ejecutar código python, procesar archivos grandes file search buscar en documentos extensos del knowledge base web search consultar múltiples fuentes en internet image generation generar imágenes a partir de texto ¿qué pasa si se excede el timeout? si openai no responde dentro de los 3 minutos, se genera un error claro y el bot no queda colgado mientras tanto, los /#8 mensajes de seguimiento follow up mantienen al cliente informado durante la espera 10\ debounce inteligente cuando un cliente envía varios mensajes seguidos rápidamente (algo muy común en whatsapp), el sistema acumula todos los mensajes antes de enviarlos a openai cómo funciona el cliente envía un mensaje el sistema espera 2 segundos por si llegan más mensajes si llega otro mensaje dentro de esos 2 segundos, reinicia el timer cuando pasan 2 segundos sin mensajes nuevos, envía todo junto a openai si ya había un request en vuelo a openai, lo cancela y reenvía todo junto beneficios ahorro de tokens en lugar de hacer 3 llamadas separadas, hace una sola con los 3 mensajes combinados mejores respuestas el bot ve el contexto completo del cliente antes de responder menor costo menos llamadas a la api = menor gasto ejemplo cliente (18 30 01) "hola" cliente (18 30 02) "quería consultar por un producto" cliente (18 30 03) "es una laptop dell" (el bot recibe los 3 mensajes juntos y responde una sola vez de forma coherente) 11\ preguntas frecuentes ¿puedo usar responses api y assistants en paralelo? sí podés tener bots con diferentes providers activos al mismo tiempo cada bot usa su propio provider de forma independiente ¿los archivos de mi knowledge base se mantienen al cambiar de provider? los archivos fuente se mantienen en asisteclick, pero necesitás hacer clic en regenerar para crear un nuevo vector store compatible con responses api ¿funciona con todos los canales? sí responses api funciona con todos los canales soportados por asisteclick web, whatsapp, telegram, facebook messenger, instagram y más ¿cómo veo el costo de cada consulta? el costo se calcula automáticamente en base a los tokens de input y output usando las tarifas de cada modelo podés ver el detalle en los reportes de consumo de tu cuenta ¿las herramientas builtin tienen costo adicional? sí web search, code interpreter e image generation pueden generar costos adicionales según el uso estos costos los cobra openai directamente sobre tu api key 12\ migración desde openai assistants importante openai assistants api será deprecada el 26 de agosto de 2026 se recomienda migrar a responses api antes de esa fecha ¿por qué migrar? assistants api dejará de funcionar después del 26 de agosto de 2026 responses api ofrece modelos más nuevos (familia gpt 5), herramientas más potentes y menor costo las herramientas web search, code interpreter e image generation se activan automáticamente pasos para migrar paso 1 clonar el bot existente antes de modificar el bot en producción, cloná el bot actual usando el botón clonar en la configuración del bot esto te permite hacer pruebas sin afectar al bot activo paso 2 cambiar el provider en el bot clonado, cambiá el provider a "openai responses api (beta)" en el selector de provider paso 3 seleccionar el modelo equivalente los modelos de assistants (como gpt 4o) no están disponibles en responses api elegí un modelo equivalente de la familia gpt 5 modelo assistants modelo responses api recomendado gpt 4o gpt 5 mini (mejor y más barato) gpt 4o mini gpt 5 nano (más barato) o gpt 5 mini (mejor calidad) paso 4 regenerar el knowledge base si tu bot usaba knowledge base con assistants, necesitás crear un nuevo vector store hacé clic en el botón regenerar (ícono de recarga junto al selector de provider) esperá a que se complete el proceso ("creating vector store") el sistema creará un nuevo vector store y eliminará el anterior automáticamente \[screenshot botón de regenerar junto al selector de provider] paso 5 adaptar el system prompt el system prompt funciona de la misma manera, pero podés aprovechar las nuevas capacidades configurá custom assignments para extraer variables automáticamente usá /private para generar notas internas revisá y ajustá las instrucciones si es necesario paso 6 qa probar antes de activar probá el bot clonado en un canal de prueba verificá que responda correctamente a las consultas habituales probá el knowledge base con preguntas que requieran buscar en documentos verificá que los ai tools (function calling) funcionen correctamente probá el envío de archivos, imágenes y audio paso 7 switch a producción una vez que estés conforme con las pruebas cambiá el bot default en los canales de producción al bot clonado monitoreá las primeras conversaciones para confirmar que todo funcione diferencias clave a tener en cuenta aspecto assistants api responses api web search no incluida siempre activa, automática code interpreter requería configuración siempre activo, automático image generation no incluida siempre activa, automática ai tools / function calling funciona igual funciona igual, sin cambios necesarios knowledge base vector store del assistant nuevo vector store (requiere regenerar) timeout 30 60 segundos 180 segundos (3 minutos) debounce no incluido automático (2 segundos) mensajes de seguimiento no incluidos automáticos (20s, 50s, 100s, 140s) modelos gpt 4o, gpt 4o mini gpt 5 2, gpt 5, gpt 5 mini, gpt 5 nano, gpt 4 1, gpt 4 1 mini