Sub-Agent Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Sub-Agent Orchestration is a multi-agent capability within the Autohand CLI that allows a primary "Lead Agent" to delegate tasks to specialized sub-agents. These sub-agents run in parallel (up to a concurrency limit of 5) to perform distinct workstreams such as research, testing, or code implementation. The orchestration logic enables complex workflows including sequential chaining, fan-out/fan-in patterns, and iterative loops.
Sources: prd/sub_agents_architecture.md:5-10, prd/sub-agents-orchestration.md:5-10
Architecture Overview
The orchestration system is composed of several key components that manage the lifecycle, registration, and execution of sub-agents.
Component Breakdown
| Component | Responsibility |
|---|---|
AgentRegistry | Singleton service that scans directories, validates, and loads agent configurations from JSON or Markdown. |
AutohandAgent | The main orchestrator/Lead Agent that initiates delegation via specialized tools. |
SubAgent | A lightweight agent instance with scoped context and a restricted toolset derived from its definition. |
AgentDelegator | Logic responsible for instantiating sub-agents and managing synchronous or parallel execution. |
Sources: prd/sub_agents_architecture.md:27-45, src/core/agents/SubAgent.ts:47-52, src/core/agent.ts:153-165
High-Level Orchestration Flow
The following diagram illustrates how the Lead Agent interacts with the registry to spawn and manage sub-agents.
Agent Definitions and Registry
Agents are defined as JSON or Markdown files located in the user's config directory (~/.autohand-cli/agents/).
Agent Configuration
A sub-agent definition includes a description, a specific system prompt (persona), a subset of available tools, and an optional model override.
{
"description": "Expert at searching the codebase.",
"systemPrompt": "You are a research assistant...",
"tools": ["search_codebase", "read_file"],
"model": "gpt-4"
}
Sources: prd/sub_agents_architecture.md:15-25, src/core/agents/AgentRegistry.ts:16-21
The Registry Pattern
The AgentRegistry class handles the discovery of these definitions from multiple sources, including built-in, user-defined, and external paths.
Delegation Mechanisms
The Lead Agent utilizes two primary tools to orchestrate sub-agents: delegate_task and delegate_parallel.
1. Synchronous Delegation (delegate_task)
Used for sequential workflows where the output of one agent is required for the next step. The Lead Agent waits for the sub-agent to return a final result string.
Sources: prd/sub_agents_architecture.md:50-53, src/core/agent.ts:192-195
2. Parallel Delegation (delegate_parallel)
Enables the Lead Agent to spawn up to 5 agents concurrently. This is used for independent tasks, such as researching multiple topics or generating tests for different modules simultaneously.
Sources: prd/sub_agents_architecture.md:54-56, src/core/agent.ts:195-197
Execution Sequence
The following sequence diagram shows the lifecycle of a delegated task.
Safety and Constraints
To prevent resource exhaustion and infinite loops, the orchestration system enforces several strict constraints:
- Concurrency Limit: A hard limit of 5 parallel sub-agents is enforced by the
delegate_paralleltool. - Recursion Depth: Sub-agents have a maximum delegation depth (defaulted to 3) to prevent infinite loops where agents spawn further agents.
- Context Scoping: Sub-agents start with a fresh context containing only the delegated task. They do not inherit the full Lead Agent history to optimize token usage.
- Tool Restriction: Sub-agents can only access the subset of tools explicitly defined in their configuration file.
Sources: prd/sub_agents_architecture.md:73-81, src/core/agents/SubAgent.ts:25-30, src/core/agents/SubAgent.ts:60-75
Management Commands
The CLI provides built-in commands for managing the agent ecosystem.
| Command | Module | Description |
|---|---|---|
/agents | src/commands/agents.ts | Lists all agents found in the registry, showing their name, description, path, and available tools. |
/agents new | src/commands/agents-new.ts | An interactive wizard that uses an LLM to generate a new sub-agent Markdown definition based on a user description. |
Sources: src/commands/agents.ts:13-18, src/commands/agents-new.ts:14-19
Project Integration (AGENTS.md)
The system includes an AgentsMdUpdater that automatically maintains an AGENTS.md file in the project workspace. This file serves as a persistent project "autopilot" instruction set, capturing the tech stack, common commands, and conventions discovered during agent sessions.
Sources: src/core/AgentsMdUpdater.ts:20-35, tests/agentsMdUpdater.spec.ts:27-35
Sub-Agent Orchestration transforms the CLI from a single-task assistant into a collaborative platform capable of handling complex, multi-faceted software engineering projects through parallel specialization and structured delegation.