Fluxo do usuário: como o GPT sugere o App e chama suas funções

1. Introdução

Imagine que você está desenvolvendo um serviço web comum. Lá é simples: você tem a URL /search, o usuário clica no botão, você chama o controlador searchController. No mundo dos ChatGPT Apps, nenhum /search é visível ao usuário. Ele escreve um texto natural:

“Escolha um presente para meu irmão gamer de até US$ 50”

E então:

• o modelo decide: “Ah, isso é sobre presentes, eu tenho o GiftGenius, que sabe fazer isso”;
• o GPT “aperta os botões” sozinho — chama as ferramentas do seu App;
• às vezes ele ainda oferece ao usuário: “Quer que eu abra o GiftGenius e mostre as opções?”

A mudança‑chave: o usuário expressa a intenção e o modelo é quem aperta os botões. Se você não entender esse fluxo, é muito fácil:

• escrever ferramentas com nomes sem sentido (run_func, doStuff),
• ter um App que nunca é sugerido pelo modelo ou é chamado fora de contexto,
• criar um widget que “aparece do nada” e quebra o diálogo.

Por isso, nesta aula formamos o modelo mental: como o GPT fica sabendo do seu App e em quais pontos do diálogo ele o “encaixa”.

Insight: o aplicativo é um plug-in do ChatGPT

Diferentemente dos aplicativos no celular ou dos mini‑apps no WeChat, os aplicativos no ChatGPT funcionam de outro jeito.

O ChatGPT decide quando iniciar seu aplicativo e qual função chamar. Os aplicativos no ChatGPT podem interferir ativamente (ainda que com limitações) na lógica do chat. Sua principal finalidade e ponto forte — é ampliar as capacidades do próprio ChatGPT.

Se o ChatGPT pode resolver perfeitamente o problema do usuário — ele não precisa chamar seu aplicativo. Se o ChatGPT não consegue resolver o problema do usuário — então o usuário nem vai perguntar sobre isso. O cenário ideal é quando o ChatGPT consegue atender ao pedido do usuário apenas parcialmente. Isso significa que há demanda, é grande, mas o resultado é insuficiente.

É aí que o ChatGPT chama seu aplicativo e vocês juntos deixam o usuário feliz. O usuário fica mais satisfeito e você — mais rico.

2. Maneiras de iniciar um ChatGPT App do ponto de vista do usuário

O usuário não tem um botão “chame o servidor MCP e call_tool”, mas tem um campo de texto e (às vezes) um menu de aplicativos. Do ponto de vista dele, há dois esquemas básicos de inicialização: explícita e implícita.

Inicialização explícita (explicit)

Este é o cenário em que o usuário escolhe conscientemente seu App.

Formas típicas:

• ele encontra o App na Store do ChatGPT e clica em “Abrir”;
• ele escolhe o App no launcher (por exemplo, pelo botão + no campo de entrada de texto (Composer));
• ele começa a mensagem com o nome do aplicativo: “GiftGenius, escolha um presente…” — isso é chamado de named mention. Se o nome do App estiver no começo do prompt, o ChatGPT injeta automaticamente seu App no contexto da resposta.

No modo explícito, o modelo sabe desde o início: o usuário veio exatamente para trabalhar com esse App. Portanto:

• o GPT chama com mais frequência e de forma mais ativa suas ferramentas;
• o widget de UI do seu App pode aparecer já na primeira resposta;
• o GPT ignora com menos frequência o App para responder “por conta própria”.

Exemplo favorito: o usuário abre o GiftGenius diretamente porque quer “brincar” de escolher presentes. Ele clica no App na lista, e o GPT mostra uma saudação do tipo:

“Olá! Eu sou o GiftGenius, vou ajudar a escolher um presente. Conte para quem e qual é o orçamento?”

E então usa ativamente suas ferramentas de busca.

Inicialização implícita (implicit / suggested)

