Skip to main content

Multi-Agent Delegation (ACP)

DotAgents supports multi-agent orchestration through the Agent Client Protocol (ACP). Your main agent can delegate tasks to specialized sub-agents — each running as a separate process with its own capabilities.

How Delegation Works​

User: "Review the code in my latest PR and fix any issues"
    │
    ▼
Main Agent (internal)
    │
    ├── Sees available agents: Code Reviewer, Bug Fixer
    │
    ├── Delegates review to Code Reviewer
    │   │
    │   ▼
    │   Code Reviewer Agent (ACP)
    │   ├── Reads PR changes via GitHub MCP
    │   ├── Analyzes code quality
    │   └── Returns findings
    │
    ├── Delegates fixes to Bug Fixer with findings
    │   │
    │   ▼
    │   Bug Fixer Agent (ACP)
    │   ├── Reads flagged files
    │   ├── Applies fixes
    │   └── Returns result
    │
    └── Summarizes results to user

Setting Up Delegation​

1. Create a Delegation-Target Agent​

First, create an agent that can receive delegated tasks:

---
id: code-reviewer
name: code-reviewer
displayName: Code Reviewer
description: Reviews code for bugs, security issues, and best practices
enabled: true
role: delegation-target
connection-type: internal
---

You are a meticulous code reviewer...

Key: set role: delegation-target so the main agent knows this agent is available for delegation.

2. Configure the Connection​

Set the connection type in the agent's agent.md frontmatter. Put command details, environment variables, working directory, or remote URL in config.json.

Internal Agent (uses DotAgents' LLM)​

---
id: code-reviewer
name: code-reviewer
displayName: Code Reviewer
description: Reviews code for bugs, security issues, and best practices
enabled: true
role: delegation-target
connection-type: internal
---

You are a meticulous code reviewer...

Claude Code via acpx​

---
id: claude-reviewer
name: claude-reviewer
displayName: Claude Reviewer
description: Reviews code through Claude Code
enabled: true
role: delegation-target
connection-type: acpx
---

You are a meticulous code reviewer...
{
  "connection": {
    "agent": "claude-code"
  }
}

Custom acpx Adapter​

This example assumes the agent's agent.md has connection-type: acpx.

{
  "connection": {
    "command": "python",
    "args": ["my_agent.py", "--acp"],
    "cwd": "/path/to/agent",
    "env": {
      "AGENT_CONFIG": "production"
    }
  }
}

3. Enable Delegation on the Main Agent​

Ensure the main agent has access to the delegation runtime tools:

{
  "toolConfig": {
    "enabledRuntimeTools": [
      "set_session_title",
      "execute_command",
      "read_more_context",
      "mark_work_complete",
      "delegate_to_agent",
      "check_agent_status",
      "respond_to_user"
    ]
  }
}

The ACP Protocol​

Communication​

ACP uses JSON-RPC 2.0 for agent-to-agent communication. DotAgents routes local external agents through acpx:

Main Agent                    Sub-Agent
    │                             │
    ├── runs/create ────────────► │
    │                             ├── processes task
    │  ◄──── permission request ──┤
    ├── permission grant ────────►│
    │                             ├── continues
    │  ◄──── streaming output ────┤
    │  ◄──── runs/complete ───────┤
    │                             │

Bidirectional Capabilities​

Sub-agents can request things from the parent:

RequestDescription
File readRead files from the workspace
File writeWrite files to the workspace
PermissionAsk for user approval before actions
Resource accessRequest access to shared resources

Session Management​

  • Each delegation creates a run with a unique session ID
  • Runs are tracked by the agentSessionStateManager (in-flight) and agentSessionTracker (completed)
  • Sub-agents can be stateful — maintaining context across multiple delegations

Delegation Tools​

The main agent sees available delegation targets in prompt context and uses these runtime tools for delegation:

delegate_to_agent​

Sends a task to a specific agent:

→ delegate_to_agent({
    agentId: "code-reviewer",
    task: "Review the changes in PR #42 for security issues",
    context: { pr_number: 42 }
  })
← { result: "Found 3 issues: ...", status: "complete" }

check_agent_status​

Checks an async delegated run:

→ check_agent_status({ runId: "acp_delegation_..." })
← { status: "completed", output: "..." }

Timeouts and Lifecycle​

SettingDefaultDescription
Task timeoutConfigurable per agentMax time for a single delegation
Idle timeoutConfigurableKill idle agent processes
Emergency stopCtrl+Shift+EscapeAbort all active agents immediately

Example: Multi-Agent Workflow​

Here's a complete example of setting up a two-agent workflow:

Agent 1: Researcher​

---
id: researcher
name: researcher
displayName: Research Assistant
description: Deep research on topics using web search
enabled: true
role: delegation-target
---

You are a thorough researcher. Search the web, cross-reference sources,
and provide detailed findings with citations.

Agent 2: Writer​

---
id: writer
name: writer
displayName: Content Writer
description: Writes polished content based on research
enabled: true
role: delegation-target
---

You are a skilled writer. Take research findings and produce clear,
engaging content. Maintain accuracy while making the content accessible.

Usage​

"Research the latest trends in AI agent frameworks and write a blog post summary"

The main agent will:

  1. Delegate research to the Research Assistant
  2. Receive findings
  3. Delegate writing to the Content Writer with the research
  4. Return the finished blog post

Next Steps​