Esta nota responde a uma pergunta que soa de reunião de produto e que, na prática, é uma decisão de engenharia: dado um requisito de negócio, qual forma de aplicação escolher (uma resposta única, um RAG, um workflow fixo ou um agente), e como justificar a escolha com custo, latência e confiabilidade?

Ao terminar, você deve conseguir traduzir um requisito em três perguntas (o que o modelo decide, o que o código decide e o que um humano aprova), escolher a forma com critérios e não por costume, acompanhar um caso de ponta a ponta até a arquitetura e escrever a decisão de um jeito que alguém entenda daqui a um ano.

Esta aula é uma integração. Ela não repete o que as aulas anteriores ensinaram: quando um conceito já tem nota própria, aponto o link e fico com a parte que liga as peças. Três notas sustentam quase tudo. RAG explica o pipeline de busca e geração, Agents explica o laço de ferramentas e os padrões de orquestração, e 1.3 Mecânica da API Claude explica o que cada chamada devolve. O caso prático da parte 3 é ilustrativo: uma triagem de chamados de suporte inventada para esta aula, sem dados reais. Os números que aparecem têm a origem dita no texto.

Mapa da aula

Pré-requisitos: 1.3 Mecânica da API Claude para a parte da chamada, RAG e Agents para as formas com busca e com laço, e 4.1 Implementação de ferramentas para a parte das ferramentas. Os diagramas seguem um mapa de cores fixo: laranja é a pessoa (quem pede, quem aprova), claude é o modelo, azul é o código (regras, busca, validação), verde é o resultado que passou pelas verificações, rosa é a falha e cinza é a entrada ou um dado neutro.

Parte 1: a decisão antes do código

1. O requisito esconde decisões

Pense numa reforma. Quando o cliente diz “quero a cozinha maior e mais iluminada”, o arquiteto não escolhe o tipo de janela naquela hora. Ele separa três coisas: o que é gosto do cliente, o que é exigência da prefeitura (o recuo do muro não se negocia com o pedreiro) e o que só se faz com a assinatura do dono, como derrubar uma parede de sustentação. Só depois dessa triagem o projeto começa. Um requisito de software passa pela mesma separação. A frase “quero que a IA faça a triagem dos chamados” não diz nada sobre arquitetura, mas esconde pelo menos três decisões diferentes, e cada uma pertence a um dono diferente.

Uma decisão, nesta aula, é qualquer ponto em que o sistema escolhe um caminho. Ela pode ser pequena, como classificar um chamado em uma de cinco categorias, ou grande, como devolver dinheiro ao cliente. Para cada requisito, a pergunta de três partes obriga a listar as decisões antes de desenhar qualquer caixa. Boa parte dos problemas de arquitetura nasce de decisões que ninguém percebeu que estavam sendo tomadas, como um modelo escolhendo a fila de atendimento sem que alguém tenha pedido isso.

O modelo decide quando a entrada é linguagem natural e a resposta depende de leitura. Classificar um texto livre, resumir uma conversa ou extrair o produto citado num e-mail são tarefas em que regras escritas à mão falham de forma previsível e em que um modelo lê o contexto e costuma acertar. A contrapartida é que o modelo não dá garantia. Ele pode errar, e a mesma entrada pode receber respostas diferentes em duas chamadas. Por isso o que ele produz precisa ser conferido por algo que não seja ele mesmo.

O código decide quando a regra pode ser escrita. Quem tem direito a reembolso, qual fila recebe qual categoria, quanto custa o frete e quantas vezes uma chamada pode ser repetida têm respostas exatas. Uma resposta exata escrita em código é testável, auditável e igual toda vez. Pôr essa mesma regra no prompt transforma uma regra em um pedido. O modelo costuma obedecer, e o dia em que não obedece é o dia em que alguém pergunta por que o reembolso saiu errado.

O humano aprova quando o erro é caro, difícil de desfazer ou quando alguma política exige um responsável. O modelo erra com a mesma tranquilidade com que acerta, então o tom confiante de um texto não diz nada sobre a exatidão dele. Ações irreversíveis, como estornar um pagamento, cancelar um contrato ou enviar uma mensagem que não pode ser retirada, pedem um olho humano antes da execução. Esse ponto de aprovação custa tempo de alguém, e por isso precisa ser escolhido com critério, e não espalhado por todo o fluxo.

A figura segue um chamado de ponta a ponta e separa os donos por grupo. O grupo Código (azul) tem a maior parte das caixas, e isso é de propósito: a maior parte da engenharia está nas regras determinísticas ao redor do modelo. O modelo aparece uma vez, no meio, e o losango “Valida saída” é a peça que costuma faltar em projetos novos. Se o JSON devolvido não tiver uma categoria da lista, o caso vai para a fila manual, em rosa, com a seta barrada, e não volta ao modelo sem limite. A fila do atendente só recebe o caso depois de passar pelo losango de ação sensível, e a aprovação humana (laranja) fica no caminho dos casos que a regra marca.

