O sistema ao redor do modelo

Quando uma resposta erra, é tentador dizer que “a IA falhou”. Essa frase esconde pelo menos quatro componentes. O modelo transforma entradas em saídas. O produto oferece interface, histórico e integrações. Um agente usa o modelo em um ciclo para observar, escolher uma ação e tentar alcançar uma condição de parada. O harness é o software que monta contexto, declara ferramentas, aplica permissões, executa chamadas, registra o que ocorreu e decide continuar ou parar.

Uma analogia útil é a oficina. O modelo é o profissional capaz de raciocinar; o produto é o balcão pelo qual o pedido chega; ferramentas são instrumentos; o harness contém bancada, regras de acesso, ordem de serviço, medidores e botão de emergência. O limite da analogia é importante: um modelo não possui intenção humana estável nem compreende o mundo como uma pessoa. Ele produz saídas condicionadas à entrada e ao sistema que o cerca.

Diagnosticar pela camada

Considere a solicitação “aprove a OS 184”. Se o modelo não sabe o que é uma OS, pode faltar contexto. Se propõe delete_order, a declaração de ferramenta está inadequada. Se um eletricista consegue aprovar, a política de autorização falhou. Se a ação ocorre duas vezes após timeout, faltou idempotência. Se o botão não mostra confirmação, há problema de produto. Trocar o modelo pode não corrigir nenhuma dessas causas.

Um sistema simples pode fazer uma única chamada e validar a saída. Chame-o de workflow assistido, não de agente, se não existe ciclo de ação. Um agente mínimo precisa de objetivo, estado, ferramenta, observação e parada externa. “Autônomo” não significa ilimitado: significa poder avançar dentro de autoridade e orçamento definidos.

Essa preferência por workflows simples antes de sistemas mais autônomos é consistente com a orientação primária da Anthropic sobre construção de agentes.

Passo a passo da execução

Para tornar o ciclo concreto, acompanhe uma solicitação: “verifique se a OS 184 pode ser aprovada e prepare a decisão”.

1. O produto coleta a intenção. A interface identifica a pessoa e mostra que a ação ainda não foi executada.
2. O harness compõe o contexto. Inclui a regra de alçada, o identificador da OS e as ferramentas estreitas disponíveis. Não envia o banco inteiro.
3. O modelo propõe uma ação. Pode pedir read_order({id: "184"}); essa saída é uma proposta, não permissão.
4. A política valida a chamada. Confere schema, identidade, escopo, orçamento e se leitura é permitida naquele momento.
5. A ferramenta executa e devolve observação. O resultado é tratado como dado e incorporado ao estado do ciclo.
6. O modelo produz uma decisão ou outra chamada. Uma chamada com efeito, como request_approval, passa novamente pela política.
7. O harness para. Resultado válido, limite, timeout, cancelamento ou bloqueio são estados terminais observáveis.

Esse desenho impede uma confusão comum: o modelo não “chama o banco”. Ele emite dados que o harness interpreta; a aplicação decide se e como uma capacidade será executada.

type Decision =
  | { kind: "final"; answer: string }
  | { kind: "tool"; name: "read_order"; args: { id: string } };

for (let step = 0; step < 4; step++) {
  const decision: Decision = await model.decide(state);
  if (decision.kind === "final") return validate(decision.answer);
  policy.assertAllowed(decision.name, identity);
  state.observations.push(await tools.readOrder(decision.args.id));
}
throw new Error("stop:max_steps");

O exemplo é conceitual: produção ainda exige timeout, redaction, orçamento, cancelamento, schema e trace. Note que o código — não o texto do prompt — impõe o máximo de passos e a allowlist.

Versão executável mínima

O trecho abaixo pode ser salvo como agent-loop.ts e executado num projeto TypeScript com tsx. Ele não usa um provedor real; um modelo determinístico permite observar a trajetória e testar os limites antes de integrar uma API externa.

type State = { step: number; observations: string[] };
type Decision =
  | { kind: "tool"; name: "read_order"; id: string }
  | { kind: "final"; answer: string };

