Skip to content

QueryMT Agent - Delegation System

The delegation system enables multi-agent workflows where a planner agent can delegate tasks to specialized delegate agents. This allows for division of labor and specialized expertise.

Overview

Delegation allows agents to: - Delegate tasks to specialized agents - Coordinate work across multiple agents - Verify results from delegates - Run in parallel multiple delegations - Route to remote agents via mesh networking

Architecture

flowchart TD
    P["Planner Agent<br/>(Analyzes task, decides which delegate to use)"]
    O["Delegation Orchestrator<br/>(Manages delegation lifecycle)"]
    D1["Delegate 1<br/>(Coder)"]
    D2["Delegate 2<br/>(Tester)"]

    P -->|"Delegation Request"| O
    O --> D1 & D2

Configuration

Enabling Delegation

Delegation is enabled in the quorum configuration:

1
2
3
[quorum]
delegation = true
verification = false  # Optional: enable verification

Defining Delegates

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[[delegates]]
id = "coder"
provider = "anthropic"
model = "claude-sonnet-4-5-20250929"
description = "Coder agent that implements code changes"
capabilities = ["coding", "filesystem", "shell"]
tools = ["edit", "write_file", "shell", "read_tool", "glob"]

system = """You are a coder agent. Implement the requested changes
efficiently and correctly. Focus on writing clean, maintainable code."""

[delegates.execution]
max_steps = 200

Planner Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[planner]
provider = "anthropic"
model = "claude-sonnet-4-5-20250929"
tools = ["delegate", "read_tool", "shell", "glob"]

system = """You are a planner agent. Your role is to:
1. Analyze user requests
2. Decide if delegation is needed
3. Choose the appropriate delegate
4. Provide clear instructions to delegates
5. Review and integrate delegate results"""

Delegation Lifecycle

1. Delegation Request

The planner decides to delegate and creates a delegation request.

If hooks are enabled, pre_delegation runs before the delegation is recorded. It can block the delegation entirely or rewrite fields such as target_agent_id, objective, context, constraints, and expected_output.

The planner-side tool result is updated when a delegation is blocked, so the model sees Delegation blocked by hook: ... instead of a misleading queued message.

The delegation request shape is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
pub struct Delegation {
    pub public_id: String,              // Unique delegation ID
    pub target_agent_id: String,        // Which delegate to use
    pub objective: String,              // What needs to be done
    pub context: Option<String>,        // Additional context
    pub constraints: Option<String>,    // Constraints to follow
    pub expected_output: Option<String>,// Expected result format
    pub task_id: Option<String>,        // Associated task ID
    pub planning_summary: Option<String>,// Summary of planning conversation
    pub verification_spec: Option<VerificationSpec>, // Optional verification
}

2. Session Creation

The orchestrator creates a new session for the delegate:

1
2
3
4
// Planner creates delegation session
let (session_id, session_ref) = target_agent
    .create_delegation_session(cwd)
    .await?;

3. Context Injection

The planner's context is injected into the delegate session.

If hooks are enabled, delegation_start runs just before the delegate begins work. This hook is observe-only: it cannot block execution, but its additional_context is appended to the child session planning context.

The planner's context is injected into the delegate session:

1
2
3
4
// Planning summary is injected via kameo message
session_ref
    .set_planning_context(planning_summary)
    .await?;

4. Task Execution

The delegate receives the task and begins execution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Delegate receives:
  - Objective: "Add user authentication"
  - Context: [Planning summary]
  - Constraints: "Use JWT, follow security best practices"
  - Expected Output: "Working authentication with tests"

Delegate:
  - Analyzes requirements
  - Reads existing code
  - Implements changes
  - Writes tests

5. Result Collection

The delegate's work is collected.

If hooks are enabled, post_delegation runs after the delegate summary is extracted. This hook is observe-only and can append context to the summary that gets injected back into the planner session.

The delegate's work is collected:

1
2
3
4
5
// Get delegate's history
let history = session_ref.get_history().await?;

// Extract summary
let summary = extract_session_summary_from_history(&history);