2. Quando o modelo decide e quando não deve

Existe um teste simples para separar as duas coisas: se você consegue escrever a regra como um if, ela é do código. Se a regra depende de entender o que a pessoa quis dizer, ela é do modelo. Na prática, quase toda aplicação tem as duas, e o trabalho de projeto é desenhar a fronteira entre elas.

Considere as decisões de um mesmo chamado. Saber se o texto é sobre cobrança ou sobre entrega é leitura, e o modelo faz bem. Saber qual fila recebe a categoria cobrança é uma tabela, e a tabela fica no código. Dizer se o produto chegou com defeito também é leitura, porque o cliente escreve “veio com a tela rachada” de mil jeitos diferentes. Mas dizer se a troca é gratuita por defeito dentro de 90 dias é uma regra. Essa regra deve ser aplicada pelo código sobre um campo extraído (o produto tem defeito, a compra foi há 40 dias), e não pelo modelo sobre o texto inteiro. O frete é aritmética, e aritmética não deve ser entregue ao modelo.

Essa divisão tem uma consequência prática. Quando a regra muda, você altera uma linha de código, que tem teste, e não um parágrafo de prompt que pode mexer em outras respostas sem que ninguém perceba. A fronteira também se move. Se a medição mostrar que uma regra escrita à mão deixa passar casos demais, a decisão pode voltar para o modelo, desde que a saída seja estruturada e um gate de código confira o resultado depois. Mover essa fronteira é uma mudança de arquitetura, e por isso ela entra no registro da decisão (seção 13).

3. O que um humano aprova

Antes de pôr uma pessoa no fluxo, pergunte duas coisas sobre cada ação: se ela estiver errada, quanto custa, e quem percebe o erro antes do cliente? Um rascunho de resposta que o atendente lê antes de enviar tem erro barato, porque o erro é visto antes de sair. Um estorno automático tem erro caro, porque o dinheiro já saiu, e o erro costuma aparecer só quando o cliente reclama. A aprovação humana faz sentido onde a segunda pergunta não tem boa resposta.

Há três casos típicos. O primeiro é a ação irreversível: estorno, cancelamento, exclusão ou mensagem enviada. O segundo é a exceção de política, quando o caso não se encaixa na regra e a decisão exige julgamento e responsabilidade. O terceiro é a confiança baixa, quando nem o modelo nem o código conseguem dizer com segurança o que fazer. Nesse caso o sistema entrega o caso a alguém, e não escolhe por ele. Escolher por ele, com aparência de decisão, é o que torna o erro silencioso.

Uma observação de honestidade. Nos trechos da documentação da Anthropic que consultei para esta aula, não encontrei um padrão nomeado de aprovação humana. Tratar a aprovação como parte do desenho é uma decisão de projeto que a aula defende pela lógica do custo do erro, e não um padrão citado. Se você for usar esse argumento numa revisão de arquitetura, diga isso com a mesma clareza.

Parte 2: escolher a forma

4. As quatro formas

A Anthropic publicou em dezembro de 2024 um texto de referência sobre a construção de sistemas com Claude, chamado “Building effective agents”. Ele começa por uma distinção que organiza todo o resto. Um workflow é um sistema em que o modelo e as ferramentas são orquestrados por caminhos de código definidos antes da execução. Um agente é um sistema em que o próprio modelo dirige o seu processo e o uso das ferramentas. A diferença fica em quem decide o próximo passo: no workflow é o código que decide, e no agente é o modelo, a cada volta.

A partir dessa distinção convém separar quatro formas, da mais simples à mais livre. A resposta única é uma chamada ao modelo, com a pergunta, as instruções e alguns exemplos no prompt. Um caso é reescrever um e-mail de desculpas num tom mais cordial. O texto da Anthropic sugere começar por aqui: para muitas aplicações, otimizar uma única chamada, com a informação certa e exemplos no contexto, já resolve. Essa forma tem o menor custo e a menor superfície de erro, e é a referência contra a qual as outras precisam se justificar.

O RAG (geração aumentada por busca, explicada em RAG) acrescenta uma busca antes da chamada. Quem escolhe os trechos é o código, numa consulta a um índice, e o modelo lê esses trechos e responde. Um caso é responder dúvidas sobre a política de troca de uma loja, citando o documento. A aula RAG fez uma classificação que esta aula mantém: um RAG com busca fixa é um workflow, porque os passos (buscar e depois gerar) estão no código. Quando o modelo decide quando e o que buscar, o sistema passa a ser um agente naquele ponto, e isso se chama RAG agêntico.

