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

• El SDK de Apps es una opción práctica si necesitas lanzar pronto un flujo de trabajo en ChatGPT o probar allí tus herramientas antes de invertir en una arquitectura de agente personalizada. Si necesitas controlar cada detalle del comportamiento del agente, no suele ser la opción adecuada.

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

• El SDK de Apps encaja en productos que combinan el chat con unos pocos pasos breves de interfaz. Lanzas antes, pero cedes parte del control.

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

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

La mayoría de los equipos aún realizan proyectos piloto de IA o la destinan a usos periféricos con una baja relación entre riesgo y beneficio. Pocos lanzan un producto crítico para el negocio que los usuarios utilicen cada semana. El SDK de Apps de ChatGPT permite reducir esa brecha si tu objetivo es integrarte en ChatGPT en vez de crear por tu cuenta todo el asistente.

Nuestros aprendizajes proceden 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.

El SDK de Apps encajaba con esos requisitos 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 y una pequeña interfaz para tareas concretas: unos pocos pasos específicos mediante 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 agente personalizado y controlado de principio a fin.

• Descubrimiento dentro de ChatGPT: los usuarios debían encontrar el flujo de trabajo donde ya trabajaban.

Validamos estas decisiones con el cliente a medida que desarrollábamos. La contrapartida se mantiene: cuando ChatGPT aloja la sesión, no controlas el entorno de ejecución externo. Puedes orientarlo, pero no controlarlo por completo.

Una aplicación del SDK de Apps 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 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 siguiente paso: más llamadas a herramientas, una respuesta al usuario o ambas cosas. Si has asociado un widget a esa herramienta, puede mostrarse en este turno.

5. El usuario continúa en el chat o en el widget, ya sea con un texto de seguimiento, una elección o una llamada a una herramienta iniciada por el widget. Esto actualiza el hilo; ChatGPT ejecuta otro turno y los pasos 2–4 se repiten hasta completar la tarea.

La clave es esa combinación de chat, acciones del backend y pasos breves de interfaz. También implica 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 centrarse en la lógica del dominio y las medidas de seguridad.

Desarrollar dentro de ChatGPT no equivale a ejecutar tu propio agente. La dificultad del proyecto no residía en los trucos con prompts. Consistía en explicitar lo suficiente las herramientas, los widgets y los siguientes pasos para mantener alineados el modelo y la interfaz.

El SDK de Apps ofrece un enfoque de producto diferente al de un frontend habitual, pero es importante saber para qué situaciones resulta idóneo.

Usa el SDK de Apps cuando quieras

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

• Dejar que ChatGPT aloje la conversación.

• Combinar el lenguaje natural con unos pocos pasos específicos de interfaz.

• Evitar crear tu propia interfaz de chat, el contenedor del agente y el sistema de descubrimiento.

Este último punto importa cuando tus usuarios ya trabajan habitualmente en ChatGPT.

Crea tu propio agente cuando necesites

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

• Una interfaz y un proceso de confirmación personalizados 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 todo el flujo de trabajo constituyen tu producto, una arquitectura personalizada suele encajar mejor.

Durante el proyecto, la palabra que se repetía era «control»: por un lado, rapidez y un entorno conocido; por otro, control parcial del entorno de ejecución. Esa fue la contrapartida que el cliente aceptó al priorizar llegar a los usuarios en ChatGPT frente a controlar toda la arquitectura.

El caso ideal parece sencillo: el usuario pide algo, se ejecuta la herramienta, vuelven los datos y aparece un widget cuando hay que elegir.

En la práctica, el problema eran las transiciones. Un widget no es un elemento decorativo. Cuando aparece en pantalla, cambia lo que ve el modelo y lo que hace a continuación. Trata las acciones de los widgets como eventos con nombre, no como mensajes de chat imprecisos.

La arquitectura del proyecto era sencilla: FastMCP, Pydantic, React y TypeScript. Integrar estos componentes no supuso ningún problema. El verdadero trabajo consistió en lograr que el modelo, las herramientas y la interfaz coincidieran en el siguiente paso.

