Agente longo com verificação | INEMA Agent Runtime

Entenda por que o agente acha que terminou

Tarefa longa é coisa como migrar planilhas, montar um site ou revisar cem arquivos. No meio do caminho, o agente perde detalhes e começa a achar que já terminou. Ele escreve "tudo pronto" com toda a convicção.

A receita R6 muda a regra do jogo: o agente só termina quando os critérios provam que terminou, e não quando ele acha. Quem dá o veredito é um script, o runtime/scripts/verificar.mjs.

🆕 Novo aqui? Quatro palavras deste módulo

Goal — um arquivo de texto com o resultado que você quer e a lista de critérios de pronto.
Critério — uma linha que diz "rode este comando; na resposta tem de aparecer este texto". Resposta sim ou não.
Saída 0 / saída 1 — todo comando termina com um número. 0 quer dizer "deu certo"; qualquer outro, "deu errado". Scripts e agentes leem esse número.
Portão humano — um ponto do goal em que o agente para e espera o seu sim.

Como ler o desenho: em cima, o caminho do palpite: a tarefa acaba quando o agente se convence. Embaixo, o caminho da R6: entre o trabalho e o fim existe a caixa roxa, e a seta tracejada devolve o agente ao trabalho a cada falha.

✗ Pronto por palpite

✗ "Revisei tudo e está ótimo"
✗ Ninguém consegue conferir depois
✗ Depende do humor do modelo naquela hora
✗ Você descobre o erro só no uso

✓ Pronto por prova

✓ 4/4 critérios OK e saída 0
✓ Você roda de novo amanhã e dá o mesmo
✓ Vale para o Claude Code e para o Codex
✓ A falha aparece com nome e linha

📄

Goal

resultado + critérios

✅

Critério

comando → saída

🧮

verificar

o juiz do pronto

🚧

Portão

só com seu sim

Escreva critérios comando → saída

Cada critério é uma linha de lista com dois trechos entre crases: o comando e o texto que tem de aparecer na saída, separados por uma seta.

O kit traz um goal pronto, sobre a ponte da agenda da Clara e o resumo de vendas da Sônia. Este é o arquivo inteiro, como está no kit:

📄 runtime/exemplos/goal-exemplo.md

# Goal de exemplo — ponte da agenda

## Resultado
A ponte MCP lê a agenda e o resumo de vendas, e o kit continua saudável.

## Critérios de pronto
- [ ] `node runtime/pontes/mcp-modelo/server.mjs --selftest` → `tools: 2`
- [ ] `node runtime/pontes/mcp-modelo/server.mjs --selftest` → `2026-10-06 09:00 · Dra. Ana`
- [ ] `node runtime/pontes/mcp-modelo/server.mjs --selftest` → `TOTAL: R$ 856.00`
- [ ] `node runtime/scripts/doctor.mjs` → `PRONTO`

Rode da raiz do kit: `node runtime/scripts/verificar.mjs runtime/exemplos/goal-exemplo.md`

Repare: o mesmo comando aparece três vezes, cada vez com um texto esperado diferente. Um critério confere uma coisa só.

✓ Bom critério

✓ Dá para checar com um comando
✓ A resposta é sim ou não
✓ É impossível passar sem fazer o trabalho
✓ Ex.: o total da Sônia, TOTAL: R$ 856.00, conferido à mão

✗ Não é critério

✗ "Deixar bom"
✗ "Revisar com cuidado"
✗ Um texto que aparece mesmo sem o trabalho feito
✗ Algo que só você, olhando, sabe dizer

💡 Como o script decide

Pelo código do verificar.mjs, um critério passa só se as duas coisas acontecem: o comando termina com saída 0 e a saída contém o texto esperado. Texto certo com comando quebrado não passa.

☑️

- [ ]

linha de lista

⌨️

`comando`

entre crases

➡️

→

a seta separa

🔤

`esperado`

texto da saída

Rode o verificar no goal de exemplo

Antes de entregar o goal a um agente, rode o verificar por conta própria. Ele não chama modelo: só executa os comandos dos critérios. Pode rodar quantas vezes quiser.

