System‑prompt e o “contrato de função” do ChatGPT App

1. System‑prompt como contrato, e não como um texto bonito

Nos módulos anteriores, olhamos para o ChatGPT App pela ótica da arquitetura: widget, tools e servidor MCP. Nesta aula, vamos focar em quais palavras usamos para explicar à modelo o seu papel: o que ela pode fazer, o que não deve fazer e como usar as ferramentas. Na prática, vamos projetar o system‑prompt como um contrato entre você e a modelo.

Num chat comum com o ChatGPT, você talvez esteja acostumado a prompts do tipo “Imagine que você é um assistente pirata bem‑humorado” ou “Explique tudo como se fosse para uma criança de cinco anos”. Isso fala de persona e de estilo. No contexto do ChatGPT App, o termo system‑prompt tem um sentido bem diferente.

Aqui, o system‑prompt é a primeira mensagem oculta para o usuário do papel system, que define para a modelo:

• quem ela é dentro do seu App;
• em qual tarefa está focada;
• do que ela NÃO trata;
• como e quando deve chamar as ferramentas do seu aplicativo.

No fundo, é uma especificação de comportamento, muito próxima de um contrato formal. Se houver acordo — a modelo tenta segui‑lo. Se não houver — ela agirá como um ChatGPT “geral”, e todo o seu ótimo App ficará de lado.

Importante: para o ChatGPT App, esse system‑prompt:

• fica vinculado ao próprio aplicativo, e não a um diálogo específico;
• impõe limites tanto ao uso do widget quanto às chamadas de tools;
• vive enquanto durar a sessão do App (enquanto o usuário interage com o seu aplicativo).

Simplificando, o acordo é: você oferece ferramentas à modelo e descreve seu papel — que tipo de assistente ela é, o que faz, o que não faz, como usa as ferramentas e como lida com os dados do usuário. Em troca, a modelo tenta se comportar exatamente assim.

2. Onde o system‑prompt “vive” na arquitetura

Para não parecer uma entidade mágica, é útil vê‑lo no diagrama.

sequenceDiagram
    participant User as Usuário
    participant ChatGPT as ChatGPT + modelo
    participant App as Seu ChatGPT App
    participant MCP as MCP/Backend

    Note over ChatGPT: Na inicialização do App
o modelo recebe o system‑prompt

    User->>ChatGPT: "Escolha um presente para um amigo até US$ 50"
    ChatGPT->>ChatGPT: Aplica o system‑prompt + descrições das tools
    ChatGPT->>App: callTool recommend_gifts(...)
    App->>MCP: HTTP /tools/recommend_gifts
    MCP-->>App: Lista de presentes
    App-->>ChatGPT: Tool result (JSON)
    ChatGPT-->>User: Texto + indicação de um widget com cards

O system‑prompt chega à modelo no momento da inicialização do App, quando o ChatGPT decide “conectar” seu aplicativo ao diálogo. A partir daí, cada decisão do ChatGPT — chamar ou não uma tool, sugerir um widget, o que dizer quando não há dados — passa pelo prisma desse contrato.

Do ponto de vista de código no Apps SDK, geralmente é apenas uma string armazenada junto da configuração do App, por exemplo:

// app/config/systemPrompt.ts
export const giftGeniusSystemPrompt = `
Você é o GiftGenius, um assistente de recomendação de presentes...
`;

Depois, essa string vai para onde seu aplicativo se integra ao ChatGPT. A “camada de cola” técnica pode variar, mas o que importa para você é: o system‑prompt é um artefato de código, assim como o schema de uma ferramenta ou um componente React, e precisa ser projetado e versionado com o mesmo cuidado.

Agora que está claro onde o system‑prompt vive na arquitetura e como chega à modelo, o mais importante é — o que exatamente colocar nele para que seja um contrato, e não apenas a descrição de uma “persona simpática”.

3. Papel do App e limites de responsabilidade

A primeira e principal seção de qualquer system‑prompt decente é: quem você é e pelo que é responsável.

A diferença entre “persona” e “contrato do App” é simples: dizer “você é um pirata e fala como marinheiro” é sobre tom; dizer “você é a interface do nosso catálogo de presentes, seleciona presentes e não se mete em outros assuntos” — isso já é contrato.

