ai-deep-research-agent

AI Deep Research Agent

A deep research assistant that plans, searches the web, writes to a virtual filesystem, and renders each tool call as a live card in a workspace pane. Built with CopilotKit, Deep Agents, AG-UI, and Tavily on top of Next.js + LangGraph (Python).

demo-deep-agents.mp4

Gen UI concept — tool-rendered components with a sidecar workspace. The Deep Agent emits four tools — write_todos, write_file, read_file, and research — and each one renders inline as a status card in the chat while updating a parallel workspace pane (plan, files, expandable tool results). Local React state mirrors the agent's filesystem via useDefaultTool rather than useCoAgent, sidestepping a Python Dict ↔ TypeScript Array type mismatch.

Prerequisites

• Node.js 18+
• Python 3.12+
• OpenAI API Key
• Tavily API Key
• uv (or pip) for Python deps

Getting Started

1. Install Node dependencies:

npm install

2. Install Python dependencies for the agent:

cd agent
uv venv && source .venv/bin/activate
uv pip install -e .
cd ..

Or with pip:

cd agent
python -m venv .venv && source .venv/bin/activate
pip install -e .
cd ..

3. Copy .env.example to .env in both the root and agent/ directories, then fill in OPENAI_API_KEY and TAVILY_API_KEY.

4. Start the agent (terminal 1):

cd agent
uv run python main.py

5. Start the frontend (terminal 2):

npm run dev

Open http://localhost:3000 and ask the assistant to research any topic.

Architecture

[User asks research question]
        ↓
Next.js Frontend (CopilotChat + Workspace)
        ↓
CopilotKit Runtime → LangGraphHttpAgent
        ↓
Python Backend (FastAPI + AG-UI)
        ↓
Deep Agent (research_assistant)
    ├── write_todos        (planning, built-in)
    ├── write_file         (filesystem, built-in)
    ├── read_file          (filesystem, built-in)
    └── research(query)
            └── internal Deep Agent [thread-isolated]
                    └── internet_search (Tavily)

Environment Variables

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	-	Get API key
TAVILY_API_KEY	Yes	-	Get API key
OPENAI_MODEL	No	gpt-5.5	Model to use (gpt-5.5)
LANGGRAPH_DEPLOYMENT_URL	No	http://localhost:8123	Backend URL
SERVER_HOST	No	0.0.0.0	Backend host
SERVER_PORT	No	8123	Backend port

Learn more

• Deep Agents documentation
• Building Frontends for Deep Agents
• CopilotKit documentation
• Tavily documentation

License

Upstream license applies — see CopilotKit/CopilotKit.