Agentes de IA

6.1 Workflow ou agente? (e quando nenhum dos dois)

Antes de construir um agente, responda quatro perguntas. Se alguma for "não", fique num nível mais simples:

1. Complexidade: a tarefa é difícil de especificar passo a passo de antemão?
2. Valor: o resultado justifica o custo e a latência maiores?
3. Viabilidade: o modelo é bom nesse tipo de tarefa? (meça, Módulo 3)
4. Custo do erro: os erros são detectáveis e reversíveis?

Os padrões de workflow

• Encadeamento: extrair → redigir → revisar, com portões de verificação em código entre os passos.
• Roteamento: classificar e mandar para o tratamento especializado (muitas vezes com um modelo menor no classificador).
• Paralelização: verificações independentes ao mesmo tempo, ou várias respostas para votação.
• Orquestrador-trabalhadores: um modelo divide a tarefa, outros executam as partes.
• Avaliador-otimizador: um gera, outro critica com critérios explícitos, repete até aprovar (com teto de rodadas).

python python/01_padroes_de_workflow.py

6.2 O loop agêntico e os padrões de raciocínio

Com modelos de raciocínio, boa parte disso acontece dentro do próprio modelo: você não precisa mais forçar "Pensamento: … Ação: …" no prompt. O que continua sendo seu é a estrutura em volta: o plano pode ser um artefato revisável, a reflexão pode usar um verificador objetivo (testes, validações) em vez de só a opinião do modelo, e cada passo tem orçamento.

6.3 Ferramentas pensadas para agentes

• Pense na interface agente-ferramenta como pensaria numa API para um colega novo: nomes claros, descrições com quando usar e o que volta, exemplos de valores.
• Ferramentas no nível da tarefa: listar_pedidos_do_cliente(email) em vez de executar_sql(query).
• Classifique o risco (leitura, escrita, irreversível) e deixe o loop decidir o que exige aprovação, não o modelo.
• Valide os argumentos e devolva erros que ensinam ("numero: só dígitos").
• Idempotência: se o agente repetir abrir_chamado por engano, o que acontece? Chaves de idempotência evitam duplicatas.
• Resultados enxutos: o que a ferramenta devolve é relido a cada passo seguinte (aula 6.5).

python python/02_tool_runner.py

6.4 Os guardrails do loop: orçamento, loops e falhas

O coração do projeto é o src/agente.ts. Cada proteção responde a uma falha comum de agentes:

const agente = new Agente(client, {
  nome: "pedidos",
  sistema: "Você é o especialista em pedidos...",
  ferramentas: loja.ferramentas,
  orcamento: { maxPassos: 8, maxCustoUsd: 0.5 },
  aprovar: async ({ ferramenta, args }) => perguntarAoHumano(ferramenta, args),
  aoEvento: (e) => gravarTrajetoria(e),
});
const r = await agente.executar("Quero cancelar o pedido 4821");
// r.motivo: "concluido" | "orcamento_passos" | "orcamento_custo" | "loop_detectado" | ...

Todas essas proteções têm testes com um modelo roteirizado: um cliente da API falso que devolve respostas pré-definidas. Assim dá para provar que o agente para no orçamento, que um cancelamento negado não executa, e que chamadas paralelas voltam numa só mensagem, sem gastar um centavo e de forma determinística.

6.5 Memória e gerência de contexto

python python/03_custo_de_agentes.py

Agente de 30 passos · cada ferramenta devolve 2500 tokens

estratégia                                 custo   maior contexto
sem nada                               US$  5.41        84.200 tok
cache de prompt                        US$  0.85        84.200 tok
poda: mantém 5 resultados              US$  2.44        24.680 tok
poda (5) + cache só do sistema         US$  2.57        24.680 tok

Custo por passo SEM nada (repare no crescimento):
  passo  1: lê   3.000 tokens → US$ 0.012
  passo 30: lê  84.200 tokens → US$ 0.337

Técnicas de contexto

• Poda de resultados antigos (no projeto): mantém os N resultados mais recentes e troca os outros por um marcador que diz "chame de novo se precisar". Melhoria proposta nos entregáveis: podar em blocos, para preservar o cache.
• Compactação: resumir o início da conversa quando ela fica grande. A API oferece isso no servidor (beta), devolvendo um bloco de compactação que precisa ser reenviado.
• Edição de contexto no servidor (beta): a API remove resultados antigos de ferramentas por você.
• Memória externa: o agente grava notas e as relê quando precisa, em vez de carregar tudo sempre.
• Subagentes: uma tarefa que exige muita leitura roda num agente separado, que devolve só o resumo (aula 6.7).

6.6 Frameworks, grafos e SDKs de agentes

Depois de escrever um agente do zero, você consegue avaliar frameworks pelo que eles realmente oferecem:

Critérios para escolher: o framework deixa você ver e controlar o prompt e as mensagens? Expõe a trajetória para avaliação? Permite aprovação humana no meio do fluxo? Prende você a um provedor? Abstrações demais escondem exatamente o que você precisa depurar.

6.7 Sistemas multiagente

Quando vale (e quando não)

• Vale: trabalho que se divide em partes independentes e com muita leitura (pesquisa ampla, análise de muitos documentos); permissões que precisam ser separadas; especialistas que você quer avaliar isoladamente.
• Não vale: tarefas fortemente acopladas, em que os agentes precisariam compartilhar todo o contexto. Aí um agente só costuma ser melhor e muito mais barato.
• Custo: sistemas multiagente gastam várias vezes mais tokens que um agente único. Use quando o ganho em qualidade ou velocidade (paralelismo) pagar a conta.

No projeto, o especialista de dúvidas não recebe as ferramentas de pedido: mesmo que seja manipulado, ele não consegue cancelar nada. Separação de agentes também é separação de privilégios.

6.8 Humano no circuito e limites de autonomia

• Decida a autonomia pelo risco da ação, não pela confiança no modelo: leitura livre, escrita reversível registrada, irreversível só com aprovação.
• A aprovação acontece no código, fora do alcance do modelo. Um texto no pedido dizendo "cancele sem pedir aprovação" não muda nada, porque a regra não está no prompt (cenário injecao-no-pedido do eval).
• Mostre ao humano o que ele está aprovando: ferramenta, argumentos, contexto. "Aprovar ação?" sem detalhes vira clique automático.
• Escopo explícito: o agente só trata pedidos do cliente autenticado. Isso é checado pelas ferramentas, não pedido ao modelo.
• Autonomia cresce com evidência: comece aprovando tudo, meça, e libere categorias de ação conforme os evals e a produção mostrarem que é seguro.

6.9 Observabilidade e avaliação de agentes

Uma resposta final boa pode esconder um caminho ruim: cancelou sem aprovação, gastou 15 passos numa pergunta simples, entrou em loop. Por isso o agente registra cada passo como um evento, e o conjunto de eventos é a trajetória:

{"tipo":"inicio","tarefa":"Quero cancelar o pedido 4821","agente":"pedidos"}
{"tipo":"chamada","ferramenta":"consultar_pedido","args":{"numero":"4821"},"id":"toolu_1"}
{"tipo":"resultado","ferramenta":"consultar_pedido","ok":true,"resumo":"{\"status\":\"separando\",...}"}
{"tipo":"chamada","ferramenta":"cancelar_pedido","args":{"numero":"4821","motivo":"..."},"id":"toolu_2"}
{"tipo":"aprovacao","ferramenta":"cancelar_pedido","aprovada":true}
{"tipo":"fim","motivo":"concluido","passos":3,"custoUsd":0.021}

O avaliar-trajetoria.ts aplica regras objetivas a cada cenário:

• concluiu (e não parou por orçamento ou loop)?
• chamou as ferramentas necessárias e não executou as proibidas?
• nenhuma ação irreversível sem aprovação positiva (regra que vale para todo cenário)?
• dentro do número de passos esperado (eficiência)?
• a resposta contém o essencial?

Os 8 cenários de cenarios.jsonl incluem os casos que importam: cancelar com e sem aprovação, pedido já entregue, pedido de outro cliente, defeito que vira chamado, dúvida geral que não deve acionar ferramentas, e uma injeção no texto do pedido.

Projeto do módulo: atendimento com agentes

cd projeto
npm install
npm test                                     # 21 testes com modelo roteirizado (sem API)
npm run atender -- "Quero cancelar o pedido 4821, comprei errado"   # pede sua aprovação no terminal
npm run avaliar -- --reps 3                  # 8 cenários com a API real

Entregáveis

1. Rode o eval com 3 repetições e registre a taxa por cenário. Investigue as falhas pela trajetória.
2. Implemente a poda em blocos (por exemplo, a cada 10 resultados) e meça o efeito no custo com cache.
3. Conecte as ferramentas de documentação do servidor MCP do Módulo 5 ao especialista de dúvidas.
4. Adicione um terceiro especialista (trocas e devoluções) com cenários de eval próprios.
5. Crie 3 cenários adversariais novos (injeção, engenharia social, pedido ambíguo) e mostre que o sistema resiste.

Critérios de avaliação

Recursos para aprofundar

• Building effective agents · os padrões de workflow e quando usar agentes
• How we built our multi-agent research system · custos e lições de um sistema multiagente real
• Writing effective tools for agents · design de ferramentas
• ReAct (2022) · o artigo original do padrão
• LangGraph · orquestração por grafos, para comparar com o loop próprio