Use A3S Code task delegation, .a3s/agents, automatic subagents, and run inspection from the Node SDK.

Build a Multi-Agent Review Flow

This tutorial builds a review flow from the current A3S Code Node SDK: one parent session delegates focused work, gathers compact child results, and uses run replay for inspection.

This tutorial covers model-driven delegation — the LLM decides what to delegate via task / tasks / auto-delegation. For developer-authored, deterministic steps (parallel / pipeline / parallelResumable), see Programmable Orchestration.

The snippets below use these Node SDK entry points: Agent.create, agent.session, session.registerAgentDir, session.task, session.tasks, session.runs, and session.runEvents.

What Changed

Routine multi-agent work is driven through task delegation from a normal session. It can also launch automatic subagents when autoDelegation is enabled. Child runs return compact results instead of pushing full transcripts back into the parent prompt.

review goal
  -> lead session
  -> task / tasks / automatic subagents
  -> child summaries
  -> run replay and verification evidence

Agent Config

Use ACL, not legacy HCL:

default_model = "openai/docs-model"
max_parallel_tasks = 4
auto_parallel = false

providers "openai" {
  apiKey = env("A3S_OPENAI_API_KEY")
  baseUrl = env("A3S_OPENAI_BASE_URL")

  models "docs-model" {
    name = "Docs Model"
    tool_call = true
  }
}

auto_delegation {
  enabled        = true
  auto_parallel  = false
  min_confidence = 0.72
  max_tasks      = 3
}

Optional Role Files

registerAgentDir() loads role definitions from a directory. For durable project roles, prefer .a3s/agents.

.a3s/agents/
  release-reviewer.yaml

name: release-reviewer
description: Reviews release blockers and separates required fixes from follow-up work.
prompt: |
  Inspect the requested scope. Report blockers first, then risks, then optional improvements.

Coordinator

import { Agent } from '@a3s-lab/code';
import path from 'node:path';

const agent = await Agent.create('agent.acl');
const session = agent.session(process.cwd(), {
  builtinSkills: true,
  planningMode: 'auto',
  autoDelegation: { enabled: true, maxTasks: 3 },
  autoParallel: false,
});

const registered = session.registerAgentDir(path.join(process.cwd(), '.a3s/agents'));
console.log({ registered });

const summary = await session.task({
  agent: 'general',
  description: 'Review auth release blockers',
  prompt: 'Review src/auth for release blockers. Focus on token validation and error handling.',
  maxSteps: 4,
});

const parallel = await session.tasks([
  {
    agent: 'general',
    description: 'Auth security review',
    prompt: 'Review src/auth for security risks.',
    maxSteps: 3,
  },
  {
    agent: 'general',
    description: 'Auth test review',
    prompt: 'Review src/auth tests for missing edge cases.',
    maxSteps: 3,
  },
]);

const final = await session.send(`
Merge these child review results into a findings-first release note.

Single review:
${summary.output}

Parallel reviews:
${parallel.output}
`);

console.log(final.text);
console.log(final.verificationSummaryText);
console.log(await session.runs());

Inspect the Run

Use replay APIs for run evidence:

const runs = await session.runs();
for (const run of runs) {
  console.log(run.id, run.status);
  console.log(await session.runEvents(run.id));
}

currentRun() may be null when the session is idle. Use runs() for completed history and inspect a run's status before attempting cancellation.

Production Boundary

Direct host calls such as session.bash(), session.tool(), and session.git() are privileged host operations. Gate them in your application before exposing this flow to untrusted users.