O workflow fixo é uma sequência de passos definida pelo código, em que o modelo preenche cada passo. Resumir um documento, conferir o resumo contra o original e só então publicá-lo é um exemplo. O texto da Anthropic apresenta cinco padrões de workflow. No encadeamento de prompts, a saída de uma chamada alimenta a próxima, com uma verificação no meio, e serve para tarefas que se dividem em etapas conhecidas. No roteamento, um classificador encaminha cada entrada para um tratamento próprio, o que faz sentido quando as categorias são bem separadas e a classificação é confiável. Na paralelização, subtarefas independentes rodam ao mesmo tempo, ou a mesma tarefa roda várias vezes para comparar respostas. No orquestrador com workers, um modelo central decide as subtarefas depois de ver a entrada e as delega. No avaliador e otimizador, um modelo produz e outro critica, em ciclos, quando existe um critério claro de qualidade. A Agents desenvolve cada um na seção 10 com exemplos de subagents. O orquestrador com workers é a fronteira do grupo: o texto o trata como workflow, mas é o modelo quem define as subtarefas, o que o aproxima do agente. Por isso ele merece um desenho cuidadoso.

O agente é o modelo rodando em laço, com ferramentas, até uma condição de parada. Investigar um bug num repositório é um caso: o modelo lê arquivos, roda testes, formula uma hipótese, lê de novo, e ninguém escreveu essa sequência de antemão. O custo e a incerteza são maiores, porque o número de passos não é conhecido no início.

As quatro colunas mostram o mesmo tipo de desenho em formas diferentes, com o modelo sempre na mesma cor. A diferença entre as formas está no que cerca o modelo. Na resposta única há uma seta só. No RAG, o cilindro azul é a busca feita pelo código, e os trechos chegam ao modelo, enquanto a linha pontilhada mostra a pergunta indo direto ao prompt. No workflow, o losango do gate é a peça que muda o comportamento: a saída do modelo só segue se o código a aceitar. No agente, a seta de ida e volta com a ferramenta é o laço, e o limite de voltas, escrito como propriedade do modelo, é o que impede o laço de girar para sempre.

5. Critérios para escolher

Com as quatro formas na mesa, a escolha deixa de ser questão de gosto e vira uma sequência de perguntas. A primeira é se os passos podem ser escritos antes da execução. Se podem, o workflow é mais barato, mais previsível e mais fácil de testar, porque cada passo tem entrada e saída conhecidas. Se não podem, porque o próximo passo depende do que aparecer no meio do caminho, a forma livre passa a ser candidata. A segunda é se existe um critério objetivo de correção. Um classificador tem critério: a categoria está certa ou não está. Um texto de marketing não tem, e a avaliação vira julgamento. Sem critério, o laço de melhoria e a comparação entre formas perdem a base.

A terceira pergunta é onde mora o conhecimento. Se a resposta depende de um acervo que não cabe no prompt, ou que muda com frequência, a busca entra. Se o acervo cabe e não muda, o RAG é complexidade sem ganho. A quarta é quantos passos o trabalho exige e se esse número depende do que se observa. A quinta é quanto custa errar, e ela decide onde colocar o humano.

A forma nasce das respostas a essas perguntas, e não o contrário. A recomendação da própria Anthropic é começar pela solução mais simples e subir um degrau só quando a medição mostrar que o anterior não basta. A Agents chama isso de escada, e a versão desta aula é a mesma: resposta única, depois busca, depois workflow, depois agente, com medição entre um degrau e outro. Subir sem medir costuma produzir um sistema caro que ninguém consegue explicar depois.

A tabela resume os critérios. Ela não substitui a conversa com o requisito, mas ajuda a conferir se a escolha tem motivo.

6. Custo, latência, confiabilidade e manutenção

A escolha da forma é, no fundo, uma troca entre quatro coisas. Vale discutir cada uma com o mecanismo por trás, porque é o mecanismo que você vai precisar explicar a alguém.

