Delegate Tool¶

The Delegate Tool is Amplifier's primary mechanism for agent delegation. It spawns specialized sub-agents that work autonomously, absorb the token cost of complex operations, and return concise summaries. Delegation is not an optimization -- it is the default operating mode for any non-trivial task.

What You'll Learn¶

• Why delegation exists (the context sink pattern)
• How to choose the right agent for a task
• How context inheritance works across two independent parameters
• How to run agents in parallel for speed
• How to resume agent sessions for iterative work
• How to use self-delegation for token management

Why Delegate?¶

Every tool call the main agent makes consumes its context window permanently. Twenty file reads cost roughly 20,000 tokens of context. Delegate those same reads to a sub-agent and you get back a ~500-token summary instead.

This is the context sink pattern -- agents absorb exploration cost so the parent session stays lean and effective.

Direct approach (expensive):
  read_file(a.py)   -> 800 tokens consumed
  read_file(b.py)   -> 600 tokens consumed
  read_file(c.py)   -> 900 tokens consumed
  grep(pattern)      -> 400 tokens consumed
  ... total: ~2,700 tokens permanently in context

Delegated approach (efficient):
  delegate(agent="foundation:explorer", instruction="Survey a.py, b.py, c.py and
           find uses of pattern X")
  -> returns ~500-token summary with all findings

The parent session stays small. The sub-agent session is discarded after it reports back.

Parameters¶

The delegate tool accepts the following parameters:

Context Parameters In Depth¶

Context inheritance uses two independent, orthogonal parameters:

context_depth -- How much history to pass:

context_scope -- Which content types to include:

These combine freely. For example, context_depth="recent", context_scope="agents" gives the last 5 turns of conversation plus any agent results from those turns.

Available Agents¶

Foundation Bundle¶

Other Bundles¶

When to Delegate¶

Always Delegate¶

Git operations -- Always use foundation:git-ops:

Commits, branches, PRs, merges, conflict resolution, release tagging. This agent has safety protocols that raw bash git commands lack.

Multi-file exploration -- Use foundation:explorer:

Understanding codebases, mapping dependencies, surveying documentation, finding patterns across many files.

Debugging -- Use foundation:bug-hunter:

Tracing errors, analyzing test failures, finding root causes through systematic investigation.

Often Beneficial¶

• Architecture decisions -- foundation:zen-architect
• Feature implementation (with spec) -- foundation:modular-builder
• Security review before deploy -- foundation:security-guardian
• Test gap analysis -- foundation:test-coverage
• External documentation lookup -- foundation:web-research

Don't Delegate¶

Simple, single-step operations are faster done directly:

• Reading 1-2 known files -- use read_file
• A single grep search -- use grep
• Running a test command -- use bash
• A quick file edit -- use edit_file

Parallel Dispatch¶

One of the most powerful features of delegate is concurrent execution. When tasks are independent, send all delegate calls in a single message and they run simultaneously.

User: "Analyze the auth module -- check architecture, tests, and security."

Agent response (one message, three delegate calls):

  delegate(agent="foundation:zen-architect",
           instruction="Review architecture of src/auth/...")

  delegate(agent="foundation:test-coverage",
           instruction="Analyze test coverage for src/auth/...")

  delegate(agent="foundation:security-guardian",
           instruction="Security audit of src/auth/...")

All three run concurrently. Results return together.

Three agents that each take 2 minutes = 2 minutes total, not 6.

Example: Feature Development Pipeline¶

Some stages depend on prior results; others can overlap:

Phase 1 (parallel):
  foundation:explorer     -> Understand existing code
  foundation:web-research -> Research libraries/patterns

Phase 2 (after Phase 1):
  foundation:zen-architect -> Design the feature using Phase 1 findings

Phase 3 (after Phase 2):
  foundation:modular-builder -> Implement from the architect's spec

Phase 4 (parallel, after Phase 3):
  foundation:test-coverage    -> Write tests
  foundation:security-guardian -> Security review

Phase 5 (after Phase 4):
  foundation:git-ops -> Commit and create PR

Session Resumption¶

When a delegate call completes, it returns a session_id. You can pass this back to continue where the agent left off, preserving its accumulated context.

Basic Resumption¶

// First call -- agent explores and returns session_id
{
  "agent": "foundation:explorer",
  "instruction": "Survey the authentication module in src/auth/"
}
// Returns: { "session_id": "abc123_def456", "result": "Found 12 files..." }

// Second call -- resume with follow-up
{
  "agent": "foundation:explorer",
  "session_id": "abc123_def456",
  "instruction": "Now look at how the token refresh logic connects to the session store"
}

The resumed agent remembers everything from the first call -- files it read, patterns it found, conclusions it drew.

When to Resume vs. Start Fresh¶

Resume when:

• You need follow-up analysis on the same area
• The agent built up significant context you want to keep
• You are iterating on a design or investigation

Start fresh when:

• The new task is unrelated to the previous one
• You want a clean perspective
• The previous instruction was comprehensive enough

Self-Delegation¶

The special value agent="self" spawns a copy of yourself as a sub-agent. This is a token management technique for long sessions.

{
  "agent": "self",
  "instruction": "Refactor the payment module to use the new API client",
  "context_depth": "all",
  "context_scope": "full"
}

The sub-agent inherits your full context (when configured with "all" / "full"), performs the work, and returns a summary. The parent session absorbs only the summary, not the full cost of every tool call the sub-agent made.

When to use self-delegation:

• Your session is getting long and you want to preserve context budget
• A task will require many tool calls whose intermediate results you don't need
• You want to isolate a chunk of work into a clean sub-session

Multi-Agent Collaboration¶

Agents can build on each other's work using context_scope="agents":

Step 1: Delegate to foundation:explorer
  -> Returns architectural findings

Step 2: Delegate to foundation:zen-architect
  with context_scope="agents"
  -> Architect sees explorer's findings in its context
  -> Designs improvements based on real codebase understanding

Step 3: Delegate to foundation:modular-builder
  with context_scope="agents"
  -> Builder sees both explorer and architect results
  -> Implements the spec with full context

Each agent's output becomes input context for the next, creating a pipeline without manual copy-paste of results.

Writing Good Instructions¶

The quality of your delegation depends heavily on the instruction you write.

Be Specific¶

Bad:  "Check the auth code"

Good: "Explore the authentication module in src/auth/. Document the login flow
       from request to response, identify all middleware involved, check that
       password hashing uses bcrypt or argon2, and list any endpoints missing
       rate limiting. Return a structured report."

State the Desired Output¶

Tell the agent what format and content you need back:

"Return your findings as:
 1. A summary paragraph
 2. A list of security issues with severity (high/medium/low)
 3. Recommended fixes for each issue
 4. Files that need changes"

Clarify Intent¶

Be explicit about whether you want research, code changes, or both:

Research only: "Investigate and report findings. Do not modify any files."
Code changes:  "Implement the feature and write tests."
Both:          "Research the best approach, then implement it."

Provide Starting Points¶

Include file paths, module names, or other anchors:

"The user wants to add OAuth2 authentication.
 Current auth uses JWT tokens, implemented in src/auth/.
 The User model is in src/models/user.py.
 Target: Add Google and GitHub OAuth providers.
 Check existing dependencies in requirements.txt first."

Provider Preferences¶

You can specify which model or provider an agent should use:

{
  "agent": "foundation:zen-architect",
  "instruction": "Review the caching architecture",
  "provider_preferences": [
    {"provider": "anthropic", "model": "claude-sonnet-*"},
    {"provider": "openai", "model": "gpt-4*"}
  ]
}

The array is ordered by preference -- the system tries the first match, falls back to the second, and so on. Model names support glob patterns.

Common Errors¶

"Agent not found"¶

Cause: Invalid agent name or typo.

Fix: Use the full namespace:name format from the Available Agents tables. For example, foundation:git-ops, not git-ops or gitops.

Agent Returns Vague or Empty Results¶

Cause: Instruction was too broad or lacked starting points.

Fix:

• Provide specific file paths or directories to examine
• State exactly what information you need back
• Narrow the scope -- "look at src/auth/" not "look at the project"

Agent Doesn't See Previous Context¶

Cause: Default context is context_depth="recent" with context_scope="conversation", which excludes prior agent results.

Fix: Use context_scope="agents" to include previous delegate results, or context_scope="full" to include all tool output.

Task Timeout¶

Cause: Agent task was too large or got stuck.

Fix:

• Break the work into smaller, focused delegate calls
• Provide more specific instructions to reduce exploration
• Check that target files and directories actually exist

Try It Yourself¶

Exercise 1: Simple Delegation¶

Delegate a git status check:

delegate(
  agent="foundation:git-ops",
  instruction="Show the current git status and the last 5 commits on this branch"
)

Exercise 2: Parallel Exploration¶

Survey frontend and backend simultaneously:

// Call 1 (in the same message):
delegate(
  agent="foundation:explorer",
  instruction="Survey the React frontend in src/frontend/. Map component
               hierarchy and identify the routing structure."
)

// Call 2 (in the same message):
delegate(
  agent="foundation:explorer",
  instruction="Survey the Python backend in src/api/. Map the endpoint
               structure, middleware chain, and database models."
)

Both agents run concurrently. You get two reports back at once.

Exercise 3: Agent Pipeline¶

Chain agents where each builds on the previous:

// Step 1: Explore
delegate(agent="foundation:explorer",
         instruction="Survey src/billing/ and document the payment flow")

// Step 2: Architect (sees explorer's results)
delegate(agent="foundation:zen-architect",
         instruction="Design a refactor of the billing module to support
                      multiple payment providers",
         context_scope="agents")

// Step 3: Implement (sees both prior agents)
delegate(agent="foundation:modular-builder",
         instruction="Implement the billing refactor per the architect's spec",
         context_scope="agents")

// Step 4: Commit
delegate(agent="foundation:git-ops",
         instruction="Commit all changes with a descriptive message")

Summary¶

The Delegate Tool enables:

• Context efficiency -- Agents absorb token cost; parent stays lean
• Specialization -- Right agent for each job, with domain-specific tools
• Parallelism -- Independent tasks run concurrently
• Collaboration -- Agents build on each other's results via context sharing
• Session continuity -- Resume agents for iterative work

Golden rules:

1. Delegation is the default, not the exception. If a task touches more than 2 files or benefits from specialized expertise, delegate it.
2. Git operations always go through foundation:git-ops.
3. Write self-contained, detailed instructions -- agents start with zero prior context.

Next Steps:

• Learn about Recipes for multi-step orchestrated workflows
• Explore Filesystem for direct file operations
• See Search (Grep & Glob) for code search patterns