Haz que cada transición sea evidente

Dejamos de tratar los resultados de las herramientas como datos sin procesar del backend. Cada respuesta pasó a ser una transición.

Un buen resultado de herramienta:

• Proporciona al widget lo necesario para renderizarse.

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

• Cuando el flujo lo requiere, indica qué debe ocurrir a continuación para que el modelo no tenga que adivinarlo.

Las acciones de los widgets no deberían enviar texto impreciso al hilo. Deben indicar qué hizo el usuario y qué debe ocurrir después.

La fiabilidad aumentó cuando las transiciones quedaron claras.

El modelo sigue instrucciones breves y claras cuando se incluyen en la salida de la herramienta y en las acciones de los widgets.

A continuación mostramos una pequeña estructura de Pydantic que utilizamos. El campo output contiene los datos estructurados que necesita el widget cuando se muestra uno, así como los hechos que ChatGPT debe usar en la sesión. El campo agent_directions contiene una breve indicación de lo que 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 sencillos

Los widgets que funcionaron servían para tomar una decisión y luego devolvían el control. Las listas cortas, las confirmaciones o una pantalla de revisión sencilla funcionaron mejor que convertir el widget en una aplicación en miniatura. Incluir algo de lógica en el widget, como una validación sencilla o un siguiente paso fijo, también ayudó cuando queríamos que el flujo fuera 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 («He seleccionado...», «He confirmado...»). Los redactamos como informes breves sobre lo que había hecho el usuario («El usuario ha seleccionado...», «El usuario ha confirmado...»). Probamos este enfoque porque ChatGPT añadía los mensajes de los widgets como mensajes de herramientas, no como mensajes del usuario.

Acciones directas cuando el siguiente paso 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 datos de ChatGPT.

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

Gestión de errores

Cuando fallaba una llamada a una herramienta, devolvíamos los códigos de error MCP adecuados 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 siguiente paso razonable o ambas cosas.

Gestión del contexto de las herramientas

Guardamos 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 pedir a ChatGPT que los enviara de nuevo 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.

• Conservamos los registros de sesión en nuestros sistemas para la depuración y el soporte.

Al principio mostrábamos un widget, suponíamos que el modelo «lo había entendido» y esperábamos la llamada de seguimiento correcta. A veces ocurría. A menudo, no.

Sin una transición clara, ChatGPT podía resumir cuando queríamos una acción, pedir al usuario que repitiera una elección o seguir planificando cuando debía haberse detenido.

La solución consistió en explicitar el siguiente paso en los resultados estructurados y los datos de los widgets, no en esperar que el modelo lo dedujera.

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

La documentación del SDK de Apps describe herramientas que pueden excluirse de la lista del agente para que no las elija, pero que el widget aún puede llamar. Cuando configuramos la visibilidad como exclusiva de la aplicación, esas herramientas también dejaron de estar disponibles para el widget, no solo para el agente. No logramos configurar el sistema de modo que el agente no pudiera ver una herramienta, pero el widget sí.

El silencio o un «éxito» genérico cuando no había ocurrido nada útil era peor que un error directo. Por eso tratamos los fallos de herramientas y widgets como resultados de pleno derecho: si un paso no podía continuar, lo indicábamos con claridad y devolvíamos un error explícito, en vez de dejar al usuario ante un widget que se había renderizado pero no le permitía avanzar. Esto mejoró la usabilidad y aumentó la fiabilidad del comportamiento del modelo.

Si buscas un flujo de trabajo en ChatGPT que requiera menos desarrollo de plataforma a medida, el SDK de Apps es una solución práctica. 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 desde el principio tu propia arquitectura de agente. Es probable que, con el tiempo, desarrollar solo dentro de ChatGPT deje de ser suficiente.

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

El siguiente paso para los equipos en la misma situación es elegir un flujo de trabajo con un resultado claro, documentar las transiciones entre el chat, las herramientas y los widgets, y someter a pruebas intensivas los reintentos y errores antes de dedicar demasiado tiempo a ajustar los prompts.