What are deep agents and how do they solve complex problems?

# Example: Deep agent system prompt structure
system_prompt = """
You are a senior document processing specialist with expertise in:

## Domain knowledge
- Document classification and structure analysis
- Data extraction from legal and financial documents
- Compliance requirements for different industries
- Quality assurance and validation workflows

## Decision framework
When processing documents:
1. Document type classification and confidence scoring
2. Field extraction accuracy and validation
3. Compliance rule application and exceptions
4. Quality control and human review triggers
5. Audit trail and documentation requirements

## Examples of expert reasoning
[Detailed examples of document processing decision-making...]
"""

# Example: Todo list tool - essentially a "no-op" for context engineering
from langchain.tools import BaseTool

class TodoListTool(BaseTool):
    name = "todo_list"
    description = "A simple todo list for organizing thoughts and maintaining focus"

    def _run(self, action: str, item: str = None) -> str:
        """
        This tool doesn't actually do anything substantive - it's pure context engineering.
        The agent uses it to structure its thinking, but the real value is psychological.
        """
        if action == "add" and item:
            return f"✓ Added to todo list: {item}"

        elif action == "complete" and item:
            return f"✓ Marked as completed: {item}"

        elif action == "list":
            return "✓ Todo list reviewed - staying focused on current objectives"

        else:
            return "✓ Todo list accessed - use this to organize your thinking"

# Usage example showing the psychological benefit
agent_prompt = """
You have access to a todo_list tool. Use it to break down complex tasks
and maintain focus, even though it doesn't perform any real operations.

Task: Process a complex legal document workflow

Agent: I'll start by organizing my approach with the todo list.
Action: todo_list(action="add", item="1. Classify document type")
Action: todo_list(action="add", item="2. Extract key legal terms")
Action: todo_list(action="add", item="3. Validate compliance requirements")

Now I'll work through each item systematically...
"""

# Example: Subagent structure (based on LangChain's deepagents package)
from typing import TypedDict, Optional, List
from typing_extensions import Annotated
from langgraph.prebuilt import InjectedState

# Subagent definition as used in the actual deepagents package
class SubAgent(TypedDict):
    name: str
    description: str
    prompt: str
    tools: Optional[List[str]]
    model_settings: Optional[dict]

# Task tool implementation for coordinating with subagents
def create_task_tool(sub_agents: List[SubAgent]):
    """
    Creates a task tool that can delegate work to specialized subagents
    """

    def task_tool(
        instructions: str,
        agent_name: Optional[str] = None,
        state: Annotated[dict, InjectedState] = None
    ) -> str:
        """
        Delegate a task to a specialized subagent or the general-purpose agent
        """
        # Default to general-purpose agent if no specific agent requested
        if agent_name is None:
            agent_name = "general-purpose"

        # Find the specified subagent
        selected_agent = None
        for agent in sub_agents:
            if agent["name"] == agent_name:
                selected_agent = agent
                break

        if selected_agent is None:
            return f"Agent '{agent_name}' not found. Available agents: {[a['name'] for a in sub_agents]}"

        # In the actual implementation, this would invoke the subagent
        # with its specialized prompt and tools
        return f"Task delegated to {agent_name}: {instructions}"

    return task_tool

# Example usage with document processing subagents
document_sub_agents = [
    {
        "name": "document-classifier",
        "description": "Classifies document types and structures",
        "prompt": "You are an expert at identifying document types and analyzing their structure...",
        "tools": ["document_parser", "structure_analyzer"],
        "model_settings": {"temperature": 0.1}
    },
    {
        "name": "compliance-checker",
        "description": "Validates documents against compliance requirements",
        "prompt": "You are a compliance expert who validates documents against regulatory requirements...",
        "tools": ["regulation_lookup", "compliance_validator"],
        "model_settings": {"temperature": 0.0}
    },
    {
        "name": "data-extractor",
        "description": "Extracts specific data fields from documents",
        "prompt": "You are specialized in extracting structured data from unstructured documents...",
        "tools": ["field_extractor", "data_validator"],
        "model_settings": {"temperature": 0.2}
    }
]

# Create the coordinating task tool
task_coordinator = create_task_tool(document_sub_agents)

# Example: File system tools (based on LangChain's virtual file system)
from langchain.tools import BaseTool
import json
import os
from typing import Dict, Any

class FileSystemTool(BaseTool):
    name = "file_system"
    description = "Read, write, and manage files in the agent workspace"

    def __init__(self, workspace_path: str = "./agent_workspace"):
        super().__init__()
        self.workspace_path = workspace_path
        os.makedirs(workspace_path, exist_ok=True)

    def _run(self, action: str, filename: str = None, content: str = None) -> str:
        """
        File system operations for persistent storage
        Actions: read, write, list, delete
        """
        if action == "write" and filename and content:
            file_path = os.path.join(self.workspace_path, filename)
            with open(file_path, 'w') as f:
                f.write(content)
            return f"Written to {filename}"

        elif action == "read" and filename:
            file_path = os.path.join(self.workspace_path, filename)
            try:
                with open(file_path, 'r') as f:
                    content = f.read()
                return f"Content of {filename}:\n{content}"
            except FileNotFoundError:
                return f"File {filename} not found"

        elif action == "list":
            files = os.listdir(self.workspace_path)
            if not files:
                return "Workspace is empty"
            return f"Files in workspace:\n" + "\n".join(files)

        elif action == "delete" and filename:
            file_path = os.path.join(self.workspace_path, filename)
            try:
                os.remove(file_path)
                return f"Deleted {filename}"
            except FileNotFoundError:
                return f"File {filename} not found"

        return "Available actions: read, write, list, delete"

# Example usage for collaborative workflows
class CollaborativeWorkspace:
    def __init__(self):
        self.fs_tool = FileSystemTool()

    def save_agent_state(self, agent_id: str, state: Dict[Any, Any]):
        """Save agent state for persistence across sessions"""
        state_file = f"agent_{agent_id}_state.json"
        self.fs_tool._run("write", state_file, json.dumps(state, indent=2))

    def load_agent_state(self, agent_id: str) -> Dict[Any, Any]:
        """Load previous agent state"""
        state_file = f"agent_{agent_id}_state.json"
        result = self.fs_tool._run("read", state_file)
        if "not found" in result:
            return {}
        # Extract JSON from the formatted response
        json_start = result.find('{\n')
        if json_start != -1:
            json_content = result[json_start:]
            return json.loads(json_content)
        return {}

Think: Need to find performance bottlenecks
Act: `analyze_metrics()`
Observe: Database queries taking 2.3s average
Think: That's slow, let me optimize queries
Act: `suggest_query_optimization()`
Observe: Suggested adding indexes
Think: Task complete

Plan:
1. Analyze overall system architecture
2. Identify multiple optimization strategies
3. Evaluate tradeoffs between approaches
4. Implement coordinated optimization plan
5. Measure results against performance objectives

Execute:
- Architecture analysis subagent — Reviews system design patterns
- Database subagent — Analyzes query performance and indexing
- Frontend subagent — Evaluates client-side optimization opportunities
- Caching subagent — Identifies caching strategy improvements

Synthesize:
- Coordinate all findings into comprehensive optimization strategy