DeepAgents Workspace

Harnessing Autonomous planning, Context Management, and Multi-Agent Orchestration

An educational and production-ready workspace demonstrating agentic design patterns using the DeepAgents harness. The project exhibits the creation of basic state-based agents and advanced deep agents with planning capabilities, todo lists, context management, and sub-agent delegation.

---

How It Works

This repository contains independent modules showcasing the DeepAgents harness. DeepAgents is an open-source agent harness built on LangGraph by LangChain, designed to handle complex, multi-step tasks out of the box instead of requiring manual wiring of prompts, tools, and state machines.

View System Orchestration & Flow Diagram

graph TD
    classDef main fill:#1C3C3C,stroke:#333,stroke-width:1px,color:#fff;
    classDef agent fill:#3776AB,stroke:#333,stroke-width:1px,color:#fff;
    classDef deep fill:#F55036,stroke:#333,stroke-width:1px,color:#fff;
    classDef tool fill:#f4f4f4,stroke:#333,stroke-width:1px,color:#333;

    Workspace([User Query]) --> Select{Select Agent Architecture}
    
    %% Standard Agent Flow
    Select -->|Standard Agent| Simple[Simple Agent]:::agent
    Simple -->|Execute Tool Call| TavilyTool1[Tavily Search Tool]:::tool
    TavilyTool1 -->|Context Grounding| Simple
    Simple -->|Final Completion| Output1([User Response])

    %% Deep Agent Flow
    Select -->|Deep Agent Harness| Deep[Deep Agent]:::deep
    Deep -->|Internal Planning| Plan[Plan & Todo Management]:::deep
    Deep -->|Execute Query| TavilyTool2[Tavily Search Tool]:::tool
    TavilyTool2 -->|Context Grounding| Plan
    Plan -->|Sub-Agent Delegation| SubAgent[Sub-Agent Spawning]:::deep
    SubAgent -->|Final Completion| Output2([Research Report Output])

Loading

Key Features

• Out-of-the-box Agent Harness — Pre-configured agent execution state machines with filesystem integration, todo lists, sub-agent delegation, and custom skills built on top of LangGraph.
• Advanced Context Management — Efficient formatting and handling of conversational messages, system instructions, and tool output history.
• Dynamic Web Grounding — Real-time search grounding using the Tavily Search API for up-to-date facts.
• Low-Latency Inference — High-speed completions running groq:llama-3.3-70b-versatile through LangChain's unified init_chat_model API.
• Project Extensibility — Clean separation of research specifications and interactive notebook implementations.

Tech Stack

Layer	Technology	Description
Agent Harness		Opinionated agent harness with sub-agent spawning, todo list orchestration, and local file access out of the box.
Agent Abstraction		Unified model initialization interfaces, prompt managers, and tool validations.
Inference Engine		High-speed Groq Cloud endpoint executing Llama 3.3.
Search Grounding		Grounds agent reasoning in real-time web results.

Project Structure

.
├── deepagentsbasic/
│   ├── basic-deep-agent.ipynb    # Jupyter notebook implementing simple and deep agents
│   └── deepagents_research.txt   # Research notes detailing DeepAgents harness
├── main.py                       # Project entrypoint script
├── pyproject.toml                # UV tool configuration & dependency specifications
├── requirements.txt              # Standard requirements file
├── uv.lock                       # UV lock file
├── .env                          # API secrets (GROQ & TAVILY)
├── .gitignore                    # Git ignore file
├── .python-version               # Python version file
└── README.md                     # System documentation

Getting Started

Prerequisites

• Python 3.13+
• A Groq API Key (get one from console.groq.com)
• A Tavily API Key (get one from tavily.com)

Installation

# Clone the repository
git clone <your-repository-url>
cd DeepAgents

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies using uv (recommended)
uv pip install -r requirements.txt
# Or using standard pip:
pip install -r requirements.txt

Configuration

Create a .env file in the root of the project to configure your credentials:

GROQ_API_KEY=your_groq_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here

---

The Workflows

1. Simple ReAct Agent

Located in basic-deep-agent.ipynb, this workflow configures a standard ReAct agent using create_agent from the deepagents SDK. It binds a Tavily web search tool directly to the Llama 3.3 model, executing linear actions, tool invocations, and answers.

Note

Simple Agent Creation

from langchain.agents import create_agent

simple_agents = create_agent(
    model=llm,
    tools=[web_search]
)

---

2. Autonomous Deep Agent Harness

Also configured in basic-deep-agent.ipynb, this workflow upgrades the implementation to create_deep_agent. This harness manages sub-agent spawning, context parsing, planning checklist states, and Mock File System updates dynamically based on the system instructions.

Tip

Deep Agent Initialization

from deepagents import create_deep_agent

deepagent = create_deep_agent(
    model=llm,
    tools=[web_search],
    system_prompt="Act as a researcher"
)

View Sample Query Execution State

The Deep Agent's execution flow passes through state transitions, invoking tools like web_search and formatting tool message payloads:

{
  "messages": [
    {
      "role": "human",
      "content": "what is deepagents?"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "name": "web_search",
          "args": {"query": "deepagents"}
        }
      ]
    }
  ]
}

---

Customization

The configuration parameters are highly modular and can be modified to suit your specific agent objectives:

Component	Target File	Modification Details
Change LLM Model	basic-deep-agent.ipynb	Change "groq:llama-3.3-70b-versatile" inside init_chat_model() to your model choice.
System Prompts	basic-deep-agent.ipynb	Edit system_prompt parameter inside create_deep_agent() to guide the agent behavior.
Search Grounding	basic-deep-agent.ipynb	Modify parameters in web_search() like max_results or filter topic fields.

---

Acknowledgments

• DeepAgents GitHub & Documentation for the planning and sub-agent harness framework.
• LangChain AI for standard model and state abstractions.
• Groq Cloud for low-latency Llama inference.