O modelo é só um componente

Um modelo pode escrever uma chamada como aprovar_ordem(742). Isso não significa que ele conhece a identidade do solicitante, que a ordem pertence ao tenant correto, que o supervisor tem autoridade, que a operação ainda não ocorreu ou que há orçamento para continuar. O modelo propõe uma saída com base no contexto. Quem transforma essa proposta em efeito é o sistema ao redor dele.

Esse sistema é o harness: o runtime que compõe contexto, chama o modelo, valida sua saída, aplica políticas, executa ferramentas, persiste estado, mede uso e decide quando parar. A documentação de avaliações da Anthropic explicita essa separação: ao avaliar “um agente”, avaliam-se modelo e harness juntos, porque ferramentas, ambiente e orquestração alteram o resultado (Anthropic, 2026).

Vocabulário antes da arquitetura

Os termos abaixo se relacionam, mas não são intercambiáveis.

Termo	Definição operacional	Quem escolhe o próximo passo?
modelo	função probabilística que recebe entrada e produz saída	o próprio modelo escolhe apenas o conteúdo da saída
assistente	produto que organiza conversa, instruções e talvez ferramentas	pessoa e produto conduzem a interação
workflow	sequência previamente desenhada de etapas e decisões	código, regras ou grafo determinístico
agente	sistema em que o modelo participa da escolha de ações e usa ferramentas	modelo, dentro dos limites do harness
agent loop	ciclo observar → decidir → agir → observar	modelo decide a próxima ação até uma parada externa
grafo	tarefas como nós ligados por dependências, eventos ou condições	o orquestrador libera nós; cada nó pode ser determinístico ou agentic
harness	runtime que fornece contexto, tools, policy, estado, isolamento, telemetria e parada	governa o que o modelo pode realmente fazer

Um workflow pode chamar um modelo sem ser um agente. Um agente pode operar sem multiagente. Um grafo pode conter apenas funções determinísticas. E “Maestro” não é um tipo especial de modelo: neste Grimório, é o papel de projetar e operar a coordenação entre tarefas, agentes, verificadores e controles.

A escada: do auxílio à orquestração

Subir esta escada aumenta capacidade, mas também modos de falha, custo e necessidade de operação.

1. Assistente

A pessoa pede, lê e decide o próximo turno. É apropriado para exploração, explicação e produção de rascunho. O risco cai porque a ação externa continua humana, embora dados sensíveis e respostas incorretas ainda exijam cuidado.

2. Agente limitado

O modelo recebe uma ou poucas ferramentas estreitas, como consultar_ordem, e escolhe quando chamá-las. Use quando a sequência varia com os dados. Comece somente leitura; limite passos, tempo e saída.

3. Workflow

O código conhece o caminho: validar formulário, consultar ordem, verificar permissão, pedir aprovação e então gravar. Se as etapas são previsíveis, um workflow é mais simples que autonomia aberta. Agente e workflow podem cooperar: o modelo classifica a intenção, enquanto a API de domínio executa o processo conhecido.

4. Loop avaliado

O agente itera, mas o runtime registra trajetória, mede orçamento, detecta repetição e verifica o estado final. “Avaliado” é parte do nome porque repetir sem um oráculo apenas automatiza tentativa e erro. A execução para por critérios externos, não porque o modelo afirmou que terminou.

5. Grafo

Um grafo torna dependências explícitas. Pesquisa de segurança e pesquisa de UX podem ocorrer em paralelo; integração só começa quando contratos anteriores estiverem prontos. Um grafo é útil quando há ramificações reais, handoffs ou tarefas independentes. Não o use para desenhar como paralelo um trabalho que compartilha os mesmos arquivos e decisões.

6. Maestro

O Maestro governa o sistema completo: escolhe a topologia, define contratos, limita autoridade, distribui orçamento, acompanha traces, trata falhas e decide quando a complexidade deve ser removida. É uma competência de arquitetura e operação, não o ato de abrir várias sessões.

Anatomia do harness

Um harness mínimo executa nove responsabilidades:

1. recebe objetivo, identidade e limites;
2. compõe somente o contexto necessário;
3. oferece ferramentas com schemas e efeitos claros;
4. chama uma versão registrada do modelo;
5. valida sintaxe e semântica da proposta;
6. aplica policy determinística e aprovação humana;
7. executa em sandbox com timeout e idempotency key;
8. persiste checkpoint e trace redigido;
9. avalia resultado e retorna uma razão de parada.

O pseudocódigo abaixo descreve a ordem; ele é deliberadamente ilustrativo, não uma biblioteca pronta para copiar:

