Prompt and Context Engineering

A primeira versão da plataforma de automação de suporte que construí era rápida, barata e embaraçosa. Cada ticket chegava como texto livre — "Meu login não está funcionando," "Fui cobrado duas vezes," "O botão de exportar está quebrado" — e o agente processava cada um em isolamento: sem histórico, sem prompt de sistema, apenas uma mensagem ingênua de usuário. Funcionou bem em um conjunto de teste de vinte tickets selecionados manualmente.

Duas semanas em produção, as regressões começaram. Um usuário abriria um ticket, adicionaria um comentário de follow-up e depois uma esclarecimento. No terceiro turno, o agente havia repetido a mesma etapa de solução de problemas duas vezes e depois perguntado por informações que o usuário já havia fornecido no turno um. O histórico da conversa estava lá no banco de dados — eu estava adicionando cada turno anterior literalmente. Quando uma conversa atingia oito ou dez turnos, a contagem combinada de tokens cruzava o limite prático do modelo e turnos mais antigos começavam a ser aparados silenciosamente.

O modo de falha não foi um crash. Foi sutil e caro: o agente re-classificava tickets que já haviam sido resolvidos, pedia aos usuários que se repetissem, e agentes humanos — que poderiam ter tratado casos mais difíceis — gastavam seu tempo re-triando trabalho que o sistema deveria ter gerenciado.

Três problemas que eu havia ignorado: o que entra no contexto, quanto, e o que acontece quando algo dá errado. Este módulo aborda todos os três.

Ao final deste módulo você será capaz de:

• Escrever prompts de sistema estruturados que dão ao modelo um contrato operacional claro (Fator 2)
• Construir um gerenciador de contexto de janela deslizante que mantém conversas multi-turno dentro do orçamento (Fator 3)
• Lidar com saída malformada ou truncada do modelo de forma graciosa sem travar (Fator 10)

O exemplo em execução é o agente de triagem de suporte ao cliente dos módulos anteriores — o mesmo sistema, crescendo uma camada arquitetural por vez.

A maior diferença entre um protótipo e um agente de produção é o prompt de sistema. Meu primeiro prompt era uma frase: "Você é um agente de suporte. Ajude o usuário." Isso não é uma descrição de trabalho — é um desejo.

Pense no prompt de sistema como uma descrição de trabalho para um novo contratado. Uma descrição vaga ("ajude os usuários") produz trabalho vago: respostas em prosa, formatos inconsistentes e comportamento de escalação imprevisível. Uma precisa ("classifique tickets em quatro categorias, retorne JSON estruturado, encaminhe qualquer coisa incerta para revisão humana") produz resultados previsíveis e auditáveis. Quanto mais específico o contrato, mais consistente a saída — porque um LLM, como qualquer função, é determinístico em sua relação com a entrada.

Veja como era a chamada ingênua de turno único:

Isso retorna prosa de forma livre. Cada execução parece ligeiramente diferente. Não há contrato sobre formato de saída, sem restrição de categoria, sem regra de escalação. Analisar o resultado downstream requer heurísticas, não código.

A solução é um prompt de sistema estruturado. Ele define o papel do agente, o formato exato de saída e o que fazer quando o ticket não se encaixa claramente em nenhuma categoria:

Agora chame com um parâmetro system e uma mensagem de usuário:

A saída agora é um dict com um schema garantido. O contrato é explícito. Cada etapa downstream pode confiar que result["category"] existe e é um dos quatro valores permitidos.

Reflita antes de continuar: O que você adicionaria ao TRIAGE_SYSTEM_PROMPT para lidar com um ticket que contém informações de identificação pessoal — um número de telefone ou ID de conta no corpo? Considere o trade-off entre especificidade e comprimento do prompt.

Uma vez que o prompt de sistema estava sólido, o próximo modo de falha chegou: conversas multi-turno. O agente de triagem lidava com mensagens de follow-up adicionando cada turno a uma lista de mensagens crescente e passando a lista completa para o modelo. Isso funcionou até não funcionar mais. Quando uma conversa atingia cerca de oito turnos com descrições de tickets longas, o histórico combinado crescia além de 50.000 tokens e o modelo começava a perder o rastro do contexto anterior.

Pense em uma janela de contexto como um quadro branco em uma sala. Você pode escrever tudo nela, mas eventualmente fica sem espaço e tem que apagar algo. A questão não é se apagar — é o que apagar primeiro. Relevância e recência são os dois critérios. A troca mais recente é quase sempre relevante. Um turno de confirmação de seis etapas atrás — "Entendo que seu problema é X" — é candidato a aparamento porque seu conteúdo é recuperável dos turnos ao redor.

Ponto de Verificação do Módulo

Antes de ver o código de janela deslizante, preveja: se você descarta o turno mais antigo de uma conversa de 10 turnos para dar espaço, que informações você perdeu permanentemente? Considere uma conversa onde o turno 1 continha a mensagem de erro original que todos os turnos subsequentes referenciam. O que o modelo faria sem ela?

Aqui está um gerenciador de contexto de janela deslizante mínimo. Ele mantém no máximo max_turns turnos e descarta o mais antigo quando a contagem excede esse limite:

Usando com a chamada de triagem estruturada:

A janela deslizante é um instrumento grosseiro. Ela mantém os últimos N turnos independentemente do conteúdo. Para a maioria das conversas de suporte que ficam abaixo de oito ou dez turnos, isso é suficiente. Quando as conversas são mais longas — ou quando o turno 1 carrega informações das quais todos os turnos posteriores dependem — você precisa de uma abordagem mais inteligente: fixar o primeiro turno e aparar do meio.

Dois tipos de erros quebraram o agente de triagem em produção. O primeiro: o modelo retornando algo que não era JSON válido — geralmente quando o texto do ticket era incomumente longo e o modelo gastava seu orçamento de tokens em análise em vez da saída estruturada. O segundo: um truncamento de max_tokens no meio da resposta. A saída foi cortada em uma chave de abertura, o parser JSON lançou e o agente travou sem fallback.

Nenhuma falha foi culpa do modelo. Ambas foram minhas. Eu havia assumido que o modelo sempre retorna JSON bem formado e que max_tokens=512 era sempre suficiente. O Fator 10 significa assumir o oposto: trate cada chamada de LLM como se pudesse retornar lixo, e tenha um plano para cada modo de falha que seja específico, auditável e testável.

Aqui está a função de triagem endurecida contra erros:

O fallback escala para um agente humano e não atualiza a janela de contexto. O próximo turno começa a partir do último estado bom conhecido em vez de adicionar uma troca quebrada.

Juntando tudo — a sessão de triagem multi-turno completa:

Reflita antes de continuar: Este fallback sempre escala para um humano. Em uma fila de alto volume onde 15% dos tickets têm descrições incomumente longas que disparam erros de parse, o que "sempre escalar na falha" faz com a fila de revisão humana? Qual seria um padrão melhor — e como você decidiria quando tentar novamente versus quando enviar para um humano?