feat: Add metadata and descriptions to various documentation pages in Chinese
- Added titles and descriptions to workspace usage, configuration, customization, design principles, installation, integration guide, lead agent, MCP integration, memory system, middleware, quick start, sandbox, skills, subagents, and tools documentation. - Removed outdated API/Gateway reference and concepts glossary pages. - Updated configuration reference to reflect current structure and removed unnecessary sections. - Introduced new model provider documentation for Ark and updated the index page for model providers. - Enhanced tutorials with titles and descriptions for better clarity and navigation.
This commit is contained in:
JeffJiang
@@ -25,6 +25,15 @@ const meta: MetaRecord = {
|
||||
blog: {
|
||||
type: "page",
|
||||
},
|
||||
posts: {
|
||||
type: "page",
|
||||
},
|
||||
login: {
|
||||
type: "page",
|
||||
},
|
||||
setup: {
|
||||
type: "page",
|
||||
},
|
||||
};
|
||||
|
||||
export default meta;
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Agents and Threads
|
||||
description: DeerFlow App supports multiple named agents and maintains conversation state across sessions through threads and checkpointing.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# Agents and Threads
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: DeerFlow App is configured through two files and a set of environment variables. This page covers the application-level configuration that most operators need to set up before deploying.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Tabs } from "nextra/components";
|
||||
|
||||
# Configuration
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Deployment Guide
|
||||
description: "This guide covers all supported deployment methods for DeerFlow App: local development, Docker Compose, and production with Kubernetes-managed sandboxes."
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps, Tabs } from "nextra/components";
|
||||
|
||||
# Deployment Guide
|
||||
@@ -16,14 +21,15 @@ make dev
|
||||
|
||||
Services started:
|
||||
|
||||
| Service | Port | Description |
|
||||
|---|---|---|
|
||||
| LangGraph | 2024 | DeerFlow Harness runtime |
|
||||
| Gateway API | 8001 | FastAPI backend |
|
||||
| Frontend | 3000 | Next.js UI |
|
||||
| nginx | 2026 | Unified reverse proxy |
|
||||
| Service | Port | Description |
|
||||
| ----------- | ---- | ------------------------ |
|
||||
| LangGraph | 2024 | DeerFlow Harness runtime |
|
||||
| Gateway API | 8001 | FastAPI backend |
|
||||
| Frontend | 3000 | Next.js UI |
|
||||
| nginx | 2026 | Unified reverse proxy |
|
||||
|
||||
Access the app at **http://localhost:2026**.
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
```bash
|
||||
@@ -31,6 +37,7 @@ make stop
|
||||
```
|
||||
|
||||
Stops all four services. Safe to run even if a service is not running.
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
```
|
||||
@@ -41,9 +48,11 @@ logs/nginx.log # nginx access/error logs
|
||||
```
|
||||
|
||||
Tail a log in real time:
|
||||
|
||||
```bash
|
||||
tail -f logs/langgraph.log
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
</Tabs>
|
||||
|
||||
@@ -103,11 +112,11 @@ For production, use a named volume or a Persistent Volume Claim (PVC) instead of
|
||||
|
||||
### Sandbox mode selection
|
||||
|
||||
| Sandbox | Use case |
|
||||
|---|---|
|
||||
| `LocalSandboxProvider` | Single-user, trusted local workflows |
|
||||
| `AioSandboxProvider` (Docker) | Multi-user, moderate isolation requirement |
|
||||
| `AioSandboxProvider` + K8s Provisioner | Production, strong isolation, multi-user |
|
||||
| Sandbox | Use case |
|
||||
| -------------------------------------- | ------------------------------------------ |
|
||||
| `LocalSandboxProvider` | Single-user, trusted local workflows |
|
||||
| `AioSandboxProvider` (Docker) | Multi-user, moderate isolation requirement |
|
||||
| `AioSandboxProvider` + K8s Provisioner | Production, strong isolation, multi-user |
|
||||
|
||||
For any deployment with more than one concurrent user, use a container-based sandbox to prevent users from interfering with each other's execution environments.
|
||||
|
||||
@@ -154,10 +163,10 @@ When `USERDATA_PVC_NAME` is set, the provisioner automatically uses subPath (`th
|
||||
|
||||
nginx routes all traffic. Key environment variables that control routing:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | LangGraph service address |
|
||||
| `LANGGRAPH_REWRITE` | `/` | URL rewrite prefix for LangGraph routes |
|
||||
| Variable | Default | Description |
|
||||
| -------------------- | ---------------- | --------------------------------------- |
|
||||
| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | LangGraph service address |
|
||||
| `LANGGRAPH_REWRITE` | `/` | URL rewrite prefix for LangGraph routes |
|
||||
|
||||
These are set in the Docker Compose environment and processed by `envsubst` at container startup.
|
||||
|
||||
@@ -175,12 +184,12 @@ openssl rand -base64 32
|
||||
|
||||
### Resource recommendations
|
||||
|
||||
| Service | Minimum | Recommended |
|
||||
|---|---|---|
|
||||
| LangGraph (agent runtime) | 2 vCPU, 4 GB RAM | 4 vCPU, 8 GB RAM |
|
||||
| Gateway | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB |
|
||||
| Frontend | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB |
|
||||
| Sandbox container (per session) | 1 vCPU, 1 GB | 2 vCPU, 2 GB |
|
||||
| Service | Minimum | Recommended |
|
||||
| ------------------------------- | ---------------- | ---------------- |
|
||||
| LangGraph (agent runtime) | 2 vCPU, 4 GB RAM | 4 vCPU, 8 GB RAM |
|
||||
| Gateway | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB |
|
||||
| Frontend | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB |
|
||||
| Sandbox container (per session) | 1 vCPU, 1 GB | 2 vCPU, 2 GB |
|
||||
|
||||
## Deployment verification
|
||||
|
||||
@@ -201,5 +210,8 @@ A working deployment returns a `200` response from each endpoint. The `/api/mode
|
||||
|
||||
<Cards num={2}>
|
||||
<Cards.Card title="Configuration" href="/docs/application/configuration" />
|
||||
<Cards.Card title="Operations & Troubleshooting" href="/docs/application/operations-and-troubleshooting" />
|
||||
<Cards.Card
|
||||
title="Operations & Troubleshooting"
|
||||
href="/docs/application/operations-and-troubleshooting"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: DeerFlow App
|
||||
description: DeerFlow App is the reference implementation of what a production DeerFlow experience looks like. It assembles the Harness runtime, a web-based conversation workspace, an API gateway, and a reverse proxy into a single deployable system.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# DeerFlow App
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Operations and Troubleshooting
|
||||
description: This page covers day-to-day operational tasks and solutions to common problems when running DeerFlow App.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Operations and Troubleshooting
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Quick Start
|
||||
description: This guide walks you through starting DeerFlow App on your local machine using the `make dev` workflow. All four services (LangGraph, Gateway, Frontend, nginx) start together and are accessible through a single URL.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# Quick Start
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Workspace Usage
|
||||
description: The DeerFlow App workspace is a browser-based interface for having multi-turn conversations with the agent, tracking task progress, viewing artifacts, and managing files.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Workspace Usage
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: "DeerFlow's configuration system is designed around one goal: every meaningful behavior should be expressible in a config file, not hardcoded in the application. This makes deployments reproducible, auditable, and easy to customize per environment."
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Configuration
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Customization
|
||||
description: DeerFlow's pluggable architecture means most parts of the system can be replaced or extended without forking the core. This page maps the extension points and explains how to use each one.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Customization
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Design Principles
|
||||
description: Understanding the design principles behind DeerFlow Harness helps you use it effectively, extend it confidently, and reason about how your agents will behave in production.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Design Principles
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Install DeerFlow Harness
|
||||
description: The DeerFlow Harness is the Python SDK and runtime foundation for building your own Super Agent systems.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Install DeerFlow Harness
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Integration Guide
|
||||
description: DeerFlow Harness is not only a standalone application. It is a Python library you can import and use inside your own backend, API server, automation system, or multi-agent orchestrator.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Integration Guide
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Lead Agent
|
||||
description: The Lead Agent is the central executor in a DeerFlow thread. Every conversation, task, and workflow flows through it. Understanding how it works helps you configure it effectively and extend it when needed.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# Lead Agent
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: MCP Integration
|
||||
description: The **Model Context Protocol (MCP)** is an open standard for connecting language models to external tools and data sources. DeerFlow's MCP integration allows you to extend the agent with any tool server that implements the MCP protocol — without modifying the harness itself.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# MCP Integration
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Memory
|
||||
description: Memory is a runtime feature of the DeerFlow Harness. It is not a simple conversation log — it is a structured store of facts and context summaries that persist across separate sessions and inform the agent's behavior in future conversations.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Memory
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Middlewares
|
||||
description: Every time the Lead Agent calls the LLM, it runs through a **middleware chain** before and after the model call. Middlewares can read and modify the agent's state, inject content into the system prompt, intercept tool calls, and react to model outputs.
|
||||
---
|
||||
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# Middlewares
|
||||
|
||||
@@ -1,14 +1,18 @@
|
||||
---
|
||||
title: Quick Start
|
||||
description: Learn how to create and run a DeerFlow agent with create_deerflow_agent, from model setup to streaming responses.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# Quick Start
|
||||
|
||||
<Callout type="info" emoji="🚀">
|
||||
This guide shows you how to use the DeerFlow Harness programmatically — not
|
||||
through the App UI, but by importing and calling the harness directly in
|
||||
Python.
|
||||
This guide shows you how to build and run a DeerFlow agent in Python with
|
||||
<code>create_deerflow_agent</code>.
|
||||
</Callout>
|
||||
|
||||
The DeerFlow Harness is the Python SDK and runtime foundation. This quick start walks you through the key APIs for running an agent, streaming its output, and working with threads.
|
||||
The fastest way to understand DeerFlow Harness is to create an agent directly in code. This quick start walks through model setup, agent creation, and streaming a response.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -21,130 +25,86 @@ cd backend
|
||||
uv sync
|
||||
```
|
||||
|
||||
## Configuration
|
||||
You will also need a chat model instance from the LangChain provider package you want to use.
|
||||
|
||||
All harness behaviors are driven by `config.yaml`. At minimum, you need at least one model configured:
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
config_version: 6
|
||||
|
||||
models:
|
||||
- name: gpt-4o
|
||||
use: langchain_openai:ChatOpenAI
|
||||
model: gpt-4o
|
||||
api_key: $OPENAI_API_KEY
|
||||
request_timeout: 600.0
|
||||
max_retries: 2
|
||||
|
||||
sandbox:
|
||||
use: deerflow.sandbox.local:LocalSandboxProvider
|
||||
|
||||
tools:
|
||||
- use: deerflow.community.ddg_search.tools:web_search_tool
|
||||
- use: deerflow.community.jina_ai.tools:web_fetch_tool
|
||||
- use: deerflow.sandbox.tools:ls_tool
|
||||
- use: deerflow.sandbox.tools:read_file_tool
|
||||
- use: deerflow.sandbox.tools:write_file_tool
|
||||
- use: deerflow.sandbox.tools:bash_tool
|
||||
```
|
||||
|
||||
Copy `config.example.yaml` to `config.yaml` and fill in your API key.
|
||||
|
||||
## Running the harness
|
||||
|
||||
The primary entry point for the DeerFlow Harness is `DeerFlowClient`. It manages thread state, invokes the Lead Agent, and streams the response.
|
||||
## Create your first agent
|
||||
|
||||
<Steps>
|
||||
|
||||
### Import and configure
|
||||
### Import the factory and model
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from deerflow.client import DeerFlowClient
|
||||
from deerflow.config import load_config
|
||||
|
||||
# Load config.yaml from the current directory or DEER_FLOW_CONFIG_PATH
|
||||
load_config()
|
||||
|
||||
client = DeerFlowClient()
|
||||
from deerflow.agents import create_deerflow_agent
|
||||
from langchain_openai import ChatOpenAI
|
||||
```
|
||||
|
||||
### Create a thread
|
||||
### Create a model
|
||||
|
||||
```python
|
||||
thread_id = "my-thread-001"
|
||||
model = ChatOpenAI(
|
||||
model="gpt-4o",
|
||||
api_key="YOUR_OPENAI_API_KEY",
|
||||
)
|
||||
```
|
||||
|
||||
Thread IDs are arbitrary strings. Reusing the same ID continues the existing conversation (if a checkpointer is configured).
|
||||
|
||||
### Send a message and stream the response
|
||||
### Create an agent
|
||||
|
||||
```python
|
||||
async def run():
|
||||
async for event in client.astream(
|
||||
thread_id=thread_id,
|
||||
message="Research the top 3 open-source LLM frameworks and summarize them.",
|
||||
config={
|
||||
"configurable": {
|
||||
"model_name": "gpt-4o",
|
||||
"thinking_enabled": False,
|
||||
"is_plan_mode": True,
|
||||
"subagent_enabled": True,
|
||||
}
|
||||
},
|
||||
):
|
||||
print(event)
|
||||
agent = create_deerflow_agent(model)
|
||||
```
|
||||
|
||||
asyncio.run(run())
|
||||
This returns a compiled LangGraph agent with DeerFlow's default middleware chain.
|
||||
|
||||
### Stream a response
|
||||
|
||||
```python
|
||||
for event in agent.stream(
|
||||
{"messages": [{"role": "user", "content": "Explain what DeerFlow Harness is."}]},
|
||||
stream_mode=["messages", "values"],
|
||||
):
|
||||
print(event)
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
## Configurable options
|
||||
## Add tools or behavior
|
||||
|
||||
The `config.configurable` dict controls per-request behavior:
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `model_name` | `str \| None` | first model in config | Model to use for this request |
|
||||
| `thinking_enabled` | `bool` | `True` | Enable extended thinking mode (if supported) |
|
||||
| `reasoning_effort` | `str \| None` | `None` | Reasoning effort level (model-specific) |
|
||||
| `is_plan_mode` | `bool` | `False` | Enable TodoList middleware for task tracking |
|
||||
| `subagent_enabled` | `bool` | `False` | Allow the agent to delegate subtasks |
|
||||
| `max_concurrent_subagents` | `int` | `3` | Maximum parallel subagent calls per turn |
|
||||
| `agent_name` | `str \| None` | `None` | Name of a custom agent to load |
|
||||
|
||||
## Streaming event types
|
||||
|
||||
`client.astream()` yields events from the LangGraph runtime. The key event types are:
|
||||
|
||||
| Event type | Description |
|
||||
|---|---|
|
||||
| `messages` | Individual message chunks (text, thinking, tool calls) |
|
||||
| `thread_state` | Thread state updates (title, artifacts, todo list) |
|
||||
|
||||
Message chunks contain the token stream as the agent generates its response.
|
||||
|
||||
## Working with a custom agent
|
||||
|
||||
If you have defined a custom agent, pass its `name` in the configurable:
|
||||
You can customize the agent by passing tools, a system prompt, runtime features, middleware, or a checkpointer.
|
||||
|
||||
```python
|
||||
async for event in client.astream(
|
||||
thread_id="thread-002",
|
||||
message="Analyze the attached CSV and generate a summary chart.",
|
||||
config={
|
||||
"configurable": {
|
||||
"agent_name": "data-analyst",
|
||||
"subagent_enabled": True,
|
||||
}
|
||||
},
|
||||
):
|
||||
...
|
||||
from deerflow.agents import RuntimeFeatures, create_deerflow_agent
|
||||
|
||||
agent = create_deerflow_agent(
|
||||
model,
|
||||
system_prompt="You are a concise research assistant.",
|
||||
features=RuntimeFeatures(subagent=True, memory=False),
|
||||
plan_mode=True,
|
||||
name="research-agent",
|
||||
)
|
||||
```
|
||||
|
||||
The custom agent's configuration (model, skills, tool groups) is loaded automatically from `agents/data-analyst/config.yaml`.
|
||||
Common parameters:
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `tools` | Additional tools available to the agent |
|
||||
| `system_prompt` | Custom system prompt |
|
||||
| `features` | Enable or replace built-in runtime features |
|
||||
| `extra_middleware` | Insert custom middleware into the default chain |
|
||||
| `plan_mode` | Enable Todo-style task tracking |
|
||||
| `checkpointer` | Persist agent state across runs |
|
||||
| `name` | Logical agent name |
|
||||
|
||||
## When to use DeerFlowClient instead
|
||||
|
||||
`create_deerflow_agent()` is the low-level SDK factory when you want to work directly with the compiled agent graph.
|
||||
|
||||
Use `DeerFlowClient` when you want the higher-level embedded app interface, such as:
|
||||
|
||||
- thread-oriented chat helpers,
|
||||
- model / skills / memory management APIs,
|
||||
- file uploads and artifacts,
|
||||
- Gateway-like response formats.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Sandbox
|
||||
description: The sandbox gives the Lead Agent a controlled environment where it can read files, write outputs, run shell commands, and produce artifacts. Without a sandbox, the agent can only generate text. With a sandbox, it can write and execute code, process data files, generate charts, and build deliverables.
|
||||
---
|
||||
|
||||
import { Callout, Cards, Tabs } from "nextra/components";
|
||||
|
||||
# Sandbox
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Skills
|
||||
description: A skill is more than a prompt. It is a self-contained capability package that can include structured instructions, step-by-step workflows, domain-specific best practices, supporting resources, and tool configurations. Skills are loaded on demand — they inject their content when a task calls for them and stay out of the context otherwise.
|
||||
---
|
||||
|
||||
import { Callout, Cards, FileTree, Steps } from "nextra/components";
|
||||
|
||||
# Skills
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Subagents
|
||||
description: When a task is too broad for a single reasoning thread, or when parts of it can be done in parallel, the Lead Agent delegates work to **subagents**. A subagent is a self-contained agent invocation that receives a specific task, executes it, and returns the result.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Subagents
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Tools
|
||||
description: "The Lead Agent is a tool-calling agent. Tools are how it interacts with the world: searching the web, reading and writing files, running commands, delegating tasks, and presenting outputs to the user."
|
||||
---
|
||||
|
||||
import { Callout, Cards, Tabs } from "nextra/components";
|
||||
|
||||
# Tools
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Core Concepts
|
||||
description: Before you go deeper into DeerFlow, it helps to anchor on a few concepts that appear throughout the system. These concepts explain what DeerFlow is optimizing for and why its architecture looks the way it does.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Core Concepts
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Harness vs App
|
||||
description: "DeerFlow has two layers that are closely related but serve different purposes."
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Harness vs App
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Why DeerFlow
|
||||
description: DeerFlow exists because modern agent systems need more than a chat loop. A useful agent must plan over long horizons, break work into sub-tasks, use tools, manipulate files, run code safely, and preserve enough context to stay coherent across a complex task. DeerFlow was built to provide that runtime foundation.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Why DeerFlow
|
||||
|
||||
@@ -1,20 +1,8 @@
|
||||
import type { MetaRecord } from "nextra";
|
||||
|
||||
const meta: MetaRecord = {
|
||||
"concepts-glossary": {
|
||||
title: "Concepts Glossary",
|
||||
},
|
||||
"configuration-reference": {
|
||||
title: "Configuration Reference",
|
||||
},
|
||||
"api-gateway-reference": {
|
||||
title: "API / Gateway Reference",
|
||||
},
|
||||
"runtime-flags-and-modes": {
|
||||
title: "Runtime Flags and Modes",
|
||||
},
|
||||
"source-map": {
|
||||
title: "Source Map",
|
||||
"model-providers": {
|
||||
title: "Model providers",
|
||||
},
|
||||
};
|
||||
|
||||
|
||||
@@ -1,69 +0,0 @@
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# API / Gateway Reference
|
||||
|
||||
<Callout type="info">
|
||||
DeerFlow Gateway is built on FastAPI and provides interactive API
|
||||
documentation at <code>http://localhost:8001/docs</code>.
|
||||
</Callout>
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
http://localhost:8001
|
||||
```
|
||||
|
||||
Via nginx proxy:
|
||||
|
||||
```
|
||||
http://localhost:2026/api
|
||||
```
|
||||
|
||||
## Core endpoints
|
||||
|
||||
### System
|
||||
|
||||
| Method | Path | Description |
|
||||
| ------ | ------------- | --------------------------------- |
|
||||
| `GET` | `/health` | Service health check |
|
||||
| `GET` | `/api/models` | Get the list of configured models |
|
||||
|
||||
### Agent management
|
||||
|
||||
| Method | Path | Description |
|
||||
| -------- | -------------------- | ------------------------------- |
|
||||
| `GET` | `/api/agents` | List all agents |
|
||||
| `POST` | `/api/agents` | Create a custom agent |
|
||||
| `GET` | `/api/agents/{name}` | Get agent configuration |
|
||||
| `PUT` | `/api/agents/{name}` | Update agent configuration |
|
||||
| `DELETE` | `/api/agents/{name}` | Delete an agent |
|
||||
| `POST` | `/api/agents/check` | Check/suggest unique agent slug |
|
||||
|
||||
### Threads and memory
|
||||
|
||||
| Method | Path | Description |
|
||||
| -------- | -------------------------- | ------------------------- |
|
||||
| `GET` | `/api/threads` | List threads |
|
||||
| `DELETE` | `/api/threads/{thread_id}` | Delete a thread |
|
||||
| `GET` | `/api/memory` | Get global memory |
|
||||
| `GET` | `/api/memory/{agent_name}` | Get agent-specific memory |
|
||||
| `DELETE` | `/api/memory` | Clear global memory |
|
||||
|
||||
### Extensions
|
||||
|
||||
| Method | Path | Description |
|
||||
| ------ | --------------------------------------- | -------------------------------------------- |
|
||||
| `GET` | `/api/extensions` | List all extensions (MCP servers and skills) |
|
||||
| `POST` | `/api/extensions/mcp/{name}/enable` | Enable an MCP server |
|
||||
| `POST` | `/api/extensions/mcp/{name}/disable` | Disable an MCP server |
|
||||
| `POST` | `/api/extensions/skills/{name}/enable` | Enable a skill |
|
||||
| `POST` | `/api/extensions/skills/{name}/disable` | Disable a skill |
|
||||
|
||||
### File uploads
|
||||
|
||||
| Method | Path | Description |
|
||||
| ------ | ------------------------------------- | ------------------------------------- |
|
||||
| `POST` | `/api/uploads/{thread_id}` | Upload a file to the thread workspace |
|
||||
| `GET` | `/api/uploads/{thread_id}/{filename}` | Retrieve an uploaded file |
|
||||
|
||||
For the full interactive API documentation visit `http://localhost:8001/docs` (Swagger UI).
|
||||
@@ -1,67 +0,0 @@
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# Concepts Glossary
|
||||
|
||||
This glossary defines the core terms used throughout the DeerFlow documentation.
|
||||
|
||||
---
|
||||
|
||||
## Agent
|
||||
|
||||
In DeerFlow, an agent is the primary processing unit that receives user messages, decides what actions to take (tool calls or direct responses), and generates output. DeerFlow uses a two-tier architecture with a **Lead Agent** and **Subagents**.
|
||||
|
||||
## Artifact
|
||||
|
||||
A file produced by the agent — a report, chart, code file, or other deliverable. Artifacts are exposed via the `present_files` tool and persisted in the thread's user-data directory.
|
||||
|
||||
## Checkpoint
|
||||
|
||||
A persisted snapshot of thread state, saved after each agent turn. Checkpoints allow conversations to resume after server restarts and support state management for long-horizon tasks.
|
||||
|
||||
## Context Engineering
|
||||
|
||||
The practice of controlling what the agent sees, remembers, and ignores at each step — through summarization, scoped subagent contexts, and external file memory — to keep the agent effective over long-horizon tasks.
|
||||
|
||||
## Harness
|
||||
|
||||
An opinionated agent runtime that packages tool access, skill loading, sandbox execution, memory, subagent coordination, and context management — rather than just exposing abstractions.
|
||||
|
||||
## Lead Agent
|
||||
|
||||
The primary executor in each DeerFlow thread, responsible for planning, tool calls, and response generation. Built on LangGraph + LangChain Agent, augmented by the middleware chain.
|
||||
|
||||
## Long-horizon Agent
|
||||
|
||||
An agent that remains useful across a chain of actions — making plans, calling tools many times, managing intermediate files, and producing a final artifact — rather than producing only a single answer.
|
||||
|
||||
## Memory
|
||||
|
||||
Structured facts and user context that persists across independent conversation sessions, injected into the agent's system prompt in subsequent sessions.
|
||||
|
||||
## Middleware
|
||||
|
||||
A plugin that wraps every LLM call, able to read and modify agent state before and after the model invocation. DeerFlow uses middleware for memory, summarization, title generation, and other cross-cutting behaviors.
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
An open standard for connecting language models to external tools and data sources. DeerFlow's MCP integration allows connection to any compatible tool server.
|
||||
|
||||
## Sandbox
|
||||
|
||||
The isolated execution environment where the agent performs file and command-based work. DeerFlow supports local (`LocalSandboxProvider`) and container-based (`AioSandboxProvider`) sandbox modes.
|
||||
|
||||
## Skill
|
||||
|
||||
A task-oriented capability pack containing structured instructions, workflows, and best practices, loaded into the agent's context on demand. Skills provide specialization without polluting the general agent context.
|
||||
|
||||
## Subagent
|
||||
|
||||
A focused worker that handles a delegated subtask, running with an isolated context that contains only the information needed to complete its assigned work.
|
||||
|
||||
## Thread
|
||||
|
||||
The complete encapsulation of a conversation and all its associated state — message history, artifacts, todo list, and checkpoint data.
|
||||
|
||||
## ThreadState
|
||||
|
||||
The LangGraph-managed state object in DeerFlow, containing `messages`, `artifacts`, `todo_list`, and runtime metadata.
|
||||
@@ -1,123 +0,0 @@
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# Configuration Reference
|
||||
|
||||
This page is the complete reference for all top-level fields in `config.yaml`.
|
||||
|
||||
<Callout type="info">
|
||||
See <code>config.example.yaml</code> in the repository root for a fully
|
||||
commented example with all available options.
|
||||
</Callout>
|
||||
|
||||
## Top-level fields
|
||||
|
||||
| Field | Type | Description |
|
||||
| ---------------------- | ------------- | ----------------------------------------------- |
|
||||
| `config_version` | `int` | Config schema version (current: 6) |
|
||||
| `log_level` | `str` | Log verbosity: `debug`/`info`/`warning`/`error` |
|
||||
| `models` | `list` | Available LLM model configurations |
|
||||
| `image_generate_model` | `str \| list` | Model name to use for image generation |
|
||||
| `token_usage` | `object` | Token usage tracking config |
|
||||
| `tools` | `list` | Available tool configurations |
|
||||
| `tool_groups` | `list` | Named groupings of tools |
|
||||
| `tool_search` | `object` | Deferred tool loading config |
|
||||
| `sandbox` | `object` | Sandbox provider and options |
|
||||
| `skills` | `object` | Skills directory and container path |
|
||||
| `skill_evolution` | `object` | Agent-managed skill creation |
|
||||
| `subagents` | `object` | Subagent timeouts and max turns |
|
||||
| `acp_agents` | `dict` | External ACP agent configurations |
|
||||
| `memory` | `object` | Cross-session memory storage |
|
||||
| `summarization` | `object` | Conversation summarization |
|
||||
| `title` | `object` | Automatic thread title generation |
|
||||
| `checkpointer` | `object` | Thread state persistence |
|
||||
| `guardrails` | `object` | Tool call authorization |
|
||||
| `uploads` | `object` | File upload settings |
|
||||
| `channels` | `list` | IM channel integrations |
|
||||
|
||||
## models
|
||||
|
||||
```yaml
|
||||
models:
|
||||
- name: gpt-4o # Model identifier (referenced in requests)
|
||||
use: langchain_openai:ChatOpenAI # Python class path
|
||||
model: gpt-4o # Model name passed to the LLM
|
||||
api_key: $OPENAI_API_KEY # API key (env var interpolation supported)
|
||||
base_url: null # Optional: custom endpoint URL
|
||||
request_timeout: 600.0 # Request timeout in seconds
|
||||
max_retries: 2 # Number of retries on failure
|
||||
supports_vision: true # Whether to enable vision capabilities
|
||||
thinking_enabled: false # Whether to enable extended thinking
|
||||
# Any additional fields are passed through to the model constructor
|
||||
```
|
||||
|
||||
## sandbox
|
||||
|
||||
```yaml
|
||||
sandbox:
|
||||
# Local (default, no container isolation)
|
||||
use: deerflow.sandbox.local:LocalSandboxProvider
|
||||
allow_host_bash: false
|
||||
bash_output_max_chars: 20000
|
||||
read_file_output_max_chars: 50000
|
||||
ls_output_max_chars: 20000
|
||||
|
||||
# Container-based
|
||||
# use: deerflow.community.aio_sandbox:AioSandboxProvider
|
||||
# image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
|
||||
# replicas: 3
|
||||
# idle_timeout: 600
|
||||
```
|
||||
|
||||
## memory
|
||||
|
||||
```yaml
|
||||
memory:
|
||||
enabled: true
|
||||
storage_path: memory.json
|
||||
debounce_seconds: 30
|
||||
max_facts: 100
|
||||
fact_confidence_threshold: 0.7
|
||||
injection_enabled: true
|
||||
max_injection_tokens: 2000
|
||||
model_name: null
|
||||
```
|
||||
|
||||
## summarization
|
||||
|
||||
```yaml
|
||||
summarization:
|
||||
enabled: true
|
||||
model_name: null
|
||||
trigger:
|
||||
- type: tokens
|
||||
value: 15564
|
||||
keep:
|
||||
type: messages
|
||||
value: 10
|
||||
trim_tokens_to_summarize: 15564
|
||||
summary_prompt: null
|
||||
```
|
||||
|
||||
## checkpointer
|
||||
|
||||
```yaml
|
||||
checkpointer:
|
||||
type: sqlite # sqlite | redis | postgres
|
||||
connection_string: .deer-flow/checkpoints.db
|
||||
```
|
||||
|
||||
## subagents
|
||||
|
||||
```yaml
|
||||
subagents:
|
||||
timeout_seconds: 900
|
||||
agents:
|
||||
general-purpose:
|
||||
timeout_seconds: 1800
|
||||
max_turns: 160
|
||||
bash:
|
||||
timeout_seconds: 300
|
||||
max_turns: 80
|
||||
```
|
||||
|
||||
See the dedicated documentation page for each feature for full field descriptions.
|
||||
@@ -0,0 +1,9 @@
|
||||
import type { MetaRecord } from "nextra";
|
||||
|
||||
const meta: MetaRecord = {
|
||||
ark: {
|
||||
title: "火山方舟",
|
||||
},
|
||||
};
|
||||
|
||||
export default meta;
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Volcano Ark
|
||||
description: Integration guide for the Volcano Ark model provider.
|
||||
---
|
||||
|
||||
# Volcano Ark
|
||||
|
||||
## Coding Plan
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Model providers
|
||||
description: Integration references for supported model provider services.
|
||||
asIndexPage: true
|
||||
---
|
||||
|
||||
# Model providers
|
||||
@@ -1,36 +0,0 @@
|
||||
# Runtime Flags and Modes
|
||||
|
||||
This page documents the runtime flags and modes that affect DeerFlow Harness and agent runtime behavior.
|
||||
|
||||
## Per-request configurable options
|
||||
|
||||
These options are passed via `config.configurable` (for programmatic use) or selected in the web UI (for application use):
|
||||
|
||||
| Flag | Type | Default | Description |
|
||||
| -------------------------- | ------------- | ---------------------- | ------------------------------------------------ |
|
||||
| `model_name` | `str \| None` | First configured model | Model to use for the request |
|
||||
| `agent_name` | `str \| None` | `None` | Load a custom agent configuration |
|
||||
| `thinking_enabled` | `bool` | `True` | Enable extended thinking (model must support it) |
|
||||
| `reasoning_effort` | `str \| None` | `None` | Reasoning effort level (model-specific) |
|
||||
| `is_plan_mode` | `bool` | `False` | Enable TodoList middleware |
|
||||
| `subagent_enabled` | `bool` | `False` | Allow subagent delegation |
|
||||
| `max_concurrent_subagents` | `int` | `3` | Maximum parallel subagent calls per turn |
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ----------------------- | --------------- | ------------------------------------------------ |
|
||||
| `DEER_FLOW_CONFIG_PATH` | Auto-discovered | Absolute path to `config.yaml` |
|
||||
| `LOG_LEVEL` | `info` | Log level override |
|
||||
| `DEER_FLOW_ROOT` | Repo root | Base path for Docker bind mounts |
|
||||
| `BETTER_AUTH_SECRET` | — | Frontend session secret (required in production) |
|
||||
| `BETTER_AUTH_URL` | — | Public URL (for callbacks and CORS) |
|
||||
|
||||
## Model capability flags
|
||||
|
||||
Set in the model configuration in `config.yaml`:
|
||||
|
||||
| Flag | Type | Description |
|
||||
| ------------------ | ------ | ------------------------------------- |
|
||||
| `supports_vision` | `bool` | Model accepts image inputs |
|
||||
| `thinking_enabled` | `bool` | Model supports extended thinking mode |
|
||||
@@ -1,88 +0,0 @@
|
||||
# Source Map
|
||||
|
||||
This page maps DeerFlow's core concepts to where they are implemented in the codebase, helping you quickly locate specific features.
|
||||
|
||||
## Backend core paths
|
||||
|
||||
```
|
||||
backend/
|
||||
├── app/
|
||||
│ └── gateway/ # FastAPI Gateway API
|
||||
│ ├── routers/
|
||||
│ │ ├── agents.py # Custom agent CRUD
|
||||
│ │ ├── extensions.py # MCP/skill enable/disable
|
||||
│ │ ├── memory.py # Memory read/clear
|
||||
│ │ ├── threads.py # Thread management
|
||||
│ │ └── uploads.py # File uploads
|
||||
│ └── main.py # FastAPI app entry point
|
||||
│
|
||||
└── packages/harness/deerflow/
|
||||
├── agents/
|
||||
│ ├── lead_agent/
|
||||
│ │ ├── agent.py # make_lead_agent() factory
|
||||
│ │ └── prompt.py # System prompt templates
|
||||
│ ├── middlewares/ # All middleware implementations
|
||||
│ ├── memory/
|
||||
│ │ ├── middleware.py # MemoryMiddleware
|
||||
│ │ └── storage.py # Memory file storage
|
||||
│ └── thread_state.py # ThreadState dataclass
|
||||
│
|
||||
├── config/
|
||||
│ ├── app_config.py # AppConfig (top-level config)
|
||||
│ ├── model_config.py # ModelConfig
|
||||
│ ├── paths.py # Path resolution utilities
|
||||
│ └── *.py # Per-module config classes
|
||||
│
|
||||
├── mcp/
|
||||
│ ├── cache.py # mtime-based tool cache
|
||||
│ └── oauth.py # MCP OAuth support
|
||||
│
|
||||
├── models/
|
||||
│ └── factory.py # create_chat_model() LLM factory
|
||||
│
|
||||
├── sandbox/
|
||||
│ ├── local/ # LocalSandboxProvider
|
||||
│ └── sandbox.py # Sandbox base class
|
||||
│
|
||||
├── skills/
|
||||
│ ├── loader.py # load_skills() (hot reload)
|
||||
│ ├── parser.py # SKILL.md parsing
|
||||
│ ├── installer.py # Dependency installation
|
||||
│ └── manager.py # Skill lifecycle management
|
||||
│
|
||||
├── subagents/
|
||||
│ └── registry.py # Subagent lookup and config override
|
||||
│
|
||||
└── tools/
|
||||
└── builtins/ # Built-in tool implementations
|
||||
```
|
||||
|
||||
## Frontend core paths
|
||||
|
||||
```
|
||||
frontend/src/
|
||||
├── app/ # Next.js routes and pages
|
||||
├── components/
|
||||
│ └── workspace/ # Workspace UI components
|
||||
├── core/
|
||||
│ ├── agents/ # Agent types and API client
|
||||
│ ├── messages/ # Message types and tool call handling
|
||||
│ └── threads/ # Thread state management
|
||||
└── content/ # Documentation content (MDX)
|
||||
├── en/ # English documentation
|
||||
└── zh/ # Chinese documentation
|
||||
```
|
||||
|
||||
## Quick index
|
||||
|
||||
| Goal | File |
|
||||
| -------------------------- | ----------------------------- |
|
||||
| Lead agent creation | `agents/lead_agent/agent.py` |
|
||||
| System prompt template | `agents/lead_agent/prompt.py` |
|
||||
| All middleware | `agents/middlewares/` |
|
||||
| Config loading | `config/app_config.py` |
|
||||
| Model factory | `models/factory.py` |
|
||||
| Skill loading (hot reload) | `skills/loader.py` |
|
||||
| MCP tool cache | `mcp/cache.py` |
|
||||
| File upload handling | `uploads/manager.py` |
|
||||
| Gateway main router | `app/gateway/main.py` |
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Create Your First Harness
|
||||
description: This tutorial shows you how to use the DeerFlow Harness programmatically — importing and using DeerFlow directly in your Python code rather than through the web interface.
|
||||
---
|
||||
|
||||
import { Callout, Steps } from "nextra/components";
|
||||
|
||||
# Create Your First Harness
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Deploy Your Own DeerFlow
|
||||
description: This tutorial guides you through deploying DeerFlow to a production environment using Docker Compose for multi-user access.
|
||||
---
|
||||
|
||||
import { Callout, Steps } from "nextra/components";
|
||||
|
||||
# Deploy Your Own DeerFlow
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: First Conversation
|
||||
description: This tutorial walks you through your first complete agent conversation in DeerFlow — from launching the app to getting meaningful work done with the agent.
|
||||
---
|
||||
|
||||
import { Callout, Steps } from "nextra/components";
|
||||
|
||||
# First Conversation
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Use Tools and Skills
|
||||
description: This tutorial shows you how to configure and use tools and skills in DeerFlow to give the agent access to web search, file operations, and domain-specific capabilities.
|
||||
---
|
||||
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# Use Tools and Skills
|
||||
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Work with Memory
|
||||
description: This tutorial shows you how to enable and use DeerFlow's memory system so the agent remembers important information about you across multiple sessions.
|
||||
---
|
||||
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# Work with Memory
|
||||
|
||||
Reference in New Issue
Block a user