Què hem après en llançar un producte amb l'Apps SDK de ChatGPT

• L'Apps SDK és una opció pràctica si necessiteu aviat un flux de treball a ChatGPT o si hi voleu provar les vostres eines abans d'invertir en una pila d'agents personalitzada. Si necessiteu controlar cada pas del comportament de l'agent, normalment no ho és.

• Trieu l'Apps SDK quan ChatGPT hagi de ser la interfície principal i vulgueu eines i petits elements d'IU sense crear un producte de xat complet. Trieu una pila d'agents pròpia quan necessiteu controlar estrictament el flux, la memòria, les indicacions i les operacions d'escriptura.

• L'Apps SDK encaixa amb productes que combinen el xat amb uns quants passos breus d'IU. Podeu llançar abans, però cediu part del control.

• El que ens va funcionar va ser definir amb claredat les eines, el comportament dels ginys i els passos següents. Ens vam basar en aquests elements, i no en l'LLM, per definir el flux. El model era especialment útil quan explicava resultats que el sistema ja havia triat.

• A continuació expliquem com triar i, després, què va funcionar i què no.

La majoria d'equips encara fan proves pilot d'IA o la destinen a usos perifèrics amb poc risc i poc benefici. Pocs llancen un producte essencial per a l'empresa que els usuaris utilitzin cada setmana. L'Apps SDK de ChatGPT és una manera de reduir aquesta distància si l'objectiu és integrar-vos a ChatGPT en lloc de crear tot l'assistent pel vostre compte.

Els nostres aprenentatges provenen d'un projecte per a un client en què els requisits apuntaven a ChatGPT com a interfície principal i a una via ràpida que no exigia finançar un producte de xat complet i a mida.

D'acord amb aquests requisits, l'Apps SDK encaixava perquè el client necessitava:

• No haver de crear ni allotjar cap producte de xat específic: volien arribar als usuaris dins de ChatGPT, no crear la carcassa d'un altre assistent independent.

• Xat i una IU petita i específica per a cada tasca: uns quants passos concrets amb ginys, no un segon producte complet dins del flux de treball.

• Comportament del backend exposat mitjançant eines MCP: crides d'eines estàndard, no un entorn d'execució d'agents personalitzat i gestionat de cap a cap.

• Descobriment dins de ChatGPT: els usuaris havien de trobar el flux de treball allà on ja treballen.

Vam validar aquestes decisions amb el client durant el desenvolupament. La contrapartida continua sent la mateixa: quan ChatGPT allotja la sessió, no controleu l'entorn d'execució extern. El podeu orientar, però no controlar del tot.

Una aplicació de l'Apps SDK connecta tres elements:

1. L'entorn d'execució d'agents de ChatGPT

2. Les vostres eines MCP

3. La IU dels vostres ginys

El flux a la pràctica:

1. L'usuari demana alguna cosa a ChatGPT.

2. ChatGPT pot cridar una de les vostres eines MCP.

3. El vostre servidor retorna un resultat estructurat de l'eina.

4. ChatGPT llegeix el resultat i decideix el pas següent: fer més crides d'eines, respondre a l'usuari o totes dues coses. Si heu associat un giny a l'eina, pot aparèixer en aquest torn.

5. L'usuari continua al xat o al giny (amb text de seguiment, una tria o una crida d'eina iniciada pel giny). Això actualitza el fil; ChatGPT executa un altre torn i els passos del 2 al 4 es repeteixen fins que s'acaba la tasca.

L'objectiu és precisament aquesta combinació de xat, accions del backend i passos breus d'IU. Això també vol dir que els punts fràgils són els traspassos entre el xat, les eines i la IU.

No heu de tornar a crear des de zero la IU del xat, la connexió de les eines, els patrons d'autenticació ni la carcassa dels ginys. En molts productes, això redueix molt el temps de desenvolupament i permet centrar-se en la lògica del domini i les mesures de protecció.