6. Verification (Optional)

If verification is enabled, the result is verified:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
if let Some(verification_spec) = &delegation.verification_spec {
    let passed = verification_service
        .verify(verification_spec, context)
        .await?;

    if !passed {
        // Delegation failed verification
        // Error is reported to planner
    }
}

7. Result Injection

The result is injected back into the planner session.

If a delegation fails, delegation_failure runs before the failure message is injected back into the planner. This hook is also observe-only and can append remediation context to the planner-visible failure message.

The result is injected back into the planner session:

1
2
3
4
5
6
let message = format_delegation_completion_message(
    &delegation.public_id,
    &summary
);

planner_session.prompt(message).await?;

Delegation Hooks Summary

Hook Matcher Behavior
pre_delegation target agent regex Block or rewrite the delegation before it is recorded
delegation_start target agent regex Observe start and append planning context for the child session
post_delegation target agent regex Observe completion and append context to the injected summary
delegation_failure target agent regex Observe failure and append context to the injected failure message

See the Hooks Guide for JSON payloads, schemas, and output examples.

Delegation Status

Status Description
Pending Delegation requested, waiting to start
Running Delegate is working on the task
Complete Delegate finished successfully
Failed Delegate encountered an error
Cancelled Delegation was cancelled

Verification

Verification Types

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
pub enum VerificationType {
    // Run a shell command and check exit code
    ShellCommand { command: String },

    // Check if a file exists
    FileExists { path: String },

    // Check if file contains specific content
    FileContains { path: String, content: String },

    // Custom verification logic
    Custom { spec: serde_json::Value },
}

Example Verification

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# In delegate configuration
[[delegates]]
id = "coder"
# ... other config

# Verification spec in delegation request
verification_spec = {
    verification_type = "shell_command",
    command = "cargo check && cargo test"
}

Delegation Parameters

Wait Policy

Controls how the planner waits for delegate results:

1
2
3
[quorum]
delegation_wait_policy = "any"  # "all" | "any"
delegation_wait_timeout_secs = 120
  • any: Continue when first delegate completes
  • all: Wait for all delegates to complete

Parallel Delegations

1
2
[quorum]
max_parallel_delegations = 5

Maximum concurrent delegations.

Grace Period

1
2
[quorum]
delegation_cancel_grace_secs = 5

Time to wait for graceful cancellation before force abort.

Remote Delegation

Delegates can run on remote mesh nodes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Mesh configuration
[mesh]
enabled = true
listen = "/ip4/0.0.0.0/tcp/9000"

[[mesh.peers]]
name = "gpu-server"
addr = "/ip4/192.168.1.100/tcp/9000"

# Remote delegate
[[delegates]]
id = "remote-coder"
provider = "anthropic"
model = "claude-sonnet-4-5-20250929"
description = "Coder on GPU server"
peer = "gpu-server"  # Routes LLM calls to remote node
tools = ["edit", "write_file", "shell"]

When peer is specified: - LLM calls are routed to the remote node - Tool execution happens locally - Enables "remote model, local session" pattern

Delegation Events

Agents emit events during delegation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
pub enum AgentEventKind {
    // Delegation lifecycle
    DelegationRequested { delegation: Delegation },
    SessionForked {
        parent_session_id: String,
        child_session_id: String,
        target_agent_id: String,
        origin: ForkOrigin,
        fork_point_type: ForkPointType,
        fork_point_ref: String,
        instructions: String,
    },
    DelegationCompleted {
        delegation_id: String,
        result: Option<String>,
    },
    DelegationFailed {
        delegation_id: String,
        error: String,
    },
    DelegationCancelled {
        delegation_id: String,
    },
}

Programmatic Delegation

Creating a Delegation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
use querymt_agent::prelude::*;
use agent_client_protocol::Delegation;