Custo. Cada chamada ao modelo é cobrada pelos tokens de entrada e de saída, e 1.3 Mecânica da API Claude mostra onde o campo de uso registra os dois. O custo de uma solução é, portanto, a soma das chamadas que ela faz, multiplicada pelo tamanho de cada uma. Uma resposta única faz uma chamada. Um workflow faz tantas quantas forem as etapas com modelo, mas cada uma pode ser pequena e barata, e isso permite usar um modelo menor na classificação e reservar o maior para a redação. O RAG tem um custo escondido no contexto: os trechos entram no prompt e pagam tokens a cada pergunta. Na aula RAG medi, com um tokenizador de estimativa, que um prompt com cinco trechos ficou em média perto de 564 tokens, contra 4.925 tokens do corpus inteiro. Colar tudo custaria cerca de 8,7 vezes mais por pergunta. Esse número vale para um corpus de nove documentos curtos, e a conta muda quando o acervo cresce. O agente é o caso em que o custo é mais difícil de limitar, porque o número de voltas não é conhecido e o contexto cresce a cada volta. A nota Agents registra uma ordem de grandeza que a Anthropic publicou para um sistema de pesquisa multiagente, de cerca de quatro vezes os tokens de um chat para um agente e cerca de quinze vezes para um sistema com vários agentes. Não reconferi esse número na fonte para esta aula, então ele é uma referência a checar, e não uma medição.

Latência. O tempo de uma sequência é a soma dos tempos de cada passo, e isso vale para workflows e agentes. Paralelizar passos independentes é a forma mais direta de reduzir a espera, mas não reduz o total de tokens. O processamento em lote, descrito em 1.3 Mecânica da API Claude (seção 7), troca a resposta imediata por um resultado que chega depois, e serve para trabalho que ninguém está esperando na tela. O agente tem a latência menos previsível, porque ela depende de quantas voltas o problema exigir. A aprovação humana também adiciona tempo de propósito. A fila do atendente costuma ser a parte mais lenta do sistema, e precisa estar no desenho com essa folga.

Confiabilidade. Um sistema é tão confiável quanto a sua etapa mais fraca, e a forma decide onde a falha pode morar. No workflow, cada passo tem entrada e saída conhecidas, e um gate entre eles isola o erro: se a saída de um passo não passa na validação, o problema aparece ali, com um nome e uma linha de código. No RAG, a aula RAG mostrou que uma resposta errada pode vir de três lugares, os candidatos recuperados, o prompt ou o modelo, e o diagnóstico exige separá-los. No agente, o modelo pode se recuperar de um erro ao olhar o resultado, o que é uma força. Mas os erros se acumulam, e cada execução pode seguir um caminho diferente, o que dificulta reproduzir um problema. O texto da Anthropic aponta esse acúmulo de erros. Na prática, quanto menos o modelo decide, mais fácil fica provar que o sistema está certo.

Manutenção. Um workflow é código, e código tem testes, revisão e histórico. Mudar um passo afeta a parte do sistema que depende dele, e não o todo. O RAG exige reindexar quando o acervo muda e refazer o limiar de recusa quando o modelo, o corpus ou o tipo de pergunta muda, como a aula RAG registrou. O agente exige mais observação: é preciso guardar o rastro das voltas para entender por que ele fez o que fez, e uma mudança de prompt pode alterar passos que ninguém tocou. Em todas as formas, o prompt e a versão do modelo fazem parte do sistema e precisam ser versionados como código (ver 1.6 Ciclo de vida de um sistema com LLM e 6.2 Gestão de configuração).

A tabela resume as quatro dimensões. As avaliações são qualitativas. Elas descrevem o mecanismo que acabei de explicar, e não foram medidas para nenhum caso desta aula.

Parte 3: um caso de ponta a ponta

A figura mostra o caso inteiro antes de cada etapa: a triagem de chamados com classificação, busca na política e rascunho revisado por uma pessoa. As seções 7 a 13 detalham cada parte.

Esta parte acompanha um caso inventado, ilustrativo, para mostrar como as peças se encaixam. As categorias e as prioridades seguem uma convenção comum em suporte e não vêm de nenhum produto real. Nenhum número de custo ou latência deste caso foi medido.

7. O requisito

Em linguagem de negócio, o requisito é este. A central recebe chamados de suporte por formulário. Cada chamado precisa ser classificado em uma de cinco categorias (cobrança, entrega, defeito, conta e outro), receber uma prioridade de P1 a P4 e ir para a fila certa. Quando a política da loja responde à dúvida, o atendente deve receber um rascunho de resposta que cite o trecho da política. Estorno e exceção de política não podem sair sem a aprovação de um gerente. E um chamado não pode sumir: se o sistema não souber o que fazer, o caso precisa aparecer para alguém.

Antes de desenhar, faça as perguntas que Spec-driven development recomenda: quem usa, que decisão o modelo toma e o que é inaceitável errar. Quem usa são os atendentes, que leem tudo, e o cliente, que só recebe uma resposta depois da revisão. A decisão do modelo é a categoria, a prioridade sugerida e o rascunho. O inaceitável é devolver dinheiro sem aprovação, enviar ao cliente uma resposta com política inventada e deixar um chamado sem destino. Essas três respostas valem mais do que qualquer diagrama, porque cada uma vira uma exigência que o desenho precisa cumprir.