Desenvolupar dins de ChatGPT no és el mateix que executar un agent propi. La part difícil del projecte no van ser els trucs amb les indicacions. Va ser definir les eines, els ginys i els passos següents amb prou claredat perquè el model i la IU es mantinguessin alineats.

L'Apps SDK ofereix una estructura de producte diferent de la del frontend habitual, però és important saber per a quins casos és idònia.

Utilitzeu l'Apps SDK si voleu

• Llançar ràpidament un flux de treball a ChatGPT.

• Permetre que ChatGPT allotgi la conversa.

• Combinar el llenguatge natural amb uns quants passos concrets d'IU.

• Evitar crear una interfície de xat, un contenidor d'agents i un sistema de descobriment propis.

Aquest últim punt és important quan els usuaris ja treballen habitualment a ChatGPT.

Creeu el vostre propi agent si necessiteu

• Un flux fix pas a pas que pugueu imposar mitjançant codi.

• Una IU i un procés de confirmació personalitzats que controleu de cap a cap.

• Un model propi de memòria i estat.

• Un comportament que hagi de ser predictible en cada execució.

• Traces, registres i mètriques de l'agent.

Si el planificador, les indicacions del sistema i el flux de treball complet són el vostre producte, una pila personalitzada sol encaixar millor.

En el nostre projecte, la paraula recurrent era control: d'una banda, velocitat i una plataforma coneguda; de l'altra, control parcial de l'entorn d'execució. Aquesta va ser la contrapartida que el client va acceptar en prioritzar trobar els usuaris a ChatGPT per davant de controlar tota la pila.

El camí ideal sembla senzill: l'usuari demana, l'eina s'executa, arriben les dades i el giny apareix quan cal prendre una decisió.

A la pràctica, el problema eren els traspassos. Un giny no és decoració. Quan apareix en pantalla, canvia el que veu el model i el que fa després. Tracteu les accions dels ginys com a esdeveniments amb nom, no com a xat lliure.

La pila del projecte era senzilla: FastMCP, Pydantic, React i TypeScript. Integrar aquestes tecnologies no va ser cap problema. La feina consistia a aconseguir que el model, les eines i la IU coincidissin sobre què havia de passar després.

Feu evident cada traspàs

Vam deixar de tractar els resultats de les eines com a càrregues de dades sense processar del backend. Cada resposta es va convertir en un traspàs.

Un bon resultat d'eina:

• Proporciona al giny el que necessita per representar-se.

• Proporciona a ChatGPT dades estructurades en què basar la resposta.

• Quan el flux ho requereix, indica què ha de passar després perquè el model no ho hagi d'endevinar.

Les accions dels ginys no haurien d'enviar text vague al fil. Haurien d'indicar què ha fet l'usuari i què ha de passar després.

La fiabilitat va augmentar quan els traspassos van quedar clars.

El model segueix instruccions breus i clares quan formen part de la sortida de l'eina i de les accions dels ginys.

A continuació hi ha una petita estructura de Pydantic que vam utilitzar. El camp output conté les dades estructurades que necessita el giny quan se'n mostra un, així com la informació que ChatGPT ha d'utilitzar a la sessió. El camp agent_directions conté una línia breu que indica què ha de fer l'assistent a continuació. Reason és 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

Manteniu els ginys petits

Els ginys que funcionaven permetien prendre una sola decisió i després retornaven el control. Les llistes breus, les confirmacions o una pantalla de revisió concisa funcionaven millor que convertir el giny en una miniaplicació. Una mica de lògica al giny, com ara una validació senzilla o un pas següent fix, continuava sent útil quan volíem un flux més determinista.

Tercera persona als missatges dels ginys

Vam deixar d'escriure els seguiments dels ginys com si fossin missatges de xat de l'usuari ("I selected...", "I confirmed..."). Els redactàvem com a informes breus sobre el que havia fet l'usuari ("The user selected...", "The user confirmed..."). Vam provar aquest enfocament perquè ChatGPT afegia els missatges dels ginys com a missatges d'eina, no d'usuari.

