#Tasks

The routine multi-agent path is one model-visible task tool. Its tasks array accepts one focused child or several independent children for concurrent fan-out. Child context stays isolated from the parent conversation, and only compact results return instead of full transcripts.

The same delegation core also powers automatic subagent delegation. Enable it when the runtime should proactively start specialist child agents for high-confidence work, and disable only automatic parallel fan-out with autoParallel: false when you want serial automatic delegation.

Web clients can present these states as a plan and a separate list of child-agent runs, keyed by task ID.

#Built-in Subagents

You can mention them explicitly, for example @review, @agent-plan, use the verification subagent, or delegate to general-purpose.

#Manual Delegation

Ask the parent agent to delegate a bounded job:

Use task to ask an explore agent to inspect the auth module.
Return files inspected, findings, risks, and confidence.

If the host already knows the task boundary, call the same core tool directly:

const task = await session.task({
  agent: 'explore',
  description: 'Inspect auth module',
  prompt: 'Return files inspected, findings, risks, and confidence.',
});
if (task.exitCode !== 0) throw new Error(task.output);
console.log(task.output);

A child agent should return a compact contract:

• summary
• files inspected or changed
• evidence references
• risks and unknowns
• confidence

The parent should not ingest the full child transcript.

#Parallel Delegation

Use task with several tasks items, or session.tasks(...), when independent work can run concurrently:

Run one task call with three independent tasks:
1. inspect provider config parsing
2. inspect Node SDK declarations
3. inspect release scripts

Merge the results into one release-readiness report.

const batch = await session.tasks([
  {
    agent: 'explore',
    description: 'Inspect config',
    prompt: 'Check provider parsing.',
  },
  {
    agent: 'verification',
    description: 'Verify SDK',
    prompt: 'Check SDK declarations.',
  },
]);
if (batch.exitCode !== 0) throw new Error(batch.output);
console.log(batch.output);

The unified task call accepts 1-32 items. A single item may request background; a multi-item call collects every branch and therefore rejects background: true. By default every branch must succeed. Set allow_partial_failure only for evidence-gathering work that can use incomplete results; min_success_count is available only in that mode and must not exceed the submitted task count.

session.task(...) and session.tasks(...) return ToolResult values from the same task tool. Read output for the compact child summary and check exitCode before treating the result as successful. maxParallelTasks in session options and max_parallel_tasks in ACL bound sibling fan-out.

Prefer task / session.tasks for all fan-out. Model-visible and SDK parallel_task / parallelTask helpers are removed (HARNESS-CONV4). Use multi-item task only.

#Agent-Wide Priority Scheduler

Every Agent owns one scheduler shared by all sessions created from it. The scheduler limits how many independent operations may execute at once and chooses which queued operation receives the next slot. It is backed by the a3s-lane priority queue and is enabled without extra setup.

This is an admission boundary, not a preemptive executor: work that already owns a slot continues until it completes or is cancelled. Priority determines which pending operation starts when a slot becomes available.

#What shares the boundary

The same max_active capacity covers:

• conversation runs started with send, run, or stream
• trusted or governed direct-tool calls made by the host
• detached background children
• workflows started by the host

This prevents several sessions from each consuming an independent concurrency budget. A busy background session cannot bypass interactive work by entering through a different execution API.

Three nearby controls solve different problems:

A session's single-flight rule is separate too: two transcript-changing calls on the same session fail fast instead of waiting in this scheduler.

#Configure capacity and aging

task_scheduler {
  max_active = 4
  aging_interval_ms = 30000
}

Both values must be greater than zero. Defaults are four active operations and a 30-second aging interval.

#Choose a priority

Lower classes run after higher classes. Equal effective priorities remain FIFO. Every full aging_interval_ms promotes waiting non-urgent work by one level, capped at interactive, so continuous user traffic cannot permanently starve background or maintenance work. urgent remains reserved above aged work.

Set the priority when creating a session:

use a3s_code_core::{SessionOptions, TaskPriority};

let options = SessionOptions::new()
    .with_task_priority(TaskPriority::Background);
let session = agent
    .session_builder("/repo")
    .options(options)
    .build()
    .await?;

const session = await agent.sessionAsync('/repo', {
  taskPriority: 'background',
});