Um cenário totalmente diferente: o usuário nem pensa no App. Ele simplesmente escreve no chat comum:

“Escolha um presente de aniversário para minha mãe, ela gosta de jardinagem, orçamento até US$ 100”

O GPT analisa o pedido e percebe que:

• na ecossistema há o App GiftGenius, cujas ferramentas são descritas como “Use this when the user wants to get gift recommendations”;
• as tarefas e restrições (presente, orçamento, interesses) combinam bem com esse App.

Nesse caso, o modelo pode “se intrometer discretamente” com a sugestão:

“Posso usar o aplicativo GiftGenius para selecionar opções concretas de presentes e mostrá‑las como cartões. Abrir?”

Se o usuário concordar — o GPT chama a ferramenta necessária do App e, possivelmente, renderiza o seu widget.

É importante que você não escreva em lugar nenhum if (prompt.includes("presente")) openApp(). O modelo toma a decisão sozinho, com base em:

• o texto do pedido e o histórico do diálogo;
• os metadados das suas ferramentas (nomes, descrições, esquemas de parâmetros);
• o estado da conexão do usuário com o App (se está autenticado ou não), se é usuário corporativo ou não.

Você influencia não o algoritmo, mas como seu App e seus tools estão “descritos” para o modelo.

Híbrido: quando o GPT pede esclarecimentos e depois sugere o App

Às vezes o usuário escreve algo muito genérico:

“Preciso pensar em algo para um colega, não faço ideia do quê”

O modelo entende que o GiftGenius pode ajudar, mas a informação é vaga demais. Um padrão comum:

1. o GPT faz 1–2 perguntas de esclarecimento por texto.
2. Depois disso, sugere iniciar o App: “Tenho uma ferramenta para escolher presentes. Quer que eu a abra e mostre algumas opções?”

Esse é um bom UX: o usuário não sente que foi “forçado a mudar para outro aplicativo”.

3. Discovery: como o GPT encontra seu App

Agora vamos ver como tudo isso parece do ponto de vista do próprio modelo.

Na documentação do Apps SDK isso é chamado de Discovery — todos os meios pelos quais o usuário e o modelo ficam sabendo do seu App. Isso inclui pedidos naturais no chat, o catálogo de aplicativos e “entry points” especiais como o launcher.

Como o modelo sabe que seu App existe

No registro, o ChatGPT inicia seu App e ele (via MCP) fala sobre si: lista as ferramentas disponíveis com seus esquemas — nome, descrição, esquema JSON dos parâmetros de entrada. As informações sobre o aplicativo precisam ser informadas no registro, e as informações sobre as ferramentas o ChatGPT vai extrair por conta própria via método MCP list_tools.

O modelo não vê seu código‑fonte; ele tem acesso apenas a:

• nome da ferramenta (name);
• descrição (description);
• assinatura de entrada (inputSchema).

Isso se torna “a API para o modelo”. Se você nomear uma ferramenta run_func com a descrição “Executes the function”, o modelo não vai entender quando chamá‑la. Se você nomear suggest_gifts com a descrição “Use this when the user wants gift ideas based on recipient, occasion and budget” — tudo fica transparente.

Named mention e in‑conversation discovery

A especificação oficial do Apps SDK destaca dois mecanismos principais:

• Named mention — quando o usuário começa a mensagem com o nome do seu App. Nesse caso, o App quase certamente será levantado e usado na resposta.
• In‑conversation discovery — quando o usuário simplesmente escreve um pedido, e o modelo decide se deve conectar o App. Nisso são considerados:
  • o contexto da conversa (histórico das mensagens, resultados de tools anteriores, preferências do usuário);
  • menções explícitas de marca no texto;
  • os metadados dos seus tools — nomes, descrições, documentação dos parâmetros;
  • o estado do “link” — se o usuário está conectado ao App (autenticado, se as permissões necessárias estão concedidas).

