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

Multi-Agent Patterns Reference

Pattern Catalog

1. Context Isolation Pattern

Problem: Main agent context polluted by large subtask results.

Solution: Subagent extracts and returns only essential summary.

class OrderLookupSubagent(Subagent):
    def _get_system_prompt(self) -> str:
        return """You are an order lookup specialist. Retrieve order details
        and return ONLY: order_id, status, date, customer_name, items (names only).
        Do NOT include full history, shipping details, or payment info."""

    def lookup(self, order_id: str) -> dict:
        response = self.run(f"Get details for order {order_id}", max_tokens=1024)
        return {
            "order_id": order_id,
            "status": extract_status(response),
            "date": extract_date(response),
            "items": extract_item_names(response)
        }

2. Parallel Research Pattern

Problem: Single agent cannot cover multiple research facets within context limits.

Solution: Lead agent decomposes query, subagents research in parallel.

class ResearchOrchestrator(AgentBase):
    def _get_system_prompt(self) -> str:
        return """You coordinate research projects. Decompose complex queries
        into independent research facets that can be investigated in parallel."""

    def research(self, query: str) -> dict:
        # Decompose into facets
        facets = self.run(f"Break this into independent research facets:\n{query}")
        # Run subagents in parallel
        subagents = [ResearchSubagent() for _ in facets]
        results = asyncio.run(self._run_parallel(subagents, facets))
        # Synthesize
        return self.run(f"Synthesize these findings:\n{results}")

    async def _run_parallel(self, subagents: list, tasks: list) -> list:
        async with AsyncAnthropic() as client:
            async_subagents = [AsyncSubagent(client) for _ in subagents]
            coroutines = [sa.run_async(task) for sa, task in zip(async_subagents, tasks)]
            return await asyncio.gather(*coroutines)

3. Platform Specialization Pattern

Problem: Single agent confused by tools across multiple platforms.

Solution: Separate agents per platform with focused tool sets.

class PlatformOrchestrator(OrchestratorAgent):
    def __init__(self, client: Anthropic = None):
        super().__init__(client)
        self.register_subagent("crm", CRMAgent(client))
        self.register_subagent("marketing", MarketingAgent(client))
        self.register_subagent("messaging", MessagingAgent(client))

    def _get_system_prompt(self) -> str:
        return """You are a platform integration coordinator.
        Route requests to the appropriate specialist:
        - CRM: Contacts, opportunities, accounts, sales pipeline
        - Marketing: Campaigns, lead nurturing, email sequences, scoring
        - Messaging: Notifications, alerts, team communication"""


class CRMAgent(Subagent):
    def _get_system_prompt(self) -> str:
        return """You are a CRM specialist. Manage contacts, opportunities,
        and account records. Always verify ownership before updates."""

    def _get_tools(self) -> list:
        return [crm_get_contacts, crm_create_opportunity, crm_update_account]

4. Verification Subagent Pattern

Problem: Main agent may not thoroughly validate its own work.

Solution: Independent verifier with explicit success criteria.

class VerificationAgent(Subagent):
    def _get_system_prompt(self) -> str:
        return """You are a verification specialist. Test thoroughly before
        marking anything as passed. Run complete test suites. Report all failures."""

    def verify(self, requirements: str, artifact: Any) -> dict:
        prompt = f"""
        Requirements: {requirements}
        Artifact: {artifact}

        Verify:
        1. All existing tests pass
        2. New functionality works as specified
        3. No obvious errors or security issues
        4. Edge cases are handled

        You MUST run the complete test suite.
        Report ALL failures, even minor ones.
        """
        response = self.run(prompt, max_tokens=4096)
        return {
            "passed": "FAIL" not in response,
            "details": extract_verification_details(response)
        }


class CodingAgentWithVerification(AgentBase):
    def implement_feature(self, requirements: str, max_attempts: int = 3) -> dict:
        for attempt in range(max_attempts):
            # Implement
            result = self.run(f"Implement: {requirements}", max_tokens=4096)
            # Verify
            verifier = VerificationAgent(self.client)
            verification = verifier.verify(requirements, result)
            if verification["passed"]:
                return result
            # Retry with feedback
            requirements += f"\n\nPrevious attempt issues:\n{verification['details']}"
        raise Exception(f"Failed verification after {max_attempts} attempts")

5. Summary Extraction Pattern

Problem: Need to reduce large context before passing to main agent.

Solution: Subagent extracts concise summary using system prompt.

class SummaryExtractor(Subagent):
    def _get_system_prompt(self) -> str:
        return """You extract essential information from documents.
        Return a concise summary (50-100 tokens) containing ONLY:
        - Key findings or conclusions
        - Critical data points
        - Any items requiring follow-up

        Do NOT include: background, methodology, or full details."""

    def extract_summary(self, document: str) -> str:
        response = self.run(f"Extract summary:\n{document}", max_tokens=256)
        return response.content.strip()

Anti-Patterns to Avoid

1. Sequential Handoffs

Bad: Planning agent → Implementation agent → Testing agent

• Each handoff loses context
• Coordination overhead exceeds benefits

2. Over-Fragmentation

Bad: Splitting work into too many small agents

• More coordination messages than actual work
• Token overhead multiplies

3. Ignoring Context Boundaries

Bad: Separating work that shares critical context

• "Telephone game" effect degrades results

4. Missing Verification Criteria

Bad: "Make sure it works" instead of specific tests

• Leads to early victory problem

Scaling Guidelines

Tool Search Optimization

Before adopting multi-agent for tool management, consider:

• Anthropic's Tool Search Tool can reduce token usage by 85%
• Dynamically discover tools instead of loading all definitions
• May eliminate need for tool specialization in some cases

Source

This guide is based on Anthropic's research and practical experience:

• Building multi-agent systems: when and how to use them

Quick Reference

When to Use Multi-Agent

Token Overhead

Multi-agent uses 3-10x more tokens than single-agent for equivalent tasks.

Three Success Patterns

1. Context Protection - Subagent extracts summary, main agent stays clean 2. Parallelization - Independent research runs concurrently 3. Specialization - Focused tool sets per domain/role

Decomposition Rules

Effective (Context-Centric)

• Independent research paths
• Frontend/backend with clean API
• Blackbox verification

Problematic (Problem-Centric)

• Planning → Implementation → Testing same feature
• Tightly coupled components
• Shared state synchronization

Verification Checklist

Before adding multi-agent:

• [ ] Clear constraints exist
• [ ] Context-centric decomposition
• [ ] Specific verification criteria