Lo que aprendimos al lanzar productos con el Apps SDK de ChatGPT

• El Apps SDK es una opción práctica si pronto necesitas un flujo de trabajo en ChatGPT o si quieres probar ahí tus herramientas antes de invertir en una arquitectura personalizada de agentes. Si necesitas controlar cada aspecto del comportamiento del agente, por lo general no es la opción adecuada.

• Elige el Apps SDK cuando ChatGPT deba ser la interfaz principal y quieras combinar herramientas con pequeños elementos de interfaz sin crear un producto de chat completo. Elige tu propia arquitectura de agentes cuando necesites un control estricto del flujo, la memoria, los prompts y las operaciones de escritura.

• El Apps SDK es adecuado para productos que combinan el chat con unos pocos pasos breves en la interfaz. Lanzas más rápido, pero cedes parte del control.

• Lo que nos funcionó fue definir con claridad las herramientas, el comportamiento de los widgets y los pasos siguientes. Nos basamos en esos elementos, y no en el LLM, para definir el flujo. El modelo resultó más útil al explicar resultados que el sistema ya había elegido.

• A continuación: cómo elegir y, después, qué funcionó y qué no.

La mayoría de los equipos aún realiza pruebas piloto de IA o la destina a usos secundarios con una baja relación entre riesgo y beneficio. Pocos lanzan un producto esencial para el negocio que los usuarios utilizan cada semana. El Apps SDK de ChatGPT permite cerrar esa brecha si tu objetivo es operar dentro de ChatGPT en lugar de crear todo el asistente por tu cuenta.

Nuestros aprendizajes provienen de un proyecto para un cliente cuyos requisitos apuntaban a ChatGPT como interfaz principal y a una vía rápida que no exigiera financiar un producto de chat totalmente personalizado.

Ante esos requisitos, el Apps SDK resultó adecuado porque el cliente necesitaba:

• No tener que crear y alojar un producto de chat específico: buscaba llegar a los usuarios dentro de ChatGPT, no ofrecer otra interfaz de asistente independiente.

• Chat más una interfaz pequeña y específica para cada tarea: unos pocos pasos concretos en widgets, no un segundo producto completo dentro del flujo de trabajo.

• Comportamiento del backend expuesto mediante herramientas MCP: llamadas estándar a herramientas, no un entorno de ejecución de agentes personalizado y administrado de principio a fin.

• Descubrimiento dentro de ChatGPT: los usuarios deben encontrar el flujo de trabajo donde ya trabajan.

Validamos esas decisiones con el cliente durante el desarrollo. Esto implica una limitante: cuando ChatGPT aloja la sesión, no eres propietario del entorno de ejecución externo. Puedes orientarlo, pero no controlarlo por completo.

Una aplicación del Apps SDK conecta tres elementos:

1. El entorno de ejecución de agentes de ChatGPT

2. Tus herramientas MCP

3. La interfaz de tus widgets

El flujo en la práctica:

1. El usuario le pide algo a ChatGPT.

2. ChatGPT puede llamar a una de tus herramientas MCP.

3. Tu servidor devuelve un resultado estructurado de la herramienta.

4. ChatGPT lee el resultado y decide el paso siguiente: llamar a más herramientas, responder al usuario o hacer ambas cosas. Si vinculaste un widget a esa herramienta, puede aparecer en este turno.

5. El usuario continúa en el chat o en el widget mediante texto adicional, una selección o una llamada a una herramienta activada por el widget. Esto actualiza la conversación; ChatGPT ejecuta otro turno y los pasos 2 a 4 se repiten hasta completar la tarea.

El objetivo es precisamente combinar chat, acciones del backend y pasos breves en la interfaz. Esto también significa que los puntos frágiles son las transiciones entre el chat, las herramientas y la interfaz.

No tienes que crear desde cero la interfaz de chat, la conexión de herramientas, los patrones de autenticación ni el contenedor de widgets. En muchos productos, esto reduce considerablemente el tiempo de desarrollo y permite concentrarse en la lógica del dominio y las medidas de protección.

Desarrollar dentro de ChatGPT no es lo mismo que operar tu propio agente. La parte difícil del proyecto no fueron los trucos con prompts. Fue definir las herramientas, los widgets y los pasos siguientes con suficiente claridad para que el modelo y la interfaz se mantuvieran alineados.

