🤖 DeepAgents Workspace & Chat Demo

A professional, feature-rich workspace demonstrating the capabilities of the DeepAgents SDK integrated with LangChain, LangGraph, and Streamlit. This repository showcases how to build production-grade agentic workflows featuring custom tools, specialized sub-agents, state persistence, memory management, and dynamically loaded skills.

---

🚀 Key Features

• 💻 Clean Streamlit Interface (app.py): A modern, full-bleed chat UI featuring chat history, custom styled components (using dynamic CSS), real-time status badges for environment variables, a collapsible tool execution log, and a sidebar for on-the-fly agent configuration.
• 👥 Multi-Agent Collaboration: Features four specialized sub-agents (Research, Code, Writer, Critic) working in concert using the DeepAgents delegation protocol.
• 💾 State & Persistence Backends:
  • StateBackend: Ephemeral, session-isolated scratch space.
  • StoreBackend: Persistent cross-turn / cross-thread file storage using LangGraph's InMemoryStore.
• 🧠 Prompt Engineering & Memory: Injects system context dynamically from AGENTS.md and loads context-aware skills on-demand from the /skills/ directory.
• 🔍 Tavily Web Search: Integrates Google Search capabilities into research sub-agents.
• ⚡ Free-Tier & API Optimization: Pre-configured support for various free-tier models across Google Gemini 2.5 Flash, Groq (Llama 3.3 & Llama 4 Scout), and OpenRouter models.

---

🏗️ Architecture Overview

The system architecture utilizes the DeepAgents SDK middleware stack to wrap around models and intercept tool calls:

create_deep_agent()
    │
    ├── Model (BaseChatModel)
    │     └── Gemini 2.5 Flash, Llama 3.3 70B, Llama 4 Scout, etc.
    │
    ├── Middleware Stack (wraps model calls)
    │     ├── TodoListMiddleware      → Tracks the running checklist
    │     ├── SkillsMiddleware        → Loads on-demand workflows from /skills/
    │     ├── FilesystemMiddleware    → Provides file tools (read, write, edit, grep, glob, ls)
    │     ├── SubAgentMiddleware      → Spawns sub-agents via the `task` tool
    │     ├── SummarizationMiddleware → Summarizes long conversation loops
    │     └── MemoryMiddleware        → Loads AGENTS.md context into the prompt
    │
    ├── Backend (File storage layer)
    │     ├── StateBackend            → Ephemeral storage (per session)
    │     ├── StoreBackend            → Persistent storage (cross-turn)
    │     └── FilesystemBackend       → Local disk storage
    │
    └── Built-in Tools
          ├── write_file / edit_file / read_file
          ├── ls / glob / grep
          └── task (delegate to sub-agents)

---

📂 Project Structure

├── .env                  # Local environment secrets (API keys)
├── .gitignore            # Git exclusion patterns
├── README.md             # Project documentation (this file)
├── requirements.txt      # Python dependencies
├── pyproject.toml        # Project declaration & dependencies
├── app.py                # Main Streamlit chat application UI
├── main.py               # Main CLI entry point
│
└── deepagentsdemo/       # Demo assets, notebooks, and configuration
    ├── backends.ipynb          # Notebook exploring different persistence backends
    ├── basicdeepagent.ipynb    # Introduction to building basic agents
    ├── contextengineering.ipynb # Guide to memory, system prompts, and skills
    ├── projects/
    │   └── AGENTS.md           # Architecture guidelines loaded into agent memory
    └── skills/                 # Custom domain-specific skill definition folders
        ├── aws/
        ├── langgraph/
        ├── python/
        └── report/

---

⚙️ Installation & Setup

1. Clone & Set Up Virtual Environment

It is recommended to use Python 3.12 or higher. We use uv for fast package management, but standard pip works perfectly:

# Clone the repository and navigate inside
cd DeepAgents

# Create and activate a virtual environment
python -m venv .venv
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Linux/macOS:
source .venv/bin/activate

2. Install Dependencies

Install the required packages using pip:

pip install -r requirements.txt

3. Environment Variables Configuration

Create a .env file in the root directory and add your API keys:

# Core LLM API keys (Provide at least one)
GOOGLE_API_KEY=your_google_gemini_api_key
GROQ_API_KEY=your_groq_api_key
OPENROUTER_API_KEY=your_openrouter_api_key

# Optional Search API key for the Research Subagent
TAVILY_API_KEY=your_tavily_search_api_key

---

🎮 Running the Applications

Launch Streamlit Chat Application

To start the interactive web application, run:

streamlit run app.py

This launches a browser tab at http://localhost:8501 featuring the interactive DeepAgents chat.

Run Notebook Demos

Start Jupyter Lab or VS Code to run the notebooks inside deepagentsdemo/:

jupyter notebook

---

🛠️ Customization & Conventions

• Memory Injection: Customize agent behaviors globally by editing AGENTS.md. The MemoryMiddleware reads this file automatically.
• Adding Skills: Place new domain-specific markdown guidelines inside subfolders of the skills/ directory.