mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-04-25 11:18:22 +00:00
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
foreleven
parent
62bdfe3abc
commit
839563f308
@ -5,7 +5,7 @@
|
||||
}
|
||||
],
|
||||
"settings": {
|
||||
"typescript.tsdk": "frontend/node_modules/typescript/lib",
|
||||
"js/ts.tsdk.path": "frontend/node_modules/typescript/lib",
|
||||
"python-envs.pythonProjects": [
|
||||
{
|
||||
"path": "backend",
|
||||
@ -44,4 +44,4 @@
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -34,14 +34,14 @@ export default async function DocLayout({ children, params }) {
|
||||
<Layout
|
||||
navbar={
|
||||
<Header
|
||||
className="relative max-w-full px-10"
|
||||
className="sticky max-w-full px-10"
|
||||
homeURL="/"
|
||||
locale={locale}
|
||||
/>
|
||||
}
|
||||
pageMap={pageMap}
|
||||
docsRepositoryBase="https://github.com/bytedance/deerflow/tree/main/frontend/src/content"
|
||||
footer={<Footer />}
|
||||
footer={<Footer className="mt-0" />}
|
||||
i18n={i18n}
|
||||
// ... Your additional layout options
|
||||
>
|
||||
|
||||
@ -1,9 +1,20 @@
|
||||
import { useMemo } from "react";
|
||||
|
||||
export function Footer() {
|
||||
import { cn } from "@/lib/utils";
|
||||
|
||||
export type FooterProps = {
|
||||
className?: string;
|
||||
};
|
||||
|
||||
export function Footer({ className }: FooterProps) {
|
||||
const year = useMemo(() => new Date().getFullYear(), []);
|
||||
return (
|
||||
<footer className="container-md mx-auto mt-32 flex flex-col items-center justify-center">
|
||||
<footer
|
||||
className={cn(
|
||||
"container-md mx-auto mt-32 flex flex-col items-center justify-center",
|
||||
className,
|
||||
)}
|
||||
>
|
||||
<hr className="from-border/0 to-border/0 m-0 h-px w-full border-none bg-linear-to-r via-white/20" />
|
||||
<div className="text-muted-foreground container flex h-20 flex-col items-center justify-center text-sm">
|
||||
<p className="text-center font-serif text-lg md:text-xl">
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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: Agent 与线程
|
||||
description: 了解 DeerFlow 中 Agent 与线程的关系，以及如何管理自定义 Agent 和对话线程。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# Agent 与线程
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 配置
|
||||
description: 本页面涵盖 DeerFlow 应用的所有配置层——`config.yaml`、前端环境变量、`extensions_config.json` 和运行时环境变量。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Tabs } from "nextra/components";
|
||||
|
||||
# 配置
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 部署指南
|
||||
description: 本指南涵盖 DeerFlow 应用所有支持的部署方式：本地开发、Docker Compose 以及使用 Kubernetes 管理沙箱的生产环境。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps, Tabs } from "nextra/components";
|
||||
|
||||
# 部署指南
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: DeerFlow 应用
|
||||
description: DeerFlow 应用是 DeerFlow 生产体验的参考实现。它将 Harness 运行时、基于 Web 的对话工作区、API Gateway 和反向代理组合成一个可部署的完整系统。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# DeerFlow 应用
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 运维与排障
|
||||
description: 本页面涵盖运行 DeerFlow 应用的操作信息：日志记录、常见问题和维护任务。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 运维与排障
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 快速上手
|
||||
description: 本指南引导你使用 `make dev` 工作流在本地机器上启动 DeerFlow 应用。所有四个服务（LangGraph、Gateway、前端、nginx）一起启动，通过单个 URL 访问。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# 快速上手
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 工作区使用
|
||||
description: DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中向 Agent 发送消息、上传文件、查看中间步骤，以及下载生成的产出物。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 工作区使用
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 配置
|
||||
description: DeerFlow 的配置系统围绕一个目标设计：每一个有意义的行为都应该可以在配置文件中表达，而不是硬编码在应用程序中。这使部署可重现、可审计，并且易于按环境定制。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 配置
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 自定义与扩展
|
||||
description: DeerFlow 的可插拔架构意味着系统的大多数部分都可以在不 fork 核心的情况下被替换或扩展。本页面列举了扩展点，并解释如何使用每一个。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 自定义与扩展
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 设计理念
|
||||
description: 了解 DeerFlow Harness 背后的设计理念，有助于你有效地使用它、自信地扩展它，并推断 Agent 在生产环境中的行为方式。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 设计理念
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 安装 DeerFlow Harness
|
||||
description: DeerFlow Harness 是构建自己 Super Agent 系统的 Python SDK 和运行时基础。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 安装 DeerFlow Harness
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 集成指南
|
||||
description: DeerFlow Harness 不仅仅是一个独立应用程序——它是一个可以导入并在你自己的后端、API 服务器、自动化系统或多 Agent 协调器中使用的 Python 库。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 集成指南
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Lead Agent
|
||||
description: Lead Agent 是 DeerFlow 线程中的核心执行者。每个对话、任务和工作流都通过它进行。理解它的工作方式有助于你有效地配置它，并在需要时扩展它。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# Lead Agent
|
||||
|
||||
@ -1,9 +1,15 @@
|
||||
---
|
||||
title: MCP 集成
|
||||
description: Model Context Protocol（MCP） 是连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许你用任何实现了 MCP 协议的工具服务器扩展 Agent——无需修改 Harness 本身。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# MCP 集成
|
||||
|
||||
<Callout type="info" emoji="🔌">
|
||||
Model Context Protocol（MCP）让 DeerFlow 能够连接任何外部工具服务器。连接后，MCP 工具与内置工具一样对 Lead Agent 可用。
|
||||
Model Context Protocol（MCP）让 DeerFlow
|
||||
能够连接任何外部工具服务器。连接后，MCP 工具与内置工具一样对 Lead Agent 可用。
|
||||
</Callout>
|
||||
|
||||
**Model Context Protocol（MCP）** 是连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许你用任何实现了 MCP 协议的工具服务器扩展 Agent——无需修改 Harness 本身。
|
||||
@ -37,6 +43,7 @@ MCP 服务器在 `extensions_config.json` 中配置，这个文件独立于 `con
|
||||
```
|
||||
|
||||
每个服务器条目支持：
|
||||
|
||||
- `command`：要运行的可执行文件（如 `npx`、`uvx`、`python`）
|
||||
- `args`：命令参数数组
|
||||
- `enabled`：服务器是否激活（可切换而无需删除条目）
|
||||
@ -81,6 +88,7 @@ tool_search:
|
||||
某些 MCP 服务器需要 OAuth 认证。DeerFlow 的 `mcp/oauth.py` 处理声明了 OAuth 需求的服务器的 OAuth 流程。
|
||||
|
||||
当连接到受 OAuth 保护的 MCP 服务器时，DeerFlow 会：
|
||||
|
||||
1. 从服务器能力头中检测 OAuth 需求
|
||||
2. 使用 `get_initial_oauth_headers()` 构建适当的授权头
|
||||
3. 通过 `build_oauth_tool_interceptor()` 用 OAuth 拦截器包装工具调用
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 记忆系统
|
||||
description: 记忆是 DeerFlow Harness 的一个运行时功能。它不是简单的对话日志，而是跨多个独立会话持久化、在未来对话中影响 Agent 行为的结构化事实和上下文摘要存储。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 记忆系统
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 中间件
|
||||
description: 每次 Lead Agent 调用 LLM 时，都会先后执行一条**中间件链**。中间件可以读取和修改 Agent 的状态、向系统提示注入内容、拦截工具调用，并对模型输出做出反应。
|
||||
---
|
||||
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# 中间件
|
||||
|
||||
@ -1,12 +1,18 @@
|
||||
---
|
||||
title: 快速上手
|
||||
description: 学习如何使用 create_deerflow_agent 创建并运行 DeerFlow Agent，从模型初始化到流式响应。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Steps } from "nextra/components";
|
||||
|
||||
# 快速上手
|
||||
|
||||
<Callout type="info" emoji="🚀">
|
||||
本指南介绍如何以编程方式使用 DeerFlow Harness——不是通过应用界面，而是直接在 Python 中导入和调用 Harness。
|
||||
本指南介绍如何在 Python 中通过 <code>create_deerflow_agent</code>
|
||||
创建并运行一个 DeerFlow Agent。
|
||||
</Callout>
|
||||
|
||||
DeerFlow Harness 是 Python SDK 和运行时基础。本快速上手指南将带你了解运行 Agent、流式传输输出和使用线程的核心 API。
|
||||
理解 DeerFlow Harness 的最快方式，是直接在代码里创建一个 Agent。本快速上手指南将带你完成模型初始化、Agent 创建，以及响应流式输出。
|
||||
|
||||
## 前置条件
|
||||
|
||||
@ -19,130 +25,86 @@ cd backend
|
||||
uv sync
|
||||
```
|
||||
|
||||
## 配置
|
||||
你还需要准备一个来自对应 LangChain Provider 包的聊天模型实例。
|
||||
|
||||
所有 Harness 行为由 `config.yaml` 驱动。至少需要配置一个模型：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
将 `config.example.yaml` 复制到 `config.yaml` 并填写你的 API Key。
|
||||
|
||||
## 运行 Harness
|
||||
|
||||
DeerFlow Harness 的主要入口是 `DeerFlowClient`。它管理线程状态、调用 Lead Agent，并流式传输响应。
|
||||
## 创建第一个 Agent
|
||||
|
||||
<Steps>
|
||||
|
||||
### 导入并配置
|
||||
### 导入工厂函数与模型类
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from deerflow.client import DeerFlowClient
|
||||
from deerflow.config import load_config
|
||||
|
||||
# 从当前目录或 DEER_FLOW_CONFIG_PATH 加载 config.yaml
|
||||
load_config()
|
||||
|
||||
client = DeerFlowClient()
|
||||
from deerflow.agents import create_deerflow_agent
|
||||
from langchain_openai import ChatOpenAI
|
||||
```
|
||||
|
||||
### 创建线程
|
||||
### 创建模型
|
||||
|
||||
```python
|
||||
thread_id = "my-thread-001"
|
||||
model = ChatOpenAI(
|
||||
model="gpt-4o",
|
||||
api_key="YOUR_OPENAI_API_KEY",
|
||||
)
|
||||
```
|
||||
|
||||
线程 ID 是任意字符串。使用相同 ID 可以继续已有对话（需要配置检查点）。
|
||||
|
||||
### 发送消息并流式传输响应
|
||||
### 创建 Agent
|
||||
|
||||
```python
|
||||
async def run():
|
||||
async for event in client.astream(
|
||||
thread_id=thread_id,
|
||||
message="研究前三大开源 LLM 框架并进行总结。",
|
||||
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())
|
||||
这会返回一个已经编译好的 LangGraph Agent，并带有 DeerFlow 默认的中间件链。
|
||||
|
||||
### 流式获取响应
|
||||
|
||||
```python
|
||||
for event in agent.stream(
|
||||
{"messages": [{"role": "user", "content": "解释一下 DeerFlow Harness 是什么。"}]},
|
||||
stream_mode=["messages", "values"],
|
||||
):
|
||||
print(event)
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
## 可配置选项
|
||||
## 添加工具或行为
|
||||
|
||||
`config.configurable` 字典控制每次请求的行为：
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `model_name` | `str \| None` | 配置中第一个模型 | 本次请求使用的模型 |
|
||||
| `thinking_enabled` | `bool` | `True` | 启用扩展思考模式（如果支持） |
|
||||
| `reasoning_effort` | `str \| None` | `None` | 推理努力程度（特定模型参数） |
|
||||
| `is_plan_mode` | `bool` | `False` | 启用 TodoList 中间件进行任务跟踪 |
|
||||
| `subagent_enabled` | `bool` | `False` | 允许 Agent 委派子任务 |
|
||||
| `max_concurrent_subagents` | `int` | `3` | 每轮最大并行子 Agent 调用数 |
|
||||
| `agent_name` | `str \| None` | `None` | 要加载的自定义 Agent 名称 |
|
||||
|
||||
## 流式事件类型
|
||||
|
||||
`client.astream()` 从 LangGraph 运行时产生事件，主要事件类型如下：
|
||||
|
||||
| 事件类型 | 说明 |
|
||||
|---|---|
|
||||
| `messages` | 消息块（文本、思考过程、工具调用） |
|
||||
| `thread_state` | 线程状态更新（标题、产出物、待办列表） |
|
||||
|
||||
消息块包含 Agent 生成响应时的 token 流。
|
||||
|
||||
## 使用自定义 Agent
|
||||
|
||||
如果已定义自定义 Agent，在 configurable 中传入其 `name`：
|
||||
你可以通过传入工具、系统提示词、运行时特性、中间件或 checkpointer 来自定义 Agent。
|
||||
|
||||
```python
|
||||
async for event in client.astream(
|
||||
thread_id="thread-002",
|
||||
message="分析上传的 CSV 并生成摘要图表。",
|
||||
config={
|
||||
"configurable": {
|
||||
"agent_name": "data-analyst",
|
||||
"subagent_enabled": True,
|
||||
}
|
||||
},
|
||||
):
|
||||
...
|
||||
from deerflow.agents import RuntimeFeatures, create_deerflow_agent
|
||||
|
||||
agent = create_deerflow_agent(
|
||||
model,
|
||||
system_prompt="你是一个简洁的研究助手。",
|
||||
features=RuntimeFeatures(subagent=True, memory=False),
|
||||
plan_mode=True,
|
||||
name="research-agent",
|
||||
)
|
||||
```
|
||||
|
||||
自定义 Agent 的配置（模型、技能、工具组）将从 `agents/data-analyst/config.yaml` 自动加载。
|
||||
常用参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `tools` | 提供给 Agent 的额外工具 |
|
||||
| `system_prompt` | 自定义系统提示词 |
|
||||
| `features` | 启用或替换内置运行时能力 |
|
||||
| `extra_middleware` | 将自定义中间件插入默认链路 |
|
||||
| `plan_mode` | 启用 Todo 风格的任务跟踪 |
|
||||
| `checkpointer` | 为多轮运行持久化状态 |
|
||||
| `name` | Agent 的逻辑名称 |
|
||||
|
||||
## 什么时候使用 DeerFlowClient
|
||||
|
||||
如果你想直接操作底层的编译后 Agent 图，使用 `create_deerflow_agent()`。
|
||||
|
||||
如果你想使用更高层的嵌入式应用接口，则应使用 `DeerFlowClient`，例如：
|
||||
|
||||
- 面向线程的对话封装，
|
||||
- 模型 / 技能 / 记忆管理 API，
|
||||
- 文件上传与 artifacts，
|
||||
- 与 Gateway 一致的返回格式。
|
||||
|
||||
<Cards num={3}>
|
||||
<Cards.Card title="设计理念" href="/docs/harness/design-principles" />
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 沙箱
|
||||
description: 沙箱为 Lead Agent 提供一个受控环境，在其中可以读取文件、写入输出、运行 Shell 命令并生成产出物。没有沙箱，Agent 只能生成文本；有了沙箱，它可以编写和执行代码、处理数据文件、生成图表并构建交付物。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Tabs } from "nextra/components";
|
||||
|
||||
# 沙箱
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 技能
|
||||
description: 技能不仅仅是提示词。它是一个自包含的能力包，可以包含结构化指令、分步工作流、领域最佳实践、支撑资源和工具配置。技能按需加载——在任务需要时注入内容，否则不影响上下文。
|
||||
---
|
||||
|
||||
import { Callout, Cards, FileTree, Steps } from "nextra/components";
|
||||
|
||||
# 技能
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 子 Agent
|
||||
description: 当一个任务对单个推理线程来说太宽泛，或者部分任务可以并行完成时，Lead Agent 将工作委派给**子 Agent**。子 Agent 是一个独立的 Agent 调用，接收特定任务、执行并返回结果。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 子 Agent
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 工具
|
||||
description: Lead Agent 是一个工具调用 Agent。工具是它与世界交互的方式：搜索网络、读写文件、运行命令、委派任务以及向用户呈现输出。
|
||||
---
|
||||
|
||||
import { Callout, Cards, Tabs } from "nextra/components";
|
||||
|
||||
# 工具
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 核心概念
|
||||
description: 在深入了解 DeerFlow 之前，先建立一些贯穿整个系统的核心概念。这些概念解释了 DeerFlow 的优化目标以及其架构设计的原因。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 核心概念
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Harness 与应用
|
||||
description: DeerFlow 有两个紧密相关但服务于不同目的的层次：.
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# Harness 与应用
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 为什么选择 DeerFlow
|
||||
description: DeerFlow 的诞生是因为现代 Agent 系统需要的不仅仅是一个聊天循环。一个真正有用的 Agent 必须能够进行长时序规划、将任务拆解为子任务、使用工具、操作文件、安全地运行代码，并在复杂任务中保持足够的上下文连贯性。DeerFlow 正是为提供这样的运行时基础而构建的。
|
||||
---
|
||||
|
||||
import { Callout, Cards } from "nextra/components";
|
||||
|
||||
# 为什么选择 DeerFlow
|
||||
|
||||
@ -1,20 +1,8 @@
|
||||
import type { MetaRecord } from "nextra";
|
||||
|
||||
const meta: MetaRecord = {
|
||||
"concepts-glossary": {
|
||||
title: "概念词汇表",
|
||||
},
|
||||
"configuration-reference": {
|
||||
title: "配置参考",
|
||||
},
|
||||
"api-gateway-reference": {
|
||||
title: "API / Gateway 参考",
|
||||
},
|
||||
"runtime-flags-and-modes": {
|
||||
title: "运行时标志与模式",
|
||||
},
|
||||
"source-map": {
|
||||
title: "代码映射",
|
||||
"model-providers": {
|
||||
title: "模型接入",
|
||||
},
|
||||
};
|
||||
|
||||
|
||||
@ -1,68 +0,0 @@
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# API / Gateway 参考
|
||||
|
||||
<Callout type="info">
|
||||
DeerFlow Gateway 是基于 FastAPI 构建的，提供交互式 API 文档，可通过 <code>http://localhost:8001/docs</code> 访问。
|
||||
</Callout>
|
||||
|
||||
## 基础 URL
|
||||
|
||||
```
|
||||
http://localhost:8001
|
||||
```
|
||||
|
||||
通过 nginx 代理：
|
||||
|
||||
```
|
||||
http://localhost:2026/api
|
||||
```
|
||||
|
||||
## 核心端点
|
||||
|
||||
### 系统
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
|---|---|---|
|
||||
| `GET` | `/health` | 服务健康检查 |
|
||||
| `GET` | `/api/models` | 获取已配置的模型列表 |
|
||||
|
||||
### Agent 管理
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/agents` | 列出所有 Agent |
|
||||
| `POST` | `/api/agents` | 创建自定义 Agent |
|
||||
| `GET` | `/api/agents/{name}` | 获取 Agent 配置 |
|
||||
| `PUT` | `/api/agents/{name}` | 更新 Agent 配置 |
|
||||
| `DELETE` | `/api/agents/{name}` | 删除 Agent |
|
||||
| `POST` | `/api/agents/check` | 检查/建议 Agent slug 唯一性 |
|
||||
|
||||
### 线程和记忆
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/threads` | 列出线程 |
|
||||
| `DELETE` | `/api/threads/{thread_id}` | 删除线程 |
|
||||
| `GET` | `/api/memory` | 获取全局记忆 |
|
||||
| `GET` | `/api/memory/{agent_name}` | 获取 Agent 特定记忆 |
|
||||
| `DELETE` | `/api/memory` | 清除全局记忆 |
|
||||
|
||||
### 扩展
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/extensions` | 列出所有扩展（MCP 服务器和技能） |
|
||||
| `POST` | `/api/extensions/mcp/{name}/enable` | 启用 MCP 服务器 |
|
||||
| `POST` | `/api/extensions/mcp/{name}/disable` | 禁用 MCP 服务器 |
|
||||
| `POST` | `/api/extensions/skills/{name}/enable` | 启用技能 |
|
||||
| `POST` | `/api/extensions/skills/{name}/disable` | 禁用技能 |
|
||||
|
||||
### 文件上传
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/uploads/{thread_id}` | 上传文件到线程工作区 |
|
||||
| `GET` | `/api/uploads/{thread_id}/{filename}` | 获取上传的文件 |
|
||||
|
||||
完整的交互式 API 文档请访问 `http://localhost:8001/docs`（Swagger UI）。
|
||||
@ -1,67 +0,0 @@
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# 概念词汇表
|
||||
|
||||
本词汇表定义了 DeerFlow 文档中使用的核心术语。
|
||||
|
||||
---
|
||||
|
||||
## Agent
|
||||
|
||||
在 DeerFlow 中，Agent 是接收用户消息、决定采取什么行动（工具调用或直接响应），并生成输出的主要处理单元。DeerFlow 使用 **Lead Agent** 和**子 Agent** 两级架构。
|
||||
|
||||
## Artifact（产出物）
|
||||
|
||||
Agent 生成的文件——报告、图表、代码或其他交付物。产出物通过 `present_files` 工具暴露，并持久化存储在线程的用户数据目录中。
|
||||
|
||||
## Checkpoint（检查点）
|
||||
|
||||
线程状态的持久化快照，在每次 Agent 轮次后保存。检查点允许服务器重启后恢复对话，并支持长时序任务的状态管理。
|
||||
|
||||
## Context Engineering（上下文工程）
|
||||
|
||||
通过控制 Agent 在每个步骤可见的内容（通过摘要压缩、子 Agent 上下文隔离和外部文件记忆）来保持 Agent 在长时序任务中有效的实践。
|
||||
|
||||
## Harness
|
||||
|
||||
带有主张的 Agent 运行时，打包了工具访问、技能加载、沙箱执行、记忆、子 Agent 协调和上下文管理——而不仅仅是暴露抽象接口。
|
||||
|
||||
## Lead Agent
|
||||
|
||||
每个 DeerFlow 线程中的主要执行者，负责规划、工具调用和响应生成。基于 LangGraph + LangChain Agent 构建，由中间件链增强。
|
||||
|
||||
## Long-horizon Agent（长时序 Agent）
|
||||
|
||||
在一系列动作中保持有效的 Agent——进行规划、多次调用工具、管理中间文件，并生成最终产出物——而不是只产生单一答案。
|
||||
|
||||
## Memory（记忆）
|
||||
|
||||
跨多个独立对话会话持久化的结构化事实和用户上下文存储，在后续会话中注入到 Agent 的系统提示中。
|
||||
|
||||
## Middleware（中间件）
|
||||
|
||||
包裹每次 LLM 调用的插件，可以在模型调用前后读取和修改 Agent 状态。DeerFlow 使用中间件实现记忆、摘要压缩、标题生成等跨领域行为。
|
||||
|
||||
## MCP（Model Context Protocol）
|
||||
|
||||
连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许连接任何兼容的工具服务器。
|
||||
|
||||
## Sandbox（沙箱）
|
||||
|
||||
Agent 进行文件和命令操作的隔离执行环境。DeerFlow 支持本地（`LocalSandboxProvider`）和基于容器（`AioSandboxProvider`）两种沙箱模式。
|
||||
|
||||
## Skill（技能）
|
||||
|
||||
面向任务的能力包，包含结构化指令、工作流程和最佳实践，按需加载到 Agent 上下文中。技能提供专业化而不污染通用 Agent 上下文。
|
||||
|
||||
## Subagent（子 Agent）
|
||||
|
||||
接受委派子任务的专注执行者，以隔离上下文运行，仅接收完成其分配任务所需的信息。
|
||||
|
||||
## Thread（线程）
|
||||
|
||||
对话及其所有相关状态——消息历史、产出物、待办列表和检查点数据——的完整封装。
|
||||
|
||||
## ThreadState
|
||||
|
||||
DeerFlow 中 LangGraph 管理的状态对象，包含 `messages`、`artifacts`、`todo_list` 和运行时元数据。
|
||||
@ -1,122 +0,0 @@
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# 配置参考
|
||||
|
||||
本页面提供 `config.yaml` 中所有顶层字段的完整参考。
|
||||
|
||||
<Callout type="info">
|
||||
查看仓库根目录中的 <code>config.example.yaml</code> 获取带注释的完整配置示例。
|
||||
</Callout>
|
||||
|
||||
## 顶层字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `config_version` | `int` | 配置 schema 版本（当前：6） |
|
||||
| `log_level` | `str` | 日志级别：`debug`/`info`/`warning`/`error` |
|
||||
| `models` | `list` | 可用的 LLM 模型配置 |
|
||||
| `image_generate_model` | `str \| list` | 图像生成使用的模型名称 |
|
||||
| `token_usage` | `object` | Token 使用追踪配置 |
|
||||
| `tools` | `list` | 可用工具配置 |
|
||||
| `tool_groups` | `list` | 工具的命名分组 |
|
||||
| `tool_search` | `object` | 延迟工具加载配置 |
|
||||
| `sandbox` | `object` | 沙箱提供者配置 |
|
||||
| `skills` | `object` | 技能目录和容器路径 |
|
||||
| `skill_evolution` | `object` | Agent 管理的技能创建 |
|
||||
| `subagents` | `object` | 子 Agent 超时和最大轮次 |
|
||||
| `acp_agents` | `dict` | 外部 ACP Agent 配置 |
|
||||
| `memory` | `object` | 跨会话记忆存储 |
|
||||
| `summarization` | `object` | 对话摘要压缩 |
|
||||
| `title` | `object` | 自动线程标题生成 |
|
||||
| `checkpointer` | `object` | 线程状态持久化 |
|
||||
| `guardrails` | `object` | 工具调用授权 |
|
||||
| `uploads` | `object` | 文件上传配置 |
|
||||
| `channels` | `list` | IM 频道集成 |
|
||||
|
||||
## models
|
||||
|
||||
```yaml
|
||||
models:
|
||||
- name: gpt-4o # 模型标识符（在请求中引用）
|
||||
use: langchain_openai:ChatOpenAI # Python 类路径
|
||||
model: gpt-4o # 传给 LLM 的模型名称
|
||||
api_key: $OPENAI_API_KEY # API 密钥（支持环境变量）
|
||||
base_url: null # 可选：自定义端点
|
||||
request_timeout: 600.0 # 请求超时（秒）
|
||||
max_retries: 2 # 重试次数
|
||||
supports_vision: true # 是否启用视觉功能
|
||||
thinking_enabled: false # 是否启用扩展思考
|
||||
# 任何其他字段都会传递给模型构造函数
|
||||
```
|
||||
|
||||
## sandbox
|
||||
|
||||
```yaml
|
||||
sandbox:
|
||||
# 本地（默认，无容器隔离）
|
||||
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
|
||||
|
||||
# 基于容器
|
||||
# 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
|
||||
```
|
||||
|
||||
参见各功能的文档页面了解所有字段的详细说明。
|
||||
@ -0,0 +1,9 @@
|
||||
import type { MetaRecord } from "nextra";
|
||||
|
||||
const meta: MetaRecord = {
|
||||
ark: {
|
||||
title: "火山方舟",
|
||||
},
|
||||
};
|
||||
|
||||
export default meta;
|
||||
@ -0,0 +1,8 @@
|
||||
---
|
||||
title: 火山方舟
|
||||
description: 火山方舟模型接入指南。
|
||||
---
|
||||
|
||||
# 火山方舟
|
||||
|
||||
## Coding Plan
|
||||
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: 模型厂商服务接入
|
||||
description: 已支持模型厂商服务的接入参考文档。
|
||||
asIndexPage: true
|
||||
---
|
||||
|
||||
# 更多模型厂商服务接入
|
||||
@ -1,36 +0,0 @@
|
||||
# 运行时标志与模式
|
||||
|
||||
本页面记录影响 DeerFlow Harness 和 Agent 运行时行为的运行时标志和模式。
|
||||
|
||||
## 每次请求的可配置选项
|
||||
|
||||
这些选项通过 `config.configurable` 字典传递（用于程序化使用）或在 Web UI 中选择（用于应用使用）：
|
||||
|
||||
| 标志 | 类型 | 默认值 | 描述 |
|
||||
|---|---|---|---|
|
||||
| `model_name` | `str \| None` | 配置的第一个模型 | 请求使用的模型 |
|
||||
| `agent_name` | `str \| None` | `None` | 加载自定义 Agent 配置 |
|
||||
| `thinking_enabled` | `bool` | `True` | 启用扩展思考（模型必须支持） |
|
||||
| `reasoning_effort` | `str \| None` | `None` | 推理努力程度（模型特定） |
|
||||
| `is_plan_mode` | `bool` | `False` | 启用 TodoList 中间件 |
|
||||
| `subagent_enabled` | `bool` | `False` | 允许子 Agent 委派 |
|
||||
| `max_concurrent_subagents` | `int` | `3` | 最大并行子 Agent 调用数 |
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 默认值 | 描述 |
|
||||
|---|---|---|
|
||||
| `DEER_FLOW_CONFIG_PATH` | 自动发现 | `config.yaml` 的绝对路径 |
|
||||
| `LOG_LEVEL` | `info` | 日志级别覆盖 |
|
||||
| `DEER_FLOW_ROOT` | 仓库根目录 | Docker 挂载的基础路径 |
|
||||
| `BETTER_AUTH_SECRET` | — | 前端会话密钥（生产必须设置） |
|
||||
| `BETTER_AUTH_URL` | — | 公开 URL（用于回调和 CORS） |
|
||||
|
||||
## 模型能力标志
|
||||
|
||||
在 `config.yaml` 中的模型配置里设置：
|
||||
|
||||
| 标志 | 类型 | 描述 |
|
||||
|---|---|---|
|
||||
| `supports_vision` | `bool` | 模型接受图像输入 |
|
||||
| `thinking_enabled` | `bool` | 模型支持扩展思考模式 |
|
||||
@ -1,88 +0,0 @@
|
||||
# 代码映射
|
||||
|
||||
本页面将 DeerFlow 的核心概念映射到其在代码库中的实现位置，帮助你快速定位特定功能的代码。
|
||||
|
||||
## 后端核心路径
|
||||
|
||||
```
|
||||
backend/
|
||||
├── app/
|
||||
│ └── gateway/ # FastAPI Gateway API
|
||||
│ ├── routers/
|
||||
│ │ ├── agents.py # 自定义 Agent CRUD
|
||||
│ │ ├── extensions.py # MCP/技能启用禁用
|
||||
│ │ ├── memory.py # 记忆读取/清除
|
||||
│ │ ├── threads.py # 线程管理
|
||||
│ │ └── uploads.py # 文件上传
|
||||
│ └── main.py # FastAPI 应用入口
|
||||
│
|
||||
└── packages/harness/deerflow/
|
||||
├── agents/
|
||||
│ ├── lead_agent/
|
||||
│ │ ├── agent.py # make_lead_agent() 工厂
|
||||
│ │ └── prompt.py # 系统提示模板
|
||||
│ ├── middlewares/ # 所有中间件实现
|
||||
│ ├── memory/
|
||||
│ │ ├── middleware.py # MemoryMiddleware
|
||||
│ │ └── storage.py # 记忆文件存储
|
||||
│ └── thread_state.py # ThreadState 数据类
|
||||
│
|
||||
├── config/
|
||||
│ ├── app_config.py # AppConfig（顶层配置）
|
||||
│ ├── model_config.py # ModelConfig
|
||||
│ ├── paths.py # 路径解析工具
|
||||
│ └── *.py # 各模块配置类
|
||||
│
|
||||
├── mcp/
|
||||
│ ├── cache.py # 基于 mtime 的工具缓存
|
||||
│ └── oauth.py # MCP OAuth 支持
|
||||
│
|
||||
├── models/
|
||||
│ └── factory.py # create_chat_model() LLM 工厂
|
||||
│
|
||||
├── sandbox/
|
||||
│ ├── local/ # LocalSandboxProvider
|
||||
│ └── sandbox.py # Sandbox 基类
|
||||
│
|
||||
├── skills/
|
||||
│ ├── loader.py # load_skills()（热重载）
|
||||
│ ├── parser.py # SKILL.md 解析
|
||||
│ ├── installer.py # 依赖安装
|
||||
│ └── manager.py # 技能生命周期
|
||||
│
|
||||
├── subagents/
|
||||
│ └── registry.py # 子 Agent 查找与配置覆盖
|
||||
│
|
||||
└── tools/
|
||||
└── builtins/ # 内置工具实现
|
||||
```
|
||||
|
||||
## 前端核心路径
|
||||
|
||||
```
|
||||
frontend/src/
|
||||
├── app/ # Next.js 路由
|
||||
├── components/
|
||||
│ └── workspace/ # 工作区 UI 组件
|
||||
├── core/
|
||||
│ ├── agents/ # Agent 类型和 API 客户端
|
||||
│ ├── messages/ # 消息类型和工具调用处理
|
||||
│ └── threads/ # 线程状态管理
|
||||
└── content/ # 文档内容（MDX）
|
||||
├── en/ # 英文文档
|
||||
└── zh/ # 中文文档
|
||||
```
|
||||
|
||||
## 关键文件快速索引
|
||||
|
||||
| 目标 | 文件 |
|
||||
|---|---|
|
||||
| Lead Agent 创建 | `agents/lead_agent/agent.py` |
|
||||
| 系统提示模板 | `agents/lead_agent/prompt.py` |
|
||||
| 所有中间件 | `agents/middlewares/` |
|
||||
| 配置加载 | `config/app_config.py` |
|
||||
| 模型工厂 | `models/factory.py` |
|
||||
| 技能加载（热重载） | `skills/loader.py` |
|
||||
| MCP 工具缓存 | `mcp/cache.py` |
|
||||
| 文件上传处理 | `uploads/manager.py` |
|
||||
| Gateway 主路由器 | `app/gateway/main.py` |
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 创建你的第一个 Harness
|
||||
description: 本教程介绍如何以编程方式使用 DeerFlow Harness Python SDK——直接在你的 Python 代码中导入和使用 DeerFlow，而不是通过 Web 界面。
|
||||
---
|
||||
|
||||
# 创建你的第一个 Harness
|
||||
|
||||
本教程介绍如何以编程方式使用 DeerFlow Harness Python SDK——直接在你的 Python 代码中导入和使用 DeerFlow，而不是通过 Web 界面。
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 部署你的 DeerFlow
|
||||
description: 本教程引导你将 DeerFlow 部署到生产环境，使用 Docker Compose 进行多用户访问。
|
||||
---
|
||||
|
||||
# 部署你的 DeerFlow
|
||||
|
||||
本教程引导你将 DeerFlow 部署到生产环境，使用 Docker Compose 进行多用户访问。
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 第一次对话
|
||||
description: 本教程引导你在 DeerFlow 中完成第一次完整的 Agent 对话，从启动应用到与 Agent 进行实质性任务交互。
|
||||
---
|
||||
|
||||
# 第一次对话
|
||||
|
||||
本教程引导你在 DeerFlow 中完成第一次完整的 Agent 对话，从启动应用到与 Agent 进行实质性任务交互。
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 使用工具和技能
|
||||
description: 本教程介绍如何在 DeerFlow 中配置和使用工具（Tools）与技能（Skills），让 Agent 能够访问搜索、文件操作和特定领域能力。
|
||||
---
|
||||
|
||||
# 使用工具和技能
|
||||
|
||||
本教程介绍如何在 DeerFlow 中配置和使用工具（Tools）与技能（Skills），让 Agent 能够访问搜索、文件操作和特定领域能力。
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: 使用记忆系统
|
||||
description: 本教程介绍如何在 DeerFlow 中启用和使用记忆系统，让 Agent 在多次会话中记住关于你的重要信息。
|
||||
---
|
||||
|
||||
# 使用记忆系统
|
||||
|
||||
本教程介绍如何在 DeerFlow 中启用和使用记忆系统，让 Agent 在多次会话中记住关于你的重要信息。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user