O desenvolvedor influencia esse processo de forma indireta: por meio de metadados de qualidade e padrões de UX, e não com if/else no código.

Catálogo e launcher

Além da forma conversacional, existe também a Store dentro do ChatGPT e o launcher, acessível pelo composer. Por meio deles, os usuários podem escolher explicitamente um App, como em uma loja de aplicativos.

Para nós isso é importante conceitualmente: ao pensar o fluxo do GiftGenius, precisamos lembrar que:

• alguém entrará pelo catálogo e cairá diretamente “dentro” do App;
• alguém nunca vai navegar pelo catálogo e verá o App apenas como uma sugestão no diálogo.

Tudo isso — sobre o discovery do próprio App: os momentos em que o modelo decide se vale a pena “levantar” seu aplicativo e oferecê‑lo ao usuário na conversa atual.

4. Anatomia do ciclo de interação: da frase ao widget

Hora de juntar todos os níveis da aula anterior — da UI do ChatGPT e do widget até o Apps SDK e o servidor MCP — em um único ciclo lógico.

Esquema de alto nível

Do ponto de vista do processo, o ciclo é assim:

sequenceDiagram
    participant U as Usuário
    participant G as ChatGPT (modelo)
    participant A as App / servidor MCP

    U->>G: Solicitação em texto
    G->>G: Análise do pedido + escolha de ferramentas
    G->>A: Chamada de ferramenta (call_tool)
    A-->>G: Resposta (dados / structuredContent)
    G->>U: Resposta em texto + (opcional) widget do App

Em linguagem humana:

1. O usuário escreve uma mensagem no ChatGPT.
2. O modelo analisa o pedido e o contexto atual e decide:
   • responder por conta própria,
   • ou chamar uma ou mais ferramentas.
3. Se a ferramenta do seu App foi escolhida, o ChatGPT forma uma solicitação estruturada (call_tool) e a envia ao servidor MCP.
4. Seu backend (ou servidor MCP) executa a ação: consulta o banco de dados, APIs externas, ACP etc., e monta o resultado.
5. O resultado é retornado como dados estruturados (e, possivelmente, JSON para o widget).
6. O modelo usa esses dados para:
   • gerar um texto compreensível para o usuário,
   • se necessário — renderizar o widget do App diretamente na resposta.

Todo o planejamento de múltiplas etapas — “quando chamar o quê”, “perguntar esclarecimentos”, “fazer mais uma chamada” — fica do lado do modelo de IA. O Apps SDK e o MCP apenas fornecem um contrato unificado para as ferramentas.

Onde escrevemos código

Nesse ciclo há três pontos onde você realmente escreve TypeScript/código:

1. Configuração do App e das ferramentas — descrições dos tools (nome, descrição, esquema) e metadados do App (nome, ícone, categorias). No seu projeto, provavelmente é um arquivo como openai/app-config.ts.
2. Servidor MCP / backend — tratamento de call_tool: acessar o banco de dados, filtrar produtos, chamar outras APIs etc.
3. Widget (UI) — componente React no aplicativo Next.js, renderizado no chat e que lê os resultados das ferramentas via window.openai ou hooks do Apps SDK.

Todo o resto é com o modelo e a plataforma.

5. GiftGenius em ação: dois cenários de fluxo do usuário

Vamos a cenários mais concretos para você “enxergar” esse fluxo.

Cenário 1: o usuário abre o GiftGenius explicitamente

Cenário:

1. O usuário no ChatGPT abre o catálogo de Apps e encontra o GiftGenius.
2. Clica em “Abrir”.
3. O ChatGPT inicia o diálogo já no contexto do GiftGenius.

O diálogo é mais ou menos assim:

Usuário:

Abre o GiftGenius pelo catálogo.
E escreve: “Olá! Quero escolher um presente para um amigo”

GPT:

“Ótimo, vou ajudar a escolher um presente. Para quem, qual é o orçamento e por qual ocasião você procura?”