Rode sempre da raiz do kit, porque os comandos do goal usam caminhos que começam em runtime/.

🎯 Objetivo: provar o goal de exemplo

No terminal, na raiz da pasta do kit:

node runtime/scripts/verificar.mjs runtime/exemplos/goal-exemplo.md

Saída real (05/10/2026, Linux), saída 0:

OK     node runtime/pontes/mcp-modelo/server.mjs --selftest
OK     node runtime/pontes/mcp-modelo/server.mjs --selftest
OK     node runtime/pontes/mcp-modelo/server.mjs --selftest
OK     node runtime/scripts/doctor.mjs

4/4 critérios OK

Como verificar: a última linha é 4/4 critérios OK. Se aparecer FALHA no doctor, volte ao módulo 1.2; se for no selftest, ao módulo 2.2.

Linha da saída	Critério conferido	De quem
1ª OK	`tools: 2`: a ponte tem as duas ferramentas	ponte-modelo
2ª OK	`2026-10-06 09:00 · Dra. Ana`: horário livre lido	agenda da Clara
3ª OK	`TOTAL: R$ 856.00`: soma das vendas	ERP da Sônia
4ª OK	`PRONTO`: o kit continua saudável	doctor

O que olhar na tabela: as três primeiras linhas da saída mostram o mesmo comando. Quem diferencia é o texto esperado de cada critério, que o OK não repete.

💡 O total da Sônia foi conferido à mão

10×18,50 + 25×5,20 + 40×5,20 + 6×18,50 + 12×18,50 = 185 + 130 + 208 + 111 + 222 = 856. Um critério só vale se o valor esperado estiver certo. Confira o número uma vez, com calma, antes de confiar nele para sempre.

📍

Raiz do kit

onde rodar

🆓

Sem cota

não chama modelo

4/4

Contagem

a última linha

0️⃣

Saída 0

tudo passou

Quebre um critério de propósito

Um juiz que sempre diz "OK" não serve para nada. Antes de confiar no verificar, veja ele reprovar. Trabalhe numa cópia, para o goal de exemplo continuar intacto.

É o mesmo teste que o kit fez na prova da versão 0.2.0.

Crie a cópia

Crie meu-goal.md na raiz do kit com o mesmo conteúdo do goal-exemplo.md, pelo seu editor de texto ou pedindo ao agente.

Mude um valor esperado

Na cópia, troque o texto entre crases depois de uma seta. Por exemplo, o total da Sônia de R$ 856.00 para outro valor.

Rode o verificar na cópia

Use o comando do quadro abaixo, o mesmo que o prompt da R6 manda o agente rodar.

Desfaça a mudança

Volte o valor certo na cópia. Ela vira o ponto de partida do seu próprio goal.

🎯 Objetivo: ver o verificar reprovar

No terminal, na raiz do kit, depois de mudar um valor esperado em meu-goal.md:

node runtime/scripts/verificar.mjs meu-goal.md

Resultado provado no CHANGELOG 0.2.0:

com um valor esperado errado: FALHA, saída 1

Como verificar: a linha do critério que você mudou começa com FALHA em vez de OK. Pelo código do script, logo abaixo dela vêm o texto esperado: e as últimas linhas da saída real, para você comparar.

Como ler o desenho: o desenho se repete para cada linha do goal. A caixa roxa é a regra inteira do script. Basta uma linha cair à direita, embaixo, para o número de saída virar 1, e é esse número que o agente lê para saber se pode parar.

📑

Cópia

meu-goal.md

✏️

Um valor

trocado de propósito

❌

FALHA

com esperado e saída

1️⃣

Saída 1

o agente não para

Rode o agente até passar

Com o goal escrito e o verificar testado, entregue a tarefa ao agente. O pedido da R6 diz três coisas: cumpra o goal, rode o verificar depois de cada etapa e só pare com tudo OK ou num portão humano.

Funciona no Claude Code e no Codex, porque o juiz é o mesmo script para os dois.

🆕 Novo aqui? O que é `/goal`