Para o nosso app didático GiftGenius, que seleciona presentes, o núcleo do papel pode ser assim:

Função:
- Você é o GiftGenius, o assistente do nosso serviço para seleção de presentes.
- Sua tarefa é ajudar o usuário a escolher um presente adequado usando apenas o nosso catálogo.
- Você não fornece conselhos médicos, jurídicos ou financeiros.

Preste atenção aos destaques.

Primeiro, definimos o domínio de forma estreita: apenas a seleção de presentes dentro do nosso serviço. Isso evita que a modelo comece a “explicar física quântica” em vez de abrir o seu App, e que tente montar workflows estranhos envolvendo outros aplicativos no seu lugar.

Segundo, fixamos explicitamente o que o App não faz. Por exemplo:

• não dá conselhos sobre temas não relacionados a presentes e compras;
• não inventa presentes que não existem no catálogo;
• não decide pelo usuário; apenas sugere opções e apresenta justificativas.

Tais restrições negativas muitas vezes são mais importantes do que instruções positivas: a modelo “sabe fazer de tudo” por padrão, e no system‑prompt você corta o excesso.

Para contextos mais complexos, em que um desenvolvedor tem vários Apps (por exemplo, “seleção de presentes” e “rastreamento de entregas”), vale escrever diretamente no system‑prompt que, neste App, você trata apenas de seleção de presentes, não cuida de pedidos e logística e não inicia outros aplicativos. Isso reduz o risco de a modelo se confundir sobre “de quem é esse trabalho”.

4. Quando chamar o App e quando responder por conta própria

O próximo bloco crítico do contrato: regras de uso das ferramentas.

Se elas não forem definidas, tudo costuma ir para um de dois extremos:

• a modelo quase nunca chama seu App, porque é mais simples e barato responder “de cabeça”;
• ou, ao contrário, começa a chamar ferramentas por qualquer motivo, até para perguntas puramente teóricas.

No system‑prompt do App, é preciso fixar com clareza:

• em quais casos é preciso usar as ferramentas;
• em quais casos é preciso responder por conta própria, sem tools;
• o que fazer se o usuário pedir explicitamente para “não abrir o aplicativo”.

Exemplo de trecho textual para o GiftGenius:

Trabalho com ferramentas:
- Use as ferramentas do App quando precisar obter dados factuais do catálogo (lista de presentes, preços, tipos de produto, disponibilidade de entrega e descontos).
- Responda por conta própria se a pergunta for teórica e não exigir acesso ao catálogo (por exemplo, "quais presentes costumam dar para um open house").
- Se o usuário pedir explicitamente "não abrir o aplicativo" ou "responder sem widget", respeite isso e não chame as ferramentas.

Há várias coisas importantes acontecendo aqui.

Primeiro, vinculamos a chamada de tools ao tipo de solicitação: dados factuais/do catálogo → ferramenta; teoria geral → a modelo responde sozinha.

Segundo, falamos explicitamente sobre respeitar as intenções do usuário: se a pessoa escreve “não rode nada, só explique”, a modelo não deve ignorar esse sinal.

Terceiro, passamos a gerenciar a frequência de uso do App. Um bom system‑prompt ajuda a modelo a encontrar o equilíbrio: o App é usado quando necessário, mas não vira um pop‑up insistente que aparece sempre.

Mais adiante, na próxima aula sobre instruções de UX, falaremos separadamente sobre como a modelo deve anunciar a abertura do widget e o que dizer após concluir o fluxo. Aqui, o que nos interessa são as regras de decisão: usar o App ou não.

5. Uso seguro de tools e trabalho com dados do usuário

Agora — sobre segurança e bom senso.

As ferramentas do seu App podem ser de tipos diferentes:

• as que trabalham com dados públicos (catálogos de presentes, disponibilidade de produtos, condições de entrega);
• as que trabalham com dados pessoais e/ou executam ações em nome do usuário (criar pedido, debitar valores, alterar configurações).

No system‑prompt, é preciso indicar como a modelo deve tratar essas diferenças.

Um conjunto típico de regras:

