furyhawk/deer-flow
1
0
Fork 0
mirror of https://github.com/bytedance/deer-flow.git synced 2026-05-23 08:25:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: align runtime docs with gateway mode (#2868)

Browse Source 
Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
This commit is contained in:
Eilen Shin
2026-05-12 16:19:21 +08:00
committed by GitHub
parent 20d2d2b373
commit 84f88b6610
21 changed files with 135 additions and 201 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/CONTRIBUTING.md
+1 -4
View File
@@ -56,11 +56,8 @@ export OPENAI_API_KEY="your-api-key"
### Run the Development Server
```bash
# Terminal 1: LangGraph server
# Gateway API + embedded agent runtime
make dev
# Terminal 2: Gateway API
make gateway
```
## Project Structure
backend/README.md
+23 -34
View File
@@ -11,34 +11,26 @@ DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent
│ Nginx (Port 2026) │
│ Unified reverse proxy │
└───────┬──────────────────┬───────────┘
│ │
/api/langgraph/* │ │ /api/* (other)
▼ ▼
┌──────────────────────────────────────────────┐
│ Gateway API (8001) │
│ FastAPI REST + LangGraph-compatible runtime │
│ │
│ Models, MCP, Skills, Memory, Uploads, │
│ Artifacts, Threads, Runs, Streaming │
│ │
│ ┌────────────────┐ │
│ │ Lead Agent │ │
│ │ ┌──────────┐ │ │
│ │ │Middleware│ │ │
│ │ │ Chain │ │ │
│ │ └──────────┘ │ │
│ │ ┌──────────┐ │ │
│ │ │ Tools │ │ │
│ │ └──────────┘ │ │
│ │ ┌──────────┐ │ │
│ │ │Subagents │ │ │
│ │ └──────────┘ │ │
│ └────────────────┘ │
└──────────────────────────────────────────────┘
│
/api/langgraph/* │ /api/* (other)
rewritten to /api/* │
▼
┌────────────────────────────────────────┐
│ Gateway API (8001) │
│ FastAPI REST + agent runtime │
│ │
│ Models, MCP, Skills, Memory, Uploads, │
│ Artifacts, Threads, Runs, Streaming │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Lead Agent │ │
│ │ Middleware Chain, Tools, Subagents │ │
│ └────────────────────────────────────┘ │
└────────────────────────────────────────┘
```
**Request Routing** (via Nginx):
- `/api/langgraph/*` → Gateway API - LangGraph-compatible agent interactions, threads, runs, and streaming translated to native `/api/*` routers
- `/api/langgraph/*` → Gateway LangGraph-compatible API - agent interactions, threads, streaming
- `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads, thread-local cleanup
- `/` (non-API) → Frontend - Next.js web interface
@@ -196,7 +188,7 @@ export OPENAI_API_KEY="your-api-key-here"
**Full Application** (from project root):
```bash
make dev # Starts LangGraph + Gateway + Frontend + Nginx
make dev # Starts Gateway + Frontend + Nginx
```
Access at: http://localhost:2026
@@ -204,14 +196,11 @@ Access at: http://localhost:2026
**Backend Only** (from backend directory):
```bash
# Terminal 1: LangGraph server
# Gateway API + embedded agent runtime
make dev
# Terminal 2: Gateway API
make gateway
```
Direct access: LangGraph at http://localhost:2024, Gateway at http://localhost:8001
Direct access: Gateway at http://localhost:8001
---
@@ -247,7 +236,7 @@ backend/
│ └── utils/ # Utilities
├── docs/ # Documentation
├── tests/ # Test suite
├── langgraph.json # LangGraph server configuration
├── langgraph.json # LangGraph graph registry for tooling/Studio compatibility
├── pyproject.toml # Python dependencies
├── Makefile # Development commands
└── Dockerfile # Container build
@@ -365,8 +354,8 @@ If a provider is explicitly enabled but required credentials are missing, or the
```bash
make install # Install dependencies
make dev # Run LangGraph server (port 2024)
make gateway # Run Gateway API (port 8001)
make dev # Run Gateway API + embedded agent runtime (port 8001)
make gateway # Run Gateway API without reload (port 8001)
make lint # Run linter (ruff)
make format # Format code (ruff)
```
backend/docs/API.md
+20 -11
View File
@@ -561,12 +561,13 @@ location /api/ {
---
## WebSocket Support
## Streaming Support
The LangGraph server supports WebSocket connections for real-time streaming. Connect to:
Gateway's LangGraph-compatible API streams run events with Server-Sent Events (SSE):
```
ws://localhost:2026/api/langgraph/threads/{thread_id}/runs/stream
```http
POST /api/langgraph/threads/{thread_id}/runs/stream
Accept: text/event-stream
```
---
@@ -602,13 +603,21 @@ const response = await fetch('/api/models');
const data = await response.json();
console.log(data.models);
// Using EventSource for streaming
const eventSource = new EventSource(
`/api/langgraph/threads/${threadId}/runs/stream`
);
eventSource.onmessage = (event) => {
console.log(JSON.parse(event.data));
};
// Create a run and stream SSE events
const streamResponse = await fetch(`/api/langgraph/threads/${threadId}/runs/stream`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "text/event-stream",
},
body: JSON.stringify({
input: { messages: [{ role: "user", content: "Hello" }] },
stream_mode: ["values", "messages-tuple", "custom"],
}),
});
const reader = streamResponse.body?.getReader();
// Decode and parse SSE frames from reader in your client code.
```
### cURL Examples
backend/docs/ARCHITECTURE.md
+24 -25
View File
@@ -20,24 +20,22 @@ This document provides a comprehensive overview of the DeerFlow backend architec
│ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬────────────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ Embedded Runtime │ │ Gateway API │ │ Frontend │
│ (inside Gateway) │ │ (Port 8001) │ │ (Port 3000) │
│ │ │ │ │ │
│ - Agent Runtime │ │ - Models API │ │ - Next.js App │
│ - Thread Mgmt │ │ - MCP Config │ │ - React UI │
│ - SSE Streaming │ │ - Skills Mgmt │ │ - Chat Interface │
│ - Checkpointing │ │ - File Uploads │ │ │
│ │ │ - Thread Cleanup │ │ │
│ │ │ - Artifacts │ │ │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
│ │
│ ┌─────────────────┘
│ │
▼ ▼
┌───────────────────────┴───────────────────────┐
│ │
▼ ▼
┌─────────────────────────────────────────────┐ ┌─────────────────────┐
│ Gateway API │ │ Frontend │
│ (Port 8001) │ │ (Port 3000) │
│ │ │ │
│ - LangGraph-compatible runs/threads API │ │ - Next.js App │
│ - Embedded Agent Runtime │ │ - React UI │
│ - SSE Streaming │ │ - Chat Interface │
│ - Checkpointing │ │ │
│ - Models, MCP, Skills, Uploads, Artifacts │ │ │
│ - Thread Cleanup │ │ │
└─────────────────────────────────────────────┘ └─────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Shared Configuration │
│ ┌─────────────────────────┐ ┌────────────────────────────────────────┐ │
@@ -52,9 +50,9 @@ This document provides a comprehensive overview of the DeerFlow backend architec
## Component Details
### Embedded LangGraph Runtime
### Gateway Embedded Agent Runtime
The LangGraph-compatible runtime runs inside the Gateway process and is built on LangGraph for robust multi-agent workflow orchestration.
The agent runtime is embedded in the FastAPI Gateway and built on LangGraph for robust multi-agent workflow orchestration. Nginx rewrites `/api/langgraph/*` to Gateway's native `/api/*` routes, so the public API remains compatible with LangGraph SDK clients without running a separate LangGraph server.
**Entry Point**: `packages/harness/deerflow/agents/lead_agent/agent.py:make_lead_agent`
@@ -65,7 +63,7 @@ The LangGraph-compatible runtime runs inside the Gateway process and is built on
- Tool execution orchestration
- SSE streaming for real-time responses
**Configuration**: `langgraph.json`
**Graph registry**: `langgraph.json` remains available for tooling and Studio compatibility.
```json
{
@@ -84,6 +82,7 @@ FastAPI application providing REST endpoints plus the public LangGraph-compatibl
**Routers**:
- `models.py` - `/api/models` - Model listing and details
- `thread_runs.py` / `runs.py` - `/api/threads/{id}/runs`, `/api/runs/*` - LangGraph-compatible runs and streaming
- `mcp.py` - `/api/mcp` - MCP server configuration
- `skills.py` - `/api/skills` - Skills management
- `uploads.py` - `/api/threads/{id}/uploads` - File upload
@@ -91,7 +90,7 @@ FastAPI application providing REST endpoints plus the public LangGraph-compatibl
- `artifacts.py` - `/api/threads/{id}/artifacts` - Artifact serving
- `suggestions.py` - `/api/threads/{id}/suggestions` - Follow-up suggestion generation
The web conversation delete flow is now split across both backend surfaces: LangGraph handles `DELETE /api/langgraph/threads/{thread_id}` for thread state, then the Gateway `threads.py` router removes DeerFlow-managed filesystem data via `Paths.delete_thread_dir()`.
The web conversation delete flow first deletes Gateway-managed thread state through the LangGraph-compatible route, then the Gateway `threads.py` router removes DeerFlow-managed filesystem data via `Paths.delete_thread_dir()`.
### Agent Architecture
@@ -354,9 +353,9 @@ SKILL.md Format:
{"input": {"messages": [{"role": "user", "content": "Hello"}]}}
2. Nginx → Gateway API (8001)
Routes `/api/langgraph/*` to the Gateway's LangGraph-compatible runtime
`/api/langgraph/*` is rewritten to Gateway's LangGraph-compatible `/api/*` routes
3. Embedded LangGraph runtime
3. Gateway embedded runtime
a. Load/create thread state
b. Execute middleware chain:
- ThreadDataMiddleware: Set up paths
@@ -412,7 +411,7 @@ SKILL.md Format:
### Thread Cleanup Flow
```
1. Client deletes conversation via LangGraph
1. Client deletes conversation via the LangGraph-compatible Gateway route
DELETE /api/langgraph/threads/{thread_id}
2. Web UI follows up with Gateway cleanup