Agent Definitions

@dataclass
class AgentDefinition:
    """Custom agent configuration."""

    description: str
    prompt: str
    tools: list[str] | None = None
    model: Literal["sonnet", "opus", "haiku", "inherit"] | None = None

from claude_agent_sdk import AgentDefinition

# Code reviewer agent
reviewer = AgentDefinition(
    description="Reviews code for quality and best practices",
    prompt="You are an expert code reviewer. Focus on code quality, security, and best practices.",
    tools=["Read", "Grep", "Glob"],
    model="sonnet"
)

# Documentation writer agent
doc_writer = AgentDefinition(
    description="Writes technical documentation",
    prompt="You are a technical writer. Create clear, comprehensive documentation.",
    tools=["Read", "Write", "Glob"],
    model="sonnet"
)

# Bug fixer agent
bug_fixer = AgentDefinition(
    description="Diagnoses and fixes bugs",
    prompt="You are a debugging expert. Find and fix bugs efficiently.",
    tools=["Read", "Write", "Edit", "Bash", "Grep"],
    model="opus"
)

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

# Define agents
agents = {
    "reviewer": AgentDefinition(
        description="Code reviewer",
        prompt="Review code for quality",
        tools=["Read", "Grep"],
        model="sonnet"
    ),
    "writer": AgentDefinition(
        description="Documentation writer",
        prompt="Write clear documentation",
        tools=["Read", "Write"],
        model="sonnet"
    )
}

# Use with options
options = ClaudeAgentOptions(
    agents=agents,
    allowed_tools=["Read", "Write", "Grep"]
)

SettingSource = Literal["user", "project", "local"]

from claude_agent_sdk import ClaudeAgentOptions

# Load settings from specific sources
options = ClaudeAgentOptions(
    setting_sources=["project", "local"]  # Exclude user settings
)

# Load only project settings
options = ClaudeAgentOptions(
    setting_sources=["project"]
)

# Load all settings (default behavior)
options = ClaudeAgentOptions(
    setting_sources=["user", "project", "local"]
)

from claude_agent_sdk import (
    ClaudeAgentOptions, AgentDefinition, query,
    AssistantMessage, TextBlock
)
import anyio

# Define specialized agents
agents = {
    "python_expert": AgentDefinition(
        description="Python development expert",
        prompt="""You are an expert Python developer with deep knowledge of:
        - Python best practices and idioms
        - Async/await programming
        - Type hints and mypy
        - Testing with pytest
        - Performance optimization
        Always write clean, well-documented Python code.""",
        tools=["Read", "Write", "Edit", "Bash", "Grep"],
        model="sonnet"
    ),

    "security_auditor": AgentDefinition(
        description="Security vulnerability auditor",
        prompt="""You are a security expert specializing in:
        - Code vulnerability analysis
        - Security best practices
        - OWASP Top 10
        - Dependency security
        Review code for security issues and suggest fixes.""",
        tools=["Read", "Grep", "Glob"],
        model="opus"
    ),

    "test_writer": AgentDefinition(
        description="Test suite creator",
        prompt="""You are a testing expert who writes:
        - Comprehensive unit tests
        - Integration tests
        - Edge case coverage
        - Clear test documentation
        Use pytest and follow testing best practices.""",
        tools=["Read", "Write", "Bash"],
        model="sonnet"
    ),

    "doc_generator": AgentDefinition(
        description="Documentation generator",
        prompt="""You are a technical writer who creates:
        - Clear API documentation
        - Usage examples
        - Architecture diagrams (as text)
        - README files
        Write documentation that developers love to read.""",
        tools=["Read", "Write", "Glob"],
        model="sonnet"
    ),
}

# Use agents
async def main():
    options = ClaudeAgentOptions(
        agents=agents,
        allowed_tools=["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
    )

    async for msg in query(
        prompt="Review my Python code for security issues",
        options=options
    ):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock):
                    print(block.text)

anyio.run(main)

from claude_agent_sdk import AgentDefinition

# Web application agents
web_agents = {
    "frontend": AgentDefinition(
        description="Frontend React developer",
        prompt="""You are a React expert specializing in:
        - Modern React with hooks
        - TypeScript
        - Component design
        - Accessibility
        - Performance optimization""",
        tools=["Read", "Write", "Edit", "Bash"],
        model="sonnet"
    ),

    "backend": AgentDefinition(
        description="Backend API developer",
        prompt="""You are a backend expert specializing in:
        - RESTful API design
        - Database optimization
        - Authentication/authorization
        - Error handling
        - API documentation""",
        tools=["Read", "Write", "Edit", "Bash"],
        model="sonnet"
    ),

    "devops": AgentDefinition(
        description="DevOps engineer",
        prompt="""You are a DevOps expert specializing in:
        - CI/CD pipelines
        - Docker and containerization
        - Infrastructure as code
        - Monitoring and logging
        - Cloud deployment""",
        tools=["Read", "Write", "Bash"],
        model="sonnet"
    ),
}