Segurança e privacidade:
- Não execute ações que exijam consentimento do usuário (compra, assinatura, alteração de dados pessoais) sem confirmação explícita no chat.
- Não envie para as ferramentas mais dados do que o necessário para seu funcionamento (minimização de dados).
- Se a solicitação envolver dados sensíveis (saúde, finanças, crianças), primeiro confirme se o usuário autoriza o envio desses dados ao aplicativo.

Assim, resolvemos várias questões de uma vez.

Primeiro, protegemos o usuário de atividades inesperadas: a modelo não tem o direito de comprar um presente ou fazer um pedido por conta própria, se você deu a ela tal tool. Primeiro — a confirmação em texto; depois — a chamada da ferramenta.

Segundo, reduzimos o risco de vazamento desnecessário de dados: a modelo tende a “enfiar tudo o que vê” nos argumentos da ferramenta; você pede explicitamente que se limite ao mínimo necessário.

Terceiro, destacamos domínios sensíveis em que, mesmo sem uma tool financeira, podem existir riscos jurídicos/éticos.

Uma boa prática é escrever, nas descrições das ferramentas perigosas (description), que elas alteram estado ou realizam pagamento, e duplicar isso no system‑prompt. Assim, você cria uma barreira dupla: tanto no contrato quanto na descrição da tool específica.

6. Formato e estilo do system‑prompt: escreva como especificação

Um erro muito comum é escrever o system‑prompt como texto de marketing: “Você é um assistente inovador e incrivelmente inteligente que torna o mundo melhor…”. É bonito, mas não ajuda a modelo. O que interessa a ela é:

• quem sou eu;
• o que fazer;
• o que não fazer;
• como usar as ferramentas;
• como lidar com os dados e com outros Apps.

Por isso, trate o system‑prompt como uma especificação:

• divida em blocos lógicos: “Função”, “Tarefas”, “Limites”, “Trabalho com ferramentas”, “Segurança”;
• dentro dos blocos, escreva frases curtas e sem ambiguidade;
• destaque explicitamente o que “fazer” e “não fazer” (sim, listas dentro do próprio prompt são totalmente pertinentes).

Um trecho estruturado do prompt para o GiftGenius pode ficar assim:

Função:
- Você é o GiftGenius, o assistente do nosso serviço para seleção de presentes.

Tarefas:
- Ajude o usuário a selecionar presentes conforme a necessidade, os interesses do destinatário e o orçamento.
- Explique os prós e contras de cada opção em linguagem simples.

Não faça:
- Não invente presentes que não existem no catálogo.
- Não prometa funcionalidades do serviço que não existem (por exemplo, frete grátis se, pelo catálogo, ele for pago).

O estilo deve ser neutro e “seco”: isto não é um texto de venda, é um contrato. Quanto menos ambiguidades — mais estável o comportamento.

Outra prática importante: versionar e armazenar o system‑prompt no repositório junto com o código. Prompts também têm versões, e mudanças neles quebram o comportamento tanto quanto alterações na lógica em TypeScript. É muito mais agradável ver um diff no review do PR:

- Não invente presentes que não existem no catálogo.
+ Não invente presentes que não existem no catálogo, mesmo que o usuário peça explicitamente “inventar algo”.

do que tentar lembrar que você “deu uma leve ajustada no texto direto na interface”.

7. Exemplo completo de system‑prompt para o nosso App didático

Vamos juntar tudo e escrever um system‑prompt caprichado para o nosso GiftGenius. Vamos quebrá‑lo em partes para facilitar a leitura e a manutenção.

Primeiro, descreva a função e as tarefas:

Função:
- Você é o GiftGenius, o assistente do nosso serviço para seleção de presentes.
- Você conversa com o usuário de forma educada e profissional, sem gírias ou piadas, a menos que o usuário as utilize.

Tarefas:
- Ajude a selecionar presentes com base nos parâmetros fornecidos (perfil do destinatário, interesses, ocasião, orçamento).
- Explique, em linguagem simples e clara, por que você está sugerindo exatamente essas opções.

Agora, defina limites e restrições:

Limites de responsabilidade:
- Trabalhe apenas com o nosso catálogo de presentes e seus metadados.
- Não invente presentes, promoções e descontos que não existem no catálogo ou na resposta das ferramentas.
- Não forneça conselhos médicos, jurídicos ou financeiros.
- Não responda pela operação de outros aplicativos ou sites; se o usuário perguntar sobre isso, diga que você não pode ajudar.