8. Dividir as decisões

A tabela abaixo aplica a divisão da parte 1 ao caso. Cada linha é uma decisão que o sistema toma, com o dono e o motivo.

A prioridade é o caso mais instrutivo da tabela. O modelo sugere porque a leitura do texto carrega o sinal. O código aplica o piso porque a regra “cobrança duplicada é P1” não pode depender de o modelo lembrar dela numa tarde qualquer. O valor exato do piso é decisão de negócio, e não algo que esta aula possa afirmar.

9. Escolher a forma, decisão por decisão

A classificação é uma resposta única com saída estruturada. Os passos são fixos (receber, classificar, rotear), a saída tem critério objetivo (a categoria está na lista ou não) e não há acervo para buscar. Uma chamada resolve, e o código valida o resultado. Acrescentar qualquer coisa além disso seria complexidade sem ganho.

O rascunho é um RAG dentro de um workflow fixo. A busca na política é código, o modelo redige com os trechos e o código confere as citações. Aqui o RAG resolve o problema do conhecimento, porque a resposta depende de um documento que não está no modelo, e o workflow mantém a ordem dos passos. Como o caminho é fixo, cada falha de cada passo pode ser escrita de antemão.

O agente foi rejeitado de propósito. O fluxo é conhecido, então nenhum passo precisa ser decidido pelo modelo. Um agente aqui pagaria a incerteza de custo e de latência sem entregar nada que o workflow não entregue. Eu reconsideraria se o requisito mudasse para algo como investigar a conta de um cliente em várias consultas encadeadas, em que o próximo passo depende do que cada consulta devolve. Mesmo nesse caso, a primeira pergunta seria se o trabalho pode ser dividido em passos conhecidos, com uma ou duas ferramentas.

A figura 03 mostra a etapa de classificação. O chamado entra pelo código (azul), que limpa o texto e anexa o id, e segue para o modelo (claude), que devolve um JSON. O losango de validação é o gate: se o JSON não tiver os campos ou se a categoria estiver fora da lista, o caso cai na fila manual (rosa, com a seta barrada) e não é reenviado sem limite. O roteamento é código, uma tabela sem decisão do modelo, e a fila de cada categoria aparece como um conjunto de slots. A seta tracejada para a próxima etapa indica que o rascunho só acontece quando a categoria pede. A temperatura baixa escrita no modelo é uma escolha de projeto para reduzir a variação entre chamadas. Ela não garante respostas idênticas.

A figura 04 mostra a etapa do rascunho. A busca na política é código e devolve os trechos mais relevantes acima de uma nota mínima. Se nenhum trecho passa do limiar, a saída é a recusa: o atendente escreve do zero, e a seta pontilhada mostra que o chamado segue sem rascunho. Se houver trecho, o modelo redige, e o segundo gate confere se as citações apontam para índices que existem no prompt. Uma citação inválida não segue para o cliente, e vai para a fila manual. Os losangos laranja mostram que nada com cara de estorno sai sem um humano, e o atendente é o último a tocar no texto antes do envio.

10. A API, o prompt e a saída

A chamada de classificação usa o endpoint de mensagens que 1.3 Mecânica da API Claude descreveu. Três decisões dessa chamada merecem atenção. O modelo deve ser fixado por um identificador com data, e não por um alias que pode mudar com o tempo, porque o comportamento de uma triagem não pode mudar sem aviso (1.3 Mecânica da API Claude explica a diferença). O campo de sistema carrega as regras, a lista de categorias e o formato da saída, e fica no repositório junto com o código. E o limite de tokens de saída impede que uma resposta longa demais consuma o orçamento de uma tarefa que precisa de algumas linhas.

O trecho a seguir é uma versão reduzida. Não tem tentativas, tempo limite nem registro de logs, que aparecem nas seções 11 e 12. O identificador do modelo é um marcador de propósito: escolha-o na documentação na data da implantação, e não copie um nome de texto antigo.

import json
import anthropic

client = anthropic.Anthropic()  # a chave vem do ambiente, nunca do código

CATEGORIAS = {"cobrança", "entrega", "defeito", "conta", "outro"}

class SaidaInvalida(Exception):
    pass

def classificar(texto_do_chamado: str) -> dict:
    resposta = client.messages.create(
        model="<id-do-modelo-fixado>",  # id com data, conferido na documentação
        max_tokens=300,
        system=PROMPT_CLASSIFICACAO,    # regras, categorias e formato, versionados no git
        messages=[{"role": "user", "content": texto_do_chamado}],
    )
    texto = next(b.text for b in resposta.content if b.type == "text")
    try:
        dados = json.loads(texto)
    except json.JSONDecodeError as erro:
        raise SaidaInvalida("a saída não é JSON") from erro
    if not isinstance(dados, dict) or dados.get("categoria") not in CATEGORIAS:
        raise SaidaInvalida(f"categoria fora da lista: {dados!r}")
    return dados