let delegation = Delegation {
    public_id: uuid::Uuid::new_v4().to_string(),
    target_agent_id: "coder".to_string(),
    objective: "Implement user authentication".to_string(),
    context: Some("Project uses JWT for authentication".to_string()),
    constraints: Some("Follow security best practices".to_string()),
    expected_output: Some("Working auth with tests".to_string()),
    task_id: None,
    planning_summary: None,
    verification_spec: None,
};

// Request delegation
agent.delegate(delegation).await?;

Subscribing to Delegation Events

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
let mut events = agent.subscribe_events();

while let Ok(event) = events.recv().await {
    match event.kind() {
        AgentEventKind::DelegationRequested { delegation } => {
            println!("Delegation requested: {}", delegation.objective);
        }
        AgentEventKind::DelegationCompleted { delegation_id, result } => {
            println!("Delegation {} completed: {:?}", delegation_id, result);
        }
        AgentEventKind::DelegationFailed { delegation_id, error } => {
            println!("Delegation {} failed: {}", delegation_id, error);
        }
        _ => {}
    }
}

Error Handling

Common Errors

Error Cause Resolution
AgentNotFound Delegate not registered Register delegate with correct ID
SessionCreationFailed Cannot create delegate session Check delegate configuration
VerificationFailed Verification check failed Fix the issue or adjust verification
Timeout Delegation took too long Increase timeout or optimize task
Cancelled Delegation was cancelled Retry or handle cancellation

Error Classification

The system classifies delegation errors:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Patch Application Failure
// → Use read_tool to see current file state
// → Verify context lines match actual file

// Verification Failure  
// → Read verification error output
// → Fix compilation/test errors

// Invalid Working Directory
// → Do NOT specify workdir in patches
// → Verify file paths are correct

// Too Many Retries
// → Current approach not working
// → Try different strategy

Best Practices

When to Delegate

Good candidates for delegation: - Well-defined, isolated tasks - Tasks requiring specific expertise - Parallelizable work - Tasks with clear success criteria

Poor candidates for delegation: - Highly ambiguous requirements - Tasks requiring deep context - Interactive, multi-turn tasks - Tasks needing human judgment

Writing Good Delegation Requests

  1. Clear objective: Be specific about what needs to be done
  2. Relevant context: Include necessary background information
  3. Explicit constraints: List any requirements or restrictions
  4. Expected output: Describe what success looks like
  5. Verification criteria: If applicable, specify how to verify

Planning for Delegation

  1. Break down tasks: Split complex tasks into smaller delegations
  2. Order dependencies: Plan delegation sequence
  3. Set expectations: Clearly communicate goals to delegates
  4. Review results: Always review delegate output before integrating

Examples

Simple Delegation

1
2
3
4
5
6
7
# Planner delegates coding task to coder
[planner]
tools = ["delegate"]

[[delegates]]
id = "coder"
tools = ["edit", "write_file", "shell"]

User: "Add a new API endpoint" Planner: Delegates to coder with task details Coder: Implements the endpoint Planner: Reviews and integrates the changes

Parallel Delegation

1
2
3
4
5
6
7
[[delegates]]
id = "frontend-coder"
tools = ["edit", "write_file"]

[[delegates]]
id = "backend-coder"
tools = ["edit", "write_file", "shell"]

User: "Implement feature X" Planner: Delegates frontend to frontend-coder, backend to backend-coder Both delegates work in parallel Planner: Integrates both results

Verification Example

1
2
3
4
5
6
7
8
9
[[delegates]]
id = "coder"
# ...

# Verification in delegation request
verification_spec = {
    verification_type = "shell_command",
    command = "cargo test --lib"
}

Troubleshooting

Delegation Not Starting

  1. Check delegate is registered: agent.agent_registry().list_agents()
  2. Verify delegate configuration is valid
  3. Check for middleware errors
  4. Review logs for delegation events

Delegate Not Completing

  1. Check delegate has necessary tools
  2. Verify delegate can access required files
  3. Check for infinite loops in delegate logic
  4. Review timeout settings

Verification Failing

  1. Check verification command is correct
  2. Verify delegate made expected changes
  3. Adjust verification criteria if too strict
  4. Review delegate output for issues