multi-agent-systems

Multi-Agent Systems

When to Use Multi-Agent Architectures

Multi-agent systems introduce overhead. Every additional agent represents another potential point of failure, another set of prompts to maintain, and another source of unexpected behavior.

Multi-agent systems use 3-10x more tokens than single-agent approaches due to:

• Duplicating context across agents
• Coordination messages between agents
• Summarizing results for handoffs

Start with a Single Agent

A well-designed single agent with appropriate tools can accomplish far more than expected. Use single agent when:

• Tasks are sequential and context-dependent
• Tool count is under 15-20
• No clear benefit from parallelization

Three Cases Where Multi-Agent Excels

1. Context pollution - Subtasks generate >1000 tokens but most info is irrelevant to main task
2. Parallelization - Tasks can run independently and explore larger search space
3. Specialization - Different tasks need different tools, prompts, or domain expertise

Decision Framework

Context Protection Pattern

Use when subtasks generate large context but only summary is needed for main task.

Example: Customer Support

class OrderLookupAgent:
    def lookup_order(self, order_id: str) -> dict:
        messages = [{"role": "user", "content": f"Get essential details for order {order_id}"}]
        response = client.messages.create(
            model="claude-sonnet-4-5", max_tokens=1024,
            messages=messages, tools=[get_order_details_tool]
        )
        return extract_summary(response)  # Returns 50-100 tokens, not 2000+

class SupportAgent:
    def handle_issue(self, user_message: str):
        if needs_order_info(user_message):
            order_id = extract_order_id(user_message)
            order_summary = OrderLookupAgent().lookup_order(order_id)
            context = f"Order {order_id}: {order_summary['status']}, purchased {order_summary['date']}"
        # Main agent gets clean context

Best when:

• Subtask generates >1000 tokens, most irrelevant
• Subtast is well-defined with clear extraction criteria
• Lookup/retrieval operations need filtering before use

Parallelization Pattern

Use when exploring larger search space or independent research facets.

import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic()

async def research_topic(query: str) -> dict:
    facets = await lead_agent.decompose_query(query)
    tasks = [research_subagent(facet) for facet in facets]
    results = await asyncio.gather(*tasks)
    return await lead_agent.synthesize(results)

async def research_subagent(facet: str) -> dict:
    messages = [{"role": "user", "content": f"Research: {facet}"}]
    response = await client.messages.create(
        model="claude-sonnet-4-5", max_tokens=4096,
        messages=messages, tools=[web_search, read_document]
    )
    return extract_findings(response)

Benefit: Thoroughness, not speed. Covers more ground at higher token cost.

Specialization Patterns

Tool Set Specialization

Split by domain when agent has 20+ tools, shows domain confusion, or degraded performance.

Signs you need specialization:

1. Quantity: 20+ tools
2. Domain confusion: Tools span unrelated domains
3. Degraded performance: New tools hurt existing tasks

System Prompt Specialization

Different tasks require conflicting behavioral modes:

• Customer support: empathetic, patient
• Code review: precise, critical
• Compliance: rigid rule-following
• Brainstorming: creative flexibility

Domain Expertise Specialization

Deep domain context that would overwhelm a generalist:

• Legal analysis: case law, regulatory frameworks
• Medical research: clinical trial methodology

Multi-Platform Integration Example

class CRMAgent:
    system_prompt = """You are a CRM specialist. You manage contacts,
    opportunities, and account records. Always verify record ownership
    before updates and maintain data integrity across related records."""
    tools = [crm_get_contacts, crm_create_opportunity]  # 8-10 CRM tools

class MarketingAgent:
    system_prompt = """You are a marketing automation specialist. You
    manage campaigns, lead scoring, and email sequences."""
    tools = [marketing_get_campaigns, marketing_create_lead]  # 8-10 tools

class OrchestratorAgent:
    def execute(self, user_request: str):
        response = client.messages.create(
            model="claude-sonnet-4-5", max_tokens=1024,
            system="""Route to appropriate specialist:
    - CRM: Contacts, opportunities, accounts, sales pipeline
    - Marketing: Campaigns, lead nurturing, email sequences""",
            messages=[{"role": "user", "content": user_request}],
            tools=[delegate_to_crm, delegate_to_marketing]
        )
        return response

Context-Centric Decomposition

Problem-centric (counterproductive): Split by work type (writer, tester, reviewer) - creates coordination overhead, context loss at handoffs.

Context-centric (effective): Agent handling a feature also handles its tests - already has necessary context.

Effective Boundaries

• Independent research paths
• Separate components with clean API contracts
• Blackbox verification

Problematic Boundaries

• Sequential phases of same work
• Tightly coupled components
• Work requiring shared state

Verification Subagent Pattern

Dedicated agent for testing/validating main agent's work. Succeeds because verification requires minimal context transfer.

class CodingAgent:
    def implement_feature(self, requirements: str) -> dict:
        response = client.messages.create(
            model="claude-sonnet-4-5", max_tokens=4096,
            messages=[{"role": "user", "content": f"Implement: {requirements}"}],
            tools=[read_file, write_file, list_directory]
        )
        return {"code": response.content, "files_changed": extract_files(response)}

class VerificationAgent:
    def verify_implementation(self, requirements: str, files_changed: list) -> dict:
        messages = [{"role": "user", "content": f"""
Requirements: {requirements}
Files changed: {files_changed}

Run the complete test suite and verify:
1. All existing tests pass
2. New functionality works as specified
3. No obvious errors or security issues

You MUST run: pytest --verbose
Only mark as PASSED if ALL tests pass with no failures.
"""}]
        response = client.messages.create(
            model="claude-sonnet-4-5", max_tokens=4096,
            messages=messages, tools=[run_tests, execute_code, read_file]
        )
        return {"passed": extract_pass_fail(response), "issues": extract_issues(response)}

Mitigate "Early Victory Problem"

Verifier marks passing without thorough testing. Prevention:

• Concrete criteria: "Run full test suite" not "make sure it works"
• Comprehensive checks: Test multiple scenarios and edge cases
• Negative tests: Confirm inputs that should fail do fail
• Explicit instructions: "You MUST run the complete test suite"

Moving Forward Checklist

Before adding multi-agent complexity:

1. Genuine constraints exist (context limits, parallelization, specialization need)
2. Decomposition follows context, not problem type
3. Clear verification points where subagents can validate

Start with simplest approach that works. Add complexity only when evidence supports it.

References

• Building multi-agent systems: when and how to use them
• Building effective agents
• Effective context engineering for AI agents
• Writing effective tools for agents