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

• O Apps SDK é uma opção prática se você precisa lançar logo um fluxo de trabalho no ChatGPT ou quer testar suas ferramentas nele antes de investir em uma estrutura personalizada de agentes. Em geral, não é a opção certa se você precisa controlar cada etapa do comportamento do agente.

• Escolha o Apps SDK quando o ChatGPT for a interface principal e você quiser combinar ferramentas com pequenos elementos de interface sem criar um produto completo de chat. Escolha sua própria estrutura de agentes quando precisar de controle rigoroso sobre o fluxo, a memória, os prompts e as operações de gravação.

• O Apps SDK é adequado para produtos que combinam chat com algumas etapas curtas de interface. Você lança mais rápido, mas abre mão de parte do controle.

• O que funcionou para nós foram ferramentas claras, comportamento claro dos widgets e próximos passos bem definidos. Foram esses elementos, e não o LLM, que usamos para definir o fluxo. O modelo foi mais útil ao explicar resultados que o sistema já havia escolhido.

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

A maioria das equipes ainda conduz projetos-piloto de IA ou a aplica a usos periféricos, com baixo risco e baixo retorno. Poucas lançam um produto essencial para o negócio que os usuários utilizam toda semana. O ChatGPT Apps SDK é uma forma de reduzir essa lacuna se seu objetivo for operar dentro do ChatGPT, em vez de criar todo o assistente por conta própria.

Nossos aprendizados vêm de um projeto para um cliente cujos requisitos apontavam para o ChatGPT como interface principal e para uma implementação rápida, sem exigir o financiamento de um produto de chat totalmente personalizado.

Diante dessas necessidades, o Apps SDK era adequado porque o cliente precisava de:

• Nenhum produto de chat dedicado para criar e hospedar — ele queria alcance dentro do ChatGPT, não a estrutura de outro assistente independente.

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

• Comportamento do backend exposto por ferramentas MCP — chamadas de ferramentas padronizadas, não um ambiente de execução de agentes personalizado e controlado de ponta a ponta.

• Descoberta dentro do ChatGPT — os usuários deveriam encontrar o fluxo de trabalho onde já trabalham.

Validamos essas escolhas com o cliente durante o desenvolvimento. A contrapartida permanece: quando o ChatGPT hospeda a sessão, você não controla o ambiente de execução externo. Você o orienta, mas não o controla por completo.

Um aplicativo criado com o Apps SDK conecta três elementos:

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

2. Suas ferramentas MCP

3. A interface dos seus widgets

O fluxo na prática:

1. O usuário pede algo ao ChatGPT.

2. O ChatGPT pode chamar uma de suas ferramentas MCP.

3. Seu servidor retorna um resultado estruturado da ferramenta.

4. O ChatGPT lê o resultado e decide o próximo passo: fazer mais chamadas de ferramentas, responder ao usuário ou ambos. Se você vinculou um widget à ferramenta, ele pode aparecer nessa interação.

5. O usuário continua no chat ou no widget, com um texto de acompanhamento, uma escolha ou uma chamada de ferramenta acionada pelo widget. Isso atualiza a conversa; o ChatGPT executa outra interação e repete as etapas 2 a 4 até concluir a tarefa.

Essa combinação de chat, ações de backend e etapas curtas de interface é justamente o objetivo. Isso também significa que os pontos frágeis são as transições entre o chat, as ferramentas e a interface.

Você não precisa recriar do zero a interface de chat, a integração de ferramentas, os padrões de autenticação nem a estrutura dos widgets. Para muitos produtos, isso reduz bastante o tempo de desenvolvimento e permite focar a lógica do domínio e as proteções.

Desenvolver dentro do ChatGPT não é o mesmo que operar seu próprio agente. A parte difícil do projeto não foram truques de prompt. Foi tornar as ferramentas, os widgets e os próximos passos explícitos o bastante para manter o modelo e a interface alinhados.

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

Use o Apps SDK quando quiser

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

• Deixar o ChatGPT hospedar a conversa.

• Combinar linguagem natural com algumas etapas específicas de interface.

• Evitar criar sua própria interface de chat, estrutura de agentes e experiência de descoberta.

Esse último ponto é importante quando seus usuários já trabalham no ChatGPT.

Crie seu próprio agente quando precisar de

• Um fluxo fixo, passo a passo, que possa ser imposto por código.

• Uma interface e um processo de confirmação personalizados, controlados por você de ponta a ponta.

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

• Comportamento previsível em todas as execuções.

• Rastreamentos, logs e métricas do agente.

Se o planejador, os prompts do sistema e todo o fluxo de trabalho forem seu produto, uma estrutura personalizada geralmente será mais adequada.

Em nosso projeto, a palavra recorrente era controle: de um lado, velocidade e uma plataforma conhecida; do outro, controle apenas parcial do ambiente de execução. Essa foi a contrapartida aceita pelo cliente ao priorizar o contato com os usuários no ChatGPT em vez do controle de toda a estrutura.

O fluxo ideal parece simples: o usuário faz uma solicitação, a ferramenta é executada, os dados retornam e o widget aparece quando é preciso fazer uma escolha.

Na prática, o problema estava nas transições. Um widget não é mera decoração. Quando aparece na tela, ele muda o que o modelo vê e faz em seguida. Trate as ações dos widgets como eventos nomeados, não como um chat sem estrutura.

A pilha tecnológica do projeto era simples: FastMCP, Pydantic, React e TypeScript. A integração dessas tecnologias correu bem. O trabalho foi fazer o modelo, as ferramentas e a interface concordarem sobre o próximo passo.

Deixe cada transição evidente

Paramos de tratar os resultados das ferramentas como dados brutos do backend. Cada retorno passou a ser uma transição.