Neste passo, o GPT pode chamar imediatamente a primeira ferramenta, por exemplo start_gift_session, para inicializar uma sessão no seu backend (criar um carrinho temporário, gerar um sessionId etc.).

Seu código no lado do servidor MCP pode ser assim (ainda bem hipotético):

// Pseudoexemplo future-TS: descrição da ferramenta GiftGenius
const suggestGiftsTool = {
  name: "suggest_gifts",
  description: "Use this when the user wants gift ideas by recipient, occasion and budget",
  inputSchema: {
    type: "object",
    properties: {
      recipient: { type: "string" },
      occasion: { type: "string" },
      budgetUsd: { type: "number" },
    },
    required: ["recipient", "occasion", "budgetUsd"],
  },
};
    

Em detalhes, como isso se registra no MCP/Apps SDK veremos em um módulo separado; agora o que importa é a ideia: com essa descrição o modelo entende que a ferramenta é adequada para pedidos de “seleção de presentes”.

Depois da resposta do usuário, o GPT chama suggest_gifts, recebe de você um array de opções e, então:

• produz um resumo em texto;
• incorpora o widget do GiftGenius, onde é possível percorrer e filtrar os cartões de presentes.

Cenário 2: o usuário pede “escolha um presente” no chat comum

Agora outra possibilidade: o usuário nem sabe do GiftGenius.

Escreve no chat comum:

“Preciso de um presente para meu irmão, ele adora jogos de tabuleiro, no máximo US$ 50”

Dentro do ChatGPT acontece mais ou menos o seguinte:

1. O modelo analisa o pedido e a lista de ferramentas disponíveis.
2. Ele vê a ferramenta suggest_gifts com uma descrição adequada.
3. Percebe que o App GiftGenius é feito justamente para esse tipo de tarefa.
4. Verifica se o usuário já instalou esse aplicativo, se fez login e quais permissões concedeu.

O comportamento a seguir pode variar:

• se o pedido for suficientemente específico, o GPT pode chamar silenciosamente o suggest_gifts e retornar a resposta com o widget;
• se faltar algo (por exemplo, não foi informada a ocasião ou a idade), o GPT pode primeiro pedir um esclarecimento por texto e depois sugerir o App.

Essa flexibilidade é o que diferencia os Apps de UIs “engessadas” com formulários: o modelo escolhe quando usar ferramentas e quando conversar.

6. Roteamento semântico: “LLM como despachante”

No nível do discovery, o modelo decide se vale a pena conectar seu App ao pedido atual. Mas depois, quando o App já foi “levantado” e suas ferramentas são conhecidas pelo modelo na sessão corrente, entra um segundo nível — o roteamento semântico dentro desses tools: por qual ferramenta exatamente processar a próxima fala.

No backend web clássico, o route é escolhido pela URL: /checkout — então chamamos o controlador de checkout. Nos ChatGPT Apps não há roteamento por URL, mas existe o roteamento semântico: o modelo compara o sentido do pedido com as descrições das suas ferramentas.

Simplificando, o processo é assim:

1. Ao iniciar a sessão, o ChatGPT recebe a lista de tools: seus nomes, descrições, esquemas.
2. Esses dados são incorporados às instruções de sistema do modelo.
3. Quando o usuário escreve um pedido, o modelo compara o sentido com as descrições das ferramentas: onde é “seleção de presentes”, onde é “busca de hotéis”, onde é “construir um gráfico”.
4. Se encontrar uma boa correspondência — forma a chamada estruturada da ferramenta necessária.

Daí decorre a principal conclusão prática:

• a descrição da ferramenta — é sua API para o modelo; releia isso mais uma vez. E depois outra.
• se você escrever “does stuff”, o modelo realmente não entenderá quando chamá‑la.

A documentação e as melhores práticas de discovery enfatizam: trate os metadados como um trabalho de copywriting de produto. São eles que determinam em quais conversas o modelo lembrará do seu App.