Repare em três coisas. A saída do modelo é um texto que precisa ser interpretado, e por isso o código faz o parse e valida a categoria contra a lista fixa. Os dois tipos de erro levantam a mesma exceção, e esse é o contrato: quem chama a função recebe um dado válido ou recebe um caso para a fila manual, sem meio-termo. E o texto do cliente entra como mensagem do usuário, separado das instruções. Essa separação não impede injeção de prompt, mas deixa claro o que é regra e o que é dado. A aula RAG trata a mesma defesa para documentos recuperados.

Existe uma alternativa para a saída: descrever o formato como uma ferramenta, com um esquema, como 4.1 Implementação de ferramentas ensina. Ela dá um formato mais rígido, ao custo de desenhar a ferramenta. Para uma saída de três campos, a validação em código costuma bastar. A escolha deve ficar registrada.

11. Ferramentas e controles

O sistema precisa consultar o status de um pedido quando o chamado é de entrega. Essa consulta é uma ferramenta somente leitura, e quem a chama é o código, antes do modelo, e não o modelo. A diferença importa. Se o modelo decidisse quando consultar o pedido, a aplicação teria um laço de ferramentas, que é o núcleo de um agente, com os custos da seção 6. Como o caminho é fixo, a consulta vira um passo de dados, e a definição da ferramenta (nome, descrição e esquema de entrada) segue as regras da aula 4.1 Implementação de ferramentas. Para uma ferramenta que altera dados, como o estorno, a regra é outra: a execução fica no código e depende da aprovação humana.

Os controles são o que impede o caso de sair do trilho. O primeiro é o limite de tamanho do texto de entrada, aplicado antes de qualquer chamada, que protege o custo de um chamado colado com um documento inteiro. O segundo é o limite de tentativas e o tempo máximo de espera. 1.3 Mecânica da API Claude descreve o limite de taxa e o cabeçalho de espera, e 1.7 Engenharia de software para aplicações com Claude mostra como separar erros que valem nova tentativa dos que não valem. Repetir uma classificação é seguro, porque ela não tem efeito colateral. Gravar o rascunho não é. Por isso a gravação usa o id do chamado como chave, e uma segunda execução atualiza o mesmo registro em vez de criar outro. Essa propriedade se chama idempotência, e vale para qualquer passo que escreva.

O terceiro controle é o registro de logs. Ele deve guardar o que o sistema decidiu, como a categoria, a prioridade, o motivo e a rota, e não o texto completo do cliente, que costuma trazer nome, endereço e dados de pagamento. Os controles mais amplos, como barreiras de entrada e de saída, limites de ação e confirmação antes de operações irreversíveis, são o assunto de 7.2 Guardrails e implantação segura. Até lá, a regra prática é tratar o texto do chamado como dado, nunca como instrução.

12. Avaliação

Um desenho só está pronto quando alguém consegue medi-lo. A avaliação deste caso começa com um conjunto de chamados com categoria e prioridade rotuladas por uma pessoa, montado como 2.1 Escolha de modelo contra um eval descreve. Três medidas separam os erros, porque uma média esconderia o que importa. A primeira é o acerto de categoria, que mede a qualidade da classificação. A segunda é o número de estornos ou exceções enviados sem aprovação, que deve ser zero. Isso é exigência de negócio, e não uma taxa a otimizar. A terceira é a quantidade de rascunhos com citação inválida que chegaram ao atendente sem passar pela fila manual. O gate pega índice inexistente e frase sem citação. Ele não pega uma citação válida que não sustenta a frase. Essa falha exige conferência por amostragem ou um juiz, e a aula RAG (seção 12) trata do assunto.

Para o custo, o campo de uso de cada resposta permite somar os tokens de entrada e de saída por chamado. A média por chamado, multiplicada pelo volume mensal, dá a estimativa, e ela precisa ser conferida com a tabela de preços oficial no dia da decisão. Antes de qualquer avaliação feita por outro modelo, rode as verificações determinísticas: o JSON parseia, a categoria está na lista e as citações existem. Elas são baratas e não variam de uma execução para outra. A regra de conferir com código antes de usar um juiz modelo é um tema que ainda não tem nota própria.

13. Documentar a decisão

