DeepAgent Studio

DeepAgent Studio is a full-stack application for configuring and executing LangGraph-based AI agents. The backend, powered by FastAPI, handles thread-safe session tracking and dynamic agent instantiation using a custom factory pattern. The frontend is a React SPA managed by Zustand, providing an interface to select model providers, toggle backends, and view expandable tool calls. Under the hood, the system orchestrates subagent delegation for complex research tasks, injects markdown-based skill context into the agent's memory, and utilizes a sandboxed virtual filesystem for safe file operations.

---

Key Features:

• Context Engineering: Loads durable AGENTS.md context and specific skills (Python, AWS, LangGraph, etc.) into the agent's memory.
• Subagent Delegation: Includes a research-agent for deep web searches and a structured-researcher that enforces Pydantic JSON outputs.
• Virtual File System: Maintains an isolated in-memory or on-disk file system for the agent to read and write without polluting your actual drive.
• Session Management: Robust server-side state with thread-safe UUID-based session tracking.

---

🏗️ Architecture Flow

graph LR
    subgraph Frontend [⚛️ React SPA]
        UI[User Interface] --> State[Zustand Store]
        State --> API_Fetch[API Service]
    end

    subgraph Backend [🐍 FastAPI Server]
        Router[API Routers] --> Store[(Session Store)]
        Router --> Factory[Agent Factory]
        Factory --> LangGraph[LangGraph Engine]
        LangGraph <--> Tools[Tavily Search, etc.]
    end

    API_Fetch -- POST /api/chat --> Router
    Router -- REST (JSON) --> API_Fetch

Loading

1. Frontend: User configures the agent (Model, Backend Type, Prompts) via a clean Tailwind UI. State is managed by Zustand.
2. Backend: FastAPI receives the configuration, retrieves the user's SessionData, and dynamically builds the LangGraph agent via the Factory.
3. Execution: The agent executes tools and subagents in a dedicated thread to prevent blocking the async event loop.
4. Response: Results are returned cleanly formatted to the React UI, including expandable Tool Call cards and Virtual File panels.

---

🚀 Setup & Installation

Prerequisites

• Python 3.13+ (We recommend using uv for dependency management)
• Node.js 18+ & npm

1. Environment Setup

Clone the repository, then set up your API keys:

cp .env.example .env

Open .env and add your required API keys (e.g., OPENAI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, TAVILY_API_KEY). Note: .env is ignored by Git to protect your secrets.

2. Start the Backend

Open your terminal in the project root:

# Install Python dependencies (using uv)
uv sync

# Or using standard pip:
# pip install -r requirements.txt

# Start the FastAPI server
python main.py

The backend will run at http://127.0.0.1:8000.

3. Start the Frontend

Open a second terminal and navigate to the frontend folder:

cd frontend

# Install Node dependencies
npm install

# Start the Vite development server
npm run dev

The frontend will run at http://localhost:5173. (Vite automatically proxies /api requests to the backend).

---

📁 Project Structure

DeepAgent_Studio/
├── backend/          # FastAPI server, LangGraph agent factory, session store & tools
├── frontend/         # React SPA (Vite + Tailwind CSS + Zustand)
├── data/             # System context (AGENTS.md) and skills (aws, langgraph, python, report-writer)
├── main.py           # FastAPI server entry point
├── pyproject.toml    # Dependencies & project metadata
└── .env.example      # Environment variable template

---

🛠️ Adding New Tools

The architecture is designed to be highly modular. To give your agent a new ability:

1. Create a new file in backend/tools/ (e.g., calculator.py).
2. Define a standard Python function with type hints and a clear """docstring""" explaining what the tool does.
3. Import the function into backend/agents/factory.py and append it to the ALL_TOOLS array.

The agent will immediately possess the new skill upon the next chat request!