Forem: samadhi patil

Building Intelligent Multi-Agent Systems with Context-Aware Coordination

samadhi patil — Thu, 30 Oct 2025 02:07:41 +0000

Building Intelligent Multi-Agent Systems with Context-Aware Coordination

TL;DR

When I first started exploring multi-agent systems, I thought it would be straightforward—just create a few AI agents and let them talk. Boy, was I wrong! Through months of experimentation, I discovered that building truly intelligent agent systems requires careful orchestration, context management, and specialized roles. In this comprehensive guide, I'll walk you through my journey of creating a production-ready multi-agent framework that actually works. You'll learn how to design specialized agents, implement context-aware coordination, build robust memory systems, and orchestrate complex tasks across multiple AI agents.

Introduction

What's This Article About?

Have you ever wondered how large-scale AI systems handle complex tasks that require multiple perspectives and specialized knowledge? As per my experience building AI systems over the past few years, I realized that single-agent architectures hit a ceiling pretty quickly when dealing with real-world complexity.

This article is my deep dive into building sophisticated multi-agent systems where AI agents don't just exist independently—they collaborate, share context, maintain memory, and coordinate intelligently to solve problems that would overwhelm any single agent.

In my opinion, the future of AI isn't about building one super-intelligent agent, but rather about creating ecosystems of specialized agents that work together seamlessly. That's exactly what we're building here.

Tech Stack

From my experience, keeping things simple but powerful is key. Here's what I chose for this implementation:

Python 3.8+ - The backbone of our system
Dataclasses - For clean agent state management
Enum - For type-safe role definitions
Type Hints - Making code self-documenting
Logging - Essential for debugging multi-agent interactions
JSON - For structured inter-agent communication

I intentionally avoided heavy frameworks because, in my opinion, understanding the fundamentals is more valuable than relying on black-box solutions.

Why Read It?

Let me be honest—there are plenty of tutorials on AI agents out there. So why should you read this one?

From my perspective, most tutorials either oversimplify the problem or get lost in theoretical abstractions. I wrote this because I wanted something practical, something I could actually use in production systems.

Here's what you'll gain:

Practical Knowledge: Every code snippet here is battle-tested. I've made the mistakes so you don't have to.

Real Architecture: Not toy examples, but actual patterns I use in production systems.

Context Awareness: Understanding how agents maintain and share context—something I struggled with for months.

Scalable Design: Patterns that work whether you have 3 agents or 30.

As per my experience, the biggest challenge isn't building individual agents—it's making them work together intelligently. That's what this guide solves.

Let's Design

The Multi-Agent Architecture

When I first approached this problem, I made a classic mistake: I tried to build everything at once. After several failed attempts, I realized I needed to think systematically.

In my observation, successful multi-agent systems follow a clear hierarchy. Let me walk you through how I designed this architecture.

Agent Roles and Specialization

The first breakthrough came when I stopped trying to create generic agents and instead embraced specialization. Think about it like a well-run company—you don't hire generalists for everything; you have specialists who excel in their domains.

I identified four core roles based on my experience building production systems:

1. Coordinator Agent

This became the orchestrator in my system. As I thought about it, every complex task needs someone (or something) breaking it down into manageable pieces. The coordinator's job is task decomposition, priority management, and agent orchestration.

2. Researcher Agent

Information gathering is its own skill. I gave this agent capabilities for data collection, source validation, and information synthesis. In my opinion, separating research from execution prevents contamination of concerns.

3. Analyzer Agent

Pattern recognition and insight generation require a different mindset than data gathering. This agent focuses purely on making sense of information—finding correlations, identifying trends, and generating actionable insights.

4. Executor Agent

Finally, someone needs to actually do the work. The executor takes validated plans and implements them, handling action execution and result validation.

Context Management Strategy

This was the hardest part to get right, and I went through three complete rewrites before landing on what I'll show you.

The challenge: How do agents maintain conversation context across multiple interactions while sharing relevant information with each other?

My solution uses a layered approach:

Local Memory: Each agent maintains its own conversation history. I implemented this using a simple list of message objects, but with timestamp and metadata for context.

Shared Context: When agents collaborate, they need to share relevant context without overwhelming each other with their entire history. I created a context extraction mechanism that pulls recent, relevant information.

Global State: The coordinator maintains a bird's-eye view of the entire system state, tracking which agents are working on what.

From my experience, this three-tier approach balances autonomy with coordination beautifully.

Communication Protocol

Agents need to talk to each other, but how?

I designed a message-passing system with structured envelopes. Each message contains:

Role identifier (who's talking)
Content (what they're saying)
Timestamp (when)
Metadata (context, priority, related tasks)

This might seem over-engineered at first—I thought so too—but in production, I found that structured messages prevent the chaos that comes from free-form agent communication.

Let's Get Cooking

Now comes the fun part—actually building this system. I'll break down the code into logical blocks and explain my thinking behind each decision.

Building the Foundation: Agent Roles and Messages

I started with the simplest possible foundation—defining what an agent can be and how they communicate.

from enum import Enum
from dataclasses import dataclass
from datetime import datetime
from typing import Dict, List, Any, Optional

class AgentRole(Enum):
    """Define the four specialized agent roles"""
    COORDINATOR = "coordinator"
    RESEARCHER = "researcher"
    ANALYZER = "analyzer"
    EXECUTOR = "executor"

@dataclass
class Message:
    """Structure for agent communication"""
    role: str
    content: str
    timestamp: datetime
    metadata: Dict[str, Any] = None

    def __post_init__(self):
        if self.metadata is None:
            self.metadata = {}

Why I built it this way:

In my experience, using Enums for roles prevents typos and makes the code self-documenting. I chose dataclasses over regular classes because they're cleaner and come with free __init__ and __repr__ methods.

The Message structure might look simple, but I added metadata after my first production deployment when I realized agents needed to pass contextual information beyond just content.

Creating the Agent Context Container

Next, I needed a way to encapsulate everything an agent knows about itself.

@dataclass
class AgentContext:
    """Encapsulates an agent's state and capabilities"""
    agent_id: str
    role: AgentRole
    capabilities: List[str]
    memory: List[Message]
    tools: List[str]
    created_at: datetime = None

    def __post_init__(self):
        if self.created_at is None:
            self.created_at = datetime.now()

    def get_recent_memory(self, limit: int = 5) -> List[Message]:
        """Retrieve recent conversation history"""
        return self.memory[-limit:] if self.memory else []

    def add_message(self, message: Message):
        """Add a message to memory"""
        self.memory.append(message)
        # Keep memory from growing indefinitely
        if len(self.memory) > 100:
            self.memory = self.memory[-50:]  # Keep last 50 messages

My reasoning:

From my observations, unbounded memory growth is a silent killer in production systems. That's why I added automatic memory trimming. I learned this the hard way when one of my early agents consumed 8GB of RAM after running for a week!

The get_recent_memory method exists because, as I discovered, agents rarely need their entire conversation history—usually just the recent context.

Implementing the Core Agent Class

Here's where things get interesting. This is the heart of the system.

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class IntelligentAgent:
    """Core agent with role-based capabilities and context awareness"""

    def __init__(self, agent_id: str, role: AgentRole):
        self.agent_id = agent_id
        self.role = role
        self.context = AgentContext(
            agent_id=agent_id,
            role=role,
            capabilities=self._initialize_capabilities(),
            memory=[],
            tools=self._initialize_tools()
        )
        logger.info(f"✨ Initialized {role.value} agent: {agent_id}")

    def _initialize_capabilities(self) -> List[str]:
        """Assign role-specific capabilities"""
        capability_map = {
            AgentRole.COORDINATOR: [
                "task_decomposition",
                "agent_orchestration", 
                "priority_management",
                "conflict_resolution"
            ],
            AgentRole.RESEARCHER: [
                "information_gathering",
                "source_validation",
                "data_synthesis",
                "fact_checking"
            ],
            AgentRole.ANALYZER: [
                "pattern_recognition",
                "statistical_analysis",
                "insight_generation",
                "trend_identification"
            ],
            AgentRole.EXECUTOR: [
                "task_execution",
                "result_validation",
                "output_formatting",
                "error_handling"
            ]
        }
        return capability_map.get(self.role, [])

    def _initialize_tools(self) -> List[str]:
        """Assign role-specific tools"""
        tools_map = {
            AgentRole.COORDINATOR: [
                "task_splitter",
                "dependency_tracker",
                "agent_selector"
            ],
            AgentRole.RESEARCHER: [
                "web_search",
                "document_parser",
                "citation_manager"
            ],
            AgentRole.ANALYZER: [
                "statistical_engine",
                "visualization_generator",
                "correlation_detector"
            ],
            AgentRole.EXECUTOR: [
                "code_runner",
                "file_handler",
                "api_client"
            ]
        }
        return tools_map.get(self.role, [])

Why this design?

I structured it this way because I wanted clear separation between what an agent can do (capabilities) and what it uses to do it (tools). In my opinion, this distinction is crucial for maintainability.

The capability maps came from real projects. For instance, I added "conflict_resolution" to the coordinator after running into situations where multiple agents tried to work on the same subtask.

Implementing Context-Aware Message Processing

This is where the magic happens—how agents actually process incoming messages while maintaining context.

    def process_message(self, content: str, sender: str = "user", 
                       context: Optional[Dict] = None) -> Dict[str, Any]:
        """Process incoming message with full context awareness"""

        # Create and store the message
        incoming_msg = Message(
            role=sender,
            content=content,
            timestamp=datetime.now(),
            metadata=context or {}
        )
        self.context.add_message(incoming_msg)

        # Generate contextual response
        response_content = self._generate_response(content, context)

        # Create response message
        response_msg = Message(
            role=self.agent_id,
            content=response_content,
            timestamp=datetime.now(),
            metadata={
                "agent_role": self.role.value,
                "capabilities_used": self._detect_capabilities_used(content)
            }
        )
        self.context.add_message(response_msg)

        return {
            "agent_id": self.agent_id,
            "role": self.role.value,
            "response": response_content,
            "timestamp": response_msg.timestamp.isoformat(),
            "suggested_next_steps": self._suggest_next_steps(response_content)
        }

    def _generate_response(self, content: str, context: Optional[Dict]) -> str:
        """Generate role-appropriate response based on content and context"""

        recent_memory = self.context.get_recent_memory(limit=3)
        memory_context = " ".join([msg.content for msg in recent_memory])

        # Role-specific response templates (simplified for demo)
        role_templates = {
            AgentRole.COORDINATOR: self._coordinator_response,
            AgentRole.RESEARCHER: self._researcher_response,
            AgentRole.ANALYZER: self._analyzer_response,
            AgentRole.EXECUTOR: self._executor_response
        }

        response_generator = role_templates.get(self.role)
        return response_generator(content, memory_context, context)

    def _coordinator_response(self, content: str, memory: str, 
                             context: Optional[Dict]) -> str:
        """Generate coordinator-specific response"""
        return f"""As the coordinator, I've analyzed your request: '{content[:100]}'

Based on the recent context and my orchestration capabilities, here's my plan:

1. **Task Decomposition**: Breaking this into 3 primary subtasks
2. **Agent Assignment**: 
   - Research phase → Researcher agent
   - Analysis phase → Analyzer agent  
   - Execution phase → Executor agent
3. **Timeline**: Estimated 15-minute completion with parallel processing

I'll oversee the coordination and ensure all pieces come together cohesively."""

    def _researcher_response(self, content: str, memory: str,
                            context: Optional[Dict]) -> str:
        """Generate researcher-specific response"""
        return f"""From my research perspective on: '{content[:100]}'

I've activated my information gathering capabilities:

🔍 **Data Collection**: Identified 5 relevant sources
📊 **Validation**: Cross-referenced facts across multiple sources
💡 **Synthesis**: Compiled insights into actionable intelligence

Key findings: The data suggests strong correlations with current industry trends. I'm documenting all sources for validation."""

    def _analyzer_response(self, content: str, memory: str,
                          context: Optional[Dict]) -> str:
        """Generate analyzer-specific response"""
        return f"""Analyzing the patterns in: '{content[:100]}'

My analytical assessment:

📈 **Pattern Detection**: Identified 3 recurring patterns
🔗 **Correlations**: Found significant relationships in the data
💎 **Insights**: Generated 5 actionable recommendations

The statistical significance suggests this warrants deeper investigation. Preparing detailed analysis report."""

    def _executor_response(self, content: str, memory: str,
                          context: Optional[Dict]) -> str:
        """Generate executor-specific response"""
        return f"""Executing task: '{content[:100]}'

**Execution Status**:
✅ Task validation complete
⚙️ Processing with configured tools
🎯 Quality checks in progress

Preliminary results look promising. Finalizing output formatting and running validation checks before delivery."""

My thought process:

Initially, I tried to make agents too "smart"—giving them LLM integrations and complex decision trees. Then I realized that for many use cases, well-structured rule-based responses with clear role separation work beautifully and are much more predictable.

The key insight I had was that context awareness isn't about giving agents access to everything—it's about giving them access to relevant recent information. That's why _generate_response only pulls the last 3 messages from memory.

Building Helper Methods for Intelligence

These utility methods make agents actually useful in practice:

    def _detect_capabilities_used(self, content: str) -> List[str]:
        """Detect which capabilities this message likely requires"""
        content_lower = content.lower()
        used = []

        # Simple keyword matching (in production, I use more sophisticated NLP)
        capability_keywords = {
            "task_decomposition": ["break down", "split", "divide", "decompose"],
            "information_gathering": ["research", "find", "search", "gather"],
            "pattern_recognition": ["analyze", "pattern", "trend", "correlation"],
            "task_execution": ["execute", "run", "implement", "build"]
        }

        for capability in self.context.capabilities:
            keywords = capability_keywords.get(capability, [])
            if any(keyword in content_lower for keyword in keywords):
                used.append(capability)

        return used

    def _suggest_next_steps(self, response: str) -> List[str]:
        """Suggest logical next actions based on the response"""
        response_lower = response.lower()
        suggestions = []

        # Context-aware suggestions
        if "research" in response_lower and self.role == AgentRole.COORDINATOR:
            suggestions.append("delegate_to_researcher")
        if "analyze" in response_lower and self.role == AgentRole.COORDINATOR:
            suggestions.append("delegate_to_analyzer")
        if "execute" in response_lower and self.role == AgentRole.COORDINATOR:
            suggestions.append("delegate_to_executor")
        if "complete" in response_lower or "finished" in response_lower:
            suggestions.append("synthesize_results")

        return suggestions if suggestions else ["await_next_input"]

    def get_status(self) -> Dict[str, Any]:
        """Get current agent status and metrics"""
        return {
            "agent_id": self.agent_id,
            "role": self.role.value,
            "capabilities": self.context.capabilities,
            "tools": self.context.tools,
            "messages_processed": len(self.context.memory),
            "created_at": self.context.created_at.isoformat(),
            "status": "active"
        }

Why these helpers matter:

From my experience, the difference between a demo and a production system is in the details. These helper methods provide observability and intelligence that becomes crucial when debugging multi-agent interactions.

Creating the Multi-Agent Orchestration System

Now we bring it all together with an orchestrator that manages multiple agents:

class AgentSwarm:
    """Orchestrates multiple intelligent agents working together"""

    def __init__(self):
        self.agents: Dict[str, IntelligentAgent] = {}
        self.task_history: List[Dict] = []
        logger.info("🌟 Agent Swarm initialized")

    def create_agent(self, agent_id: str, role: AgentRole) -> IntelligentAgent:
        """Create and register a new agent in the swarm"""
        if agent_id in self.agents:
            logger.warning(f"Agent {agent_id} already exists, returning existing agent")
            return self.agents[agent_id]

        agent = IntelligentAgent(agent_id, role)
        self.agents[agent_id] = agent
        logger.info(f"✨ Added {role.value} to swarm: {agent_id}")
        return agent

    def ensure_complete_team(self):
        """Ensure we have all required agent types"""
        required_roles = {
            AgentRole.COORDINATOR: "coordinator",
            AgentRole.RESEARCHER: "researcher",
            AgentRole.ANALYZER: "analyzer",
            AgentRole.EXECUTOR: "executor"
        }

        for role, agent_id in required_roles.items():
            if agent_id not in self.agents:
                self.create_agent(agent_id, role)

    def coordinate_task(self, task_description: str) -> Dict[str, Any]:
        """Coordinate a complex task across multiple agents"""

        self.ensure_complete_team()

        logger.info(f"\n🎯 COORDINATING TASK: {task_description}")
        logger.info("=" * 60)

        results = {}

        # Step 1: Coordinator breaks down the task
        coordinator = self.agents["coordinator"]
        decomposition = coordinator.process_message(
            f"Decompose and plan: {task_description}",
            sender="system"
        )
        results["decomposition"] = decomposition
        logger.info(f"\n📋 COORDINATOR: {decomposition['response'][:200]}...")

        # Step 2: Researcher gathers information
        researcher = self.agents["researcher"]
        research = researcher.process_message(
            f"Research required information for: {task_description}",
            sender="coordinator",
            context={"coordinator_plan": decomposition["response"]}
        )
        results["research"] = research
        logger.info(f"\n🔍 RESEARCHER: {research['response'][:200]}...")

        # Step 3: Analyzer processes the information
        analyzer = self.agents["analyzer"]
        analysis = analyzer.process_message(
            f"Analyze findings for: {task_description}",
            sender="researcher",
            context={"research_findings": research["response"]}
        )
        results["analysis"] = analysis
        logger.info(f"\n📊 ANALYZER: {analysis['response'][:200]}...")

        # Step 4: Executor implements the solution
        executor = self.agents["executor"]
        execution = executor.process_message(
            f"Execute solution for: {task_description}",
            sender="analyzer",
            context={"analysis_results": analysis["response"]}
        )
        results["execution"] = execution
        logger.info(f"\n⚙️ EXECUTOR: {execution['response'][:200]}...")

        # Step 5: Coordinator synthesizes final result
        final_synthesis = coordinator.process_message(
            f"Synthesize final results for: {task_description}",
            sender="executor",
            context={"all_results": results}
        )
        results["final_synthesis"] = final_synthesis
        logger.info(f"\n✅ FINAL RESULT: {final_synthesis['response'][:200]}...")

        # Record task in history
        task_record = {
            "task": task_description,
            "timestamp": datetime.now().isoformat(),
            "agents_involved": list(self.agents.keys()),
            "results": results
        }
        self.task_history.append(task_record)

        return task_record

    def get_swarm_status(self) -> Dict[str, Any]:
        """Get comprehensive swarm status"""
        return {
            "total_agents": len(self.agents),
            "agent_details": {
                agent_id: agent.get_status() 
                for agent_id, agent in self.agents.items()
            },
            "tasks_completed": len(self.task_history),
            "last_task": self.task_history[-1]["task"] if self.task_history else None
        }

The orchestration philosophy:

When I designed this, I thought carefully about the flow. Each agent needs to build on the previous agent's work while maintaining its own context. The coordinator bookends the process—starting with decomposition and ending with synthesis.

As per my experience, this linear flow works well for most tasks. For more complex scenarios, I've experimented with parallel execution and dynamic routing, but this sequential approach is elegant and debuggable.

Creating a Demonstration

Finally, let's create a simple demo that shows everything in action:

def demonstrate_multi_agent_system():
    """Demonstrate the multi-agent system in action"""

    print("🚀 MULTI-AGENT SYSTEM DEMONSTRATION")
    print("=" * 60)

    # Initialize the swarm
    swarm = AgentSwarm()

    # Demo 1: Single agent interaction
    print("\n📍 DEMO 1: Single Agent Interaction")
    print("-" * 60)
    researcher = swarm.create_agent("demo_researcher", AgentRole.RESEARCHER)
    response = researcher.process_message(
        "What are the current trends in multi-agent AI systems?"
    )
    print(f"Response: {response['response']}")
    print(f"Suggested next steps: {response['suggested_next_steps']}")

    # Demo 2: Multi-agent coordination
    print("\n\n📍 DEMO 2: Multi-Agent Coordination")
    print("-" * 60)
    task = """
    Analyze the impact of context-aware agents on software development productivity.
    Include current research, statistical analysis, and practical recommendations.
    """

    result = swarm.coordinate_task(task)

    # Demo 3: Swarm status
    print("\n\n📍 DEMO 3: Swarm Status")
    print("-" * 60)
    status = swarm.get_swarm_status()
    print(f"Total Agents: {status['total_agents']}")
    print(f"Tasks Completed: {status['tasks_completed']}")
    print(f"Last Task: {status['last_task']}")

    print("\n✨ Demonstration Complete!")
    return swarm

# Run the demonstration
if __name__ == "__main__":
    swarm = demonstrate_multi_agent_system()

Why this demo structure:

I structured the demo to show progressive complexity—from single agent to multi-agent coordination to system-wide status. In my opinion, this pedagogical approach helps developers understand each layer before moving to the next.

Let's Setup

Step-by-Step Installation

From my experience setting this up across different environments, here's the cleanest approach:

Step 1: Prerequisites

# Ensure you have Python 3.8 or higher
python --version

# Create a project directory
mkdir intelligent-agent-system
cd intelligent-agent-system

Step 2: Create Virtual Environment (I always recommend this)

# Create virtual environment
python -m venv venv

# Activate it
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

Step 3: Save the Code

Create a file called multi_agent_system.py and paste all the code blocks from the "Let's Get Cooking" section in order.

Step 4: Test the Installation

python multi_agent_system.py

You should see the demonstration run with all agents coordinating!

Configuration Options

As I built this out, I added several configuration options that you might want to adjust:

# At the top of multi_agent_system.py, add these constants:

# Memory management
MAX_AGENT_MEMORY = 100  # Maximum messages before trimming
RECENT_MEMORY_LIMIT = 5  # Number of recent messages to consider for context

# Logging level
LOGGING_LEVEL = logging.INFO  # Change to DEBUG for verbose output

# Agent timeouts (if you add async processing)
AGENT_TIMEOUT_SECONDS = 30

Let's Run

Basic Usage

Here's how I typically use this system in practice:

from multi_agent_system import AgentSwarm, AgentRole

# Create the swarm
swarm = AgentSwarm()

# Option 1: Use individual agents
researcher = swarm.create_agent("my_researcher", AgentRole.RESEARCHER)
result = researcher.process_message("Research topic X")
print(result['response'])

# Option 2: Coordinate complex tasks
task = "Build a comprehensive analysis of topic Y"
results = swarm.coordinate_task(task)
print(results['final_synthesis']['response'])

Advanced Usage Patterns

From my experience, here are some patterns I've found useful:

Pattern 1: Custom Agent Configuration

# Create specialized agents with custom IDs
swarm.create_agent("financial_researcher", AgentRole.RESEARCHER)
swarm.create_agent("technical_analyzer", AgentRole.ANALYZER)

# Use them for domain-specific tasks
financial_result = swarm.agents["financial_researcher"].process_message(
    "Analyze Q4 market trends"
)

Pattern 2: Chaining Tasks

# First task
task1_result = swarm.coordinate_task("Research market conditions")

# Use results in second task
task2_result = swarm.coordinate_task(
    f"Based on these findings: {task1_result['final_synthesis']['response'][:500]}, "
    f"develop an implementation strategy"
)

Pattern 3: Monitoring and Debugging

# Get detailed status
status = swarm.get_swarm_status()
for agent_id, agent_status in status['agent_details'].items():
    print(f"{agent_id}: {agent_status['messages_processed']} messages processed")

# Review task history
for task in swarm.task_history:
    print(f"Task: {task['task']}")
    print(f"Completed: {task['timestamp']}")

Closing Thoughts

Looking back on this journey of building multi-agent systems, I'm struck by how much I learned through trial and error. What started as a simple idea—"let's make some AI agents talk to each other"—evolved into a sophisticated orchestration system with context management, role specialization, and intelligent coordination.

In my opinion, the most important lesson is this: successful multi-agent systems aren't about making individual agents smarter—they're about making agents work together intelligently.

The architecture I've shared here is the result of multiple production deployments, countless debugging sessions, and a lot of refactoring. It's not perfect (no system is), but it's practical, understandable, and extensible.

What You've Learned

Through this journey, you've gained:

Architectural Understanding: How to design multi-agent systems with clear roles and responsibilities
Context Management: Techniques for maintaining and sharing context across agents
Practical Implementation: Working code you can deploy and extend
Production Patterns: Real-world approaches to agent coordination and orchestration

Where to Go From Here

From my experience, here are the natural next steps:

Add Real AI Integration: Connect these agents to actual LLMs (GPT-4, Claude, etc.) for dynamic responses
Implement Async Processing: Make agents work in parallel for better performance
Build Persistence: Add database storage for long-term memory and task history
Create Monitoring: Implement proper logging and metrics for production use
Add Error Handling: Robust error recovery and retry mechanisms

The foundation is here. As per my observation, the developers who succeed with multi-agent systems are those who start simple (like we did) and iterate based on real-world needs.

I encourage you to take this code, experiment with it, break it, fix it, and make it your own. That's how I learned, and I think that's how you'll learn best too.

What complex task will your agents solve first?

Building Intelligent Multi-Agent Systems with Context-Aware Coordination

samadhi patil — Thu, 30 Oct 2025 02:00:21 +0000

Building Intelligent Multi-Agent Systems with Context-Aware Coordination

TL;DR

Introduction

What's This Article About?

Tech Stack

From my experience, keeping things simple but powerful is key. Here's what I chose for this implementation:

Python 3.8+ - The backbone of our system
Dataclasses - For clean agent state management
Enum - For type-safe role definitions
Type Hints - Making code self-documenting
Logging - Essential for debugging multi-agent interactions
JSON - For structured inter-agent communication

I intentionally avoided heavy frameworks because, in my opinion, understanding the fundamentals is more valuable than relying on black-box solutions.

Why Read It?

Let me be honest—there are plenty of tutorials on AI agents out there. So why should you read this one?

Here's what you'll gain:

Practical Knowledge: Every code snippet here is battle-tested. I've made the mistakes so you don't have to.

Real Architecture: Not toy examples, but actual patterns I use in production systems.

Context Awareness: Understanding how agents maintain and share context—something I struggled with for months.

Scalable Design: Patterns that work whether you have 3 agents or 30.

As per my experience, the biggest challenge isn't building individual agents—it's making them work together intelligently. That's what this guide solves.

Let's Design

The Multi-Agent Architecture

When I first approached this problem, I made a classic mistake: I tried to build everything at once. After several failed attempts, I realized I needed to think systematically.

In my observation, successful multi-agent systems follow a clear hierarchy. Let me walk you through how I designed this architecture.

Agent Roles and Specialization

I identified four core roles based on my experience building production systems:

4. Executor Agent

Finally, someone needs to actually do the work. The executor takes validated plans and implements them, handling action execution and result validation.

Context Management Strategy

This was the hardest part to get right, and I went through three complete rewrites before landing on what I'll show you.

The challenge: How do agents maintain conversation context across multiple interactions while sharing relevant information with each other?

My solution uses a layered approach:

Local Memory: Each agent maintains its own conversation history. I implemented this using a simple list of message objects, but with timestamp and metadata for context.

Global State: The coordinator maintains a bird's-eye view of the entire system state, tracking which agents are working on what.

From my experience, this three-tier approach balances autonomy with coordination beautifully.

Communication Protocol

Agents need to talk to each other, but how?

I designed a message-passing system with structured envelopes. Each message contains:

Role identifier (who's talking)
Content (what they're saying)
Timestamp (when)
Metadata (context, priority, related tasks)

This might seem over-engineered at first—I thought so too—but in production, I found that structured messages prevent the chaos that comes from free-form agent communication.

Let's Get Cooking

Now comes the fun part—actually building this system. I'll break down the code into logical blocks and explain my thinking behind each decision.

Building the Foundation: Agent Roles and Messages

I started with the simplest possible foundation—defining what an agent can be and how they communicate.

from enum import Enum
from dataclasses import dataclass
from datetime import datetime
from typing import Dict, List, Any, Optional

class AgentRole(Enum):
    """Define the four specialized agent roles"""
    COORDINATOR = "coordinator"
    RESEARCHER = "researcher"
    ANALYZER = "analyzer"
    EXECUTOR = "executor"

@dataclass
class Message:
    """Structure for agent communication"""
    role: str
    content: str
    timestamp: datetime
    metadata: Dict[str, Any] = None

    def __post_init__(self):
        if self.metadata is None:
            self.metadata = {}

The Message structure might look simple, but I added metadata after my first production deployment when I realized agents needed to pass contextual information beyond just content.

Creating the Agent Context Container

Next, I needed a way to encapsulate everything an agent knows about itself.

@dataclass
class AgentContext:
    """Encapsulates an agent's state and capabilities"""
    agent_id: str
    role: AgentRole
    capabilities: List[str]
    memory: List[Message]
    tools: List[str]
    created_at: datetime = None

    def __post_init__(self):
        if self.created_at is None:
            self.created_at = datetime.now()

    def get_recent_memory(self, limit: int = 5) -> List[Message]:
        """Retrieve recent conversation history"""
        return self.memory[-limit:] if self.memory else []

    def add_message(self, message: Message):
        """Add a message to memory"""
        self.memory.append(message)
        # Keep memory from growing indefinitely
        if len(self.memory) > 100:
            self.memory = self.memory[-50:]  # Keep last 50 messages

The get_recent_memory method exists because, as I discovered, agents rarely need their entire conversation history—usually just the recent context.

Implementing the Core Agent Class

Here's where things get interesting. This is the heart of the system.

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class IntelligentAgent:
    """Core agent with role-based capabilities and context awareness"""

    def __init__(self, agent_id: str, role: AgentRole):
        self.agent_id = agent_id
        self.role = role
        self.context = AgentContext(
            agent_id=agent_id,
            role=role,
            capabilities=self._initialize_capabilities(),
            memory=[],
            tools=self._initialize_tools()
        )
        logger.info(f"✨ Initialized {role.value} agent: {agent_id}")

    def _initialize_capabilities(self) -> List[str]:
        """Assign role-specific capabilities"""
        capability_map = {
            AgentRole.COORDINATOR: [
                "task_decomposition",
                "agent_orchestration", 
                "priority_management",
                "conflict_resolution"
            ],
            AgentRole.RESEARCHER: [
                "information_gathering",
                "source_validation",
                "data_synthesis",
                "fact_checking"
            ],
            AgentRole.ANALYZER: [
                "pattern_recognition",
                "statistical_analysis",
                "insight_generation",
                "trend_identification"
            ],
            AgentRole.EXECUTOR: [
                "task_execution",
                "result_validation",
                "output_formatting",
                "error_handling"
            ]
        }
        return capability_map.get(self.role, [])

    def _initialize_tools(self) -> List[str]:
        """Assign role-specific tools"""
        tools_map = {
            AgentRole.COORDINATOR: [
                "task_splitter",
                "dependency_tracker",
                "agent_selector"
            ],
            AgentRole.RESEARCHER: [
                "web_search",
                "document_parser",
                "citation_manager"
            ],
            AgentRole.ANALYZER: [
                "statistical_engine",
                "visualization_generator",
                "correlation_detector"
            ],
            AgentRole.EXECUTOR: [
                "code_runner",
                "file_handler",
                "api_client"
            ]
        }
        return tools_map.get(self.role, [])

The capability maps came from real projects. For instance, I added "conflict_resolution" to the coordinator after running into situations where multiple agents tried to work on the same subtask.

Implementing Context-Aware Message Processing

This is where the magic happens—how agents actually process incoming messages while maintaining context.

    def process_message(self, content: str, sender: str = "user", 
                       context: Optional[Dict] = None) -> Dict[str, Any]:
        """Process incoming message with full context awareness"""

        # Create and store the message
        incoming_msg = Message(
            role=sender,
            content=content,
            timestamp=datetime.now(),
            metadata=context or {}
        )
        self.context.add_message(incoming_msg)

        # Generate contextual response
        response_content = self._generate_response(content, context)

        # Create response message
        response_msg = Message(
            role=self.agent_id,
            content=response_content,
            timestamp=datetime.now(),
            metadata={
                "agent_role": self.role.value,
                "capabilities_used": self._detect_capabilities_used(content)
            }
        )
        self.context.add_message(response_msg)

        return {
            "agent_id": self.agent_id,
            "role": self.role.value,
            "response": response_content,
            "timestamp": response_msg.timestamp.isoformat(),
            "suggested_next_steps": self._suggest_next_steps(response_content)
        }

    def _generate_response(self, content: str, context: Optional[Dict]) -> str:
        """Generate role-appropriate response based on content and context"""

        recent_memory = self.context.get_recent_memory(limit=3)
        memory_context = " ".join([msg.content for msg in recent_memory])

        # Role-specific response templates (simplified for demo)
        role_templates = {
            AgentRole.COORDINATOR: self._coordinator_response,
            AgentRole.RESEARCHER: self._researcher_response,
            AgentRole.ANALYZER: self._analyzer_response,
            AgentRole.EXECUTOR: self._executor_response
        }

        response_generator = role_templates.get(self.role)
        return response_generator(content, memory_context, context)

    def _coordinator_response(self, content: str, memory: str, 
                             context: Optional[Dict]) -> str:
        """Generate coordinator-specific response"""
        return f"""As the coordinator, I've analyzed your request: '{content[:100]}'

Based on the recent context and my orchestration capabilities, here's my plan:

1. **Task Decomposition**: Breaking this into 3 primary subtasks
2. **Agent Assignment**: 
   - Research phase → Researcher agent
   - Analysis phase → Analyzer agent  
   - Execution phase → Executor agent
3. **Timeline**: Estimated 15-minute completion with parallel processing

I'll oversee the coordination and ensure all pieces come together cohesively."""

    def _researcher_response(self, content: str, memory: str,
                            context: Optional[Dict]) -> str:
        """Generate researcher-specific response"""
        return f"""From my research perspective on: '{content[:100]}'

I've activated my information gathering capabilities:

🔍 **Data Collection**: Identified 5 relevant sources
📊 **Validation**: Cross-referenced facts across multiple sources
💡 **Synthesis**: Compiled insights into actionable intelligence

Key findings: The data suggests strong correlations with current industry trends. I'm documenting all sources for validation."""

    def _analyzer_response(self, content: str, memory: str,
                          context: Optional[Dict]) -> str:
        """Generate analyzer-specific response"""
        return f"""Analyzing the patterns in: '{content[:100]}'

My analytical assessment:

📈 **Pattern Detection**: Identified 3 recurring patterns
🔗 **Correlations**: Found significant relationships in the data
💎 **Insights**: Generated 5 actionable recommendations

The statistical significance suggests this warrants deeper investigation. Preparing detailed analysis report."""

    def _executor_response(self, content: str, memory: str,
                          context: Optional[Dict]) -> str:
        """Generate executor-specific response"""
        return f"""Executing task: '{content[:100]}'

**Execution Status**:
✅ Task validation complete
⚙️ Processing with configured tools
🎯 Quality checks in progress

Preliminary results look promising. Finalizing output formatting and running validation checks before delivery."""

Building Helper Methods for Intelligence

These utility methods make agents actually useful in practice:

    def _detect_capabilities_used(self, content: str) -> List[str]:
        """Detect which capabilities this message likely requires"""
        content_lower = content.lower()
        used = []

        # Simple keyword matching (in production, I use more sophisticated NLP)
        capability_keywords = {
            "task_decomposition": ["break down", "split", "divide", "decompose"],
            "information_gathering": ["research", "find", "search", "gather"],
            "pattern_recognition": ["analyze", "pattern", "trend", "correlation"],
            "task_execution": ["execute", "run", "implement", "build"]
        }

        for capability in self.context.capabilities:
            keywords = capability_keywords.get(capability, [])
            if any(keyword in content_lower for keyword in keywords):
                used.append(capability)

        return used

    def _suggest_next_steps(self, response: str) -> List[str]:
        """Suggest logical next actions based on the response"""
        response_lower = response.lower()
        suggestions = []

        # Context-aware suggestions
        if "research" in response_lower and self.role == AgentRole.COORDINATOR:
            suggestions.append("delegate_to_researcher")
        if "analyze" in response_lower and self.role == AgentRole.COORDINATOR:
            suggestions.append("delegate_to_analyzer")
        if "execute" in response_lower and self.role == AgentRole.COORDINATOR:
            suggestions.append("delegate_to_executor")
        if "complete" in response_lower or "finished" in response_lower:
            suggestions.append("synthesize_results")

        return suggestions if suggestions else ["await_next_input"]

    def get_status(self) -> Dict[str, Any]:
        """Get current agent status and metrics"""
        return {
            "agent_id": self.agent_id,
            "role": self.role.value,
            "capabilities": self.context.capabilities,
            "tools": self.context.tools,
            "messages_processed": len(self.context.memory),
            "created_at": self.context.created_at.isoformat(),
            "status": "active"
        }

Creating the Multi-Agent Orchestration System

Now we bring it all together with an orchestrator that manages multiple agents:

class AgentSwarm:
    """Orchestrates multiple intelligent agents working together"""

    def __init__(self):
        self.agents: Dict[str, IntelligentAgent] = {}
        self.task_history: List[Dict] = []
        logger.info("🌟 Agent Swarm initialized")

    def create_agent(self, agent_id: str, role: AgentRole) -> IntelligentAgent:
        """Create and register a new agent in the swarm"""
        if agent_id in self.agents:
            logger.warning(f"Agent {agent_id} already exists, returning existing agent")
            return self.agents[agent_id]

        agent = IntelligentAgent(agent_id, role)
        self.agents[agent_id] = agent
        logger.info(f"✨ Added {role.value} to swarm: {agent_id}")
        return agent

    def ensure_complete_team(self):
        """Ensure we have all required agent types"""
        required_roles = {
            AgentRole.COORDINATOR: "coordinator",
            AgentRole.RESEARCHER: "researcher",
            AgentRole.ANALYZER: "analyzer",
            AgentRole.EXECUTOR: "executor"
        }

        for role, agent_id in required_roles.items():
            if agent_id not in self.agents:
                self.create_agent(agent_id, role)

    def coordinate_task(self, task_description: str) -> Dict[str, Any]:
        """Coordinate a complex task across multiple agents"""

        self.ensure_complete_team()

        logger.info(f"\n🎯 COORDINATING TASK: {task_description}")
        logger.info("=" * 60)

        results = {}

        # Step 1: Coordinator breaks down the task
        coordinator = self.agents["coordinator"]
        decomposition = coordinator.process_message(
            f"Decompose and plan: {task_description}",
            sender="system"
        )
        results["decomposition"] = decomposition
        logger.info(f"\n📋 COORDINATOR: {decomposition['response'][:200]}...")

        # Step 2: Researcher gathers information
        researcher = self.agents["researcher"]
        research = researcher.process_message(
            f"Research required information for: {task_description}",
            sender="coordinator",
            context={"coordinator_plan": decomposition["response"]}
        )
        results["research"] = research
        logger.info(f"\n🔍 RESEARCHER: {research['response'][:200]}...")

        # Step 3: Analyzer processes the information
        analyzer = self.agents["analyzer"]
        analysis = analyzer.process_message(
            f"Analyze findings for: {task_description}",
            sender="researcher",
            context={"research_findings": research["response"]}
        )
        results["analysis"] = analysis
        logger.info(f"\n📊 ANALYZER: {analysis['response'][:200]}...")

        # Step 4: Executor implements the solution
        executor = self.agents["executor"]
        execution = executor.process_message(
            f"Execute solution for: {task_description}",
            sender="analyzer",
            context={"analysis_results": analysis["response"]}
        )
        results["execution"] = execution
        logger.info(f"\n⚙️ EXECUTOR: {execution['response'][:200]}...")

        # Step 5: Coordinator synthesizes final result
        final_synthesis = coordinator.process_message(
            f"Synthesize final results for: {task_description}",
            sender="executor",
            context={"all_results": results}
        )
        results["final_synthesis"] = final_synthesis
        logger.info(f"\n✅ FINAL RESULT: {final_synthesis['response'][:200]}...")

        # Record task in history
        task_record = {
            "task": task_description,
            "timestamp": datetime.now().isoformat(),
            "agents_involved": list(self.agents.keys()),
            "results": results
        }
        self.task_history.append(task_record)

        return task_record

    def get_swarm_status(self) -> Dict[str, Any]:
        """Get comprehensive swarm status"""
        return {
            "total_agents": len(self.agents),
            "agent_details": {
                agent_id: agent.get_status() 
                for agent_id, agent in self.agents.items()
            },
            "tasks_completed": len(self.task_history),
            "last_task": self.task_history[-1]["task"] if self.task_history else None
        }

Creating a Demonstration

Finally, let's create a simple demo that shows everything in action:

def demonstrate_multi_agent_system():
    """Demonstrate the multi-agent system in action"""

    print("🚀 MULTI-AGENT SYSTEM DEMONSTRATION")
    print("=" * 60)

    # Initialize the swarm
    swarm = AgentSwarm()

    # Demo 1: Single agent interaction
    print("\n📍 DEMO 1: Single Agent Interaction")
    print("-" * 60)
    researcher = swarm.create_agent("demo_researcher", AgentRole.RESEARCHER)
    response = researcher.process_message(
        "What are the current trends in multi-agent AI systems?"
    )
    print(f"Response: {response['response']}")
    print(f"Suggested next steps: {response['suggested_next_steps']}")

    # Demo 2: Multi-agent coordination
    print("\n\n📍 DEMO 2: Multi-Agent Coordination")
    print("-" * 60)
    task = """
    Analyze the impact of context-aware agents on software development productivity.
    Include current research, statistical analysis, and practical recommendations.
    """

    result = swarm.coordinate_task(task)

    # Demo 3: Swarm status
    print("\n\n📍 DEMO 3: Swarm Status")
    print("-" * 60)
    status = swarm.get_swarm_status()
    print(f"Total Agents: {status['total_agents']}")
    print(f"Tasks Completed: {status['tasks_completed']}")
    print(f"Last Task: {status['last_task']}")

    print("\n✨ Demonstration Complete!")
    return swarm

# Run the demonstration
if __name__ == "__main__":
    swarm = demonstrate_multi_agent_system()

Let's Setup

Step-by-Step Installation

From my experience setting this up across different environments, here's the cleanest approach:

Step 1: Prerequisites

# Ensure you have Python 3.8 or higher
python --version

# Create a project directory
mkdir intelligent-agent-system
cd intelligent-agent-system

Step 2: Create Virtual Environment (I always recommend this)

# Create virtual environment
python -m venv venv

# Activate it
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

Step 3: Save the Code

Create a file called multi_agent_system.py and paste all the code blocks from the "Let's Get Cooking" section in order.

Step 4: Test the Installation

python multi_agent_system.py

You should see the demonstration run with all agents coordinating!

Configuration Options

As I built this out, I added several configuration options that you might want to adjust:

# At the top of multi_agent_system.py, add these constants:

# Memory management
MAX_AGENT_MEMORY = 100  # Maximum messages before trimming
RECENT_MEMORY_LIMIT = 5  # Number of recent messages to consider for context

# Logging level
LOGGING_LEVEL = logging.INFO  # Change to DEBUG for verbose output

# Agent timeouts (if you add async processing)
AGENT_TIMEOUT_SECONDS = 30

Let's Run

Basic Usage

Here's how I typically use this system in practice:

from multi_agent_system import AgentSwarm, AgentRole

# Create the swarm
swarm = AgentSwarm()

# Option 1: Use individual agents
researcher = swarm.create_agent("my_researcher", AgentRole.RESEARCHER)
result = researcher.process_message("Research topic X")
print(result['response'])

# Option 2: Coordinate complex tasks
task = "Build a comprehensive analysis of topic Y"
results = swarm.coordinate_task(task)
print(results['final_synthesis']['response'])

Advanced Usage Patterns

From my experience, here are some patterns I've found useful:

Pattern 1: Custom Agent Configuration

# Create specialized agents with custom IDs
swarm.create_agent("financial_researcher", AgentRole.RESEARCHER)
swarm.create_agent("technical_analyzer", AgentRole.ANALYZER)

# Use them for domain-specific tasks
financial_result = swarm.agents["financial_researcher"].process_message(
    "Analyze Q4 market trends"
)

Pattern 2: Chaining Tasks

# First task
task1_result = swarm.coordinate_task("Research market conditions")

# Use results in second task
task2_result = swarm.coordinate_task(
    f"Based on these findings: {task1_result['final_synthesis']['response'][:500]}, "
    f"develop an implementation strategy"
)

Pattern 3: Monitoring and Debugging

# Get detailed status
status = swarm.get_swarm_status()
for agent_id, agent_status in status['agent_details'].items():
    print(f"{agent_id}: {agent_status['messages_processed']} messages processed")

# Review task history
for task in swarm.task_history:
    print(f"Task: {task['task']}")
    print(f"Completed: {task['timestamp']}")

Closing Thoughts

In my opinion, the most important lesson is this: successful multi-agent systems aren't about making individual agents smarter—they're about making agents work together intelligently.

What You've Learned

Through this journey, you've gained:

Architectural Understanding: How to design multi-agent systems with clear roles and responsibilities
Context Management: Techniques for maintaining and sharing context across agents
Practical Implementation: Working code you can deploy and extend
Production Patterns: Real-world approaches to agent coordination and orchestration

Where to Go From Here

From my experience, here are the natural next steps:

Add Real AI Integration: Connect these agents to actual LLMs (GPT-4, Claude, etc.) for dynamic responses
Implement Async Processing: Make agents work in parallel for better performance
Build Persistence: Add database storage for long-term memory and task history
Create Monitoring: Implement proper logging and metrics for production use
Add Error Handling: Robust error recovery and retry mechanisms

The foundation is here. As per my observation, the developers who succeed with multi-agent systems are those who start simple (like we did) and iterate based on real-world needs.

I encourage you to take this code, experiment with it, break it, fix it, and make it your own. That's how I learned, and I think that's how you'll learn best too.

What complex task will your agents solve first?

Building Advanced AI Agents with LangChain's DeepAgents: A Hands-On Guide

samadhi patil — Wed, 29 Oct 2025 03:53:49 +0000

Building Advanced AI Agents with LangChain's DeepAgents: A Hands-On Guide

When Simple Tool-Calling Isn't Enough—Building Agents That Actually Think

TL;DR

From my experience working with LLM agents, the biggest challenge isn't getting them to call a function—it's getting them to handle complex, multi-step workflows without falling apart. Traditional agents are like assistants who forget what they were doing mid-task. LangChain's DeepAgents changes this completely. In my opinion, it's the first framework that truly enables agents to plan strategically, remember context persistently, delegate to specialists, and iterate toward quality. This guide walks you through building a real AI policy research agent that I designed to demonstrate these capabilities. You'll see actual code, understand the design decisions behind each piece, and get a working system that produces professional research reports autonomously.

Introduction

Let me tell you about a problem that drove me crazy for months.

Building an agent that calls a single tool? Easy. Getting an LLM to search the web or query a database? Done it a hundred times. But when I tried to build something more sophisticated—an agent that could research a complex topic, synthesize findings, review its own work, and produce a polished report—everything broke down.

The agents I built were what I now call "shallow." They'd execute one step, maybe two, then lose track of what they were doing. Token limits would overflow. Context would get muddled. Quality would suffer because there was no review process. As per my experience, this is the wall that most developers hit when moving from demos to production AI systems.

Then I discovered LangChain's DeepAgents library, and honestly, it changed how I think about agent architecture entirely.

What struck me first was the philosophy behind it. The DeepAgents team studied production systems like Claude Code and Deep Research—real applications handling genuinely complex workflows—and extracted the patterns that made them work. The result is a framework that gives agents four critical capabilities that shallow agents lack:

Planning tools that let agents break down tasks strategically before diving in. File system access that provides persistent memory outside the conversation context. Sub-agent creation that enables delegation to focused specialists. And long-term memory through LangGraph's Store that maintains state across sessions.

In my view, these aren't just nice features—they're fundamental architectural requirements for any agent doing serious work.

So I decided to build something real to prove it out. Not a toy demo, but an actual policy research system that could rival human analysis. The kind of agent I wish I'd had when I was doing regulatory research manually. In this guide, I'll walk you through exactly how I built it, the decisions I made along the way, and why each piece matters.

What's This Article About?

This article is my attempt to show you—through actual working code—how to build an AI agent that thinks strategically rather than just reacting to inputs.

Here's What We're Building:

Based on my experience with various agent frameworks, I designed a policy research system that demonstrates every key capability of the DeepAgents architecture. This isn't theoretical—it's a complete implementation that I've tested extensively.

The agent can:

Accept complex research questions about AI regulations (like "What's the latest on the EU AI Act?")
Break down the research into logical steps using planning tools
Delegate the actual investigation to a specialized research sub-agent
Save intermediate work to files so context never overflows
Invoke a critique sub-agent to review draft quality
Iterate based on feedback to produce professional reports

What You'll Learn (From My Mistakes and Successes):

Through building this, I learned several critical patterns:

Strategic Planning: In my opinion, the write_todos tool is underrated. I initially skipped it, thinking agents could just "figure it out." Wrong. Explicit planning transforms chaotic execution into methodical workflow.
Context Management: This one burned me hard. My early agents would hit token limits mid-research and forget everything. File system operations (read_file, write_file, edit_file) solve this completely. As per my experience, this is non-negotiable for complex tasks.
Sub-Agent Delegation: I used to cram everything into one mega-prompt. Bad idea. Specialized sub-agents—each with focused responsibilities—produce dramatically better results. One agent researches, another critiques. Clean separation of concerns.
Custom System Prompts: Generic prompts produce generic results. I learned to design detailed, workflow-specific instructions that guide agents step-by-step through complex processes.
Tool Integration: External capabilities like web search aren't add-ons—they're core to agent functionality. I'll show you how I integrated Tavily search seamlessly.
Model Flexibility: One thing I love about DeepAgents is model-agnostic design. I've run this same system on OpenAI, Gemini, and Anthropic models interchangeably.

The Technical Architecture (How I Designed It):

When I sat down to architect this system, I thought about three layers:

Layer 1: Main Orchestrator

Receives research queries
Plans the workflow
Coordinates sub-agents
Manages file system state
Delivers final output

Layer 2: Specialized Sub-Agents

Research Sub-Agent: Conducts deep investigation using web search
Critique Sub-Agent: Reviews outputs for quality, accuracy, completeness

Layer 3: Infrastructure

File system for persistent state
LangGraph Store for long-term memory
Tavily API for real-time information gathering

From my perspective, this layered approach is what enables scalability. Each component has a single, clear responsibility.

Why This Pattern Matters:

In my experience building production AI systems, I've learned that architecture matters more than model choice. A well-designed agent with GPT-3.5 will outperform a poorly designed agent with GPT-4. The patterns you'll learn here—planning, delegation, state management, quality control—apply regardless of which LLM you're using or what domain you're working in.

Whether you're building content creation pipelines, code generation systems, data analysis workflows, or customer service automation, these fundamentals remain constant.

Tech Stack

Component	Technology	Purpose
Agent Framework	LangChain DeepAgents	Core library for building deep, planful agents with context management
LLM Provider (Primary)	OpenAI GPT-4o	Main language model for agent reasoning and generation
LLM Provider (Alternative)	Google Gemini 2.5 Flash	Alternative model option (fully interchangeable)
Default Model	Claude Sonnet 4.5	DeepAgents internal default when no model specified
Web Search	Tavily API	Real-time internet search tool for research gathering
State Management	LangGraph Store	Long-term memory and session persistence
Model Initialization	LangChain `init_chat_model`	Unified interface for multiple LLM providers
File Operations	Built-in File Tools	Context management through `read_file`, `write_file`, `edit_file`, `ls`
Planning	Built-in `write_todos`	Task breakdown and progress tracking
Sub-Agent Management	Built-in `task` tool	Creation and delegation to specialized sub-agents
Environment Management	Python `os.environ`	API key and configuration management
Development Environment	Jupyter Notebook	Interactive development and testing

Why Read It?

If you're building AI agents that do more than simple tool calls, this article is essential reading. Here's why:

1. Move Beyond Basic Agents

Most tutorials show you how to build agents that can call a function or search the web. But when you try to scale those patterns to real-world applications—research assistants, code generation systems, multi-step workflows—you hit a wall. This article shows you how to break through that limitation with architectures designed for complexity.

2. Solve Real Production Challenges

You'll learn solutions to problems you'll actually face:

Context overflow: How to handle tasks that exceed token limits through file-based state management
Task planning: How to make agents think strategically instead of reactively
Quality control: How to build self-reviewing systems through sub-agent delegation
Memory management: How to maintain state across sessions for long-running projects
Modularity: How to break complex agents into focused, maintainable components

3. Complete, Working Implementation

This isn't pseudo-code or theoretical concepts. You get:

Full source code for a production-quality research agent
Step-by-step explanations of each component
Design decisions explained in context
Multiple LLM provider options (OpenAI, Gemini, Anthropic)
Ready-to-run Jupyter notebook with all dependencies
Professional prompt engineering examples

4. Learn Patterns You Can Reuse

The patterns demonstrated here apply far beyond policy research:

Content creation systems with review workflows
Code generation with testing and refinement
Data analysis with iterative exploration
Customer service with escalation and specialization
Report generation with research and synthesis
Any multi-stage workflow requiring planning and quality control

5. Understand the "Why" Behind Design Choices

Each section explains not just what the code does, but why it's structured that way:

Why file systems prevent context overflow
Why sub-agents improve focus and quality
Why custom prompts are critical for complex tasks
Why planning tools enable strategic execution
Why this architecture scales where basic agents don't

6. Stay Current with AI Agent Evolution

The AI agent landscape is evolving rapidly from simple tool-calling to sophisticated, planful systems. DeepAgents represents the cutting edge of this evolution, incorporating lessons from production systems like Claude Code. Understanding this architecture prepares you for where the field is heading.

7. Practical Business Value

These techniques have immediate business applications:

Automating research and analysis workflows
Building intelligent content creation pipelines
Creating self-improving code generation systems
Developing sophisticated customer support agents
Implementing complex decision-making systems

Whether you're a developer building production AI systems, a researcher exploring agent architectures, or a technical leader evaluating AI capabilities, this guide provides practical knowledge you can apply immediately.

Let's Design

The Architecture Philosophy

When I set out to build this policy research agent, the fundamental question was: how do we create an AI system that thinks strategically rather than reactively? Traditional agents process tasks linearly—receive input, call tools, return output. But complex research requires something different: planning, delegation, iteration, and quality control.

The DeepAgents architecture addresses this through four interconnected capabilities that work together to enable sophisticated behavior:

1. Strategic Planning Layer

The Problem: Basic agents jump straight into action without considering the best approach. They can't break down complex tasks or track progress across multiple steps.

The Solution: DeepAgents provides a write_todos tool that enables agents to:

Decompose large research questions into specific subtasks
Create actionable checklists before starting work
Track which steps are complete and which remain
Adjust the plan dynamically as new information emerges

In Our Implementation: The main agent first saves the research question to question.txt, then creates a todo list outlining the research workflow: gather information, analyze findings, write the report, critique the draft, and finalize. This planning step transforms reactive execution into strategic orchestration.

2. Persistent Context Management

The Problem: LLMs have token limits. Complex tasks generate large amounts of intermediate data—research findings, draft content, notes—that quickly overflow the context window. Once that happens, the agent loses track of its work.

The Solution: DeepAgents integrates file system operations (read_file, write_file, edit_file, ls) that allow agents to:

Store intermediate results outside the conversation context
Retrieve specific information when needed
Build up complex outputs incrementally
Continue work across multiple sessions

In Our Implementation: The agent uses three key files:

question.txt: Stores the original research query for reference
final_report.md: Holds the evolving research report through drafts and revisions
Working memory in file system: Prevents context overflow even with extensive research

This file-based approach means the agent can handle research projects of any size without hitting token limits.

3. Specialized Sub-Agent Delegation

The Problem: Trying to do everything in one agent leads to bloated context, unclear responsibilities, and lower quality outputs. Research requires different skills than critique. Gathering information is different from synthesizing it.

The Solution: DeepAgents allows creation of focused sub-agents via the task tool. Each sub-agent has:

Its own specialized system prompt defining clear responsibilities
Dedicated tools appropriate to its function
Isolated context that doesn't clutter the main agent
Single, well-defined output that returns to the main agent

In Our Implementation: We use two sub-agents:

Policy Research Sub-Agent:

Purpose: Conduct in-depth investigation of AI regulations and policies
Tools: Internet search via Tavily API
Instructions: Find key updates, cite sources, compare global approaches, write professionally
Output: Comprehensive research findings passed back to main agent

Policy Critique Sub-Agent:

Purpose: Quality control and editorial review
Tools: File reading to access the draft report
Instructions: Check accuracy, verify citations, assess balance and tone
Output: Constructive feedback without direct modification

This separation of concerns means each sub-agent can focus deeply on its specialty without distractions.

4. Intelligent Workflow Orchestration

The Problem: Who coordinates all these pieces? How does the main agent know when to delegate, when to write, when to revise?

The Solution: A carefully crafted custom system prompt that serves as the "brain" of the operation. This prompt:

Defines the overall workflow step-by-step
Specifies when to invoke each sub-agent
Enforces quality standards and formatting requirements
Provides context about the agent's role and capabilities

In Our Implementation: The policy_research_instructions prompt creates a clear five-step workflow:

Save the Question: Write user query to question.txt for reference
Delegate Research: Invoke policy-research-agent to gather comprehensive information
Synthesize Report: Write findings to final_report.md with proper structure and citations
Quality Review: Optionally invoke policy-critique-agent for editorial feedback
Finalize: Revise based on feedback and output the complete professional report

The prompt also enforces standards:

Markdown formatting with clear section headers
Citation style using [Title](URL) format
Professional, neutral tone suitable for policy briefings
Sources section at the end

The Complete Flow

Here's how everything works together when a user asks: "What are the latest updates on the EU AI Act and its global impact?"

User Query
    ↓
Main Deep Agent
    ↓
1. Saves question to question.txt (context management)
    ↓
2. Creates todo list (planning)
    ↓
3. Invokes Policy Research Sub-Agent
    ↓
    Research Sub-Agent:
    - Uses Tavily search for EU AI Act updates
    - Finds regulations, news, analysis
    - Compares global approaches
    - Formats findings professionally
    - Returns comprehensive research to Main Agent
    ↓
4. Main Agent writes draft to final_report.md
    ↓
5. Invokes Policy Critique Sub-Agent
    ↓
    Critique Sub-Agent:
    - Reads final_report.md
    - Checks accuracy and citations
    - Verifies balanced analysis
    - Returns constructive feedback to Main Agent
    ↓
6. Main Agent revises draft based on feedback
    ↓
7. Outputs final professional policy report

Why This Architecture Scales

This design handles complexity through:

Modularity: Each component has a single, clear responsibility
Extensibility: Easy to add new sub-agents for different research domains
Robustness: File system prevents context overflow regardless of task size
Quality: Built-in review cycle ensures professional outputs
Flexibility: Works with any LLM provider (OpenAI, Gemini, Anthropic, etc.)
Maintainability: Clear separation between orchestration, execution, and review

Unlike basic agents that collapse under complexity, this architecture gets stronger as tasks become more sophisticated. The planning layer ensures strategic execution, the file system prevents memory issues, sub-agents maintain focus, and the workflow orchestration keeps everything coordinated.

This is the fundamental difference between shallow and deep agents: the ability to think, plan, delegate, and iterate rather than just react and respond.

Let's Get Cooking

Now let's build this system step by step, understanding each component and why it matters.

Step 1: Install Dependencies and Setup Environment

First, we need the core libraries that power our deep agent system.

!pip install deepagents tavily-python langchain-google-genai langchain-openai

What We're Installing:

deepagents: The core LangChain library providing planning, file tools, and sub-agent capabilities
tavily-python: Client for Tavily web search API (our research tool)
langchain-google-genai: Integration for Google's Gemini models (alternative LLM)
langchain-openai: Integration for OpenAI's GPT models (primary LLM)

Why These Dependencies: DeepAgents is model-agnostic, so we install multiple LLM provider options. Tavily provides the real-time web search capability our research sub-agent needs.

Step 2: Configure API Keys

import os
from getpass import getpass

# Required for web search functionality
os.environ['TAVILY_API_KEY'] = getpass('Enter Tavily API Key: ')

# Choose your preferred LLM provider
os.environ['OPENAI_API_KEY'] = getpass('Enter OpenAI API Key: ')

# Optional: If using Gemini instead
# os.environ['GOOGLE_API_KEY'] = getpass('Enter Google API Key: ')

Why This Matters:

The Tavily API key enables our research sub-agent to search the web for real-time information
You can use either OpenAI or Google (or other providers)—DeepAgents works seamlessly with all of them
Using getpass keeps your API keys secure and out of your code

Getting API Keys:

Tavily: Sign up at tavily.com for web search access
OpenAI: Get your key from platform.openai.com
Google: Access through Google AI Studio

Step 3: Import Core Libraries

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

# Initialize the search client
tavily_client = TavilyClient()

Why We Import These:

typing.Literal: Enables type hints for our search function parameters
TavilyClient: Provides the interface to web search functionality
create_deep_agent: The main factory function for building our deep agent system

Design Note: We initialize the Tavily client at the module level because it will be used inside our tool function, which gets called by the sub-agent.

Step 4: Define the Web Search Tool

from typing import Literal

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search and return relevant results.

    This tool allows agents to gather real-time information from the internet.
    """
    search_docs = tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
    return search_docs

What This Tool Does:

Accepts a search query string and optional parameters
Calls Tavily's search API to find relevant web content
Returns structured search results (titles, URLs, snippets, content)
Supports different topic categories (general, news, finance)

Why We Structure It This Way:

Clear docstring: Helps the LLM understand when and how to use this tool
Typed parameters: The Literal type hint tells the agent exactly what topic values are valid
Sensible defaults: 5 results and general search work for most cases
Raw content option: Can retrieve full page content when needed for deep research

How the Agent Uses It: The research sub-agent will automatically call this function when it needs to gather information about AI policies, regulations, or related topics.

Step 5: Create the Research Sub-Agent Configuration

sub_research_prompt = """
You are a specialized AI policy researcher.
Conduct in-depth research on government policies, global regulations, and ethical frameworks related to artificial intelligence.

Your answer should:
- Provide key updates and trends
- Include relevant sources and laws (e.g., EU AI Act, U.S. Executive Orders)
- Compare global approaches when relevant
- Be written in clear, professional language

Only your FINAL message will be passed back to the main agent.
"""

research_sub_agent = {
    "name": "policy-research-agent",
    "description": "Used to research specific AI policy and regulation questions in depth.",
    "system_prompt": sub_research_prompt,
    "tools": [internet_search],
}

Breaking This Down:

The System Prompt:

Defines the sub-agent's identity and expertise (AI policy researcher)
Specifies output requirements (updates, sources, comparisons)
Sets quality standards (clear, professional language)
Reminds the agent that only the final message returns to the parent

Why This Prompt Works:

Focused role: "Specialized AI policy researcher" gives clear identity
Concrete requirements: The bullet points tell the agent exactly what to include
Examples: Mentioning "EU AI Act, U.S. Executive Orders" helps the agent understand scope
Important constraint: "Only your FINAL message will be passed back" prevents verbose intermediate steps

The Configuration Dictionary:

name: Identifier the main agent uses to invoke this sub-agent
description: Helps the main agent decide when to delegate to this specialist
system_prompt: The instructions that define this sub-agent's behavior
tools: List of functions this sub-agent can call (just internet search in this case)

Design Philosophy: This sub-agent has ONE job: research AI policies thoroughly. It has the internet search tool to do that job well, and its prompt focuses it entirely on that task. No distractions, no scope creep.

Step 6: Create the Critique Sub-Agent Configuration

sub_critique_prompt = """
You are a policy editor reviewing a report on AI governance.
Check the report at `final_report.md` and the question at `question.txt`.

Focus on:
- Accuracy and completeness of legal information
- Proper citation of policy documents
- Balanced analysis of regional differences
- Clarity and neutrality of tone

Provide constructive feedback, but do NOT modify the report directly.
"""

critique_sub_agent = {
    "name": "policy-critique-agent",
    "description": "Critiques AI policy research reports for completeness, clarity, and accuracy.",
    "system_prompt": sub_critique_prompt,
}

The Critique System Prompt:

Defines role as editorial reviewer (not researcher)
Specifies exactly what files to check
Lists concrete quality criteria to evaluate
Explicitly prohibits direct modification (feedback only)

Why No Tools Here: Unlike the research sub-agent, the critique agent doesn't need internet search. It has access to the file system (built into all DeepAgents) to read the draft report and provide feedback. That's all it needs.

The Review Criteria:
Each bullet point gives the critic something specific to check:

Accuracy and completeness: Are the facts right? Is anything missing?
Proper citation: Are sources properly attributed?
Balanced analysis: Are regional differences fairly represented?
Clarity and neutrality: Is the tone appropriate for policy work?

Why "Do NOT modify": This is crucial. We want the critique agent to identify issues and suggest improvements, but leave the actual editing to the main agent. This separation prevents the critic from overstepping and ensures the main agent maintains control of the final output.

The Workflow: Main agent → writes draft → critique agent reviews → provides feedback → main agent revises. Clean separation of concerns.

Step 7: Design the Main Agent System Prompt

policy_research_instructions = """
You are an expert AI policy researcher and analyst.
Your job is to investigate questions related to global AI regulation, ethics, and governance frameworks.

1️⃣ Save the user's question to `question.txt`
2️⃣ Use the `policy-research-agent` to perform in-depth research
3️⃣ Write a detailed report to `final_report.md`
4️⃣ Optionally, ask the `policy-critique-agent` to critique your draft
5️⃣ Revise if necessary, then output the final, comprehensive report

When writing the final report:
- Use Markdown with clear sections (## for each)
- Include citations in [Title](URL) format
- Add a ### Sources section at the end
- Write in professional, neutral tone suitable for policy briefings
"""

This Is the Brain of the Operation. Let me explain why each part matters:

Identity and Purpose ("You are an expert AI policy researcher..."):

Establishes the agent's high-level role
Sets expectations for quality and expertise
Provides context for decision-making

The Numbered Workflow (Steps 1-5):
This is the most important part. It gives the agent a clear execution plan:

Save the question: Creates a persistent reference the agent can check later
Delegate to research sub-agent: Uses the specialist to gather information
Write the report: Synthesizes findings into a structured document
Get critique: Optionally invokes the editor for quality review
Finalize: Revises based on feedback and delivers the result

Why Numbered Steps Work: They create a mental model for the LLM. The agent knows there's a sequence, knows what comes next, and can track progress.

The Formatting Requirements (Markdown, citations, etc.):
These aren't just style preferences—they're quality controls:

Markdown sections: Ensures structured, navigable reports
Title citations: Makes sources clickable and verifiable
Sources section: Consolidates references for easy checking
Professional tone: Appropriate for the policy analysis domain

Why This Prompt Architecture Works:

Clear role: The agent knows who it is
Explicit workflow: The agent knows what to do
Quality standards: The agent knows how to do it well
File-based state: The agent can handle any complexity
Delegation model: The agent knows when to get help

This is the difference between an agent that wanders aimlessly and one that executes strategically.

Step 8: Initialize the Main Deep Agent

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Initialize with OpenAI GPT-4o
model = init_chat_model(model="openai:gpt-4o")

# Alternative: Use Google Gemini instead
# model = init_chat_model(model="google_genai:gemini-2.5-flash")

# Create the deep agent
agent = create_deep_agent(
    model=model,
    tools=[internet_search],
    system_prompt=policy_research_instructions,
    subagents=[research_sub_agent, critique_sub_agent],
)

What's Happening Here:

Model Initialization:

model = init_chat_model(model="openai:gpt-4o")

init_chat_model is LangChain's unified interface for any LLM
Format is "provider:model_name"
Switching providers is as simple as changing this string
If you don't specify a model, DeepAgents defaults to Claude Sonnet 4.5

Creating the Deep Agent:

agent = create_deep_agent(...)

This single function call assembles the entire complex system:

model: The LLM that powers reasoning and decision-making
tools: Functions the main agent can call directly (internet search)
system_prompt: The workflow instructions we defined above
subagents: The specialized agents available for delegation

What create_deep_agent Does Internally:

Sets up the planning system (todo management)
Configures file system tools (read, write, edit, ls)
Registers the sub-agents for delegation
Integrates the custom tools we provided
Wraps everything in a LangGraph workflow
Connects to the LLM for execution

Why This Is Powerful: In these few lines, we've created an agent that can:

Plan and track complex tasks
Search the web for information
Delegate to specialized sub-agents
Manage persistent state through files
Maintain long-term memory
Execute multi-step workflows

All the complexity is abstracted away by create_deep_agent.

Model Flexibility Note: Notice how easy it is to switch between OpenAI and Gemini (or any other provider). This is intentional—DeepAgents is designed to be model-agnostic. The architecture works the same regardless of which LLM powers it.

Step 9: Invoke the Agent with a Research Query

query = "What are the latest updates on the EU AI Act and its global impact?"

result = agent.invoke({"messages": [{"role": "user", "content": query}]})

What Happens When You Run This:

The Invocation Format:

{"messages": [{"role": "user", "content": query}]}

This is the standard LangChain message format. The agent receives it as if it were a chat conversation.

The Execution Flow (what happens behind the scenes):

Main Agent Receives Query
- Reads the question: "What are the latest updates on the EU AI Act..."
- Consults its system prompt (the numbered workflow)
- Decides to start at step 1
Step 1: Save the Question

   # Agent calls: write_file(path="question.txt", content=query)

Uses built-in file tool to persist the question
Creates a reference point for later use

Step 2: Delegate to Research Sub-Agent

   # Agent calls: task(agent="policy-research-agent", 
   #                   instruction="Research the EU AI Act updates and global impact")

Research sub-agent receives the task
Calls internet_search("EU AI Act latest updates")
Calls internet_search("EU AI Act global impact")
Calls internet_search("AI regulations worldwide comparison")
Synthesizes findings into comprehensive report
Returns final message to main agent

Step 3: Write the Draft Report

   # Agent calls: write_file(path="final_report.md", content=research_findings)

Takes sub-agent's research
Structures it into Markdown sections
Includes citations in Title format
Writes to file system

Step 4: Get Editorial Critique

   # Agent calls: task(agent="policy-critique-agent",
   #                   instruction="Review the draft report for quality")

Critique sub-agent reads final_report.md
Checks accuracy, citations, balance, tone
Provides constructive feedback
Returns review to main agent

Step 5: Revise and Finalize

   # Agent calls: edit_file(path="final_report.md", edits=improvements)

Main agent incorporates feedback
Refines sections based on critique
Ensures all quality standards are met
Outputs final comprehensive report

The Result: result contains the complete execution trace, including:

All intermediate steps taken
Tool calls made by each agent
Sub-agent invocations and responses
The final policy report
File system changes

Viewing the Output:

# Get just the final report
print(result['messages'][-1]['content'])

# Or access the file directly
# agent.read_file("final_report.md")

What Makes This Different from Basic Agents:

Basic agent: Search → Generate → Done (one step, no planning)
Deep agent: Plan → Delegate → Research → Write → Critique → Revise → Deliver (strategic, multi-stage)

The deep agent produces higher quality results because it:

Plans before acting
Uses specialists for specific tasks
Iterates based on feedback
Manages complexity through file system
Maintains focus through sub-agent delegation

This is the power of the DeepAgents architecture in action.

Let's Setup

Prerequisites

Before running this implementation, ensure you have:

1. Python Environment

Python 3.8 or higher
pip package manager
Jupyter Notebook or JupyterLab (recommended for interactive development)

2. API Access

Tavily API Key:
- Sign up at https://tavily.com
- Free tier available for testing
- Required for web search functionality
LLM Provider API Key (choose one):
- OpenAI: Get key from https://platform.openai.com
- Google AI: Get key from Google AI Studio
- Anthropic: Get key from https://console.anthropic.com
- Note: DeepAgents defaults to Claude Sonnet 4.5 if no model specified

3. Development Environment

Code editor (VS Code, PyCharm, or similar)
Terminal access for pip installations
Stable internet connection for API calls

Installation Steps

Step 1: Set Up Virtual Environment (Recommended)

# Create a virtual environment
python -m venv deepagents-env

# Activate it (Windows)
deepagents-env\Scripts\activate

# Activate it (Mac/Linux)
source deepagents-env/bin/activate

Step 2: Install Core Dependencies

pip install deepagents tavily-python langchain-google-genai langchain-openai

Step 3: Verify Installation

# Test imports
import deepagents
from tavily import TavilyClient
from langchain.chat_models import init_chat_model

print("✅ All dependencies installed successfully")

Step 4: Configure Environment Variables

Create a .env file in your project directory:

TAVILY_API_KEY=your_tavily_key_here
OPENAI_API_KEY=your_openai_key_here
# GOOGLE_API_KEY=your_google_key_here  # If using Gemini

Or set them programmatically:

import os
from getpass import getpass

os.environ['TAVILY_API_KEY'] = getpass('Enter Tavily API Key: ')
os.environ['OPENAI_API_KEY'] = getpass('Enter OpenAI API Key: ')

Step 5: Test Your Setup

Run this quick test to verify everything works:

from tavily import TavilyClient
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Test Tavily connection
client = TavilyClient()
test_search = client.search("test query", max_results=1)
print("✅ Tavily search working")

# Test model initialization
model = init_chat_model(model="openai:gpt-4o")
print("✅ LLM connection working")

# Test DeepAgents
simple_agent = create_deep_agent(model=model, tools=[])
print("✅ DeepAgents framework working")

print("\n🎉 Setup complete! You're ready to build deep agents.")

Project Structure

Organize your project like this:

deepagents-project/
│
├── deepagents_research.ipynb    # Main notebook (from GitHub)
├── .env                          # Your API keys (DO NOT commit to git)
├── .gitignore                    # Ignore .env and other sensitive files
├── requirements.txt              # Dependency list
└── README.md                     # Project documentation

Common Setup Issues and Solutions

Issue: "ModuleNotFoundError: No module named 'deepagents'"

Solution: Make sure you activated your virtual environment before installing

Issue: "Invalid API key" errors

Solution: Double-check your API keys, ensure no extra spaces, verify they're active

Issue: "Rate limit exceeded" from Tavily or OpenAI

Solution: Check your API usage limits, consider upgrading your plan, or add rate limiting

Issue: File permission errors

Solution: Ensure you have write permissions in your working directory

Quick Start Checklist

[ ] Python 3.8+ installed
[ ] Virtual environment created and activated
[ ] Dependencies installed (pip install deepagents tavily-python langchain-google-genai langchain-openai)
[ ] Tavily API key obtained and configured
[ ] LLM provider API key obtained and configured
[ ] Test imports successful
[ ] Tavily search test successful
[ ] Model initialization test successful
[ ] Ready to run the full implementation

Next Steps

Once your setup is complete, you can:

Download the complete code from the GitHub repository
Run through the implementation step by step
Experiment with different research queries
Modify sub-agent prompts for different domains
Add additional sub-agents for specialized tasks

6. Integrate with your own applications

Let's Run

Running the Complete System

Now that everything is set up, let's execute the full policy research workflow.

Step 1: Start Jupyter Notebook

jupyter notebook

Navigate to your deepagents_research.ipynb file and open it.

Step 2: Run Initialization Cells

Execute cells in order to:

Import dependencies
Configure API keys
Define the search tool
Create sub-agent configurations
Set up the main agent prompt
Initialize the deep agent

Step 3: Execute a Research Query

Run the invocation cell:

query = "What are the latest updates on the EU AI Act and its global impact?"
result = agent.invoke({"messages": [{"role": "user", "content": query}]})

What You'll See During Execution:

The agent will output its thought process and actions:

💭 Thought: I need to research the EU AI Act updates systematically.

🔧 Action: write_file
   Path: question.txt
   Content: What are the latest updates on the EU AI Act...

✅ Observation: File created successfully

💭 Thought: Now I'll delegate the research to my specialized sub-agent.

🔧 Action: task
   Agent: policy-research-agent
   Instruction: Research latest EU AI Act updates and global impact

   [Sub-agent starts executing...]

   🔍 Searching: "EU AI Act 2025 updates"
   🔍 Searching: "EU AI Act global impact"
   🔍 Searching: "AI regulations worldwide comparison"

   ✅ Sub-agent complete: [Returns comprehensive research findings]

💭 Thought: I have the research. Now I'll structure it into a report.

🔧 Action: write_file
   Path: final_report.md
   Content: [Structured Markdown report with citations]

✅ Observation: Report written

💭 Thought: Let me get editorial feedback to ensure quality.

🔧 Action: task
   Agent: policy-critique-agent
   Instruction: Review the draft report

   [Critique sub-agent executes...]

   ✅ Sub-agent complete: [Returns constructive feedback]

💭 Thought: Based on the feedback, I'll make final revisions.

🔧 Action: edit_file
   Path: final_report.md
   Edits: [Improvements based on critique]

✅ Final report complete!

Step 4: View the Results

Access the final report:

# Option 1: From the result object
final_message = result['messages'][-1]['content']
print(final_message)

# Option 2: Read from file system
report = agent.read_file("final_report.md")
print(report)

# Option 3: View all generated files
files = agent.list_files()
print("Files created:", files)

Example Output Structure:

The final report will look something like this:

# Latest Updates on the EU AI Act and Global Impact

## Executive Summary

The EU AI Act, formally adopted in [date], represents the world's first 
comprehensive regulatory framework for artificial intelligence...

## Key Updates

### Regulatory Timeline
- Final text published: [date]
- Implementation begins: [date]
- Full enforcement: [date]

### Core Provisions
- Risk-based classification system
- Prohibited AI practices
- High-risk AI requirements
- Transparency obligations

## Global Impact

### Regional Responses

**United States**: The U.S. has responded with executive orders...

**China**: China's AI regulations focus on...

**United Kingdom**: The UK has taken a different approach...

### International Standards

The EU AI Act is influencing global AI governance through...

## Industry Implications

Organizations worldwide are adapting to these regulations by...

## Sources

- [EU AI Act Official Text](https://example.com)
- [Global AI Policy Tracker](https://example.com)
- [Industry Analysis Report](https://example.com)

Step 5: Try Different Queries

Experiment with various research questions:

# Example 1: Different topic
query1 = "How are different countries regulating AI in healthcare?"
result1 = agent.invoke({"messages": [{"role": "user", "content": query1}]})

# Example 2: Specific comparison
query2 = "Compare AI ethics frameworks between US, EU, and China"
result2 = agent.invoke({"messages": [{"role": "user", "content": query2}]})

# Example 3: Narrow focus
query3 = "What are the key compliance requirements for AI systems under the EU AI Act?"
result3 = agent.invoke({"messages": [{"role": "user", "content": query3}]})

Step 6: Inspect the Workflow

View the complete execution trace:

# See all steps taken
for msg in result['messages']:
    role = msg.get('role', 'system')
    content = msg.get('content', '')[:200]  # First 200 chars
    print(f"\n[{role}]: {content}...")

# Count tool calls
tool_calls = [msg for msg in result['messages'] if msg.get('tool_calls')]
print(f"\nTotal tool calls: {len(tool_calls)}")

# See sub-agent invocations
sub_agent_calls = [call for call in tool_calls if 'task' in str(call)]
print(f"Sub-agent invocations: {len(sub_agent_calls)}")

Performance Metrics:

Monitor agent performance:

import time

start_time = time.time()
result = agent.invoke({"messages": [{"role": "user", "content": query}]})
end_time = time.time()

execution_time = end_time - start_time
print(f"⏱️  Total execution time: {execution_time:.2f} seconds")

# Token usage (if available from your LLM provider)
# This varies by provider
if 'usage' in result:
    print(f"🎫 Tokens used: {result['usage']}")

Debugging Tips:

If something goes wrong:

Check API Keys: Verify all keys are set correctly

print("Tavily:", "✅" if os.getenv('TAVILY_API_KEY') else "❌")
print("OpenAI:", "✅" if os.getenv('OPENAI_API_KEY') else "❌")

Test Components Individually:

# Test search function
test_result = internet_search("test query", max_results=1)
print("Search working:", "✅" if test_result else "❌")

# Test model
test_response = model.invoke([{"role": "user", "content": "Hi"}])
print("Model working:", "✅" if test_response else "❌")

Enable Verbose Logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Check File System:

# List all files created by agent
files = agent.list_files()
print("Files created:", files)

# Read any file to debug
content = agent.read_file("question.txt")
print("Question file:", content)

Expected Behavior:

Normal execution: 30-90 seconds depending on query complexity
Sub-agent calls: Typically 2 (research + critique)
File operations: 3-5 (write question, write report, edit report)
Search queries: 3-7 (depending on research depth)

Success Indicators:

✅ Agent completes all workflow steps
✅ Final report is well-structured Markdown
✅ Sources are properly cited
✅ Report addresses the original question
✅ Professional tone maintained throughout
✅ No errors or crashes

Next Experiments:

Once you have it working:

Modify sub-agent prompts for different domains (technology, finance, healthcare)
Add additional sub-agents (fact-checker, summarizer, translator)
Adjust search parameters (more results, different topics)
Try different LLM models (compare GPT-4 vs Gemini vs Claude)
Integrate with your own data sources or APIs

Closing Thoughts

We've just built something remarkable: an AI agent that doesn't just respond to queries but thinks strategically, delegates to specialists, manages complex state, and iterates toward high-quality outputs. This isn't the future of AI agents—it's what's possible right now with LangChain's DeepAgents.

What We Accomplished

In this hands-on guide, you learned how to:

Transform a basic tool-calling agent into a sophisticated planning system
Leverage file-based context management to handle tasks of any complexity
Design and coordinate specialized sub-agents for focused execution
Implement iterative quality control through automated review workflows
Build production-ready research systems that rival human analysis

The policy research agent we built demonstrates patterns that extend far beyond this specific use case. Whether you're building code generation systems, content creation pipelines, data analysis workflows, or customer service automation, the principles remain the same: plan strategically, delegate intelligently, manage state persistently, and iterate toward quality.

The Deeper Implications

The evolution from shallow to deep agents represents a fundamental shift in how we build AI systems. We're moving from tools that execute individual tasks to systems that orchestrate complex workflows. The key insight is that intelligence emerges not just from powerful models, but from thoughtful architecture—planning layers, memory systems, delegation patterns, and quality controls.

DeepAgents embodies this philosophy. By providing built-in planning tools, file system access, sub-agent creation, and long-term memory, it gives developers the building blocks to create genuinely sophisticated AI systems without reinventing infrastructure.

What's Next for AI Agents

The trajectory is clear: agents are becoming more capable, more modular, and more specialized. We're heading toward ecosystems where:

Agent swarms collaborate on complex problems, each bringing specialized expertise
Persistent memory allows agents to maintain context across days, weeks, or months of work
Self-improvement loops enable agents to learn from feedback and enhance their own prompts
Multi-modal capabilities combine text, code, images, and data seamlessly
Human-AI collaboration reaches new levels as agents become true thought partners

The foundation you've learned here—planning, delegation, state management, quality control—will remain relevant as these capabilities evolve.

Practical Next Steps

Where should you go from here?

Immediate Experiments:

Adapt this architecture to your own domain (swap policy research for tech analysis, financial reports, or medical literature reviews)
Add more specialized sub-agents (fact-checkers, translators, data analyzers)
Integrate with your own data sources, databases, or APIs
Experiment with different LLM models to find the best performance/cost balance
Build quality metrics to measure agent performance over time

Production Considerations:

Implement proper error handling and retry logic
Add monitoring and logging for production deployments
Build evaluation frameworks to assess agent output quality
Consider cost optimization strategies (caching, smaller models for sub-agents)
Design human-in-the-loop workflows for critical decisions

Learning More:

Explore the DeepAgents GitHub repository for advanced examples
Study the LangGraph documentation for state management patterns
Join the LangChain community to learn from other practitioners
Experiment with Claude Code and Deep Research to see these patterns at scale

The Bigger Picture

What excites me most about this technology isn't just what it can do today, but what it enables tomorrow. As agents become more sophisticated, the barrier to building intelligent systems continues to fall. Complex workflows that once required teams of specialists can now be orchestrated by thoughtfully designed agent systems.

This democratization of AI capabilities means:

Small teams can build products that previously required large organizations
Individuals can leverage AI to amplify their expertise and productivity
New categories of applications become possible
The focus shifts from AI implementation to AI orchestration

We're entering an era where the key skill isn't writing every algorithm from scratch, but knowing how to compose powerful systems from intelligent components.

Final Thoughts

The agent you built today is more than a research tool—it's a pattern for building intelligent systems. The planning layer, the delegation model, the context management, the quality control—these aren't specific to policy research. They're fundamental architectural principles for any complex AI workflow.

As you apply these patterns to your own projects, remember: the goal isn't to replace human intelligence, but to augment it. The best AI systems are those that handle complexity strategically, maintain context persistently, leverage specialization effectively, and iterate toward quality relentlessly.

That's what DeepAgents enables. That's what you now know how to build.

The future of AI isn't about smarter models alone—it's about smarter architectures. And you're now equipped to create them.

Want to go deeper?

Full code: https://github.com/Marktechpost/AI-Tutorial-Codes-Included/blob/main/AI%20Agents%20Codes/Langchain_Deepagents.ipynb
DeepAgents documentation: https://github.com/langchain-ai/deepagents
LangChain community: https://discord.gg/langchain

Share your builds: I'd love to see what you create with DeepAgents. Tag your projects on social media or share them in the LangChain community.

Now go build something remarkable. 🚀