Phase 14 - Lesson 35

Scripts de Inicialização para Agentes

Toda sessão que começa do zero (cold start) paga uma taxa. O agente lê os mesmos arquivos, tenta as mesmas sondagens e redescobre os mesmos caminhos. Um script de inicialização paga essa taxa uma única vez e grava as respostas no estado.

Tipo: Build Linguagens: Python (stdlib) Pré-requisitos: Fase 14 · 32 (Minimal Workbench), Fase 14 · 34 (Repo Memory) Tempo: ~45 minutos

Objetivos de Aprendizado

  • Identificar o trabalho que um agente nunca deveria ter que refazer por sessão.
  • Construir um script de inicialização determinístico que sonda o ambiente de execução, dependências e a integridade do repositório.
  • Persistir o resultado da sondagem para que o agente o leia em vez de executar novamente as verificações.
  • Falhar de forma barulhenta (fail loud), rápida e com um único lugar para verificar quando a inicialização falhar.

O Problema

Abra uma sessão. O agente adivinha a versão do Python. Adivinha o comando de teste. Lista a raiz do repositório cinco vezes para encontrar o ponto de entrada. Tenta importar um pacote que não está instalado. Pergunta ao usuário onde fica o arquivo de configuração. No momento em que ele faz uma edição real, dez mil tokens foram gastos em um trabalho de configuração que deveria ter sido resolvido por um único script.

A solução é ter um único script de inicialização que seja executado antes que o agente faça qualquer outra coisa e grave um arquivo init_report.json que o agente lerá na inicialização.

O Conceito

flowchart TD
  Start[Início da Sessão] --> Init[init_agent.py]
  Init --> Probes[sondar runtime / deps / caminhos / env / testes]
  Probes --> Report[init_report.json]
  Report --> Decision{saudável?}
  Decision -- sim --> Agent[Loop do Agente]
  Decision -- não --> Halt[falhar barulhento, parar, alertar humano]

O que o script de inicialização sonda

Sondagem (Probe) Por que importa
Versões de runtime Versão incorreta do Python ou do Node significa bugs silenciosos de versão incorreta
Disponibilidade de dependências Um pacote ausente mais tarde custa dez vezes mais do que detectá-lo agora
Comando de teste O agente deve saber como verificar; se o comando estiver ausente, a bancada de trabalho está quebrada
Caminhos do repositório Caminhos fixos (hard-coded) sofrem desvios; resolva-os uma vez e fixe-os
Variáveis de ambiente A ausência de OPENAI_API_KEY é uma falha explícita, não um mistério em tempo de execução
Frescor do estado + quadro (board) Estado desatualizado de uma sessão corrompida é um risco desnecessário (footgun)
Commit de última integridade conhecida (LKG) Âncora para o diff de passagem (handoff) no final da sessão

Falhar de forma barulhenta, falhar rápido, falhar em um único lugar

Uma falha de sondagem significa interromper o processo e reportar ao ser humano. Sem essa de "o agente vai dar um jeito". Todo o objetivo da inicialização é recusar o início quando a bancada de trabalho estiver quebrada.

Idempotente

Execute-o duas vezes seguidas. A segunda execução deve ser uma operação sem efeito (no-op), exceto por um carimbo de data/hora (timestamp) atualizado. A idempotência é o que permite conectar o script ao CI, hooks ou a um comando de barra pré-tarefa.

Inicialização versus regras de inicialização

As regras (Fase 14 · 33) descrevem o que deve ser verdadeiro para agir. O init é o script que estabelece que essas regras podem ser verificadas. Regras sem init tornam-se apenas "tome cuidado". Init sem regras torna-se uma falha bem-acabada.

Construa

code/main.py implementa init_agent.py:

  • Cinco sondagens: versão do Python, dependências listadas via importlib.util.find_spec, resolubilidade do comando de teste, variáveis de ambiente obrigatórias e frescor do arquivo de estado.
  • Cada sondagem retorna (name, status, detail).
  • O script grava init_report.json com o conjunto completo de sondagens e encerra com código de saída diferente de zero se qualquer sondagem com severidade de bloqueio falhar.