from a3s_code import SessionOptions

options = SessionOptions()
options.task_priority = "background"
session = agent.session("/repo", options)

session, err := agent.Session(ctx, "/repo", &code.SessionOptions{
	TaskPriority: code.TaskPriorityBackground,
})

Accepted names are urgent, interactive, foreground, background, and maintenance. Invalid names fail session-option validation.

#Observe occupancy

Hosts can read the same point-in-time snapshot through either the Agent or one of its sessions:

let stats = agent.task_scheduler_stats().await?;
let same_scheduler = session.task_scheduler_stats().await?;
println!("active={} pending={}", stats.active, stats.pending);

const stats = await agent.taskSchedulerStats();
const sameScheduler = await session.taskSchedulerStats();
console.log(stats.active, stats.pendingByPriority.background);

stats = agent.task_scheduler_stats()
same_scheduler = session.task_scheduler_stats()
print(stats["active"], stats["pendingByPriority"]["background"])

stats, err := agent.TaskSchedulerStats(ctx)
sameScheduler, err := session.TaskSchedulerStats(ctx)
fmt.Println(stats.Active, stats.PendingByPriority.Background)

Rust exposes snake-case struct fields; Node.js and the Python dictionaries use the camel-case wire names; Go exposes exported struct fields. The snapshot is diagnostic state, not a reservation—values can change immediately after it is read.

#Cancellation and shutdown

Cancellation removes pending work before it can acquire a slot. Cancelling an active operation releases its slot when that operation settles. Closing the Agent rejects queued and new admissions, then waits for already-admitted work to finish before scheduler shutdown completes.

#Automatic Delegation

Automatic delegation is opt-in. The runtime scores the current request against built-in and custom agent descriptions, then launches up to maxTasks child runs when confidence is high enough.

const session = agent.session('/repo', {
  autoDelegation: { enabled: true, minConfidence: 0.72, maxTasks: 4 },
  maxParallelTasks: 8,
  autoParallel: false,
});

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

autoParallel: false / auto_parallel = false is the global kill switch for automatic parallel child-agent fan-out. Manual task fan-out and session.tasks(...) remain available.

#Agent Directories

Load custom agent definitions through agentDirs, agent_dirs, or the built-in A3S directories:

const session = agent.session('/repo', { agentDirs: ['./.a3s/agents'] });
const loaded = session.registerAgentDir('./more-agents');

A3S scans configured agent_dirs, project/user .a3s/agents, and Claude-compatible .claude/agents migration paths. Prefer .a3s/agents for new projects.

Markdown agent files support frontmatter:

---
name: docs-auditor
description: Use proactively after documentation changes
tools: Read, Grep, Glob
disallowedTools:
  - Write
  - Bash(rm:*)
---

Audit docs for drift, broken examples, and unclear migration notes.

The tools field is an allowlist. disallowedTools is a denylist and wins over allowed tools. Model routing fields are intentionally outside this compatibility layer.

#Worker Agents

Register disposable worker agents with workerAgents or registerWorkerAgent():

const session = agent.session('/repo', {
  workerAgents: [
    {
      name: 'frontend-worker',
      description: 'Small verified frontend fixes',
      kind: 'implementer',
      model: 'provider/model-id',
      maxSteps: 24,
      confirmationInheritance: 'auto_approve',
    },
  ],
});

#Confirmation Inheritance

Control how child runs resolve Ask decisions with confirmationInheritance:

• 'auto_approve' (default): child runs auto-approve all Ask decisions
• 'deny_on_ask': child runs fail immediately when encountering an Ask
• 'inherit_parent': child runs inherit the parent's confirmation policy

Legacy lifecycle control-plane APIs are removed. Applications that need UI state should consume streaming events, run replay, and Node cancelRun(runId).

#Programmable orchestration

Everything on this page is model-driven: task, session.task(...) / session.tasks(...), and auto-delegation let the LLM decide when and how to fan out. When the host already knows the shape of the work and wants it to be deterministic and reproducible, express it programmatically instead with session.parallel(...), session.pipeline(...), and session.parallelResumable(...). See Orchestration for developer-expressed fan-out, barrier-free pipelines, and resumable/migratable workflows.