deepagents-evolution

name	DeepAgents Evolution
description	This skill should be used when the user asks to "improve agent architecture", "assess agent maturity", "refactor agents", "evolve agent system", "scale agent architecture", or needs guidance on measuring, improving, and evolving deep agent systems over time.

DeepAgents Architecture Evolution

Assess, measure, and evolve agent architectures through maturity levels.

Maturity Model Overview

Level	Name	Characteristics
1	Initial	Single agent, 40-60+ tools, frequent errors
2	Managed	2-4 subagents, basic grouping, some overlap
3	Defined	Capability-aligned, bounded contexts, documented
4	Measured	Full topologies, metrics tracked, automated testing
5	Optimizing	Self-organizing, auto-optimization, A/B testing

Level Descriptions

Level 1: Initial (Ad-Hoc)

Symptoms:

• Single agent with 40-60+ tools
• Agent confused about tool selection
• Context window overflows
• Inconsistent results

# Level 1 example
agent = create_deep_agent(tools=[tool1, tool2, ..., tool60])

Next step: Identify tool groupings, create platform subagents

Level 2: Managed (Basic Structure)

Symptoms:

• 2-4 subagents based on intuition
• Some capability separation
• Overlapping responsibilities
• Basic planning (todos)

# Level 2 example
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    subagents=[
        {"name": "data-agent", "tools": [...]},
        {"name": "api-agent", "tools": [...]}
    ]
)

Next step: Map business capabilities, define bounded contexts

Level 3: Defined (Capability-Aligned)

Symptoms:

• Subagents map to business capabilities
• Clear bounded contexts
• Documented interaction patterns
• File system for context management

# Level 3 example
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    subagents=[
        {
            "name": "customer-support",
            "system_prompt": "In support context: 'ticket' = inquiry...",
            "tools": [support_kb, ticket_system]
        }
    ]
)

Next step: Apply Team Topologies, establish metrics

Tip: Use /design-evals to scaffold your first eval dataset. This is the key step in reaching Level 4 (Measured).

Level 4: Measured (Optimized)

Symptoms:

• Full Team Topologies (platform, enabling, specialist)
• Defined interaction modes
• Performance metrics tracked
• Automated testing

Metrics to track:

• Token efficiency (tokens/task)
• Subagent utilization
• Error rate
• Cognitive load (tools/agent)

Next step: Implement evolutionary architecture

Level 5: Optimizing (Evolutionary)

Symptoms:

• Self-organizing ecosystem
• Automatic capability detection
• Dynamic subagent creation
• Continuous optimization

Migration Paths

Level 1 → 2: Basic Grouping

1. Group tools by theme (data, communication, analysis)
2. Create 2-3 basic subagents
3. Test with sample tasks
4. Measure cognitive load reduction

Level 2 → 3: Capability Alignment

1. Map business capabilities
2. Define bounded contexts
3. Redesign subagents around capabilities
4. Document vocabularies
5. Establish interaction patterns

Level 3 → 4: Measurement

1. Apply Team Topologies
2. Identify platform capabilities
3. Create enabling subagents
4. Implement metrics collection
5. Establish testing framework

Level 4 → 5: Automation

1. Implement telemetry
2. Build optimization engine
3. Create capability discovery
4. Enable automatic refactoring
5. Implement A/B testing

Assessment Checklist

Score 0-5 for each (total 80 possible):

Structure (20 points)

• Clear subagent boundaries
• Business capability alignment
• Bounded context definition
• Topology variety

Operations (20 points)

• Planning integration
• Context management
• Tool organization
• Error handling

Measurement (20 points)

• Performance metrics
• Testing coverage
• Documentation
• Monitoring

Evolution (20 points)

• Refactoring capability
• Learning from usage
• Experimentation
• Feedback loops

Score interpretation:

• 0-20: Level 1 (Initial)
• 21-40: Level 2 (Managed)
• 41-60: Level 3 (Defined)
• 61-80: Level 4+ (Measured/Optimizing)

Red Flags by Level

Level 1 Red Flags

• Context constantly overflowing
• Agent can't decide which tool
• Simple tasks take > 5 minutes

Level 2 Red Flags

• Subagents rarely used
• Unclear routing decisions
• Still context overflow

Level 3 Red Flags

• Business users don't recognize structure
• Vocabulary conflicts
• Can't add capabilities easily

Level 4 Red Flags

• Metrics not driving decisions
• Performance not improving
• Manual testing only

Refactoring Patterns

Extract Subagent

When main agent is overloaded:

# Before: 15 tools in main
agent = create_deep_agent(tools=[t1, t2, ..., t15])

# After: Extract platform
agent = create_deep_agent(
    tools=[t1, t2, t3],
    subagents=[{"name": "platform", "tools": [t4, ..., t15]}]
)

Inline Subagent

When subagent used only once:

# Before: Subagent for single use
subagents=[{"name": "calculator", "tools": [calc]}]

# After: Tool in main agent
tools=[calc]

Split Subagent

When subagent covers multiple domains:

# Before: Mixed responsibilities
{"name": "data-handler", "tools": [ingest, clean, visualize]}

# After: Separated concerns
{"name": "data-ingestion", "tools": [ingest]},
{"name": "data-visualization", "tools": [visualize]}

Merge Subagents

When subagents are too granular:

# Before: 10 tiny subagents
subagents=[{"name": "a", "tools": [t1]}, ...]

# After: Consolidated platforms
subagents=[
    {"name": "data-platform", "tools": [t1, t2, t3]},
    {"name": "analysis-platform", "tools": [t4, t5, t6]}
]

Additional Resources

Reference Files

• Maturity Model - Complete maturity model with metrics
• Refactoring Patterns - Detailed refactoring techniques

Related Skills

• Quickstart - Getting started with DeepAgents
• Architecture - Agent topologies and bounded contexts
• Patterns - System prompts, tool design, anti-patterns
• Evals - Evals-Driven Development with JTBD scenarios, trajectory evaluation, and snapshot testing

Commands

• /assess — Run the 80-point maturity assessment with level determination and next-level recommendations
• /evolve — Guided refactoring to the next maturity level (interactive, step-by-step, with EDD checkpoints)
• /validate-agent — Quick anti-pattern and security check (simplified scoring)