Subagents

A3S Code supports delegating work to child agents — independent agent instances that run their own tool loops and return results to the parent. Three built-in tools handle delegation:

All delegation tools are built-in and always available — no plugin mounting required.

task — Single Subagent

Delegates a prompt to one child agent. The child runs in its own session with its own conversation history; it does not inherit the parent's history.

{
  "agent": "general",
  "prompt": "Write unit tests for src/auth.rs covering all edge cases",
  "workspace": "/optional/override"
}

Example

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

const agent = await Agent.create('agent.hcl');
const session = agent.session('.');

// The LLM can call task() to delegate focused work
const result = await session.send(
  'Use the task tool to write unit tests for the auth module'
);
console.log(result.text);

from a3s_code import Agent

agent = Agent.create("agent.hcl")
session = agent.session(".")

result = session.send(
    "Use the task tool to write unit tests for the auth module"
)
print(result.text)

parallel_task — Concurrent Subagents

Runs multiple tasks concurrently, each with its own agent instance. Results are collected and returned together.

{
  "tasks": [
    { "agent": "general", "prompt": "Audit src/auth.rs for security issues" },
    { "agent": "general", "prompt": "Audit src/db.rs for SQL injection risks" },
    { "agent": "general", "prompt": "Audit src/api.rs for input validation gaps" }
  ]
}

run_team — Lead → Worker → Reviewer

Coordinates a three-role team for goals that require decomposition, parallel execution, and quality review:

1. Lead — Breaks the goal into a task list
2. Workers — Claim and execute tasks in parallel
3. Reviewer — Approves or rejects each result

{
  "goal": "Audit the authentication module for security issues",
  "lead_agent": "general",
  "worker_agent": "general",
  "reviewer_agent": "general",
  "max_steps": 10
}

Choosing the Right Tool

Subagent Isolation

Each subagent runs in an isolated session:

• Separate conversation history — Child does not see parent's messages
• Same workspace by default — File changes made by the child are visible to the parent
• Workspace override — Pass a different workspace to isolate file writes
• Same config — Child inherits the same agent.hcl and model settings

Orchestrating Subagents (Rust API)

For advanced control over running agents, use AgentOrchestrator:

use a3s_code_core::orchestrator::AgentOrchestrator;

let orchestrator = AgentOrchestrator::new();

// Pause / resume / cancel running subagents
orchestrator.pause_agent(&agent_id).await?;
orchestrator.resume_agent(&agent_id).await?;
orchestrator.cancel_agent(&agent_id).await?;

// Inject a prompt mid-execution
orchestrator.inject_prompt(&agent_id, "Stop and summarize what you've done so far").await?;

See Orchestrator for the full API.