Um marketplace modera os anúncios com um agente. Ele recebe o anúncio, quatro ferramentas, conferir texto, conferir imagem, conferir preço e publicar a decisão. E um prompt que diz: revise o anúncio e decida.
Aqui estão dois traces do mesmo dia. O primeiro parece perfeito. Texto, imagem, preço, decisão. Quatro turnos, uns onze segundos.
O segundo é mais rápido. Texto, e aí o modelo escreve: a imagem parece coerente com o texto. E aprova. A checagem de imagem nunca rodou.
Olhe essa frase de novo. O modelo deu opinião sobre uma imagem que nunca analisou. E o anúncio 88214 tinha uma imagem proibida.
Ninguém do time queria que a checagem de imagem fosse opcional. A regra era clara: todo anúncio passa pelas três checagens. Mas essa regra morava num prompt. E prompt é uma sugestão forte, não uma garantia. Nesta aula, você vai aprender a achar esse smell nos seus traces, e a refatoração que acaba com ele de vez.
O que está acontecendo é isto. Hoje, a cada turno, o modelo escolhe qual checagem rodar. Ou se para.
Então nada garante que toda checagem rode.
Mas a tarefa tem um caminho fixo. Numa chain, o código sempre roda as três checagens. E o modelo só entra onde precisa de julgamento de verdade: pesar os resultados e decidir.
Como reconhecer? Você consegue desenhar o fluxograma da tarefa, e ele é sempre igual.
O prompt do agente lista os passos em ordem. Primeiro faça isto, depois aquilo. Se você está escrevendo a ordem no prompt, você já sabe a ordem.
Os traces mostram ordens diferentes, passos pulados ou repetidos, para entradas parecidas.
O número de turnos varia muito, sem motivo de negócio.
E quando dá errado, a explicação é: o agente achou que não precisava.
Agente virou o padrão. Frameworks e tutoriais começam com agente, e ele parece mais moderno que uma sequência de funções.
A demo convence. Em dez testes, o agente fez tudo na ordem certa. A variação aparece nas milhares de execuções.
Flexibilidade para o futuro. E se um dia a gente quiser pular a checagem de preço em algumas categorias? Flexibilidade que talvez seja útil um dia custa confiabilidade todo dia.
E juntar tudo parece mais simples. Um prompt e quatro ferramentas parecem menos código que quatro funções encadeadas. O código some. A complexidade fica, escondida no comportamento do modelo.
O custo começa na confiabilidade. Passos obrigatórios viram opcionais. Em moderação, compliance ou finanças, um passo pulado é um incidente.
E taxa pequena vira volume de verdade. Digamos que o marketplace modera cinquenta mil anúncios por dia. Se o agente pula a imagem em só 0,1% das execuções, são cinquenta anúncios por dia publicados sem ninguém olhar a foto.
Em um mês, mil e quinhentos. Uma taxa que parece ótima no eval vira volume de verdade em produção.
Depois, dinheiro. Cada turno do agente reenvia o contexto inteiro e paga mais uma chamada para decidir algo que o código já sabia. Naquele trace perfeito, três das quatro chamadas ao modelo só serviram para escolher a próxima ferramenta.
Depois, latência. As checagens rodam uma depois da outra, esperando o modelo escolher. Elas poderiam rodar ao mesmo tempo.
E teste. Um fluxo fixo é fácil de testar. Um agente precisa de um eval estatístico só para provar que sempre faz a mesma coisa.
Uma pergunta para você. Para garantir a checagem de imagem, o time escreveu, em maiúsculas: sempre rode check image. A taxa de pulo caiu de 2% para 0,3%. O problema está resolvido?
Não. A garantia continua estatística. Enquanto o modelo decide, o passo pode ser pulado. Com cinquenta mil anúncios por dia, 0,3% são cento e cinquenta anúncios sem checagem de imagem.
E um modelo melhor também não leva a zero. Ele baixa a taxa de novo, mas o problema é o desenho, não a capacidade do modelo. Passo obrigatório precisa ser código. Aí a taxa é zero, por construção. Prompt mais alto também empurra para outro smell, o rule stacking, em que regras em maiúsculas se acumulam e brigam entre si.
O tratamento é uma refatoração chamada replace agent with chain. E a versão em chain do moderador cabe em poucas linhas.
As três checagens não dependem uma da outra, então o código roda as três ao mesmo tempo.
Depois o modelo é chamado uma vez, com os três resultados, para pesar e decidir.
Agora, pular a imagem exige apagar uma linha de código, com revisão e teste. O modelo fica onde agrega valor. E a latência vira a da checagem mais lenta, mais uma chamada ao modelo, em vez de quatro chamadas em fila.
Aí o time descobre que anúncio de veículo precisa de uma quarta checagem, no documento do carro. As outras categorias continuam com três. Você deveria voltar para o agente, já que o caminho agora varia?
Não. O caminho varia, mas de um jeito que você conhece antes da execução. Isso é um if na categoria, ou uma rota separada para veículos. Ramo conhecido é roteamento. E cada ramo continua sendo uma chain, com todo passo garantido. Escrever isso no prompt só traria o mesmo smell de volta, agora num ramo.
Esse smell não é uma regra contra agentes. Quando o caminho realmente depende do que você descobre, agente é a ferramenta certa. Um agente de suporte recebe: o sistema está lento. Pelo que encontra, ele decide se olha logs, métricas, deploys recentes ou o banco. Isso não é esse smell. É investigação aberta, o caso clássico de agente. O que ele precisa é de orçamento de passos e condições de parada.
Um agente também pode ser um bom protótipo, para descobrir quais passos a tarefa precisa. Quando os traces começarem a se repetir, transforme o caminho em código.
E se pular um passo é mesmo aceitável, e barato, a flexibilidade pode valer a pena.
Um último caso. Um agente de relatórios sempre chama as mesmas três ferramentas, na mesma ordem, e nunca pulou nenhuma em seis meses de traces. Ainda vale refatorar? Vale, mas sem pressa. O comportamento dele já é uma chain. Transformar em código corta custo e latência, e troca uma garantia estatística por uma garantia de verdade. Faça junto com a próxima mudança nesse fluxo.
Então, a ideia para levar. Se você consegue escrever os passos no prompt, consegue escrever no código. E no código, um passo obrigatório roda sempre. Deixe o julgamento para o modelo, e a ordem para o seu código.
Na próxima aula, a gente fecha esta trilha com um sistema real que junta tudo: um bot de atendimento com escalonamento para humanos. Até lá.
Agent Where a Chain Would Do
Agente Onde Bastava uma Chain (Agent Where a Chain Would Do) é um smell de IA, ou seja, um sinal de problema em sistemas com LLM, do grupo Abusos de controle. O caminho é sempre o mesmo, mas um agente autônomo decide a ordem a cada execução.
O pipeline de moderação de anúncios de um marketplace roda como agente: recebe o anúncio, tem quatro ferramentas (check_text, check_image, check_price, publish_decision) e um prompt que diz “verifique o anúncio e decida”. Dois traces do mesmo dia, lado a lado:
trace a91f anúncio 88213
llm -> check_text ok
llm -> check_image ok
llm -> check_price ok
llm -> publish_decision aprovado
4 voltas, 11,2 s
trace b07c anúncio 88214
llm -> check_text ok
llm "A imagem parece consistente com o texto."
llm -> publish_decision aprovado
2 voltas, 5,8 s <- check_image nunca rodouO anúncio 88214 tinha uma imagem proibida. O agente decidiu, naquela execução, que olhar a imagem era desnecessário. Repare na frase do segundo trace: o modelo opinou sobre uma imagem que nunca analisou.
Ninguém no time queria que a checagem de imagem fosse opcional. A regra de negócio era “todo anúncio passa pelas três checagens”. Só que essa regra vivia num prompt, e um prompt é uma sugestão forte, não uma garantia.
Sinais do smell:
flowchart LR
subgraph AG["Hoje: agente decide"]
A(["1. Modelo escolhe o próximo passo"]):::llm --> T["2. Alguma ferramenta"]:::tool
T --> A
end
subgraph CH["Bastava: chain"]
C1["3. Texto"]:::tool --> C2["Imagem"]:::tool --> C3["Preço"]:::tool --> C4(["Decisão"]):::llm
end
A distinção vem do guia “Building effective agents”, da Anthropic (dez. 2024). Workflows seguem caminhos definidos no código. Agentes deixam o modelo dirigir o próprio processo. O guia recomenda começar pela solução mais simples e só usar agente quando o caminho não pode ser previsto.
Suponha que o marketplace modere 50 mil anúncios por dia. Se o agente pula a checagem de imagem em 0,1% das execuções, são 50 anúncios por dia publicados sem ninguém olhar a foto. Em um mês, 1.500. Uma taxa que parece ótima no eval vira volume relevante em produção.
No trace a91f, o caminho completo custou quatro chamadas ao modelo em série, três delas só para escolher a próxima ferramenta. Na chain, as três verificações rodam em paralelo no código e o modelo é chamado uma vez, para a decisão. A latência passa a ser a da verificação mais lenta mais essa chamada.
A primeira reação costuma ser escrever “SEMPRE rode check_image” em maiúsculas. A taxa de pulos cai, e o time considera o problema resolvido. Ela não chega a zero, porque o modelo continua decidindo. E cada instrução nova desse tipo empurra o prompt para o smell Pilha de Regras.
| Refatoração | Escolha quando |
|---|---|
| Trocar Agente por Chain | O caminho é fixo. Os passos viram código, e o modelo fica só nas etapas que pedem julgamento, como no Encadeamento de Prompts. |
A versão em chain do moderador cabe em poucas linhas. As verificações são independentes, então rodam juntas:
async def moderate(listing):
text, image, price = await asyncio.gather(
check_text(listing), check_image(listing), check_price(listing),
)
decision = await llm(DECISION_PROMPT, listing=listing, checks=[text, image, price])
return publish_decision(listing.id, decision)Agora pular a imagem exige apagar uma linha de código, com revisão e teste. O modelo continua no lugar onde ele agrega: pesar os três resultados e decidir.
Se o caminho tem poucas bifurcações conhecidas (“anúncio de veículo tem uma checagem extra”), a forma final é um workflow com Roteamento, não um agente. Se as verificações não dependem uma da outra, como aqui, rode em paralelo com Seccionamento.
Responda as 6 perguntas para concluir a aula. Só assistir não conclui: a checagem é o que conta para a trilha e para o certificado.
Agente Onde Bastava uma Chain (Agent Where a Chain Would Do) é um smell de IA, ou seja, um sinal de problema em sistemas com LLM, do grupo Abusos de controle. O caminho é sempre o mesmo, mas um agente autônomo decide a ordem a cada execução.
Com Trocar Agente por Chain. Cada refatoração traz o passo a passo seguro, com eval antes e depois.
Nos cenários reais Moderação de conteúdo.