O que aprendemos ao lançar com o ChatGPT Apps SDK

• O Apps SDK é uma opção prática se precisar de disponibilizar rapidamente um fluxo de trabalho no ChatGPT ou se quiser testar aí as suas ferramentas antes de investir numa infraestrutura de agentes personalizada. Se precisar de controlar todas as etapas do comportamento do agente, normalmente não é a opção certa.

• Escolha o Apps SDK quando o ChatGPT deva ser a interface principal e pretenda combinar ferramentas com pequenos elementos de IU, sem criar um produto de chat completo. Escolha a sua própria infraestrutura de agentes quando precisar de controlar rigorosamente o fluxo, a memória, os prompts e as operações de escrita.

• O Apps SDK adequa-se a produtos que combinam chat com algumas etapas curtas de IU. Lança mais depressa, mas abdica de algum controlo.

• O que funcionou para nós foi definir claramente as ferramentas, o comportamento dos widgets e os passos seguintes. Foi nisso, e não no LLM, que nos apoiámos para definir o fluxo. O modelo foi mais útil ao explicar resultados que o sistema já tinha escolhido.

• A seguir: como escolher e, depois, o que funcionou e o que não funcionou.

A maioria das equipas ainda realiza projetos-piloto de IA ou aplica IA a utilizações periféricas com baixo risco e baixo retorno. Poucas lançam um produto crítico para o negócio que os utilizadores usem todas as semanas. O ChatGPT Apps SDK é uma forma de colmatar essa lacuna se o objetivo for integrar-se no ChatGPT, em vez de criar todo o assistente de raiz.

As nossas conclusões resultam de um projeto para um cliente cujos requisitos apontavam para o ChatGPT como interface principal e para uma via rápida que não exigisse financiar um produto de chat totalmente personalizado.

Perante estes requisitos, o Apps SDK era adequado porque o cliente precisava de:

• Não ter de criar nem alojar um produto de chat dedicado — pretendia chegar aos utilizadores dentro do ChatGPT, não criar mais uma interface de assistente autónoma.

• Chat com uma IU pequena e específica para cada tarefa — algumas etapas focadas em widgets, não um segundo produto completo dentro do fluxo de trabalho.

• Comportamento do backend disponibilizado através de ferramentas MCP — invocação normalizada de ferramentas, não um ambiente de execução de agentes personalizado e controlado de ponta a ponta.

• Descoberta dentro do ChatGPT — os utilizadores devem encontrar o fluxo de trabalho onde já trabalham.

Validámos estas escolhas com o cliente à medida que desenvolvíamos. A contrapartida mantém-se: quando o ChatGPT aloja a sessão, não controla o ambiente de execução externo. Pode orientá-lo, mas não controlá-lo totalmente.

Uma aplicação do Apps SDK interliga três elementos:

1. O ambiente de execução de agentes do ChatGPT

2. As suas ferramentas MCP

3. A IU dos seus widgets

O fluxo na prática:

1. O utilizador pede algo ao ChatGPT.

2. O ChatGPT pode invocar uma das suas ferramentas MCP.

3. O seu servidor devolve um resultado estruturado da ferramenta.

4. O ChatGPT lê esse resultado e decide o passo seguinte: mais invocações de ferramentas, uma resposta ao utilizador ou ambos. Se tiver associado um widget a essa ferramenta, este pode aparecer neste turno.

5. O utilizador continua no chat ou no widget (com texto adicional, uma escolha ou uma invocação de ferramenta acionada pelo widget). Isso atualiza a conversa; o ChatGPT executa outro turno e os passos 2–4 repetem-se até a tarefa estar concluída.

O objetivo é precisamente combinar chat, ações de backend e breves etapas de IU. Isto também significa que os pontos frágeis são as transições entre o chat, as ferramentas e a IU.

Não precisa de recriar de raiz a IU do chat, a integração das ferramentas, os padrões de autenticação nem a estrutura dos widgets. Em muitos produtos, isto reduz bastante o tempo de desenvolvimento e permite concentrar-se na lógica de domínio e nos mecanismos de proteção.