Adicione regras de trabalho com as ferramentas:

Trabalho com ferramentas:
- Use a tool `profile_to_segments` quando precisar transformar uma descrição livre do destinatário em segmentos de interesse.
- Use a tool `recommend_gifts` quando precisar encontrar ou filtrar presentes pelos parâmetros do usuário (segmentos, orçamento, ocasião, localidade).
- Use a tool `get_gift` quando o usuário precisar de detalhes sobre um presente específico (descrição, tipo, preço, restrições de entrega).
- Antes de chamar as ferramentas, tente esclarecer parâmetros faltantes (idade do destinatário, orçamento, ocasião) se, sem eles, o resultado for inútil.
- Se a solicitação for teórica (por exemplo, "como escolher presentes para o primeiro aniversário de casamento"), responda você mesmo, sem chamar ferramentas.

Agora — o bloco sobre segurança e ações em nome do usuário:

Segurança:
- Não conclua compra, assinatura ou envio de presente sem confirmação explícita do usuário no chat.
- Se a ferramenta precisar de dados pessoais (e‑mail do destinatário, endereço de entrega, nome), primeiro explique ao usuário por que são necessários e peça confirmação.
- Não envie para as ferramentas mais dados do que o necessário (por exemplo, não envie a mensagem completa se bastarem idade, interesses e orçamento).

E o tom geral/regras globais:

Regras gerais:
- Se as ferramentas retornarem resultado vazio, diga isso com transparência e proponha relaxar os critérios (ajustar orçamento, tipo de presente, categoria ou ocasião).
- Se o usuário pedir "não abrir o aplicativo" ou "dispensar o widget", respeite e responda apenas em texto, sem chamar tools.
- Se a solicitação não estiver relacionada a presentes ou compras, responda como o ChatGPT básico e não use as ferramentas do GiftGenius.

No fim, essa construção é muito parecida com o exemplo do material complementar: há seções “Função”, “Tarefas”, “Fazer/Não fazer”, “Trabalho com ferramentas”, “Segurança”, “Regras gerais”.

No código do Next.js, você pode colocar isso em um módulo separado:

// app/config/giftGeniusPrompt.ts
export const giftGeniusSystemPrompt = `
Função:
- Você é o GiftGenius, o assistente do nosso serviço para seleção de presentes.
...

Regras gerais:
- Se a solicitação não estiver relacionada a presentes, responda como o ChatGPT básico e não use as ferramentas do GiftGenius.
`;

Depois, use essa constante na configuração do App (como exatamente — depende da versão do Apps SDK, mas a ideia é a mesma: esse texto vai para o papel system na inicialização do diálogo do App).

8. Contexto dinâmico no system‑prompt

Às vezes, o system‑prompt precisa ser “temperado” com dinâmica: data atual, localidade, tipo de usuário (novo/antigo), status de assinatura etc.

Por exemplo, se seu catálogo e preços variam por região, você pode passar a região atual no system‑prompt:

export function buildSystemPrompt(locale: string) {
  return `
Função:
- Você é o GiftGenius, um assistente de seleção de presentes para a região ${locale}.

Limites:
- Use apenas os presentes e preços disponíveis na região ${locale}.
...
`;
}

O Apps SDK, na inicialização do App, pode fornecer _meta["openai/locale"], e você gera a variante de prompt com base nisso. Vamos tratar de localização mais adiante, mas já é útil ver que o system‑prompt não precisa ser sempre estático.

O principal é não transformá‑lo em “espaguete” de condições. Se a lógica ficar muito complexa, é melhor dividir o App ou mover as condições para as tools (por exemplo, para o servidor MCP escolher a fonte de dados pelo locale), deixando no system‑prompt apenas regras de alto nível.

9. Como o system‑prompt se relaciona com a descrição das tools e com as instruções de UX

Esta aula foca no system‑prompt, mas, num App real, ele não existe sozinho. Existem também as descrições das ferramentas (description, inputSchema) e exemplos de follow‑ups, que você configurará nos próximos tópicos. Tudo isso compõe um sistema unificado de instruções.

Gerenciamento da chamada de tools:

• o system‑prompt define a filosofia geral: “ferramentas apenas para dados factuais”, “não inventar presentes”, “não comprar sem confirmação”;
• as descriptions das tools detalham o que exatamente faz o recommend_gifts, quais parâmetros são necessários e quando chamá‑lo;
• as frases de follow‑up definem o estilo do diálogo após a chamada da ferramenta: como dizer com clareza que nada foi encontrado, como propor ajustes na consulta, como resumir resultados.

Se essas três camadas estiverem alinhadas, a modelo se comporta de forma previsível:

• chama o App quando realmente precisa;
• não alucina presentes/produtos fora da base;
• explica de forma clara ao usuário o que aconteceu (achou / não achou / precisa de mais informação).

Se não — você terá um comportamento caótico e longas sessões de “ajustes mágicos de prompt”, que rapidamente cansam a todos.

10. Erros comuns ao trabalhar com o system‑prompt do ChatGPT App

Erro nº 1: escrever o system‑prompt “para ficar bonito”, e não como contrato.
Muito frequentemente, os desenvolvedores se limitam a frases vagas como “Ajude o usuário a resolver suas tarefas como puder” e “Seja amigável”. Isso não deixa claro para a modelo quando chamar o App, onde estão os limites de responsabilidade, se pode inventar dados e o que fazer quando a ferramenta falha. Como resultado, metade da lógica fica espalhada pelas stacks de código e pela cabeça do autor, em vez de estar definida em um contrato explícito.

Erro nº 2: um papel amplo demais (“ajude em tudo”).
Se, na seção de papel, você escreve “Você é um assistente que ajuda o usuário em todos os assuntos”, a modelo vai fazer exatamente isso e nem sempre lembrará do seu App. O App vira uma opção dispensável, pouco usada, porque a modelo acha que dá conta sozinha. É melhor indicar um nicho claro: seleção de presentes, trabalho com o catálogo de presentes, ajuda em um domínio específico.

Erro nº 3: não ter regras sobre quando chamar ferramentas.
Formulações como “use as ferramentas conforme necessário” são vagas demais. A modelo pode tanto ignorar completamente as tools quanto chamá‑las onde seria possível responder “de cabeça”. É preciso separar os cenários com clareza: dados factuais → tool; explicações gerais → resposta da própria modelo; recusa explícita do usuário ao App → apenas texto.

Erro nº 4: tentar “curar” alucinações com uma única frase “não invente”.
A frase “não alucine” ajuda pouco por si só. É importante descrever explicitamente o que é proibido inventar (produtos/presentes fora do catálogo, itens sem ID, descontos inexistentes) e o que fazer quando o resultado for vazio (dizer honestamente que nada foi encontrado). Sem isso, a modelo ainda tentará “agradar” e gerar opções fictícias. É preciso o conjunto completo: proibição global no system‑prompt, restrições nas descrições das tools e templates de resposta para casos de “nada encontrado”.

Erro nº 5: ignorar segurança e consentimento do usuário.
Se no system‑prompt não estiver escrito que compra, reserva ou alteração de dados pessoais exigem confirmação explícita, a modelo pode — com “boa intenção” — chamar a ferramenta por conta própria. Do ponto de vista de UX, é desastroso. Sempre deixe claro que qualquer ação com finanças ou conta só é feita após consentimento explícito no chat.

Erro nº 6: não considerar a existência de outros Apps e ferramentas.
Num ambiente em que uma conta pode ter vários Apps e um monte de tools, não dá para achar que a modelo “vai adivinhar” qual aplicativo usar. Se o system‑prompt não fixa que este é especificamente o App para escolha de presentes e somente para isso, a modelo pode alternar de forma imprevisível entre diferentes Apps ou tentar usar ferramentas fora de contexto.

Erro nº 7: editar o system‑prompt “no calor do momento” sem versionamento e testes.
É tentador abrir a configuração, mudar uma linha e acreditar que “só melhorou”. Na prática, qualquer ajuste no prompt pode quebrar o comportamento de outros cenários. Se você não mantiver o system‑prompt no repositório, não olhar os diffs e não rodar um conjunto de testes de prompts (golden prompt set — chegaremos lá neste módulo), vai caçar regressões por semanas.