Agentes no CI

O time atualiza o Spring Boot em toda a BoxOffice numa segunda-feira de manhã. Catorze serviços, catorze builds vermelhos: uma propriedade de configuração renomeada aqui, um método depreciado ali, um teste que dependia de um padrão antigo. Cada correção é pequena e tediosa; juntas, tomam dois dias de dois engenheiros. Um agente — um modelo que planeja, usa ferramentas, observa o resultado e tenta de novo — pode fazer a maior parte desse trabalho enquanto os engenheiros revisam. Se for mal projetado, ele também pode fazer push na main, vazar a chave de deploy, ficar uma hora em loop num teste flaky ou "consertar" um build vermelho apagando a asserção. Esta página trata do projeto que obtém o primeiro resultado e torna o segundo impossível.

O que os agentes fazem em um pipeline

O loop do agente — o modelo escolhe uma ferramenta, o harness a executa, o resultado volta para o contexto, repete — vira, no CI, um loop sobre o repositório e o build:

Todas as linhas terminam no mesmo lugar: uma proposta (uma branch, um PR em rascunho) que verificações determinísticas e um humano aprovam. Esse é o nível 3 do espectro de autonomia. O nível 4 — aplicar mudanças sem aprovação a cada mudança — fica reservado para mudanças que são ao mesmo tempo de baixo risco e totalmente verificáveis, e raramente precisa de um modelo.

Anatomia de um agente que conserta o build