from claude_agent_sdk import AgentDefinition

data_agents = {
    "data_analyst": AgentDefinition(
        description="Data analysis expert",
        prompt="""You are a data analyst expert in:
        - Pandas and NumPy
        - Data cleaning and preprocessing
        - Exploratory data analysis
        - Statistical analysis
        - Data visualization with matplotlib/seaborn""",
        tools=["Read", "Write", "Bash"],
        model="sonnet"
    ),

    "ml_engineer": AgentDefinition(
        description="Machine learning engineer",
        prompt="""You are an ML engineer specializing in:
        - Scikit-learn, PyTorch, TensorFlow
        - Model training and evaluation
        - Feature engineering
        - Model optimization
        - Production ML systems""",
        tools=["Read", "Write", "Bash"],
        model="opus"
    ),

    "data_engineer": AgentDefinition(
        description="Data pipeline engineer",
        prompt="""You are a data engineer expert in:
        - ETL pipelines
        - Data warehousing
        - SQL optimization
        - Apache Spark
        - Data quality""",
        tools=["Read", "Write", "Bash"],
        model="sonnet"
    ),
}

from claude_agent_sdk import AgentDefinition

maintenance_agents = {
    "refactorer": AgentDefinition(
        description="Code refactoring specialist",
        prompt="""You are a refactoring expert who:
        - Improves code structure
        - Reduces complexity
        - Eliminates code smells
        - Maintains functionality
        - Adds clear documentation""",
        tools=["Read", "Write", "Edit", "Grep"],
        model="sonnet"
    ),

    "debugger": AgentDefinition(
        description="Bug investigation and fixing",
        prompt="""You are a debugging expert who:
        - Analyzes error messages
        - Traces code execution
        - Identifies root causes
        - Implements fixes
        - Adds tests for bug cases""",
        tools=["Read", "Write", "Edit", "Bash", "Grep"],
        model="opus"
    ),

    "optimizer": AgentDefinition(
        description="Performance optimization",
        prompt="""You are a performance expert who:
        - Profiles code
        - Identifies bottlenecks
        - Optimizes algorithms
        - Improves memory usage
        - Measures improvements""",
        tools=["Read", "Write", "Edit", "Bash"],
        model="opus"
    ),

    "updater": AgentDefinition(
        description="Dependency updater",
        prompt="""You are a dependency management expert who:
        - Updates dependencies safely
        - Resolves version conflicts
        - Tests after updates
        - Documents changes
        - Handles breaking changes""",
        tools=["Read", "Write", "Edit", "Bash"],
        model="sonnet"
    ),
}

from claude_agent_sdk import AgentDefinition

doc_agents = {
    "api_documenter": AgentDefinition(
        description="API documentation writer",
        prompt="""You create API documentation including:
        - Endpoint descriptions
        - Request/response examples
        - Error codes
        - Authentication details
        - Usage guidelines""",
        tools=["Read", "Write", "Glob"],
        model="sonnet"
    ),

    "readme_writer": AgentDefinition(
        description="README file creator",
        prompt="""You write comprehensive README files with:
        - Project overview
        - Installation instructions
        - Usage examples
        - Configuration guide
        - Contributing guidelines""",
        tools=["Read", "Write", "Glob"],
        model="sonnet"
    ),

    "tutorial_creator": AgentDefinition(
        description="Tutorial and guide writer",
        prompt="""You create step-by-step tutorials with:
        - Clear learning objectives
        - Progressive examples
        - Common pitfalls
        - Best practices
        - Exercises""",
        tools=["Read", "Write"],
        model="sonnet"
    ),
}

from claude_agent_sdk import AgentDefinition

architecture_agents = {
    "architect": AgentDefinition(
        description="System architecture designer",
        prompt="""You design software architecture considering:
        - Scalability requirements
        - Design patterns
        - Technology choices
        - Trade-offs
        - Future extensibility""",
        tools=["Read", "Write"],
        model="opus"
    ),

    "reviewer": AgentDefinition(
        description="Architecture review specialist",
        prompt="""You review architecture for:
        - Design pattern usage
        - Component coupling
        - System boundaries
        - Performance implications
        - Security considerations""",
        tools=["Read", "Grep", "Glob"],
        model="opus"
    ),

    "diagrammer": AgentDefinition(
        description="Architecture diagram creator",
        prompt="""You create architecture diagrams (as text) showing:
        - Component relationships
        - Data flow
        - Integration points
        - Deployment topology
        - Mermaid diagram syntax""",
        tools=["Read", "Write"],
        model="sonnet"
    ),
}

