Merge pull request #165 from zouyonghe/docs/deerflow-agent-runner

zouyonghe · web-flow · commit 166deaaab234 · 2026-03-08T16:47:47.000+09:00
docs: add DeerFlow agent runner documentation
diff --git a/.gitignore b/.gitignore
@@ -3,4 +3,4 @@ venv/
 .DS_Store
 node_modules/
 .vitepress/cache
-*dist
+*dist
diff --git a/.vitepress/config.mjs b/.vitepress/config.mjs
@@ -153,6 +153,7 @@ export default defineConfig({
                   { text: "Dify", link: "/agent-runners/dify" },
                   { text: "扣子 Coze", link: "/agent-runners/coze" },
                   { text: "阿里云百炼应用", link: "/agent-runners/dashscope" },
+                  { text: "DeerFlow", link: "/agent-runners/deerflow" },
                 ]
               },
             ],
@@ -393,6 +394,7 @@ export default defineConfig({
                   { text: "Dify", link: "/agent-runners/dify" },
                   { text: "Coze", link: "/agent-runners/coze" },
                   { text: "Alibaba Bailian", link: "/agent-runners/dashscope" },
+                  { text: "DeerFlow", link: "/agent-runners/deerflow" },
                 ],
               },
             ],
diff --git a/en/providers/agent-runners.md b/en/providers/agent-runners.md
@@ -4,7 +4,7 @@
 
 An Agent Runner is the component in AstrBot that executes Agent capabilities and handles AI-related workflows.
 
-AstrBot includes a powerful built-in Agent Runner. You can also integrate third-party Agent Runner services like Dify, Coze, and Alibaba Bailian, or build your own.
+AstrBot includes a powerful built-in Agent Runner. You can also integrate third-party Agent Runner services like Dify, Coze, Alibaba Bailian, and DeerFlow, or build your own.
 
 If you already have a model provider that handles single requests, you still need an execution layer for multi-turn conversations, tool calling, and orchestration. That is exactly what an Agent Runner does.
 
@@ -16,3 +16,4 @@ For more details, see [Usage · Agent Runner](/en/use/agent-runner).
 - [Dify](/en/providers/agent-runners/dify)
 - [Coze](/en/providers/agent-runners/coze)
 - [Alibaba Bailian](/en/providers/agent-runners/dashscope)