El Apps SDK ofrece un enfoque de producto distinto al de un frontend habitual, pero es importante saber para qué situaciones resulta ideal.

Usa el Apps SDK cuando quieras

• Lanzar rápidamente un flujo de trabajo en ChatGPT.

• Dejar que ChatGPT aloje la conversación.

• Combinar el lenguaje natural con algunos pasos específicos en la interfaz.

• Evitar crear tu propia interfaz de chat, contenedor de agentes y sistema de descubrimiento.

Este último punto es importante cuando tus usuarios ya trabajan en ChatGPT.

Crea tu propio agente cuando necesites

• Un flujo fijo paso a paso que puedas imponer mediante código.

• Una interfaz y una ruta de confirmación personalizadas que controles de principio a fin.

• Tu propio modelo de memoria y estado.

• Un comportamiento predecible en cada ejecución.

• Trazas, registros y métricas del agente.

Si el planificador, los prompts del sistema y el flujo de trabajo completo son tu producto, una arquitectura personalizada suele ser la mejor opción.

Durante el proyecto, la palabra recurrente fue “control”: por un lado, rapidez y una plataforma de alojamiento conocida; por otro, control parcial del entorno de ejecución. Esa fue la limitante que aceptó el cliente al priorizar llegar a los usuarios en ChatGPT sobre controlar toda la arquitectura.

El flujo ideal parece sencillo: el usuario hace una solicitud, se ejecuta la herramienta, regresan los datos y aparece un widget cuando se necesita elegir.

En la práctica, el problema fueron los traspasos. Un widget no es decorativo. Una vez en pantalla, cambia lo que el modelo ve y hace a continuación. Trata las acciones de los widgets como eventos con nombre, no como mensajes informales de chat.

La arquitectura del proyecto era sencilla: FastMCP, Pydantic, React y TypeScript. Integrarlos no presentó problemas. El verdadero trabajo consistió en lograr que el modelo, las herramientas y la interfaz coincidieran sobre lo que debía suceder después.

Hacer explícito cada traspaso

Dejamos de tratar los resultados de las herramientas como datos sin procesar del backend. Cada resultado pasó a ser un punto de traspaso.

Un buen resultado de herramienta:

• Proporciona al widget lo necesario para mostrarse.

• Proporciona a ChatGPT datos estructurados en los que basar la respuesta.

• Cuando el flujo lo requiere, indica qué debe suceder después para que el modelo no tenga que adivinarlo.

Las acciones de los widgets no deben enviar texto impreciso a la conversación. Deben indicar qué hizo el usuario y qué debe suceder después.

La confiabilidad aumentó cuando los traspasos quedaron claros.

El modelo sigue instrucciones breves y claras cuando aparecen en el resultado de la herramienta y en las acciones de los widgets.

A continuación se muestra un pequeño esquema de Pydantic que usamos. El campo output contiene los datos estructurados que necesita el widget cuando se muestra uno, además de los datos que ChatGPT debe usar durante la sesión. El campo agent_directions contiene una línea breve que indica qué debe hacer el asistente a continuación. Reason es opcional.

1from typing import Generic, TypeVar2
3from pydantic import BaseModel4
5T = TypeVar("T")6
7class AgentDirections(BaseModel):8 assistant_instruction: str9 reason: str | None = None10
11class ToolResults(BaseModel, Generic[T]):12 agent_directions: AgentDirections13 output: T

Mantén los widgets pequeños

Los widgets que funcionaron permitían tomar una sola decisión y luego devolvían el control. Las listas breves, las confirmaciones o una pantalla de revisión sencilla funcionaron mejor que convertir el widget en una aplicación pequeña. Incluir algo de lógica en el widget, como una validación sencilla o un paso siguiente fijo, también ayudó cuando buscábamos un flujo más determinista.

Tercera persona en los mensajes de los widgets

Dejamos de redactar los mensajes de seguimiento de los widgets como si fueran mensajes del usuario: “Seleccioné…” o “Confirmé…”. Los redactamos como informes breves sobre lo que hizo el usuario: “El usuario seleccionó…” o “El usuario confirmó…”. Probamos este enfoque porque ChatGPT agregaba los mensajes de los widgets como mensajes de herramientas, no como mensajes del usuario.

