🏗️ Workflows deterministas con Archon

Archon es el «harness builder» creado por Cole Medin. Permite crear workflows que orquestan múltiples sesiones de coding agent para tareas más grandes. La diferencia fundamental con el loop puro: tú defines el proceso, no el agente. En el loop puro, el agente decide cómo avanzar. En Archon, tú determinas los steps y el agente ejecuta cada uno.

Cole Medin explica la motivación directa: "Archon es mi creador de harnesses; nos permite crear flujos de trabajo que coordinan muchas sesiones de agentes de programación para encargarse de tareas más grandes." La idea es que un workflow como "fix GitHub issue" no necesita un agente que decida cómo resolverlo. El proceso es conocido: extraer contexto, clasificar, investigar, implementar, validar, crear un PR.

El workflow más clásico de Archon es "Fix GitHub Issue". Cole Medin lo usa en su día a día: "La mayor parte de lo que necesito para mi trabajo diario son issues de un repo. Puedo crearlas yo o puede crearlas otra persona." El workflow sigue una secuencia fija de steps, cada uno con un papel específico.

El punto clave: "No dejamos que el agente dirija todo el proceso. Es más determinista porque configuramos el proceso en este archivo de workflow." Tú defines los steps, Archon garantiza que se ejecuten en el orden correcto y cada step se ejecuta en una sesión aislada con el modelo ideal para esa tarea.

El principio fundamental de Archon es contraintuitivo: cuanto menos decida el agente, mejor será el resultado. Cole Medin lo deja explícito: "Queremos quitarle al agente de programación la mayor cantidad posible de decisiones y aplicar el razonamiento del LLM solo cuando necesitemos que escriba código."

// 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";
}

Uno de los mayores problemas del loop puro con /loop o /routines: "Usas un solo modelo para prácticamente todo. Eso es parte del motivo por el que resulta tan caro." En Archon, cada node del workflow puede usar un modelo diferente, optimizando el costo sin perder calidad.

Cole Medin lo demuestra en la práctica: "Podemos usar Cloud Code para la implementación y Codex para la revisión. Luego, para cargar todo el contexto y explorar al principio, podemos usar un modelo más pequeño como Kimi K 2.7." Esto es el enrutamiento de modelos aplicado a flujos de trabajo de agentes.

Una de las mayores debilidades del loop básico: si la terminal se cierra, lo pierdes todo. Archon lo resuelve guardando todo el estado en una base de datos externa. "Estoy guardando aquí todos los loops que ejecutamos, los distintos eventos y los registros para que siempre podamos reanudar un flujo de trabajo más adelante."

-- 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: "Tengo todas mis conversaciones y las bases de código en las que trabajo con Archon; todo es persistente y es muy fácil reanudar cualquier trabajo que esté haciendo." Con el estado en una base de datos Postgres (Neon), puedes reanudar workflows después de una caída, ver el historial completo de cada ejecución y auditar las decisiones del agente.

Archon resuelve muchos problemas del loop puro, pero introduce su propia complejidad. Vale la pena ser honesto sobre las ventajas y desventajas.