function fakeModel(state: State): Decision {
  return state.observations.length === 0
    ? { kind: "tool", name: "read_order", id: "184" }
    : { kind: "final", answer: `observado:${state.observations[0]}` };
}

export async function run(maxSteps = 3) {
  const state: State = { step: 0, observations: [] };
  while (state.step < maxSteps) {
    state.step += 1;
    const decision = fakeModel(state);
    if (decision.kind === "final") return { ...state, answer: decision.answer };
    if (decision.name !== "read_order") throw new Error("tool_denied");
    state.observations.push(`OS ${decision.id}: waiting_approval`);
  }
  throw new Error("stop:max_steps");
}

Teste a trajetória, não apenas o texto final:

import { strict as assert } from "node:assert";
import { run } from "./agent-loop.js";

const result = await run();
assert.equal(result.step, 2);
assert.deepEqual(result.observations, ["OS 184: waiting_approval"]);

Se o resultado estiver correto, mas o trace mostrar leitura de arquivo proibido, o sistema falhou. A trajetória é parte do contrato quando existem ferramentas e efeitos.

Falhas e controles

O antipadrão mais comum é conceder uma ferramenta ampla, como manage_order, e esperar que a instrução “tenha cuidado” limite seu uso. Prefira ferramentas estreitas (read_order, request_approval) e autorização independente do modelo. Outro erro é avaliar somente a resposta final. Uma resposta correta obtida após ler arquivo proibido continua sendo falha.

Teste trajetória e resultado: caso nominal, ferramenta negada, entrada maliciosa, timeout, repetição e orçamento esgotado. Registre versão das instruções, modelo, ferramentas oferecidas, chamadas, decisões de política, custo e artefatos — sem despejar segredos ou dados pessoais no trace.

Segurança, privacidade, custo e operação

O ativo não é apenas a resposta: código, dados de OS, credenciais, autoridade de aprovar, orçamento e disponibilidade também têm valor. Modele pelo menos estes abusos:

• documento recuperado tenta instruir o agente a revelar uma chave;
• argumento usa ../ para escapar do diretório permitido;
• retry repete uma ação que já teve efeito;
• trace armazena token ou comentário pessoal integral;
• loop consome passos ou ferramenta cara sem progresso;
• modelo tenta uma ferramenta não prevista no ticket.

Controles correspondentes ficam fora do modelo: normalização de caminho, schema, allowlist, autorização por objeto, chave idempotente, redaction, orçamento e stop condition. Meça taxa de sucesso por caso, ferramentas negadas, passos, latência, custo e intervenção humana. Mais passos não significam mais inteligência; podem indicar loop.

Troubleshooting orientado por sintoma

Sintoma	Primeira hipótese	Evidência	Próxima ação
não reconhece “OS”	contexto ausente	prompt/trace composto	incluir contrato, não conversa inteira
usa tool ampla	contrato de capacidade ruim	schema oferecido	dividir em ferramentas estreitas
eletricista aprova	policy falhou	decisão de autorização	corrigir servidor e teste negativo
duplica efeito	retry sem idempotência	mesmo request/event ID	deduplicar e reconciliar
nunca termina	parada ausente	passos e chamadas	impor limite e estado terminal

Antes e agora

Antes, demonstrações frequentemente apresentavam o modelo como aplicação inteira e loops abertos como sinal de inteligência. Hoje, a prática recomendada começa pelo workflow mais simples que passa em avaliações e adiciona agência somente quando há ganho mensurável. O método antigo ainda serve a protótipos descartáveis sem efeitos externos; não é base segura para produção.

Escada de complexidade: pare no primeiro nível suficiente

Um sistema mais complexo não é automaticamente mais capaz. Cada novo ciclo adiciona estado, custo, formas de falhar e trabalho de operação. Antes de criar um agente, classifique o problema:

Nível	Estrutura	Exemplo na manutenção	Evidência mínima
Chamada única	entrada → modelo → validação	resumir um histórico já selecionado	schema válido e comparação com casos esperados
Workflow	sequência fixa de etapas	extrair campos, validar e redigir uma minuta	teste de cada etapa e falha fechada
Agente	escolhe entre ações dentro de um loop	investigar uma OS consultando fontes permitidas	trajetória, política, orçamento e parada
Grafo orquestrado	tarefas com dependências e paralelismo	pesquisar manual, estoque e incidentes em ramos independentes	contratos dos nós, fronteira, consolidação e recuperação

Comece com uma chamada quando a entrada já contém a informação necessária e não há efeito externo. Use um workflow quando a ordem das etapas é conhecida; código determinístico é mais simples de testar do que pedir ao modelo para redescobrir a sequência. O agente passa a fazer sentido quando a próxima ação depende de uma observação que ainda não existe, como decidir qual manual consultar depois de ler o modelo do equipamento. Um grafo só se justifica quando há dependências ou ramos independentes suficientes para que a coordenação traga ganho medido.

Faça um teste de promoção antes de subir de nível. Registre o problema da versão atual — por exemplo, “a sequência fixa consulta três fontes desnecessárias” — e uma métrica, como correção, latência ou custo. Construa a alternativa mais complexa com o mesmo conjunto de casos. Promova somente se o ganho compensar coordenação e risco. Se a avaliação empatar, preserve a solução menor.

Esse critério também ajuda a interpretar a chamada “era Maestro”. O Maestro não é quem abre o maior número de agentes; é quem projeta o sistema, conhece seus limites e escolhe quando não adicionar um novo instrumento. Programação, testes, APIs, dados e segurança continuam sendo os alicerces usados para avaliar a orquestração.

Não confunda o desenho interno com a experiência do usuário. Um produto pode usar um grafo complexo e oferecer apenas um botão; outro pode exibir uma conversa, mas executar somente uma chamada. “Chat”, “agente” e “grafo” descrevem aspectos diferentes. Para diagnosticar, observe a execução real: quem escolhe a próxima ação, onde o estado é guardado, qual componente autoriza o efeito, que evidência encerra o ciclo e como o sistema se recupera se parar entre duas etapas.

Exercício e aceite

Desenhe o sistema que aprova OS e classifique cada elemento como modelo, produto, harness, ferramenta, estado ou política. Depois descreva seis falhas e indique a camada responsável. O exercício passa quando outra pessoa consegue trocar o modelo sem alterar as regras de autorização e quando todos os efeitos externos têm política, trace e parada observável.

Perguntas de recuperação: o que diferencia workflow de agente? Por que ferramenta disponível não significa ferramenta autorizada? Que falha não seria corrigida por um modelo melhor?

Exercício guiado

1. Desenhe produto, harness, modelo, duas ferramentas, estado e policy da aprovação.
2. Marque quais dados são confiáveis, não confiáveis e sensíveis.
3. Escreva um caso nominal, tool negada, timeout e repetição pós-efeito.
4. Execute o loop determinístico, reduza maxSteps para 1 e capture a parada.
5. Acrescente uma ferramenta fictícia delete_order e prove que a allowlist a nega.

Entregável: diagrama, código, saída de testes e tabela falha→camada→controle. O aceite exige que outra pessoa consiga trocar fakeModel sem alterar autorização, limite ou critérios de teste.

Desafio de transferência

Modele um agente que consulta estoque, mas não reserva peça. Depois descreva a mudança de harness necessária para permitir reserva: confirmação, idempotência, escopo, auditoria, orçamento e recuperação. Explique por que mudar apenas o prompt seria insuficiente.

Transição

Agora que as partes do sistema estão separadas, o próximo capítulo trata o recurso que todas disputam: contexto e orçamento. Você aprenderá por que janela grande não equivale a atenção perfeita e como limitar tokens, ferramentas, prazo e custo separadamente.

Fontes

• OpenAI — Codex
• Anthropic — Building effective agents
• Model Context Protocol — especificação