Acciones directas cuando el paso siguiente es evidente

Si un botón implica claramente la siguiente llamada a una herramienta, dejar que el widget la active directamente funcionó mejor que forzar otro turno de chat. Esto solo se aplica si la siguiente llamada a la herramienta no necesita información de ChatGPT.

Esto ayudó a imponer flujos deterministas y redujo la latencia al evitar otro turno de chat.

Manejo de errores

Cuando fallaba una llamada a una herramienta, devolvíamos los códigos de error MCP correctos y mensajes breves y claros desde la herramienta. Así, ChatGPT recibía información real sobre las llamadas fallidas y podía explicar el problema al usuario, elegir un paso siguiente razonable o hacer ambas cosas.

Administración del contexto de las herramientas

Mantuvimos el estado de la sesión en nuestro servidor. ChatGPT envía contexto limitado a la sesión con las llamadas a herramientas; en FastMCP asignamos a cada herramienta un parámetro Context para que el controlador pudiera leer y actualizar ese estado.

• Los identificadores estables y los resultados anteriores se guardaban en la sesión, en vez de pedirle a ChatGPT que los volviera a enviar como argumentos en cada llamada.

• Cuando aparecían bucles de llamadas a herramientas, podíamos detectar las llamadas duplicadas y devolver un error claro mediante el resultado de la herramienta.

• Los registros de sesión permanecían de nuestro lado para facilitar la depuración y el soporte.

Al principio mostrábamos un widget, suponíamos que el modelo “lo entendía” y esperábamos la llamada de seguimiento correcta a una herramienta. A veces ocurría. A menudo, no.

Sin un traspaso claro, ChatGPT podía resumir en lugar de ejecutar una acción, pedirle al usuario que repitiera una elección o seguir planificando en lugar de detenerse.

La solución fue especificar el paso siguiente en los resultados estructurados y en los datos de los widgets, en lugar de esperar que el modelo lo dedujera.

Intentamos aplicar el enfoque de la documentación del Apps SDK y dividir las respuestas entre el resultado de la herramienta, los metadatos ocultos y el texto del chat. Sin embargo, no podíamos leer los metadatos ocultos desde los widgets. Por lo tanto, no pudimos usar este enfoque.

La documentación del Apps SDK describe herramientas que pueden excluirse de la lista del agente para que no las elija, pero que aun así pueden llamarse desde el widget. Cuando configuramos la visibilidad solo para la aplicación, esas herramientas también dejaron de estar disponibles desde el widget, no solo desde el agente. Nunca logramos una configuración en la que el agente no pudiera ver una herramienta, pero el widget sí.

El silencio o un mensaje genérico de “éxito” cuando no ocurría nada útil era peor que un error directo. Por eso tratamos los fallos de herramientas y widgets como resultados de primera clase: si un paso no podía continuar, lo indicábamos claramente y devolvíamos un error explícito, en lugar de dejar al usuario frente a un widget que se mostraba, pero no le permitía avanzar. Esto mejoró la facilidad de uso y aumentó la confiabilidad del comportamiento del modelo.

Si buscas implementar un flujo de trabajo en ChatGPT con menos desarrollo personalizado de plataforma, el Apps SDK es una forma práctica de lograrlo. Cedes parte del control a cambio de rapidez y de llegar a los usuarios donde ya trabajan.

Si necesitas controlar cada rama del flujo, la interfaz y quién decide cada paso, planifica tu propia arquitectura de agentes desde el principio. Es probable que desarrollar únicamente dentro de ChatGPT termine por resultarte insuficiente.

También puedes usar el Apps SDK para ejecutar tu servidor MCP dentro de ChatGPT antes de crear por tu cuenta el chat, la autenticación y la infraestructura de agentes, y luego migrar a tu propia arquitectura cuando el producto lo requiera.

Siguiente paso para equipos en la misma situación: elijan un flujo de trabajo con un resultado claro, documenten los traspasos entre el chat, las herramientas y los widgets, y sometan los reintentos y errores a pruebas rigurosas antes de dedicar mucho tiempo a ajustar los prompts.