+- [DeerFlow](/en/providers/agent-runners/deerflow)
diff --git a/en/providers/agent-runners/deerflow.md b/en/providers/agent-runners/deerflow.md
@@ -0,0 +1,53 @@
+# Connect to DeerFlow
+
+Starting from v4.19.2, AstrBot supports connecting to the [DeerFlow](https://github.com/bytedance/deer-flow) Agent Runner.
+
+## Preparation: Deploy DeerFlow
+
+If you have not deployed DeerFlow yet, please complete installation and startup by following the official DeerFlow documentation:
+
+- [DeerFlow GitHub Repository](https://github.com/bytedance/deer-flow)
+- [DeerFlow Official Website](https://deerflow.tech/)
+- [DeerFlow Configuration Guide](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)
+
+Make sure DeerFlow is running properly and that AstrBot can reach the DeerFlow gateway. By default, the DeerFlow gateway address is `http://127.0.0.1:2026`.
+
+> [!TIP]
+> - `API Base URL` must start with `http://` or `https://`.
+> - If AstrBot and DeerFlow run in different containers or on different hosts, replace `127.0.0.1` with the actual reachable LAN address, hostname, or domain of your DeerFlow service.
+
+## Configure DeerFlow in AstrBot
+
+In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", select "DeerFlow", and enter the DeerFlow configuration page.
+
+Fill in the following fields:
+
+- `API Base URL`: DeerFlow API gateway URL. Default: `http://127.0.0.1:2026`
+- `DeerFlow API Key`: Optional. Fill this if your DeerFlow gateway is protected by Bearer auth
+- `Authorization Header`: Optional. Custom Authorization header value. This takes precedence over `DeerFlow API Key`
+- `Assistant ID`: Maps to LangGraph `assistant_id`. Default: `lead_agent`
+- `Model name override`: Optional. Overrides the default model configured in DeerFlow
+- `Enable thinking mode`: Whether to enable DeerFlow thinking mode
+- `Enable plan mode`: Maps to DeerFlow `is_plan_mode`
+- `Enable subagent`: Maps to DeerFlow `subagent_enabled`
+- `Max concurrent subagents`: Maps to `max_concurrent_subagents`. Effective only when subagents are enabled. Default: `3`
+- `Recursion limit`: Maps to LangGraph `recursion_limit`. Default: `1000`
+
+After filling in the configuration, click Save.
+
+> [!TIP]
+> - If DeerFlow already has a default model configured on its side, you can leave `Model name override` empty.
+> - Only enable `plan mode` or `subagent` related options when the corresponding DeerFlow capabilities are already configured on the DeerFlow side.
+
+## Select Agent Runner
+
+Go to the Configuration page in the left sidebar, click "Agent Execution Method", select "DeerFlow", then select the ID of the DeerFlow Agent Runner you just created in the new configuration option below, and click "Save" in the bottom right corner to complete the configuration.
+
+## Common Checks
+
+If requests are not being executed through DeerFlow correctly, check the following first:
+
+- whether the DeerFlow service is running properly
+- whether `API Base URL` is reachable from the AstrBot environment
+- whether the authentication settings are correct
+- whether `Assistant ID` matches an actual available assistant in DeerFlow
diff --git a/en/use/agent-runner.md b/en/use/agent-runner.md
@@ -2,14 +2,15 @@
 
 The Agent Runner is a component in AstrBot used to execute Agents.
 
-Starting from version v4.7.0, we have migrated three providers—Dify, Coze, and Alibaba Cloud Bailian Application—to the Agent Runner layer, reducing some conflicts with AstrBot's existing features. Rest assured, if you upgrade from an older version to v4.7.0, you don't need to take any action as AstrBot will automatically migrate for you.
+Starting from version v4.7.0, we have migrated three providers—Dify, Coze, and Alibaba Cloud Bailian Application—to the Agent Runner layer, reducing some conflicts with AstrBot's existing features. Rest assured, if you upgrade from an older version to v4.7.0, you don't need to take any action as AstrBot will automatically migrate for you. Later versions also added DeerFlow support as an Agent Runner provider.
 
-AstrBot currently has four built-in Agent Runners:
+AstrBot currently supports five Agent Runners:
 
 - AstrBot Built-in Agent Runner
 - Dify Agent Runner
 - Coze Agent Runner
 - Alibaba Cloud Bailian Application Agent Runner
+- DeerFlow Agent Runner
 
 By default, the AstrBot Built-in Agent Runner is the default runner.
 
@@ -30,19 +31,19 @@ An Agent Runner is typically a `loop` that receives user intent, context, and en
 
 ![image](https://files.astrbot.app/docs/source/images/use/agent-runner/agent-arch.svg)
 
-LLMOps platforms like Dify, Coze, and Bailian Application have this loop built-in. If you treat them as regular Chat Providers, it will conflict with AstrBot's built-in Agent Runner functionality.
+Platforms like Dify, Coze, Bailian Application, and DeerFlow have this loop built-in. If you treat them as regular Chat Providers, it will conflict with AstrBot's built-in Agent Runner functionality.
 
 ## Usage
 
 By default, the AstrBot Built-in Agent Runner is the default runner. Using the default runner can already meet most needs, and you can use AstrBot's MCP, knowledge base, web search, and other features.
 
-If you need to use the capabilities of LLMOps platforms like Dify, Coze, or Bailian Application, you can create an Agent Runner and select the corresponding provider.
+If you need to use the capabilities of platforms like Dify, Coze, Bailian Application, or DeerFlow, you can create an Agent Runner and select the corresponding provider.
 
 ## Creating an Agent Runner
 
 ![image](https://files.astrbot.app/docs/source/images/use/agent-runner/image-1.png)
 
-In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", choose the LLMOps platform you want to connect to, and fill in the relevant information.
+In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", choose the platform or runner type you want to connect to, and fill in the relevant information.
 
 ## Changing the Default Agent Runner
 
diff --git a/en/what-is-astrbot.md b/en/what-is-astrbot.md
@@ -14,7 +14,7 @@ This documentation is divided into the following sections:
 
 - **Deployment**: multiple ways to quickly deploy AstrBot on local machines or cloud servers.
 - **Messaging Platform Integration**: integration guides for 18+ mainstream instant messaging platforms.
-- **AI Provider Integration**: connect to model providers, use AstrBot's built-in Agent Runner, or integrate third-party Agent Runner services such as Dify, Coze, and Alibaba Bailian.
+- **AI Provider Integration**: connect to model providers, use AstrBot's built-in Agent Runner, or integrate third-party Agent Runner services such as Dify, Coze, Alibaba Bailian, and DeerFlow.
 - **Usage Guides**: practical guides for features such as plugins, tool calling, knowledge base, MCP, Skills, and Agent sandbox.
 
 ## Quick Start
diff --git a/zh/providers/agent-runners.md b/zh/providers/agent-runners.md
@@ -4,7 +4,7 @@
 
 Agent 执行器是 AstrBot 中用于执行 Agent 的组件，Agent 执行器负责了所有关于 AI 的功能。
 
-AstrBot 内置了**强大的** Agent 执行器，用户也可以选择接入第三方的 Agent 执行器服务，例如 Dify、Coze、阿里云百炼应用等，或者自己开发 Agent 执行器。
+AstrBot 内置了**强大的** Agent 执行器，用户也可以选择接入第三方的 Agent 执行器服务，例如 Dify、Coze、阿里云百炼应用、DeerFlow 等，或者自己开发 Agent 执行器。
 
 想象一下，你现在已经有 AI 模型提供商，它接收你的单次请求，然后返回响应。你需要一个东西来调用这个 AI 模型提供商来实现多轮对话、工具调用等功能，这就是 Agent 执行器 的作用。
 
@@ -15,4 +15,5 @@ AstrBot 内置了**强大的** Agent 执行器，用户也可以选择接入第
 - [内置 Agent 执行器](/providers/agent-runners/astrbot-agent-runner)
 - [Dify](/providers/agent-runners/dify)
 - [扣子 Coze](/providers/agent-runners/coze)
-- [阿里云百炼应用](/providers/agent-runners/dashscope)
+- [阿里云百炼应用](/providers/agent-runners/dashscope)
+- [DeerFlow](/providers/agent-runners/deerflow)
diff --git a/zh/providers/agent-runners/deerflow.md b/zh/providers/agent-runners/deerflow.md
@@ -0,0 +1,53 @@
+# 接入 DeerFlow
+
+在 v4.19.2 及之后，AstrBot 支持接入 [DeerFlow](https://github.com/bytedance/deer-flow) Agent Runner。
+
+## 预备工作：部署 DeerFlow
+
+如果你还没有部署 DeerFlow，请先参考 DeerFlow 官方文档完成安装和启动：
+
+- [DeerFlow GitHub 仓库](https://github.com/bytedance/deer-flow)
+- [DeerFlow 官方网站](https://deerflow.tech/)
+- [DeerFlow 配置文档](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)
+
+请确认 DeerFlow 已正常启动，并且 AstrBot 可以访问 DeerFlow 的网关地址。默认情况下，DeerFlow 网关地址为 `http://127.0.0.1:2026`。
+
+> [!TIP]
+> - `API Base URL` 必须以 `http://` 或 `https://` 开头。
+> - 如果 AstrBot 与 DeerFlow 运行在不同容器或主机上，请将 `127.0.0.1` 替换为 DeerFlow 实际可访问的内网地址、主机名或域名。
+
+## 在 AstrBot 中配置 DeerFlow
+
+在 WebUI 中，点击「模型提供商」->「新增提供商」，选择「Agent 执行器」，选择「DeerFlow」，进入 DeerFlow 的配置页面。
+
+填写以下配置项：
+
+- `API Base URL`：DeerFlow API 网关地址，默认为 `http://127.0.0.1:2026`
+- `DeerFlow API Key`：可选。若你的 DeerFlow 网关使用 Bearer 鉴权，可在此填写
+- `Authorization Header`：可选。自定义 Authorization 请求头，优先级高于 `DeerFlow API Key`
+- `Assistant ID`：对应 LangGraph 的 `assistant_id`，默认为 `lead_agent`
+- `模型名称覆盖`：可选。覆盖 DeerFlow 默认模型
+- `启用思考模式`：是否启用 DeerFlow 的思考模式
+- `启用计划模式`：对应 DeerFlow 的 `is_plan_mode`
+- `启用子智能体`：对应 DeerFlow 的 `subagent_enabled`
+- `子智能体最大并发数`：对应 `max_concurrent_subagents`，仅在启用子智能体时生效，默认 `3`
+- `递归深度上限`：对应 LangGraph 的 `recursion_limit`，默认 `1000`
+
+填写完成后点击「保存」。
+
+> [!TIP]
+> - 如果 DeerFlow 侧已经配置了默认模型，可以将 `模型名称覆盖` 留空。
+> - 只有在 DeerFlow 侧已经启用了相应能力时，才建议开启 `计划模式` 或 `子智能体` 相关选项。
+
+## 选择 Agent 执行器
+
+进入左边栏配置页面，点击「Agent 执行方式」，选择「DeerFlow」，然后在下方出现的新的配置项中选择你刚刚创建的 DeerFlow Agent 执行器提供商 ID，点击右下角「保存」，即可完成配置。
+
+## 常见检查项
+
+如果请求没有正常通过 DeerFlow 执行，请优先检查以下内容：
+
+- DeerFlow 服务是否已经正常启动
+- `API Base URL` 是否能从 AstrBot 所在环境访问
+- 鉴权配置是否填写正确
+- `Assistant ID` 是否与 DeerFlow 中实际可用的 assistant 一致
diff --git a/zh/use/agent-runner.md b/zh/use/agent-runner.md
@@ -2,14 +2,15 @@
 
 Agent 执行器是 AstrBot 中用于执行 Agent 的组件。
 
-在 v4.7.0 版本之后，我们将 Dify、Coze、阿里云百炼应用这三个提供商迁移到了 Agent 执行器层面，减少了与 AstrBot 目前功能的一些冲突。请放心，如果您从旧版本升级到 v4.7.0 版本，您无需进行任何操作，AstrBot 会自动为您迁移。
+在 v4.7.0 版本之后，我们将 Dify、Coze、阿里云百炼应用这三个提供商迁移到了 Agent 执行器层面，减少了与 AstrBot 目前功能的一些冲突。请放心，如果您从旧版本升级到 v4.7.0 版本，您无需进行任何操作，AstrBot 会自动为您迁移。此后，AstrBot 也新增了 DeerFlow Agent 执行器支持。
 
-AstrBot 目前内置了四种 Agent 执行器：
+AstrBot 目前支持五种 Agent 执行器：
 
 - AstrBot 内置 Agent 执行器
 - Dify Agent 执行器
 - Coze Agent 执行器
 - 阿里云百炼应用 Agent 执行器
+- DeerFlow Agent 执行器
 
 默认情况下，AstrBot 内置 Agent 执行器为默认执行器。
 
@@ -30,22 +31,22 @@ Chat Provider 本质上是一个 `单轮补全接口`，输入 prompt + 历史
 
 ![image](https://files.astrbot.app/docs/source/images/use/agent-runner/agent-arch.svg)
 
-Dify、Coze、百炼应用等 LLMOpes 平台已经内置了这个循环，如果把它们当成普通 Chat Provider，会和 AstrBot 的内置 Agent 执行器功能冲突。
+Dify、Coze、百炼应用、DeerFlow 等平台已经内置了这个循环，如果把它们当成普通 Chat Provider，会和 AstrBot 的内置 Agent 执行器功能冲突。
 
 ## 使用
 
 默认情况下，AstrBot 内置 Agent 执行器为默认执行器。使用默认执行器已经可以满足大部分需求，并且可以使用 AstrBot 的 MCP、知识库、网页搜索等功能。
 
-如果你需要使用 Dify、Coze、百炼应用等 LLMOpes 平台的能力，可以创建一个 Agent 执行器，并选择相应的提供商。
+如果你需要使用 Dify、Coze、百炼应用、DeerFlow 等平台的能力，可以创建一个 Agent 执行器，并选择相应的提供商。
 
 ## 创建 Agent 执行器
 
 ![image](https://files.astrbot.app/docs/source/images/use/agent-runner/image-1.png)
 
-在 WebUI 中，点击「模型提供商」->「新增提供商」，选择「Agent 执行器」，选择你想接入的 LLMOpes 平台，填写相关信息即可。
+在 WebUI 中，点击「模型提供商」->「新增提供商」，选择「Agent 执行器」，选择你想接入的平台或执行器类型，填写相关信息即可。
 
 ## 更换默认 Agent 执行器
 
 ![image](https://files.astrbot.app/docs/source/images/use/agent-runner/image.png)
 
-在 WebUI 中，点击「配置」->「Agent 执行方式」，将执行器类型更换为你刚刚创建的 Agent 执行器类型，然后选择 `XX Agent 执行器提供商 ID` 为你刚刚创建的 Agent 执行器提供商的 ID，点击保存即可。
+在 WebUI 中，点击「配置」->「Agent 执行方式」，将执行器类型更换为你刚刚创建的 Agent 执行器类型，然后选择 `XX Agent 执行器提供商 ID` 为你刚刚创建的 Agent 执行器提供商的 ID，点击保存即可。
diff --git a/zh/what-is-astrbot.md b/zh/what-is-astrbot.md
@@ -14,7 +14,7 @@ AstrBot 是一个开源的一站式 Agentic 个人和群聊助手，可在 QQ、
 
 - **部署**。我们提供多种方式帮助您把 AstrBot 快速部署到云服务器或本地机器上。
 - **消息平台接入**。我们提供 18+ 主流即时通讯软件的接入指南，帮助您把 AstrBot 连接到您喜欢的 IM 平台。
-- **AI 模型提供商接入**。我们支持各种 AI 模型提供商的接入，您可以选择使用 AstrBot 内置的 Agent 执行器，也可以接入第三方的 Agent 执行器服务，例如 Dify、Coze、阿里云百炼应用等，或者自己开发 Agent 执行器。
+- **AI 模型提供商接入**。我们支持各种 AI 模型提供商的接入，您可以选择使用 AstrBot 内置的 Agent 执行器，也可以接入第三方的 Agent 执行器服务，例如 Dify、Coze、阿里云百炼应用、DeerFlow 等，或者自己开发 Agent 执行器。
 - **使用指南**。我们提供了丰富的使用指南，帮助您充分利用 AstrBot 的各种功能，例如插件、工具调用、知识库、MCP、Skills、Agent 沙箱环境等。
 
 ## 快速开始