Uma decisão de arquitetura sem registro vira lenda em poucos meses. Alguém vê um agente num sistema de triagem, pergunta por que ele existe, e ninguém lembra se a escolha foi feita por custo, por prazo ou por costume. O remédio é um registro curto, em que cada campo responde a uma pergunta que a próxima pessoa vai fazer. O formato chamado ADR (Architecture Decision Record) é comum na indústria, e o modelo abaixo segue essa ideia. Ele não está no vault como nota própria.

# Triagem de chamados: workflow com busca, sem agente

Data: 2026-10-18
Responsável: (nome)
Status: aceita

## Contexto
Chamados chegam por formulário e são triados à mão. O tempo de triagem ainda não foi medido.

## Requisito
Classificar em cinco categorias, sugerir prioridade P1 a P4, rotear para a fila e rascunhar resposta com citação da política. Estorno e exceção exigem aprovação de gerente.

## Decisão
Classificação: resposta única, com saída JSON validada pelo código.
Rascunho: RAG sobre a política, dentro de workflow fixo com gate de citação.
Roteamento, validação e piso de prioridade: código.
Estorno, exceção e envio ao cliente: humano.

## Alternativas descartadas
Agente com ferramentas: os passos são conhecidos, e a incerteza de custo e latência não se paga.
Tudo no prompt: as regras de negócio ficariam como pedido, e não como garantia.

## Critério de medição
Acerto de categoria num conjunto rotulado de chamados (tamanho a definir com o time de suporte).
Estorno sem aprovação: zero.
Rascunho com citação inválida: sempre na fila manual.

## O que mudaria a decisão
Passos que dependam de consultas encadeadas e imprevisíveis.
Acerto de categoria abaixo do limite combinado com o time de suporte.

## Riscos aceitos
Citação válida que não sustenta a frase passa pelo gate. Conferência por amostragem humana cobre esse caso.

Cada campo tem uma função. O contexto explica por que o problema existe, e sem ele a decisão parece arbitrária. As alternativas descartadas respondem à pergunta que todo revisor faz, “por que não um agente?”, antes que ela seja feita. O critério de medição diz como saber se a decisão deu certo, e o campo “o que mudaria a decisão” impede que ela vire dogma, porque deixa explícito a partir de que fato ela deve ser revista. Os riscos aceitos mostram que alguém pensou no que ficou de fora. Os campos de data e status permitem ver se a decisão ainda vale. No critério de medição deixei “N” sem valor de propósito: o tamanho do conjunto é uma decisão do time, e esta aula não tem como afirmar um número.

Parte 4: erros e boas práticas

14. Erros comuns

O primeiro erro é começar pelo agente porque ele parece mais inteligente. A aparência de inteligência não entra na conta de custo, latência e verificação, e o agente tem os três itens mais difíceis de justificar. A escada da seção 5 existe para impedir esse atalho. O segundo é pôr regra de negócio no prompt. Uma regra no prompt é um pedido, e a pergunta de teste é simples: se a regra mudar, você consegue provar que o sistema mudou de comportamento? Se a resposta for “mais ou menos”, a regra deveria estar no código.

O terceiro erro é não ter caminho para a saída inválida. Sem um gate, o JSON quebrado ou a categoria inventada chega ao atendente como se fosse um dado. A pergunta “o que acontece quando a saída vem quebrada?” deve estar no desenho antes de qualquer código. O quarto é o laço sem teto. Um agente sem limite de voltas torna a conta de tokens imprevisível, e um workflow com uma repetição sem limite faz o mesmo em miniatura.

O quinto erro é entregar uma ação irreversível à automação porque o teste com dez chamados deu certo. Dez casos quase nunca mostram a cauda de erros, e é justamente na cauda que estão os estornos indevidos. O sexto é escolher o modelo maior por precaução, sem medir. 2.1 Escolha de modelo contra um eval mostra por que essa escolha costuma custar caro sem melhorar o resultado no caso real. O sétimo é documentar só o resultado, com frases como “usamos RAG”. Sem o porquê, a próxima pessoa refaz a discussão do zero ou, pior, troca a forma sem medir nada.

15. Boas práticas

A primeira prática é separar as decisões em três donos antes de desenhar qualquer caixa. Essa etapa é barata e evita a maior parte das surpresas. A segunda é começar pela solução mais simples e medir antes de subir de degrau, como a própria Anthropic recomenda. A terceira é escrever o caminho de falha de cada passo que usa modelo, incluindo a fila manual e a recusa, porque é nele que o sistema se comporta de forma útil quando algo dá errado.