Palavras que começam com barra, digitadas dentro da sessão, são comandos do agente. O /goal entrega ao agente um objetivo para perseguir até o fim, em várias etapas, em vez de uma resposta só.

🎯 Objetivo: deixar o agente trabalhar até a prova passar

Abra claude (ou codex) na pasta do kit e cole:

/goal Cumpra o goal em meu-goal.md. Depois de cada etapa rode node runtime/scripts/verificar.mjs meu-goal.md. Só pare com todos OK ou num portão humano do goal.

Como verificar: quando o agente disser que acabou, rode o verificar por conta própria no meu-goal.md. A última linha tem de mostrar todos os critérios OK. Se não mostrar, não acabou.

O agente faz uma etapa

Cria, corrige ou ajusta o que o goal pede.

Roda o verificar

Lê as linhas OK e FALHA e o número de saída.

Saída 1: volta ao passo 1

A linha FALHA diz o que faltou, com o esperado e a saída real.

Saída 0 ou portão: para

Terminou de verdade, ou chegou a um ponto em que só você decide.

💡 Sem tela, por horas

Em Linux, para rodar sem tela, com tempo e memória limitados, o kit aponta o método completo de execução longa: github.com/inematds/execucao-longa. Comece pelo pedido acima, com você olhando.

🎯

/goal

objetivo até o fim

🔁

Laço

faz, verifica, corrige

🤝

Claude ou Codex

o mesmo juiz

🔎

Você confere

a última rodada

Coloque portões humanos e anote falhas

Agente que roda por horas não pode decidir sozinho o que é irreversível. A R6 pede portões humanos escritos no próprio goal, em quatro tipos de ação: gasto, envio, apagar e publicar.

E pede um hábito: quando algo quebrar, uma linha no FALHAS.md; quando o ambiente barrar, uma linha no LIMITES.md.

Portão no goal	Teto na POLITICA	Exemplo
Gasto	N1: prepara, você executa	assinar um serviço novo
Envio	N2: pede a cada vez	Clara mandar a confirmação ao paciente
Apagar	N1 + backup	limpar exportações antigas do ERP
Publicar	N2 (é um envio: push, post)	Sônia publicar o relatório para o cliente

O que olhar na tabela: nenhum portão passa de N2. Num goal longo, escreva a frase do portão no lugar exato da etapa, por exemplo "antes de enviar, pare e me pergunte".

📄 runtime/FALHAS.md — a linha real do kit

| data | o que quebrou | menor correção | prompt \| infra |
|---|---|---|---|
| 2026-10-05 | `doctor.mjs` dizia "codex sem login" com o Codex logado | ler stdout **e** stderr (`codex login status` responde no stderr) | infra |

Repare: uma linha, sem narrativa. A "menor correção" foi uma proteção pequena, não uma reescrita. Depois de umas dez linhas, o padrão aparece sozinho.

⚠️ Portão que não está escrito não existe

Se o goal não diz "pare antes de enviar", um agente perseguindo o OK pode tratar o envio como mais uma etapa. Antes de soltar um goal longo, leia procurando gasto, envio, apagar e publicar. Cada um precisa da sua frase de parada.

Teste rápido (opcional): qual destas linhas é um critério que o verificar.mjs aceita?

💸

Gasto

📤

Envio

🗑️

Apagar

N1 + backup

📝

FALHAS · LIMITES

uma linha cada

🎓 Resumo do módulo

✓

Pronto é prova, não palpite — quem decide é o verificar.mjs.

✓

Critério = comando → saída — sim ou não, impossível passar sem o trabalho.

✓

O goal de exemplo dá 4/4 — e um valor trocado dá FALHA e saída 1.

✓

/goal com o verificar em cada etapa — no Claude Code ou no Codex.

✓

Portões escritos e falhas anotadas — gasto, envio, apagar, publicar; uma linha por falha.

Próxima trilha:

Trilha 4 — Governar e aprender (começa no 4.1, Política de autonomia)

← Voltar para a trilha Próxima trilha: Governar e aprender →