Desenvolver dentro do ChatGPT não é o mesmo que executar o seu próprio agente. A parte difícil do projeto não foram os truques com prompts. Foi tornar as ferramentas, os widgets e os passos seguintes suficientemente explícitos para manter o modelo e a IU alinhados.

O Apps SDK oferece um formato de produto diferente do frontend habitual, mas é importante saber para que cenários é ideal.

Utilize o Apps SDK quando quiser

• Lançar rapidamente um fluxo de trabalho no ChatGPT.

• Deixar o ChatGPT alojar a conversa.

• Combinar linguagem natural com algumas etapas focadas de IU.

• Evitar criar a sua própria interface de chat, estrutura de agentes e mecanismo de descoberta.

Este último ponto é importante quando os seus utilizadores já trabalham no ChatGPT.

Crie o seu próprio agente quando precisar de

• Um fluxo fixo, passo a passo, que possa impor através do código.

• Uma IU e um processo de confirmação personalizados, controlados por si de ponta a ponta.

• Um modelo próprio de memória e estado.

• Um comportamento que tenha de ser previsível em todas as execuções.

• Rastreios, registos e métricas do agente.

Se o planeador, os prompts de sistema e todo o fluxo de trabalho constituem o seu produto, uma infraestrutura personalizada costuma ser a melhor opção.

No nosso projeto, a palavra recorrente foi controlo: de um lado, rapidez e uma plataforma familiar; do outro, controlo parcial do ambiente de execução. Foi esta a contrapartida aceite pelo cliente ao dar prioridade a encontrar os utilizadores no ChatGPT, em vez de controlar toda a infraestrutura.

O cenário ideal parece simples: o utilizador faz um pedido, a ferramenta é executada, os dados regressam e o widget aparece quando é necessário fazer uma escolha.

Na prática, as transições foram o problema. Um widget não é um elemento decorativo. Quando aparece no ecrã, altera aquilo que o modelo vê e faz a seguir. Trate as ações dos widgets como eventos identificados, não como conversa informal.

A infraestrutura do projeto era simples: FastMCP, Pydantic, React e TypeScript. A integração destas tecnologias correu bem. O verdadeiro trabalho foi fazer com que o modelo, as ferramentas e a IU concordassem sobre o passo seguinte.

Torne cada transição óbvia

Deixámos de tratar os resultados das ferramentas como dados brutos do backend. Cada resultado passou a constituir uma transição.

Um bom resultado de ferramenta:

• Fornece ao widget aquilo de que precisa para ser apresentado.

• Fornece ao ChatGPT factos estruturados em que basear a resposta.

• Quando o fluxo o exige, indica o que deve acontecer a seguir para que o modelo não tenha de adivinhar.

As ações dos widgets não devem enviar texto vago para a conversa. Devem indicar o que o utilizador fez e o que deve acontecer a seguir.

A fiabilidade aumentou quando as transições se tornaram claras.

O modelo segue instruções curtas e claras quando estas estão incluídas no output da ferramenta e nas ações dos widgets.

Segue-se uma pequena estrutura Pydantic que utilizámos. O campo output contém os dados estruturados de que o widget precisa quando é apresentado, bem como os factos que o ChatGPT deve utilizar na sessão. O campo agent_directions contém uma linha curta que indica o que o assistente deve fazer a seguir. O campo Reason é 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

Mantenha os widgets pequenos

Os widgets que funcionaram tratavam uma única decisão e depois devolviam o controlo. Listas curtas, confirmações ou um ecrã de revisão simples funcionaram melhor do que transformar o widget numa miniaplicação. Alguma lógica no widget, como uma validação simples ou um passo seguinte fixo, continuou a ser útil quando pretendíamos tornar o fluxo mais determinístico.

Terceira pessoa nas mensagens dos widgets

Deixámos de escrever as mensagens subsequentes dos widgets como se fossem mensagens do utilizador («Selecionei...», «Confirmei...»). Passámos a escrevê-las como relatos breves do que o utilizador fez («O utilizador selecionou...», «O utilizador confirmou...»). Testámos esta abordagem porque o ChatGPT adicionava as mensagens dos widgets como mensagens de ferramenta, em vez de mensagens do utilizador.

Ações diretas quando o passo seguinte é óbvio