para cada passo até maxSteps:
    se orçamento, prazo ou cancelamento encerrou: parar(com motivo)
    resposta = modelo(contexto derivado do estado)
    cobrar uso e registrar hash/configuração
    se resposta final: verificar estado real e aceitar ou rejeitar
    chamada = validar schema e resolver aliases
    decisão = policy(identidade, ferramenta, argumentos resolvidos, estado)
    se proibida: parar(policy_denied)
    se sensível: exigir aprovação vinculada ao alvo resolvido
    observação = executar em sandbox(timeout, idempotencyKey)
    checkpoint = persistir transição e efeito de forma recuperável
parar(max_steps)

As extensões do Codex refletem responsabilidades diferentes: AGENTS.md guarda orientação durável, skills empacotam processos, MCP conecta sistemas e subagentes isolam trabalho (OpenAI, documentação atual). Nenhum desses artefatos substitui a policy do runtime.

Política fora do prompt

Policy é a decisão determinística sobre se uma ação é permitida. O prompt pode explicar “um eletricista não aprova uma OS”, ajudando o modelo a evitar propostas inúteis. A API ainda precisa impor essa regra.

Considere aprovar_ordem("minha-os"). Antes da autorização, o harness resolve o alias para tenant-shopping/os/742. Só então avalia:

• identidade autenticada e tenant;
• papel e escopo;
• ferramenta e efeito;
• alvo resolvido, não apenas o texto original;
• estado atual da ordem;
• aprovação humana ainda válida;
• limites de horário, custo ou risco.

Autorizar antes de resolver o alvo cria uma troca de alvo: o texto aparentemente permitido pode apontar depois para outro tenant. Da mesma forma, não aceite que uma ferramenta remota diga “usuário autorizado”; conteúdo de ferramenta é dado, não autoridade.

Políticas adequadas para código ou configuração incluem allowlist de ferramentas, caminhos permitidos, egress de rede, limite financeiro, separação de tenants e exigência de confirmação. Linters, hooks e CI são úteis quando a regra é mecânica; prompts e skills são úteis quando ela exige julgamento. Segurança não deve depender de o modelo lembrar uma frase.

Sandbox: reduzir capacidade, não pedir prudência

Uma sandbox restringe o ambiente onde a ação ocorre. O blast radius é o máximo de dano possível se modelo, prompt, ferramenta ou dependência falhar.

Um worktree isola uma árvore Git, mas não bloqueia rede, processos, segredos ou APIs de produção. Uma sandbox proporcional combina:

• filesystem limitado ao diretório necessário;
• rede negada por padrão ou egress allowlist;
• processos, CPU, memória, tempo e tamanho de saída limitados;
• credencial efêmera, específica e de menor privilégio;
• segredos fora de prompt, trace e artefatos;
• alvo destrutivo explícito e confirmação recente;
• ambiente de teste separado de produção.

No sistema de manutenção, um agente que prepara uma alteração precisa de leitura da OS e escrita em uma branch. Ele não precisa de token que aprove ordens em produção. Remover a capacidade é mais forte do que instruí-lo a não usá-la. O NIST SSDF trata práticas seguras como parte do ciclo de desenvolvimento, e não como comportamento opcional do gerador (NIST SSDF).

Estado: continuidade sem despejo de conversa

Estado operacional não é “tudo que foi dito”. É o conjunto mínimo necessário para saber o que aconteceu e retomar com segurança:

run_id: run-2026-08-09-0042
objective: preparar patch da regra de aprovação
phase: testing
version: 7
budget_spent: 1.84
artifacts:
  - worktree: feature/aprovacao-os
  - patch: 91ad7f
approvals:
  - action: write_repository
    scope: services/api
    status: approved
effects:
  - key: run-0042:update-contract
    status: committed
next: executar testes de contrato
stop_reason: null

Não serialize tokens, credenciais, documentos inteiros ou raciocínio privado. Referencie artefatos por endereço e checksum. Versione checkpoints e persista transições atomicamente sempre que possível.

A janela perigosa

O executor grava uma OS, mas cai antes de salvar a observação. Na retomada, “não vi sucesso” não significa “não aconteceu”. Repetir cegamente pode duplicar o efeito.

A defesa combina:

• idempotency key: a mesma intenção produz no máximo um efeito;
• máquina de estados: transições permitidas e registradas;
• consulta de reconciliação: verificar o sistema de registro;
• outbox/transação: aproximar efeito e registro de evento;
• checkpoint: guardar etapa, evidência e próximo passo.

Idempotência não significa repetir qualquer coisa infinitamente. Significa que o receptor reconhece a mesma intenção e devolve o resultado já produzido ou rejeita uma transição incompatível.

Stop conditions: parar também é um resultado

Uma execução deve terminar com stop_reason observável. Razões comuns:

• accepted: critérios verificados no estado real;
• final_invalid: resposta final não atende ao contrato;
• policy_denied ou approval_denied;
• budget_exhausted, deadline ou max_steps;
• repetition_detected;
• dependency_unavailable após política de retry;
• human_decision_required;
• cancelled ou kill_switch.

“O modelo parou de chamar ferramentas” é uma observação, não um critério de sucesso. Uma OS só foi criada se a API ou o banco autorizado comprovar o registro esperado.

Custo e tracing

Custo útil é custo por resultado verificado, não preço de uma chamada. Some tokens de entrada e saída, ferramentas, retries, subagentes, armazenamento, observabilidade e revisão humana. Compare com a baseline simples usando os mesmos casos.

Um trace registra o percurso necessário para diagnóstico:

• run, task e correlação com usuário/tenant pseudonimizados;
• fornecedor, modelo, versão e configuração;
• hashes de instrução e artefatos, não segredos em claro;
• ferramentas oferecidas, chamadas, duração e erros;
• decisões de policy e aprovação;
• transições de estado e idempotency keys protegidas;
• uso, custo, stop reason e resultado dos graders.

Trace não é despejo de prompt. Redaction ocorre antes da exportação; acesso, retenção e exclusão são definidos. A fonte de avaliações da Anthropic distingue trace — trajetória — de outcome — estado final. Ambos importam: uma resposta correta obtida por ferramenta proibida continua sendo falha.

Quando não usar multiagente

Multiagente não é o topo obrigatório da evolução. A Anthropic relata ganhos expressivos em pesquisa com direções independentes, mas também consumo muito maior de tokens e pior adequação quando agentes compartilham muito contexto ou tarefas têm muitas dependências (sistema multiagente de pesquisa).

Evite multiagente quando:

• um workflow ou agente único cabe no contexto e no prazo;
• tarefas alteram os mesmos arquivos ou disputam a mesma decisão;
• não existe contrato de handoff nem dono da síntese;
• o verificador só repete a opinião do executor;
• não há tracing, orçamento ou forma de cancelar descendentes;
• a tarefa tem baixo valor e não paga coordenação;
• dados sensíveis seriam copiados para mais contextos.

Use paralelismo quando subtarefas são separáveis, a saída de cada uma é pequena e verificável, e a frontier de tarefas desbloqueadas é explícita. Para revisão independente, um único agente em contexto novo pode ser melhor do que uma “equipe” inteira.

Diagnóstico de falhas

Sintoma	Causa provável	Evidência	Correção
mesma ferramenta se repete	stop/repetição ausente	trace com argumentos equivalentes	detector de ciclo e limite de passos
outro tenant foi consultado	policy antes da resolução do alvo	alvo original versus resolvido	autorizar identidade + alvo resolvido
efeito duplicado após timeout	retry sem idempotência	duas transações para a mesma intenção	idempotency key e reconciliação
custo cresce sem qualidade	grafo ou contexto excessivo	custo por outcome e subagente	retornar ao degrau anterior
retomada “esquece” bloqueio	checkpoint incompleto	transição sem aprovação/efeito	schema versionado e persistência atômica
segredo aparece no painel	trace capturado antes de redaction	amostra de telemetria	redigir na origem e reduzir retenção

Critérios de aceite e prática

Um harness deste capítulo é aceitável quando policy é independente do prompt; sandbox limita filesystem, rede, processo e credencial; escrita sensível usa aprovação e idempotência; checkpoint permite retomada; toda parada tem motivo; trace é suficiente para diagnóstico e não contém segredo; custo é medido por tarefa concluída; e a alternativa multiagente só permanece se superar uma baseline mais simples.

Desenhe a escada para uma tarefa do seu contexto. Em cada degrau, liste ganho esperado, novo risco, evidência e rollback. Se não houver evidência que justifique o próximo degrau, mantenha o sistema menor. O caderno seguinte transforma essa decisão em um runtime simulado e recuperável.

Recuperação ativa

1. Por que workflow e agente não são opostos?
2. Que responsabilidade transforma um modelo em parte de um agente?
3. Por que policy deve receber o alvo já resolvido?
4. O que um worktree não isola?
5. Como idempotência fecha a janela entre efeito e checkpoint?
6. Qual diferença existe entre trace, outcome e stop reason?
7. Em que cenário um grafo multiagente pioraria a execução?

Fontes e leitura continuada

As fontes oficiais no frontmatter sustentam definições e controles. Os vídeos LABS — agentes e harness e Maestros da IA — graph engineering são fontes pedagógicas secundárias: ajudam a visualizar o vocabulário contemporâneo, mas suas heurísticas e demonstrações não substituem especificações, testes ou medições. Para long-running work, leia também o relato oficial sobre decomposição, handoffs e avaliadores em Harness design for long-running application development.