sequenceDiagram
    autonumber
    participant CI as Execução de CI
    participant Orch as Workflow (determinístico)
    participant Agent as Loop do agente (sandbox)
    participant Model as Modelo
    participant Repo as Host Git
    CI-->>Orch: execução falhou (evento)
    Orch->>Orch: dedup pelo SHA do commit, verifica que a branch não é ai-fix/*
    Orch->>Agent: log da falha + checkout (sem token de escrita)
    loop no máximo N turnos, M dólares
        Agent->>Model: contexto + resultados das ferramentas
        Model-->>Agent: chamada de ferramenta (ler / editar / rodar build)
        Agent->>Agent: executa ferramenta permitida, registra
    end
    Agent-->>Orch: diff da árvore de trabalho + transcrição
    Orch->>Orch: verifica: caminhos permitidos, nenhum teste removido, build verde
    Orch->>Repo: job separado com token de escrita: branch + PR em rascunho
    Repo-->>Orch: humano revisa, CI roda, merge ou fechamento

Leia como dois programas. O agente é não determinístico e não confiável: pode estar errado, confuso ou ser manipulado por texto no log. O orquestrador em volta dele — gatilhos, dedup, verificação, o job do PR — é código determinístico comum, revisado como qualquer outro. Toda a segurança mora no orquestrador.

Rodando agentes headless

Agentes no CI rodam headless: sem terminal, sem um humano para responder "posso rodar este comando?". Toda decisão que uma pessoa tomaria interativamente precisa ser tomada de antemão, como configuração.

gh run view "$RUN_ID" --log-failed | tail -n 300 | \
claude --bare -p "The CI build failed; the log is on stdin. Fix the root cause with the smallest change. Never delete or weaken a test." \
  --allowedTools "Read,Edit,Write,Bash(mvn -B *)" \
  --permission-mode dontAsk \
  --max-turns 25 --max-budget-usd 1.50 \
  --output-format stream-json --verbose > transcript.jsonl

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

for step in range(MAX_STEPS):
    reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
    msg = reply.choices[0].message
    messages.append(msg.model_dump(exclude_none=True))
    if not msg.tool_calls:
        break
    for call in msg.tool_calls:
        result = run_allow_listed(call.function.name, json.loads(call.function.arguments))
        audit(step, call, result)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

Sandboxing

O agente executa o build, e o build executa o código do repositório: testes, plugins do Maven, scripts. Suponha que esse código — ou o texto que o agente lê — possa ser hostil, e contenha-o em camadas:

Nenhuma camada é perfeita. Uma lista de ferramentas permitidas com Bash(mvn *) ainda roda o que quer que os plugins Maven do projeto façam; a limpeza do ambiente não protege a chave da API do modelo mantida pelo próprio processo do agente. É por isso que a chave tem um limite de gasto, o job não tem token de escrita e a saída é verificada fora do agente.

Permissões: o token é o raio de impacto

O que quer que o modelo decida, ele nunca pode fazer mais do que suas credenciais permitem. Projete as credenciais primeiro:

• GITHUB_TOKEN com privilégio mínimo: declare permissions: em todo workflow; o job que roda o agente recebe contents: read (e actions: read para buscar os logs).
• Separe os jobs por privilégio: o job do agente produz um artefato de patch; um job pequeno com contents: write e pull-requests: write o aplica e abre um PR em rascunho. O job com acesso de escrita não roda modelo nem código não confiável.
• Nenhum segredo no contexto do agente: nunca cole segredos em prompts ou resultados de ferramentas; mantenha chaves de deploy, credenciais de nuvem e tokens de registry totalmente fora do job.
• Somente leitura por padrão: um agente que só diagnostica (explica a falha em um comentário) não precisa de acesso de escrita — comece por aí.
• Proteção de branch e rulesets: a main exige PRs, CI e uma aprovação humana; bots não podem contornar; mudanças em .github/workflows/ exigem um code owner.
• A aprovação humana é estrutural, não uma instrução no prompt: o agente não consegue fazer merge porque seu token não consegue.

jobs:
  fix:
    # Only failed runs, only branches of this repository, never our own fix branches.
    if: >-
      github.event.workflow_run.conclusion == 'failure' &&
      github.event.workflow_run.head_repository.full_name == github.repository &&
      !startsWith(github.event.workflow_run.head_branch, 'ai-fix/') &&
      !startsWith(github.event.workflow_run.head_branch, 'ai-tests/')
    runs-on: ubuntu-latest
    timeout-minutes: ${{ (vars.LLM_PROVIDER || 'ollama') == 'ollama' && 45 || 30 }}
    permissions:
      contents: read
      actions: read               # read the logs of the failed run
    outputs:
      fixed: ${{ steps.verify.outputs.fixed }}
  open-pr:                        # write access, but no model and no untrusted build here
    needs: fix
    if: needs.fix.outputs.fixed == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: write
      pull-requests: write

Orçamentos: turnos, tokens, dólares, minutos

Cada turno do agente reenvia o contexto inteiro — instruções, definições de ferramentas, o log, cada arquivo lido, cada resultado de ferramenta até ali. O contexto cresce a cada passo, então o total de tokens de entrada cresce aproximadamente de forma quadrática com o número de passos (Sistemas de IA — os números). O prompt caching lê o prefixo repetido por uma fração do preço, o que muda drasticamente a inclinação. Premissas ilustrativas: contexto inicial de 20.000 tokens (instruções, definições de ferramentas, log), 2.500 tokens adicionados por passo (resultado da ferramenta mais a saída do modelo), 400 tokens de saída por passo, preços de tabela de um modelo grande na data em que este texto foi escrito (US$ 4 de entrada, US$ 20 de saída, US$ 0,20 de leitura em cache por milhão de tokens):

Sem cache, 40 turnos custam mais de oito vezes o que custam 10 turnos (cerca de US$ 11 contra US$ 1,3); com cache, a curva é quase linear e cerca de oito vezes mais barata aos 40 turnos. De um jeito ou de outro, o orçamento precisa ser imposto pelo harness, e não pedido no prompt:

A razão que importa é dólares por correção mergeada, e não por execução: um agente que custa US$ 0,80 por execução, mas produz uma correção mergeável uma vez a cada quatro, custa US$ 3,20 por correção útil — compare isso com o tempo de engenheiro que ele economiza.

ROOT = Path.cwd().resolve()
MAX_STEPS = int(os.environ.get("AGENT_MAX_STEPS", "20"))
MAX_TOKENS = int(os.environ.get("AGENT_MAX_TOKENS", "400000"))   # input + output, whole run
MAX_USD = float(os.environ.get("AGENT_MAX_USD", "1.50"))
AUDIT = Path(os.environ.get("AGENT_AUDIT", "agent-audit.jsonl"))   # keep it outside the repo
def safe(path: str, write: bool = False) -> Path:
    p = (ROOT / path).resolve()
    if not p.is_relative_to(ROOT) or {".git", ".github"} & set(p.relative_to(ROOT).parts):
        raise PermissionError(f"{path}: outside the allowed area")
    if write and "src" not in p.relative_to(ROOT).parts:
        raise PermissionError(f"{path}: only files under services/<name>/src/ may be written")
    return p
        if done:
            break
        if usage.input_tokens + usage.output_tokens > MAX_TOKENS or usage.usd > MAX_USD:
            result = {"fixed": False, "explanation": f"stopped by budget after {step} steps"}
            break

Idempotência, retries e loops

Agentes são disparados por eventos, e eventos se repetem: uma execução de CI é reexecutada, dois pushes chegam no mesmo minuto, a própria branch do agente falha no CI. Os padrões de mensageria do curso se aplicam diretamente (Mensageria — semântica de entrega):

• Chave de idempotência: o SHA do commit que falhou. Uma proposta por SHA (branch ai-fix/<sha8>, grupo de concurrency no SHA). Reexecuções encontram a branch e param.
• Nada de autodisparo: nunca rode o agente nas próprias branches (ai-fix/*), e lembre que pushes feitos com o GITHUB_TOKEN não disparam novas execuções de workflow no GitHub — um disjuntor de loops embutido.
• Retries são para o transporte, não para a tarefa: os SDKs repetem 429/5xx com backoff. Reexecutar um agente que falhou é uma nova tentativa com um novo custo — torne isso uma decisão humana, ou no máximo um retry automático com uma estratégia diferente.
• Fail open para agentes consultivos: se o agente falhar, o build vermelho original continua lá; nada fica pior do que antes.

Auditoria: quem mudou o quê, e por quê

A mudança de um agente precisa ser explicável meses depois. Guarde:

É a mesma disciplina de qualquer mudança em produção, e ela alimenta a proveniência da cadeia de suprimentos do software: você consegue responder "que código do inventory foi escrito por um agente, e aprovado por quem?".

Agentes de dependências e de migração

Upgrades de dependências são, na prática, o workflow agêntico mais comum. Bots como o Renovate ou o Dependabot abrem o PR de upgrade de forma determinística; o trabalho do agente começa quando esse PR fica vermelho: ler o changelog e a falha, adaptar o código, manter a mudança mínima. Agrupe atualizações relacionadas (todos os artefatos do Spring juntos), deixe as atualizações de patch com CI verde fazerem merge automático sem IA e mande as versões major para um agente que propõe e um humano que aprova.

Migrações — JUnit 4 → 5, javax.* → jakarta.*, Java 17 → 21 — misturam uma grande parte mecânica com uma cauda longa de casos especiais. Use codemods determinísticos para a parte mecânica (receitas do OpenRewrite são a ferramenta padrão para Java) e o agente para as sobras que a receita não resolve. Divida a campanha em um PR por serviço, pequeno o bastante para revisar, atrás do CI e do canary normais. As mudanças em larga escala no Google seguiam o mesmo princípio muito antes dos LLMs: automatizar a mudança, fragmentá-la em pedaços revisáveis de forma independente e deixar os responsáveis revisarem cada pedaço¹.

Como se conecta

flowchart LR
    TRIG["red build event<br/>trigger + dedupe"] --> HARN["harness = orchestrator"]
    HARN --> SB["sandbox, tool allow-list,<br/>no write token"]
    HARN --> BUD["budgets: turns, tokens,<br/>dollars, minutes"]
    HARN --> LOOP["agent loop<br/>→ AI systems agents"]
    LOOP --> VER["verification<br/>outside the agent"]
    VER --> PRIV["separate privileged step<br/>opens a draft PR"]
    PRIV --> HUM["human review"]
    HARN --> IDEM["idempotency, retries, loops<br/>→ Messaging semantics"]
    HARN --> AUD["audit trail:<br/>who changed what, and why"]

Componentes da paleta: orchestrator (o harness que impõe orçamentos e permissões) · toolreg (a lista de ferramentas que o agente pode chamar) · llmgw (cotas e custo por execução) · safety (nenhum segredo ou token de escrita ao alcance do agente) · logs (a trilha de auditoria) · metrics (correções aceitas por proposta, custo por correção aceita). Cenários: ai-assistant com o perfil spike (centenas de agentes ao mesmo tempo disputam o gateway com o tráfego dos usuários). Continua em: Sistemas de IA — agentes, Mensageria — semântica (execuções pelo menos uma vez, efeitos idempotentes), Segurança e governança, Cloud-native — entrega, Hands-on 13 — agente de correção.