A quarta é pôr limites em tudo que pode crescer: tamanho de entrada, número de voltas, tokens de saída, tentativas e tempo de espera. A quinta é tornar idempotente qualquer passo que escreve, usando uma chave natural como o id do chamado. A sexta é tratar o texto do usuário como dado e não como instrução, e registrar as decisões do sistema sem registrar o conteúdo pessoal. A sétima é medir por tipo de erro, e não por média, e separar o que é exigência de negócio (estorno sem aprovação deve ser zero) do que é taxa a melhorar. A oitava é registrar a decisão num ADR com o motivo e o critério de revisão. E a última é revisar essa decisão quando o requisito, o modelo ou o acervo mudam, porque cada uma dessas mudanças pode mover a fronteira entre o código, o modelo e o humano.

Parte 5: prática

16. Exercícios

1. Escolha um requisito seu ou um destes: resumir atas de reunião, responder dúvidas de RH, classificar e-mails de fornecedores. Preencha a tabela de donos da seção 8. Quantas decisões estavam escondidas no requisito original?
2. Para cada linha da tabela da seção 8, diga se a decisão deveria ser um if ou um pedido ao modelo, e justifique. Depois mude uma delas de dono e explique o efeito no custo, na latência e na manutenção.
3. Desenhe o fluxo do seu requisito nas quatro formas. Escolha uma, em uma frase, e diga o que mudaria a escolha.
4. Escreva o ADR de um sistema seu, seguindo a seção 13. Peça a alguém que não participou da decisão para ler e diga o que não entendeu.
5. Implemente a função classificar da seção 10 com o modelo real e teste com três saídas inválidas: um JSON quebrado, uma categoria fora da lista e uma resposta vazia. Confirme que todas chegam ao tratamento de erro.
6. Calcule o custo por chamado de um fluxo com duas chamadas, usando a tabela de preços oficial e um prompt de N tokens. Não use nenhum número desta aula como referência de preço.

17. Glossário

Requisito: a necessidade de negócio, em linguagem comum, antes de qualquer decisão técnica.

Decisão: qualquer ponto em que o sistema escolhe um caminho. Cada decisão tem um dono: o modelo, o código ou um humano.

Workflow: sistema em que os passos e a ordem são definidos pelo código, e o modelo preenche cada passo.

Agente: sistema em que o modelo decide o próximo passo, em um laço com ferramentas, até uma condição de parada.

Resposta única: uma chamada ao modelo, com as instruções e os exemplos no prompt.

RAG: geração aumentada por busca. O código busca trechos num índice e o modelo responde com base neles.

Gate: uma verificação feita por código entre dois passos, que decide se a saída pode seguir.

Saída estruturada: resposta do modelo em um formato previsível, como JSON, que o código consegue validar.

Ferramenta: função que o modelo pode pedir para executar, e que a aplicação executa de fato.

Idempotência: propriedade de uma operação que, repetida com a mesma entrada, produz o mesmo efeito que uma única execução.

Conjunto de avaliação: lista de casos com a resposta esperada, usada para medir o sistema antes e depois de uma mudança.

Injeção de prompt: texto que tenta fazer o modelo abandonar as instruções, vindo de dados que o sistema processa.

ADR: registro curto de uma decisão de arquitetura, com contexto, decisão, alternativas e critério de revisão.

18. Fontes e o que ficou sem verificação

Fontes consultadas:

Anthropic, “Building effective agents”, publicado em 19 de dezembro de 2024, consultado em 18 de outubro de 2026: https://www.anthropic.com/engineering/building-effective-agents. Usei a distinção entre workflow e agente, os cinco padrões de workflow, a recomendação de começar pela solução mais simples e a orientação de tratar a definição das ferramentas com o mesmo cuidado do prompt. O próprio texto avisa que parte do cenário de ferramentas mudou desde a publicação. Ele não traz números de custo nem de latência.

Notas do vault: RAG, Agents, 1.3 Mecânica da API Claude e 4.1 Implementação de ferramentas. Os números de tokens da seção 6 vêm da aula RAG, medidos com um tokenizador de estimativa e num corpus pequeno.

Não verificado:

Identificadores e preços de modelos. Não confirmei nada disso nesta aula, e a seção 10 deixa o identificador como marcador.

A ordem de grandeza de 4 e 15 vezes citada na nota Agents, que não reconferi na fonte original.

Padrão de aprovação humana. Nos trechos consultados não há um padrão nomeado, então essa parte é princípio de projeto deste material.

As avaliações qualitativas da seção 6, que são juízo sobre o mecanismo e não medição.

O caso prático não foi executado contra a API. O código da seção 10 é ilustrativo.

Relacionados

• RAG
• Agents
• 1.3 Mecânica da API Claude
• 4.1 Implementação de ferramentas
• 7.2 Guardrails e implantação segura
• 7.4 Identidade, segredos e chaves
• 6.2 Gestão de configuração