Accions directes quan el pas següent és evident

Si un botó implica clarament quina és la crida d'eina següent, funcionava millor deixar que el giny l'activés directament que no pas forçar un altre torn de xat. Això només és aplicable si la crida d'eina següent no necessita dades de ChatGPT.

Això facilitava l'aplicació de fluxos deterministes i reduïa la latència en evitar un altre torn de xat.

Gestió d'errors

Quan fallava una crida d'eina, retornàvem els codis d'error MCP adients i missatges breus i clars des de l'eina. Així, ChatGPT rebia informació real sobre les crides fallides i podia explicar el problema a l'usuari, triar un pas següent raonable o fer totes dues coses.

Gestió del context de les eines

Manteníem l'estat de la sessió al nostre servidor. ChatGPT envia context de la sessió amb les crides d'eines; a FastMCP vam assignar un paràmetre Context a cada eina perquè el gestor pogués llegir i actualitzar aquest estat.

• Els identificadors estables i els resultats anteriors es desaven a la sessió, en lloc de demanar a ChatGPT que els tornés a passar com a arguments de l'eina en cada crida.

• Quan apareixien bucles de crides d'eines, podíem detectar les crides duplicades i retornar un error clar mitjançant el resultat de l'eina.

• Els registres de sessió es mantenien als nostres sistemes per facilitar la depuració i el suport.

Al principi mostràvem un giny, suposàvem que el model "ho havia entès" i esperàvem la crida d'eina de seguiment correcta. De vegades passava. Sovint, no.

Sense un traspàs clar, ChatGPT podia resumir quan volíem una acció, demanar a l'usuari que repetís una tria o continuar planificant quan ja s'hauria d'haver aturat.

La solució va ser especificar el pas següent als resultats estructurats i a les càrregues de dades dels ginys, en lloc d'esperar que el model el deduís.

Vam intentar ser enginyosos repartint les respostes entre la sortida de l'eina, les metadades ocultes i el text del xat, tal com indica la documentació de l'Apps SDK. Però no podíem llegir les metadades ocultes des dels ginys. Per tant, no podíem utilitzar aquest mètode.

La documentació de l'Apps SDK descriu eines que podeu excloure de la llista d'eines de l'agent perquè no les triï, però que encara es poden cridar des del giny. Quan configuràvem la visibilitat només per a l'aplicació, aquestes eines també deixaven d'estar disponibles des del giny, no només des de l'agent. No vam aconseguir cap configuració en què l'agent no pogués veure una eina però el giny sí.

El silenci o un "èxit" genèric quan no havia passat res útil era pitjor que un error directe. Per això vam tractar els errors d'eines i ginys com a resultats de primer nivell: si un pas no podia continuar, ho indicàvem amb claredat i retornàvem un error explícit, en lloc de deixar els usuaris davant d'un giny que es mostrava però no els permetia avançar. Això va millorar la usabilitat i va fer més fiable el comportament del model.

Si voleu un flux de treball a ChatGPT amb menys feina de plataforma personalitzada, l'Apps SDK és una manera pràctica d'aconseguir-ho. Cediu part del control a canvi de velocitat i d'arribar als usuaris allà on ja treballen.

Si necessiteu controlar cada branca del flux, la IU i qui decideix cada pas, planifiqueu una pila d'agents pròpia des del principi. És probable que, amb el temps, desenvolupar només dins de ChatGPT ja no sigui suficient.

També podeu utilitzar l'Apps SDK per executar el vostre servidor MCP dins de ChatGPT abans de crear pel vostre compte el xat, l'autenticació i la infraestructura d'agents, i després passar a una pila pròpia quan el producte ho necessiti.

El pas següent per als equips en la mateixa situació és triar un flux de treball amb un resultat clar, documentar els traspassos entre el xat, les eines i els ginys, i sotmetre a proves intensives els reintents i els errors abans de dedicar gaire temps a ajustar les indicacions.