# Good
AgentDefinition(
    description="Python security auditor specialized in OWASP vulnerabilities",
    ...
)

# Less clear
AgentDefinition(
    description="Code checker",
    ...
)

AgentDefinition(
    description="API documentation writer",
    prompt="""You are an expert technical writer specializing in API documentation.

Your documentation includes:
- Clear endpoint descriptions with HTTP methods
- Request/response schemas with examples
- Authentication requirements
- Error codes and handling
- Rate limiting information
- Usage examples in multiple languages

You write in a clear, concise style that developers appreciate.
Always include practical examples.""",
    ...
)

# Security auditor - read-only
AgentDefinition(
    description="Security auditor",
    tools=["Read", "Grep", "Glob"],  # No Write/Edit
    ...
)

# Code fixer - needs write access
AgentDefinition(
    description="Bug fixer",
    tools=["Read", "Write", "Edit", "Bash"],
    ...
)

# Simple tasks - use Haiku
AgentDefinition(
    description="File organizer",
    model="haiku",
    ...
)

# Standard tasks - use Sonnet
AgentDefinition(
    description="Code reviewer",
    model="sonnet",
    ...
)

# Complex tasks - use Opus
AgentDefinition(
    description="Architecture designer",
    model="opus",
    ...
)

# Inherit from parent
AgentDefinition(
    description="Helper agent",
    model="inherit",
    ...
)

# agents/python_agents.py
def get_python_agents():
    return {
        "python_dev": AgentDefinition(...),
        "python_tester": AgentDefinition(...),
        "python_doc": AgentDefinition(...),
    }

# agents/web_agents.py
def get_web_agents():
    return {
        "frontend": AgentDefinition(...),
        "backend": AgentDefinition(...),
        "fullstack": AgentDefinition(...),
    }

# Use in project
from agents.python_agents import get_python_agents
from agents.web_agents import get_web_agents

all_agents = {
    **get_python_agents(),
    **get_web_agents(),
}

options = ClaudeAgentOptions(agents=all_agents)

async def test_agent(agent_name: str, agent_def: AgentDefinition, test_prompt: str):
    """Test an agent with a sample prompt."""
    options = ClaudeAgentOptions(
        agents={agent_name: agent_def},
        allowed_tools=agent_def.tools or []
    )

    async for msg in query(prompt=test_prompt, options=options):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock):
                    print(f"[{agent_name}] {block.text}")

# Test security auditor
await test_agent(
    "security",
    AgentDefinition(
        description="Security auditor",
        prompt="You are a security expert...",
        tools=["Read", "Grep"],
        model="sonnet"
    ),
    "Review this code for SQL injection vulnerabilities"
)

agents = {
    "lead": AgentDefinition(
        description="Lead developer - coordinates tasks",
        prompt="You coordinate development work and delegate to specialists.",
        tools=["Read", "Write"],
        model="opus"
    ),
    "specialist_security": AgentDefinition(
        description="Security specialist",
        prompt="You handle security reviews.",
        tools=["Read", "Grep"],
        model="sonnet"
    ),
    "specialist_testing": AgentDefinition(
        description="Testing specialist",
        prompt="You write comprehensive tests.",
        tools=["Read", "Write", "Bash"],
        model="sonnet"
    ),
}

pipeline_agents = {
    "analyzer": AgentDefinition(
        description="Code analyzer",
        prompt="Analyze code and identify issues.",
        tools=["Read", "Grep", "Glob"],
        model="sonnet"
    ),
    "fixer": AgentDefinition(
        description="Code fixer",
        prompt="Fix identified issues.",
        tools=["Read", "Write", "Edit"],
        model="sonnet"
    ),
    "validator": AgentDefinition(
        description="Code validator",
        prompt="Validate fixes and run tests.",
        tools=["Read", "Bash"],
        model="sonnet"
    ),
}

options = ClaudeAgentOptions(
    agents={
        "reviewer": AgentDefinition(
            description="Code reviewer",
            prompt="Review code for quality",
            tools=["Read", "Grep"],
            model="sonnet"
        )
    }
)

# Claude can invoke the reviewer agent when needed
async for msg in query(
    prompt="Please review my Python code for issues",
    options=options
):
    print(msg)