Se um botão implicar claramente a invocação da ferramenta seguinte, permitir que o widget a acione diretamente funcionou melhor do que forçar outro turno de chat. Isto só se aplica se a próxima invocação de ferramenta não precisar de dados do ChatGPT.

Isto ajudou a impor fluxos determinísticos e reduziu a latência ao evitar outro turno de chat.

Tratamento de erros

Quando uma invocação de ferramenta falhava, devolvíamos os códigos de erro MCP corretos e mensagens curtas e claras através da ferramenta. Assim, o ChatGPT recebia informação concreta sobre as invocações falhadas e podia explicar o problema ao utilizador e/ou escolher um passo seguinte adequado.

Gestão do contexto das ferramentas

Mantivemos o estado da sessão no nosso servidor. O ChatGPT envia contexto limitado à sessão com as invocações de ferramentas; no FastMCP, atribuímos a cada ferramenta um parâmetro Context para que o processador pudesse ler e atualizar esse estado.

• Os identificadores estáveis e os resultados anteriores ficavam guardados na sessão, em vez de se pedir ao ChatGPT que os voltasse a enviar como argumentos das ferramentas em todas as invocações.

• Quando surgiam ciclos de invocação de ferramentas, podíamos detetar as invocações duplicadas e devolver um erro claro através do resultado da ferramenta.

• Os registos das sessões permaneciam do nosso lado para fins de depuração e apoio.

No início, apresentávamos um widget, partíamos do princípio de que o modelo «tinha percebido» e esperávamos pela invocação correta da ferramenta seguinte. Por vezes, acontecia. Muitas vezes, não.

Sem uma transição clara, o ChatGPT podia fazer um resumo quando pretendíamos uma ação, pedir ao utilizador que repetisse uma escolha ou continuar a planear quando já deveria ter parado.

A solução foi explicitar o passo seguinte nos outputs estruturados e nos dados dos widgets, em vez de esperar que o modelo o deduzisse.

Tentámos seguir a documentação do Apps SDK e distribuir as respostas de forma engenhosa entre o output da ferramenta, os metadados ocultos e o texto do chat. Contudo, não conseguíamos ler os metadados ocultos nos widgets. Por isso, não pudemos utilizar esta abordagem.

A documentação do Apps SDK descreve ferramentas que podem ser excluídas da lista de ferramentas do agente, para que este não as escolha, mas que continuam a poder ser invocadas pelo widget. Quando definimos a visibilidade como app-only, essas ferramentas também deixaram de estar disponíveis no widget, e não apenas no agente. Nunca conseguimos uma configuração em que o agente não visse uma ferramenta, mas o widget continuasse a poder utilizá-la.

O silêncio ou uma mensagem genérica de «sucesso» quando nada de útil tinha acontecido eram piores do que um erro direto. Por isso, tratámos as falhas das ferramentas e dos widgets como outputs de pleno direito: se uma etapa não pudesse continuar, indicávamo-lo de forma clara e devolvíamos um erro explícito, em vez de deixar os utilizadores perante um widget que era apresentado mas não lhes permitia avançar. Isto melhorou a usabilidade e tornou o comportamento do modelo mais fiável.

Se o objetivo for criar um fluxo de trabalho no ChatGPT com menos trabalho de plataforma personalizado, o Apps SDK é uma forma prática de o conseguir. Abdica de algum controlo em troca de rapidez e da possibilidade de chegar aos utilizadores onde estes já trabalham.

Se precisar de controlar todos os ramos do fluxo, a IU e quem decide cada etapa, planeie desde o início a sua própria infraestrutura de agentes. É provável que acabe por precisar de ir além do desenvolvimento apenas dentro do ChatGPT.

Também pode utilizar o Apps SDK para executar o seu servidor MCP dentro do ChatGPT antes de criar o chat, a autenticação e a integração dos agentes, migrando depois para a sua própria infraestrutura quando o produto o exigir.

Próximo passo para equipas na mesma situação: escolher um fluxo de trabalho com um resultado claro, documentar as transições entre o chat, as ferramentas e os widgets e, depois, testar intensivamente as novas tentativas e os erros antes de investir muito tempo a aperfeiçoar os prompts.