🏗️ Workflows Deterministicos com Archon

Archon e o "harness builder" criado por Cole Medin. Ele permite construir workflows que orquestram multiplas sessoes de coding agent para tarefas maiores. A diferenca fundamental para o loop puro: voce define o processo, nao o agente. No loop puro, o agente decide como progredir. No Archon, voce determina os steps e o agente executa dentro de cada um.

Cole Medin explica a motivacao direta: "Archon is my harness builder, allows us to build workflows that orchestrate many coding agent sessions to handle larger tasks." A ideia e que um workflow como "fix GitHub issue" nao precisa de um agente decidindo como resolver. O processo e conhecido: extrair contexto, classificar, pesquisar, implementar, validar, criar PR.

O workflow mais classico do Archon e o "Fix GitHub Issue". Cole Medin usa isso no dia a dia: "Most of the input for my day-to-day work is issues in a repo. Either I'll create them or someone else will." O workflow segue uma sequencia fixa de steps, cada um com um papel especifico.

O ponto chave: "We're not having the agent drive the entire thing. It's more deterministic because we set up the process in this workflow file." Voce define os steps, o Archon garante que eles executam na ordem certa, e cada step roda numa sessao isolada com o modelo ideal para aquela tarefa.

O principio fundamental do Archon e contra-intuitivo: quanto menos o agente decide, melhor o resultado. Cole Medin deixa isso explicito: "We want to actually take the decision away from the coding agent as much as we can, only applying the reasoning of the LLM when we actually need it to write the code."

// Step deterministico: nao precisa de LLM
async function extractIssueNumber(input: string): Promise<number> {
  const match = input.match(/issues\/(\d+)/);
  if (!match) throw new Error("Invalid issue URL");
  return parseInt(match[1], 10);
}

// Step deterministico: API call pura
async function fetchIssueContext(owner: string, repo: string, num: number) {
  const res = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/issues/${num}`,
    { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
  );
  return res.json();
}

// Step LLM: aqui sim o agente precisa raciocinar
async function classifyIssue(context: IssueContext): Promise<"bug" | "feature"> {
  // Roda num modelo barato (Haiku, Kimi K2.7)
  const response = await llm.complete({
    model: "haiku",
    prompt: `Classify this GitHub issue as "bug" or "feature":\n${context.title}\n${context.body}`
  });
  return response.trim() as "bug" | "feature";
}

Um dos maiores problemas do loop puro com /loop ou /routines: "You're just using one model for pretty much everything. That's part of the problem of why it's so expensive." No Archon, cada node do workflow pode usar um modelo diferente, otimizando custo sem perder qualidade.

Cole Medin demonstra na pratica: "We can use Cloud Code for the implementation. And then we can use Codex for the review. And then for all of our context loading and exploration up front, we can use a smaller model like Kimi K 2.7." Isso e model routing aplicado a workflows de agentes.

Uma das maiores fraquezas do loop basico: se o terminal fecha, voce perde tudo. Archon resolve isso guardando todo o estado num banco externo. "All of the loops that we run and the different events and logs, I'm storing this here so we can always resume a workflow later on."

-- Cada run tem um ID e estado persistente
CREATE TABLE workflow_runs (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  workflow_id TEXT NOT NULL,
  status      TEXT DEFAULT 'running', -- running | paused | completed | failed
  input       JSONB NOT NULL,
  state       JSONB DEFAULT '{}',
  created_at  TIMESTAMPTZ DEFAULT now(),
  updated_at  TIMESTAMPTZ DEFAULT now()
);

-- Cada step registra sua execucao
CREATE TABLE step_executions (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  run_id      UUID REFERENCES workflow_runs(id),
  step_name   TEXT NOT NULL,
  status      TEXT DEFAULT 'pending', -- pending | running | completed | failed
  input       JSONB,
  output      JSONB,
  model_used  TEXT,
  tokens_used INTEGER DEFAULT 0,
  started_at  TIMESTAMPTZ,
  finished_at TIMESTAMPTZ
);

-- Logs de conversacao para replay
CREATE TABLE conversation_logs (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  run_id      UUID REFERENCES workflow_runs(id),
  step_name   TEXT NOT NULL,
  role        TEXT NOT NULL, -- system | user | assistant
  content     TEXT NOT NULL,
  created_at  TIMESTAMPTZ DEFAULT now()
);

Cole Medin enfatiza: "I have all my conversations, the code bases that I'm operating on with Archon, everything is durable and it's super easy to resume any work that I'm doing." Com o estado num banco Postgres (Neon), voce pode: retomar workflows apos crash, ver o historico completo de cada run, e auditar decisoes do agente.

Archon resolve muitos problemas do loop puro, mas introduz sua propria complexidade. Vale a pena ser honesto sobre os trade-offs.