Execute:

python3 code/main.py

O script imprime a tabela de sondagens, grava init_report.json e encerra com código zero no caminho feliz (happy path) ou diferente de zero com uma lista das sondagens que falharam.

Padrões de produção na prática

Três padrões separam um script de inicialização útil de uma mera formalidade.

Ancoragem no commit de última integridade conhecida (LKG). Sonda o commit atual em relação a um arquivo LKG gravado na última mesclagem (merge) bem-sucedida. Se o diff exceder um limite máximo (padrão de 50 arquivos), recusa-se a iniciar e exige que um humano ratifique a nova linha de base. É isso que o AI Code Review da Cloudflare usa para delimitar o escopo dos agentes revisores: cada sessão de revisão se ancora no mesmo commit de última integridade conhecida e nunca acumula desvios entre as sessões.

Arquivos de bloqueio (lock files) com TTL. Grava um arquivo prereqs.lock após a primeira passagem bem-sucedida de sondagem. As execuções subsequentes confiam no lock por N horas (padrão de 24h) e pulam as sondagens dispendiosas. O script de inicialização lê o lock primeiro; se ele estiver atualizado e o hash do manifesto de dependências corresponder, ele faz um atalho (short-circuit). Este é o mesmo padrão que o Docker usa para caches de camada: sondagem idempotente + hash de conteúdo = pular.

Sem rede, sem LLM, sem surpresas no caminho crítico. As sondagens de inicialização são encanamentos determinísticos. Uma sondagem que chama um LLM para classificar uma falha ou que acessa um serviço externo para verificar uma licença não é uma sondagem; é um fluxo de trabalho. Se uma sondagem demorar mais de três segundos em uma execução de teste (dry run), trate isso como um indício de problema (smell) na bancada de trabalho e mova-a para fora da inicialização ou armazene seu resultado em cache.

Como usar

Em produção:

  • Hooks do Claude Code. O hook pre-task chama o script de inicialização e se recusa a iniciar o agente se ele falhar.
  • GitHub Actions. Um job setup-agent executa o script de inicialização; o job do agente depende dele.
  • Docker entrypoint. O contêiner do agente executa o script de inicialização antes de executar o tempo de execução do agente; os logs são exibidos em caso de falha.

O script de inicialização é portátil porque não faz chamadas a um framework específico. Bash, Make ou um arquivo de tarefas podem envolvê-lo.

Envie

O arquivo outputs/skill-init-script.md analisa o projeto, classifica seu trabalho de configuração em sondagens e emite um init_agent.py específico para o projeto, além de um fluxo de trabalho de CI que o executa antes de qualquer etapa do agente.

Exercícios

  1. Adicione uma sondagem que compare o commit atual com o commit de última integridade conhecida e se recuse a iniciar se mais de 50 arquivos tiverem mudado.
  2. Configure o script para gravar um arquivo prereqs.lock e recusar a inicialização se o lock for mais antigo que sete dias.
  3. Adicione uma flag --fix que instala automaticamente dependências de desenvolvimento ausentes, mas nunca modifica dependências de runtime sem aprovação.
  4. Mova as sondagens de funções fixas (hardcoded) para um registro YAML. Defenda os prós e contras.
  5. Adicione um orçamento de tempo por sondagem. Uma sondagem que roda por mais de três segundos é um indício de problema (smell) na bancada de trabalho.

Termos-Chave

Termo O que as pessoas dizem O que realmente significa
Sondagem (Probe) "Uma verificação" Uma função determinística que retorna (name, status, detail)
Relatório de init "Resultado da configuração" JSON gravado junto ao estado com os resultados das sondagens
Idempotente "Seguro para reexecutar" Duas execuções seguidas produzem relatórios idênticos, exceto pelo timestamp
Falhar de forma barulhenta (Fail loud) "Não oculte o erro" Parar e reportar ao ser humano; sem plano de contingência silencioso
Taxa de configuração (Setup tax) "Custo de inicialização" Os tokens que o agente gasta por sessão redescobrindo o óbvio

Leituras Adicionais

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).