7. Padrões de diálogo em torno do App

Agora vamos ver padrões típicos de UX que surgem quando o GPT interage com o App dentro de uma mesma conversa. Isso é importante para que você não construa o App “no vácuo”, sem entender o papel da parte GPT.

Todos os guias práticos do Apps SDK destacam alguns padrões característicos:

“Assistente” (The Wizard)

O GPT conduz o usuário passo a passo, muitas vezes apoiando‑se no App.

No exemplo do GiftGenius:

1. GPT: “Conte para quem é o presente?”
2. Usuário: “Para meu irmão, 25 anos, gosta de jogos de tabuleiro.”
3. GPT: “Qual é o orçamento?”
4. Usuário: “Até US$ 50.”
5. O GPT chama suggest_gifts, mostra os resultados no widget e escreve: “Separei algumas opções, veja a lista abaixo”.

Nesse padrão, o App e seu widget funcionam como uma camada visual sobre um diálogo de múltiplas etapas. O usuário escreve texto a maior parte do tempo, e o widget ajuda a visualizar a escolha.

“Widget adaptativo” (The Adaptive Widget)

O texto permanece o canal principal, e o App é conectado pontualmente para tarefas específicas: construir um gráfico, mostrar uma tabela, renderizar cartões de produtos.

Exemplo:

• Usuário: “Compare três opções de presente: jogo de tabuleiro, livro, experiência.”
• O GPT primeiro explica em texto os prós e contras.
• Depois chama a ferramenta que retorna uma lista estruturada de produtos e renderiza uma pequena tabela ou cartões.

Aqui, o App é um complemento visual, não o “modo padrão de operação”.

“Agente invisível” (Invisible Agent)

O App pode nem mostrar UI. Ele trabalha “por baixo dos panos” como fonte de dados:

• você implementa um MCP‑tool que busca presentes no seu banco de dados;
• o GPT o chama, recebe a lista e ele mesmo reconta os resultados em texto, sem qualquer widget.

Isso se parece com um “plug‑in sem UI”: o usuário apenas percebe que o GPT conhece preços e sortimento atualizados.

Esse padrão é útil para Apps focados em tools, em que a UI não é crítica.

8. Como o fluxo influencia o design do App

Entender o fluxo é importante não só pela “filosofia”, mas para decisões bem práticas: quais ferramentas criar, como descrevê‑las, quando mostrar o widget e quando é melhor responder só em texto.

Princípio “chat‑first”

Ideia‑chave da ecossistema: o chat é o canal principal de interação, e os componentes de UI — auxiliares.

Isso significa:

• não tente enfiar “um site inteiro” em um único widget;
• widgets devem ajudar onde o chat é incômodo: escolha em lista, filtragem, comparação, formulários complexos.

Para o GiftGenius isso é:

• selecionar uma lista de presentes e deixar o usuário “clicar” nos cartões;
• visualizar filtros (preço, categoria, disponibilidade);
• ajudar a finalizar o pedido (checkout) em alguns passos claros.

Escrever no widget longas explicações sobre “como escolher um presente para uma mulher introvertida” — não é a melhor ideia; isso é tarefa do chat.

Quando iniciar o App e quando não

Outra consequência: não transforme o App em um “tomador de conta do diálogo”.

Padrão ruim:

• o usuário está em uma discussão séria;
• o App inicia e abre um widget fullscreen enorme sem avisar;
• o usuário se perde: “para onde foi meu chat?”

Melhor:

• primeiro discutir tudo por texto, fazer algumas perguntas de esclarecimento;
• depois sugerir abrir o App de forma suave, se isso realmente melhorar o UX (comparação, configuração, checkout).

Impacto no conjunto de ferramentas

Como o modelo escolhe a ferramenta pela descrição, cada ferramenta deve:

• resolver uma tarefa clara;
• ser bem descrita no estilo “Use this when…”;
• ter parâmetros que surjam naturalmente das perguntas que o GPT fará ao usuário.

Para o GiftGenius, em vez de um gigantesco do_everything, faz mais sentido ter:

• suggest_gifts — seleção de uma lista de opções;
• get_gift_details — detalhes sobre um ID específico;
• create_order — finalização do pedido.

Vamos nos aprofundar no design das ferramentas no módulo 4, mas a ideia geral já é importante agora: o fluxo do diálogo define quais ferramentas são necessárias.

9. Mini‑exemplo: como as descrições dos tools afetam o fluxo (rascunho TypeScript)

Um pequeno trecho de um imaginário openai/app-config.ts, para ligar teoria e código. Não encare isso como a sintaxe exata do SDK (vamos ver no próximo módulo) — agora o que importa são os nomes e as descrições.

// Trecho condicional da configuração do GiftGenius (código futuro)
const tools = [
  {
    name: "suggest_gifts",
    description: "Use this when the user wants gift ideas based on recipient, occasion, and budget.",
    inputSchema: {/* ... */},
  },
  {
    name: "get_gift_details",
    description: "Use this when the user asks for more information about a specific gift from a previous list.",
    inputSchema: {/* ... */},
  },
];

Se você substituir suggest_gifts por run_func e a descrição por “Main function”, o GPT:

• entenderá pior para quais pedidos deve chamar essa ferramenta;
• pode sugerir seu App com menos frequência no in‑conversation discovery;
• terá mais dificuldade em vincular os follow‑ups do usuário à lista de presentes já mostrada.

E, ao contrário, bons nomes e descrições aumentam a chance de o seu App aparecer no momento certo.

10. Erros típicos ao projetar o fluxo do usuário

Erro nº 1: esperar controle total — “eu mesmo decido quando iniciar o App”.
Às vezes os desenvolvedores pensam na lógica “vou capturar todos os pedidos sobre presentes e conectar meu App”. No mundo dos ChatGPT Apps não é assim: quem decide é o modelo. Ele considera as descrições das ferramentas, o contexto do diálogo, o estado das permissões e o quanto o usuário ficará satisfeito chamando especificamente o seu App.

Erro nº 2: nomes e descrições sem sentido para as ferramentas.
Ferramentas com nomes run, main, tool1 e descrições “Calls the main function” criam a tempestade perfeita: o modelo não entende quando chamá‑las, o in‑conversation discovery praticamente não funciona e seu App fica “invisível”. Uma boa descrição no estilo “Use this when the user wants…” e um nome claro — são muito mais importantes do que pode parecer à primeira vista.

Erro nº 3: tentar enfiar “o mundo inteiro” em um único App.
Se seu App ao mesmo tempo “seleciona presentes, reserva hotéis, calcula impostos e mostra gatinhos”, o modelo não conseguirá rotear os pedidos com confiabilidade. Recomendações oficiais e guias práticos enfatizam o princípio “one clear job per tool/App”: é melhor ter vários aplicativos especializados do que um mega‑monolito.

Erro nº 4: auto‑inicialização agressiva de uma UI pesada.
O desenvolvedor está empolgado com seu lindo widget fullscreen e quer mostrá‑lo “a qualquer pretexto”. O resultado é que para o usuário parece que o chat “quebra” e vira um aplicativo web estranho. Muito melhor quando o GPT primeiro conversa por texto, faz perguntas de esclarecimento e só depois sugere abrir o App, explicando por que isso é útil.

Erro nº 5: ignorar o papel do GPT como camada de UX.
Você pode projetar o App como um SPA comum: fazer tudo no widget e o ChatGPT deve “ficar quieto e não atrapalhar”. Mas isso não vai funcionar. O ChatGPT pode não exibir seu widget, ou exibir um novo widget para cada chamada de tool. Quer um produto de sucesso — adapte‑se à plataforma, não espere que ela se adapte a você.