Um bom resultado de ferramenta:

• Fornece ao widget o necessário para a renderização.

• Fornece ao ChatGPT fatos estruturados nos quais basear a resposta.

• Quando necessário para o fluxo, informa o próximo passo para que o modelo não precise adivinhar.

As ações dos widgets não devem inserir textos vagos na conversa. Elas devem informar o que o usuário fez e o que deve acontecer em seguida.

A confiabilidade aumentou quando as transições ficaram claras.

O modelo segue instruções curtas e claras quando elas estão na saída da ferramenta e nas ações dos widgets.

Abaixo está uma pequena estrutura Pydantic que usamos. O campo output contém os dados estruturados necessários ao widget, quando ele é exibido, e os fatos que o ChatGPT deve usar na sessão. O campo agent_directions contém uma linha curta que informa o que o assistente deve fazer em seguida. 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 cuidavam de uma única decisão e depois devolviam o controle. Listas curtas, confirmações ou uma tela de revisão objetiva funcionaram melhor do que transformar o widget em um miniaplicativo. Um pouco de lógica no widget, como uma validação simples ou um próximo passo fixo, ainda ajudava quando queríamos tornar o fluxo mais determinístico.

Terceira pessoa nas mensagens dos widgets

Paramos de escrever as mensagens de acompanhamento dos widgets como se fossem falas do usuário (“Eu selecionei...”, “Eu confirmei...”). Passamos a escrevê-las como relatos curtos do que o usuário fez (“O usuário selecionou...”, “O usuário confirmou...”). Testamos essa abordagem porque o ChatGPT estava adicionando as mensagens dos widgets como mensagens de ferramenta, e não como mensagens do usuário.

Ações diretas quando o próximo passo é evidente

Quando um botão indicava claramente a próxima chamada de ferramenta, deixar o widget acioná-la diretamente funcionava melhor do que forçar outra interação no chat. Isso só se aplica quando a próxima chamada de ferramenta não precisa de dados do ChatGPT.

Isso ajudou a impor fluxos determinísticos e também reduziu a latência ao evitar outra interação no chat.

Tratamento de erros

Quando uma chamada de ferramenta falhava, retornávamos os códigos de erro MCP corretos e mensagens curtas e simples da própria ferramenta. Assim, o ChatGPT recebia informações concretas sobre as chamadas com falha e podia explicar o problema ao usuário e/ou escolher um próximo passo adequado.

Gerenciamento do contexto das ferramentas

Mantivemos o estado da sessão em nosso servidor. O ChatGPT envia o contexto da sessão nas chamadas de ferramentas; no FastMCP, adicionamos a cada ferramenta um parâmetro Context para que o manipulador pudesse ler e atualizar esse estado.

• IDs estáveis e resultados anteriores ficavam na sessão, em vez de pedirmos ao ChatGPT que os enviasse novamente como argumentos em todas as chamadas.

• Quando surgiam loops de chamadas de ferramentas, podíamos detectar chamadas duplicadas e retornar um erro claro pelo resultado da ferramenta.

• Os logs da sessão ficavam conosco para depuração e suporte.

No início, exibíamos um widget, presumíamos que o modelo “havia entendido” e esperávamos a chamada correta da ferramenta seguinte. Às vezes, isso acontecia. Muitas vezes, não.

Sem uma transição clara, o ChatGPT podia resumir quando queríamos uma ação, pedir ao usuário que repetisse uma escolha ou continuar planejando quando já deveria ter parado.

A solução foi explicitar o próximo passo nas saídas estruturadas e nos dados dos widgets, em vez de esperar que o modelo o deduzisse.

Tentamos adotar a estratégia descrita na documentação do Apps SDK, dividindo as respostas entre a saída da ferramenta, metadados ocultos e o texto do chat. Porém, não conseguíamos ler os metadados ocultos nos widgets. Por isso, não pudemos usar essa estratégia.

A documentação do Apps SDK descreve ferramentas que podem ficar fora da lista do agente para que ele não as escolha, mas que ainda podem ser chamadas pelo widget. Quando definimos a visibilidade como app-only, essas ferramentas também deixaram de estar disponíveis para o widget, não apenas para o agente. Não conseguimos configurar uma situação em que o agente não visse uma ferramenta, mas o widget ainda pudesse acessá-la.

O silêncio ou uma mensagem genérica de “sucesso” quando nada útil havia acontecido eram piores que um erro direto. Por isso, tratamos as falhas de ferramentas e widgets como saídas essenciais: se uma etapa não pudesse continuar, informávamos isso em linguagem simples e retornávamos um erro explícito, em vez de deixar os usuários diante de um widget renderizado que não os ajudava a avançar. Isso melhorou a usabilidade e tornou o comportamento do modelo mais confiável.

Se seu objetivo é criar um fluxo de trabalho no ChatGPT com menos trabalho personalizado de plataforma, o Apps SDK é uma opção prática. Você troca parte do controle por velocidade e pela possibilidade de encontrar os usuários onde eles já trabalham.

Se precisar controlar todas as ramificações do fluxo, a interface e quem decide cada etapa, planeje sua própria estrutura de agentes desde o início. Provavelmente chegará um momento em que desenvolver apenas dentro do ChatGPT não será mais suficiente.

Você também pode usar o Apps SDK para executar seu servidor MCP dentro do ChatGPT antes de criar por conta própria o chat, a autenticação e a infraestrutura de agentes. Depois, migre para sua própria estrutura quando o produto exigir.

Para equipes na mesma situação, o próximo passo é escolher um fluxo de trabalho com resultado claro, documentar as transições entre chat, ferramentas e widgets e testar intensamente novas tentativas e erros antes de dedicar muito tempo ao ajuste de prompts.