不用上 LangSmith，不用花一分钱，你的 Agent 链路在本地就能被看见。
DeerFlow Trace Edition is a community-maintained fork of bytedance/deer-flow that ships with native execution observability. Every LangGraph checkpoint, every sub-agent call, every tool invocation, every model inference — inspectable right inside the chat UI, with zero external services, zero cloud round-trips, and zero per-trace fees.
🚀 Quick Start · ✨ Why DeerFlow Trace Edition · 🔓 Zero LangSmith Deep Dive · 📊 3-way Comparison · 🔧 Architecture
Run agents. See every step. Pay nothing. 🦌 → 🔍 → 💡
(Launch agents → inspect every checkpoint node → iterate faster — all without a single call to langchain.com.)
- 🦌 DeerFlow Trace Edition
TL;DR — DeerFlow already uses LangGraph. LangGraph's official way to "see what the agent is doing" is LangSmith, a paid SaaS run by LangChain Inc. in the US. DeerFlow Trace Edition gives you the same (and in many cases, better-integrated) execution trace visibility 100% locally inside the chat UI you already use, with no accounts, no API keys, no per-trace billing, no data leaving your network.
| What you get | LangSmith (Free Tier) | LangSmith (Pro) | LangSmith (Team) | DeerFlow Trace Edition |
|---|---|---|---|---|
| Traces / month | 5,000 only | 50,000 | 500,000 | ∞ Unlimited |
| Price / month | $0 | $39 | $299 | $0 Forever |
| Runs in your browser / UI | ❌ Opens external smith.langchain.com tab |
❌ External tab | ❌ External tab | ✅ Embedded right in the DeerFlow chat panel |
| Data location | ☁️ LangChain servers (USA) | ☁️ USA | ☁️ USA | ✅ Local SQLite on your disk / private network only |
| Works air-gapped / offline | ❌ Impossible | ❌ Impossible | ❌ Impossible | ✅ Yes, fully works offline |
| Works on corporate intranet | ❌ Usually blocked by egress firewalls / DLP | ❌ Still blocked | ❌ Still blocked | ✅ Yes — no outbound traffic ever |
| No LangChain account needed | ❌ Requires sign-up | ❌ Requires billing | ❌ Requires enterprise contract | ✅ Zero accounts, zero API keys |
| GDPR / China data residency | ❌ US-hosted only | ❌ US-hosted only | ✉️ Ask for enterprise (extra $$$) | ✅ You own the data — compliance already solved |
If your DeerFlow Trace Edition agent runs 10 conversations/day × 20 steps each = 6,000 traces/month:
- with LangSmith Free Tier: ❌ You're over quota on day 15. Traces stop being recorded until next month.
- with LangSmith Pro: $468 / year just for basic tracing.
- with LangSmith Team: $3,588 / year.
- with DeerFlow Trace Edition: ✅ $0. Same (or better) visibility. Forever. And the UI is one click away inside chat.
Running an agent for internal docs, customer tickets, or code that contains proprietary information?
- ❌ LangSmith uploads every prompt, every tool argument, every model output, every checkpoint state to third-party servers in the United States. Even with "self-hosted datasets," execution-level spans still transit the LangSmith API by default.
- ✅ DeerFlow Trace Edition reads execution traces directly from LangGraph's local SQLite checkpointer at
backend/.deer-flow/checkpoints.db. Nothing leaves your machine. No API calls, no callbacks, no telemetry. You can even pull the network cable and the trace panel keeps working perfectly.
With LangSmith you:
- Start a chat in DeerFlow
- Agent does something wrong / interesting
- Leave DeerFlow → open a new tab → log in to LangSmith → filter by session → find your run → click 3 layers deep → finally see the spans
- Context-switch back to DeerFlow to fix the prompt / rerun
With DeerFlow Trace Edition Execution Flow panel:
- Start a chat in DeerFlow
- Agent does something wrong / interesting
- Scroll down in the same window. The Execution Flow panel is already there, live-updating with green/red status pills.
- Click any step → input / output / metadata pop open inline.
- Fix and rerun. Zero context switch.
| Capability | Official bytedance/deer-flow | Official deer-flow + LangSmith Paid | DeerFlow Trace Edition (this repo) |
|---|---|---|---|
| LangGraph super-agent harness | ✅ | ✅ | ✅ |
| Sub-agents, skills, sandboxes, MCP | ✅ | ✅ | ✅ |
| Multi-model providers | ✅ | ✅ | ✅ |
| Chat-level execution trace UI | ❌ (no UI; use LangSmith) | ❌ (opens LangSmith in a new tab) | ✅ Embedded Execution Flow panel |
| Per-step: status, node type, filters | ❌ Only via LangSmith UI | ✅ (LangSmith) | ✅ (built-in) |
| Click a step → checkpoint I/O + metadata | ❌ Only via LangSmith UI | ✅ (LangSmith) | ✅ (built-in) |
| Works without internet | ✅ for agent runs | ❌ NO — LangSmith requires egress | ✅ Yes — 100% offline |
| Cost for 10k traces / month |
|
$39 / mo (LangSmith Pro) | $0 forever |
| Trace data stays on your network | N/A | ❌ Goes to USA | ✅ Always |
| Works inside mainland China | ✅ Agent runs fine | ❌ LangSmith blocked / very slow + data residency risk | ✅ Zero issues |
| Local SQLite checkpointer preserved | ✅ | ✅ | ✅ |
| vLLM / Ollama local LLM wrapper | ❌ (bring-your-own) | ❌ (bring-your-own) | ✅ LocalChatModel built-in |
| Showcase demo threads UI | ❌ | ❌ | ✅ /workspace/demo
|
| Landing page → direct work mode | ❌ (marketing page first) | ❌ same | ✅ direct redirect |
| Skill scripts hardening (no hardcoded keys) | ❌ public skills may contain placeholders | ❌ same | ✅ API-key env-var only |
| MIT-licensed, fork-friendly | ✅ | ✅ (LangSmith is separate & proprietary) | ✅ Fully MIT |
| # | Feature | What it does |
|---|---|---|
| 1 ⭐⭐⭐ | 🔓 Execution Flow panel · No LangSmith required | Built-in, 100% local trace UI for every LangGraph step. Replaces the need for LangSmith SaaS entirely. Real-time, chat-embedded panel showing node phases (before/after agent & model), tool calls, middleware — all with status colors, filters, and click-to-expand checkpoint details. Zero external services, zero fees, zero data leaving your network. Works fully offline. |
| 2 | 🤖 Local LLM provider (vLLM / Ollama ready) | Ships with LocalChatModel so you can run DeerFlow Trace Edition against any OpenAI-compatible local inference endpoint. Auto-normalizes multi-modal payloads and strips unsupported thinking params for gateways that don't speak them. |
| 3 | 🎬 Demo threads showcase | /workspace/demo — browse pre-baked conversation demos. Perfect for onboarding teammates, internal reviews, and conference talks without firing up real LLM calls. |
| 4 | 🎨 Full-stack UI/UX polish | Direct-to-workspace landing (no marketing page by default), responsive container widths so Execution Flow renders correctly on laptops and narrow monitors, safe clipboard guard for non-HTTPS deployments, Demo entry in sidebar. |
| 5 | 🐳 Docker production readiness | Checkpointer SQLite database persists across container restarts via bind mount. Nginx config pre-wires the /api/execution route. DEER_FLOW_ROOT is auto-injected by the launch scripts. |
| 6 | 🔒 Skill-script security hardening | Public image-generation / video-generation skills no longer ship with a hardcoded inline API key fallback. Keys must be provided via the AGNES_API_KEY env var — eliminating the risk of accidental credential leakage when redistributing forks. |
DeerFlow Trace Edition is a drop-in fork. Every setup command from the official bytedance/deer-flow Quick Start works identically below. If you already know how to run DeerFlow, you already know how to run DeerFlow Trace Edition — and you get the Execution Flow panel for free, immediately, no extra config.
Help me clone deer-flow-trace-edition if needed, then bootstrap it for local development by following the Quick Start section of https://raw.githubusercontent.com/122copy/deer-flow-trace-edition/main/README.md
# Clone this fork
git clone https://github.com/122copy/deer-flow-trace-edition.git
cd deer-flow-trace-edition
# Generate local config files (creates .env.example → .env, config.yaml.example → config.yaml)
make configEdit config.yaml and define at least one model:
models:
# Option A — Cloud (OpenAI-compatible)
- name: gpt-4o-mini
display_name: GPT-4o Mini
use: langchain_openai:ChatOpenAI
model: gpt-4o-mini
api_key: $OPENAI_API_KEY
max_tokens: 4096
temperature: 0.7
# Option B — vLLM / Ollama / any OpenAI-compatible local endpoint
- name: local-qwen2.5
display_name: Qwen2.5-7B (Local vLLM)
use: deerflow.models.local_provider:LocalChatModel # DeerFlow Trace Edition addition
base_url: http://localhost:8000/v1
model: qwen2.5-7b-instruct
max_tokens: 8192Then set your API keys. Edit .env in project root (recommended):
TAVILY_API_KEY=your-tavily-key # Optional but recommended for web search
OPENAI_API_KEY=your-openai-key
INFOQUEST_API_KEY=your-infoquest-key # Optional (BytePlus search)
# AGNES_API_KEY=... # Only needed if you use the image/video skillsmake docker-init # Pull sandbox image (once, or when image updates)
make docker-start # Start all services (auto-detects sandbox mode from config.yaml)Production:
make up # Build images locally + start all production services
make down # Stop & remove containersmake check # Prerequisites: Node 22+, pnpm, uv, nginx
make install # Backend + frontend deps
make setup-sandbox # Optional: pre-pull sandbox Docker image
make dev # Start everything (backend gateway, langgraph server, frontend dev server, nginx)Open http://localhost:2026 in your browser.
- Pick a workspace and start a conversation.
- Send any message that triggers the agent (e.g. "Search the web for the latest DeerFlow news and summarize.").
- Scroll to the bottom of the conversation. You'll see the new Execution Flow panel live-updating with green/red pills, step names, node types, and timestamps.
- Click any row to expand the full checkpoint I/O, metadata, phase (before/after agent / model / tool / middleware), and raw checkpoint state — all without leaving the chat. No LangSmith sign-up, no browser tab switch, no API key, no fees. ✅
DeerFlow Trace Edition retains the upstream 3-layer separation and adds one new, purely additive HTTP gateway router + one frontend panel:
┌──────────────────────────────────────────────────────────────────────┐
│ Browser (frontend) │
│ ┌──────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ Conversation messages│ │ 🆕 Execution Flow panel (chat-end) │ │
│ └──────────┬───────────┘ └──────────────────┬───────────────────┘ │
└─────────────┼──────────────────────────────────┼─────────────────────┘
│ REST / WS │ REST GET
▼ ▼
┌──────────────────────────────────────────────────────────────────────┐
│ Nginx Gateway (:2026) │
└─────────────┬──────────────────────────────────┬─────────────────────┘
▼ ▼
┌─────────────────────────────┐ ┌──────────────────────────────────┐ │
│ Gateway REST/WS (:8001) │ │ 🆕 execution/* router (NEW) │ │
│ (messages/auth/workspaces) │ │ ├── /history/{thread_id} │ │
└─────────────┬───────────────┘ │ └── /detail/{thread_id}/{ckpt} │ │
│ └──────────────┬───────────────────┘ │
▼ ▼ │
┌──────────────────────────────────────────────────────────────────────┤
│ LangGraph Harness Server (:2024) + SQLite Checkpointer │
│ lead_agent → sub_agents → tools → model nodes → memory → sandbox │
│ backend/.deer-flow/checkpoints.db ← DeerFlow Trace Edition reads DIRECTLY │
└──────────────────────────────────────────────────────────────────────┘
DeerFlow Trace Edition does not rely on LangChain's tracing callbacks at all, so it can't accidentally send spans anywhere. The Execution Flow feature is based entirely on reading LangGraph's own local SQLite checkpointer (backend/.deer-flow/checkpoints.db):
- LangGraph writes checkpoints. Every node (agent / model / tool / middleware) runs through the standard LangGraph state machine. With the default SQLiteSaver checkpointer, each step writes a tuple into the on-disk SQLite database — exactly the same mechanism LangGraph uses for resume-on-crash and state persistence.
- DeerFlow Trace Edition adds a tiny read-only gateway router.
backend/app/gateway/routers/execution.pyexposes twoGETendpoints:GET /api/execution/history/{thread_id}?limit=1000— groups checkpoints bystep_id+ annotatesnode_type(agent / model / tool / middleware / skill / harness) +status(success / error).GET /api/execution/detail/{thread_id}/{checkpoint_id}— returns the full checkpointconfig,metadata,channel_values, and rawwritesso the UI can render exact node inputs and outputs.
- The frontend ExecutionFlow React component polls once on mount + on message settle, renders status pills, filter chips (All / Agent / Model / Tool / Error), and a clickable detail drawer per step — all inside the existing conversation view.
This architecture has three massive advantages over a callback-based tracer (like LangSmith):
| Property | Callback tracing (LangSmith) | DeerFlow Trace Edition checkpointer-reading |
|---|---|---|
| Spans are lost if tracing errors | ❌ Yes (callback exception drops the span) | ✅ No. Checkpoint was already written to SQLite by LangGraph regardless. |
| Works for historical sessions | ❌ Only if callbacks were enabled at trace time | ✅ Yes. Reconstruct any old thread from existing checkpoints. |
| Network dependency | ✅ None. Pure local DB read. |
DeerFlow Trace Edition supports all upstream sandbox execution modes:
- Local — runs sandbox code directly on the host
- Docker — runs in isolated Docker containers
- Docker + Kubernetes — provisions sandboxes via the optional
provisionerservice (enabled whenconfig.yamlsetssandbox.use: deerflow.community.aio_sandbox:AioSandboxProviderwith aprovisioner_url)
See the upstream Sandbox Configuration Guide.
DeerFlow Trace Edition supports configurable MCP Servers and extensible skills (including HTTP/SSE MCP with OAuth: client_credentials & refresh_token flows). See the upstream MCP Server Guide.
Receive tasks from IM — none of them need a public IP.
| Channel | Transport | Difficulty |
|---|---|---|
| Telegram | Bot API (long-polling) | Easy |
| Slack | Socket Mode | Medium |
| Feishu / Lark | WebSocket | Medium |
Minimal config.yaml snippet:
channels:
langgraph_url: http://localhost:2024
gateway_url: http://localhost:8001
feishu: { enabled: true, app_id: $FEISHU_APP_ID, app_secret: $FEISHU_APP_SECRET }
slack: { enabled: true, app_token: $SLACK_APP_TOKEN, bot_token: $SLACK_BOT_TOKEN }
telegram:{ enabled: true, bot_token: $TG_BOT_TOKEN }DeerFlow Trace Edition doesn't need LangSmith, and the Execution Flow panel is what 99% of users will want to use daily. But if for some reason you also want to mirror traces to LangSmith (e.g., for cross-team sharing on public internet), DeerFlow Trace Edition fully respects the standard LANGSMITH_API_KEY / LANGCHAIN_TRACING_V2=true env vars — exactly like upstream. Set them in .env:
# Optional. DeerFlow Trace Edition works perfectly without these.
LANGCHAIN_TRACING_V2=true
LANGSMITH_API_KEY=lsv2_pt_xxxxDeerFlow Trace Edition works with any LangChain ChatModel and any OpenAI-compatible endpoint via the built-in LocalChatModel.
Community favorites that the upstream DeerFlow team also recommends:
- Doubao-Seed-2.0-Code (Volcengine) — great for coding agents
- DeepSeek-V3 / Kimi 2.5 — strong reasoning + Chinese
- Qwen2.5-72B-Instruct / Llama-3.1-70B via your own vLLM deployment — 100% private, with DeerFlow Trace Edition's
LocalChatModel - GPT-4o / Claude 3.5 Sonnet / Gemini 2.5 Flash via OpenRouter — plug-and-play with
base_url
| Resource | Location |
|---|---|
| This README (DeerFlow Trace Edition) | ./README.md |
| Official DeerFlow documentation (upstream) | bytedance/deer-flow docs |
| Config reference | backend/docs/CONFIGURATION.md |
| MCP Server guide | backend/docs/MCP_SERVER.md |
| Contributing guide (applies to both) | CONTRIBUTING.md |
| Official website (demos & news) | deerflow.tech |
- DeerFlow Trace Edition intentionally removes all hardcoded skill-script API keys (e.g.
image-generation,video-generation). If you use those skills, supply keys via env vars (AGNES_API_KEY, etc.) — never commit them. - The Execution Flow router reads checkpoints read-only, but the SQLite file contains full checkpoint state including tool args and model outputs. Treat
backend/.deer-flow/checkpoints.dbas sensitive and don't expose the gateway (:8001) directly to the internet — always go through the fronting Nginx (:2026) in production. - DeerFlow inherits all upstream security boundaries: the code-execution sandbox must be isolated (Docker / Kubernetes modes for production), and you should restrict which skills are enabled in untrusted environments.
Contributions to DeerFlow Trace Edition (the Execution Flow panel and this fork's extras) are very welcome!
DeerFlow Trace Edition is a source-available community fork that tracks bytedance/deer-flow as its upstream. Our changes are intentionally small, modular, and additive so they can be rebased cleanly on top of upstream releases:
upstream main (bytedance/deer-flow) → deer-flow-trace-edition/main (this repo: + execution/* router + ExecutionFlow.tsx + i18n + local_provider + demo + polish)
The Execution Flow change ships as one commit on top of a base snapshot — you can verify this with git log --oneline and review the diff as a single patch. This makes it trivial to:
- forward-port the feature to new upstream tags, or
- submit the execution trace feature as a clean PR back to upstream if the DeerFlow maintainers want to adopt it natively.
DeerFlow Trace Edition is released under the MIT License — identical to the upstream bytedance/deer-flow project. See LICENSE.
- 🙌 The entire bytedance/deer-flow team at ByteDance for building such a powerful, MIT-licensed Super Agent Harness. DeerFlow Trace Edition is a tribute to their great work — it simply would not exist without DeerFlow itself.
- The LangGraph team at LangChain for the excellent SQLite checkpointer design that makes the Execution Flow panel possible. DeerFlow Trace Edition chooses to read that local data directly rather than paying LangChain SaaS to re-serve it back to us — with zero disrespect intended. 😄
- You, the user reading this far — star this repo if it saved you a LangSmith bill. ⭐