claude-to-deerflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DeerFlow Skill

DeerFlow 技能

Communicate with a running DeerFlow instance via its HTTP API. DeerFlow is an AI agent platform built on LangGraph that orchestrates sub-agents for research, code execution, web browsing, and more.

通过HTTP API与运行中的DeerFlow实例通信。DeerFlow是基于LangGraph构建的AI Agent平台，可编排子Agent完成调研、代码执行、网页浏览等多种任务。

Architecture

架构

DeerFlow exposes two API surfaces behind an Nginx reverse proxy:

Service	Direct Port	Via Proxy	Purpose
Gateway API	8001	`$DEERFLOW_GATEWAY_URL`	REST endpoints (models, skills, memory, uploads)
LangGraph API	2024	`$DEERFLOW_LANGGRAPH_URL`	Agent threads, runs, streaming

DeerFlow在Nginx反向代理后暴露两套API接口：

服务	直接端口	代理访问地址	用途
网关API	8001	`$DEERFLOW_GATEWAY_URL`	REST接口（模型、技能、内存、上传）
LangGraph API	2024	`$DEERFLOW_LANGGRAPH_URL`	Agent线程、运行、流式传输

Environment Variables

环境变量

All URLs are configurable via environment variables. Read these env vars before making any request.

Variable	Default	Description
`DEERFLOW_URL`	`http://localhost:2026`	Unified proxy base URL
`DEERFLOW_GATEWAY_URL`	`${DEERFLOW_URL}`	Gateway API base (models, skills, memory, uploads)
`DEERFLOW_LANGGRAPH_URL`	`${DEERFLOW_URL}/api/langgraph`	LangGraph API base (threads, runs)

When making curl calls, always resolve the URL like this:

bash

undefined

所有URL都可通过环境变量配置。发起任何请求前请先读取这些环境变量。

变量	默认值	描述
`DEERFLOW_URL`	`http://localhost:2026`	统一代理基础URL
`DEERFLOW_GATEWAY_URL`	`${DEERFLOW_URL}`	网关API基础地址（模型、技能、内存、上传）
`DEERFLOW_LANGGRAPH_URL`	`${DEERFLOW_URL}/api/langgraph`	LangGraph API基础地址（线程、运行）

发起curl调用时，请按如下方式解析URL：

bash

undefined

Resolve base URLs from env (do this FIRST before any API call)

从环境变量解析基础URL（发起任何API调用前请先执行此步骤）

DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}" DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}" DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"

undefined

DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}" DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}" DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"

undefined

Available Operations

可用操作

1. Health Check

1. 健康检查

Verify DeerFlow is running:

bash

curl -s "$DEERFLOW_GATEWAY_URL/health"

验证DeerFlow是否正在运行：

bash

curl -s "$DEERFLOW_GATEWAY_URL/health"

2. Send a Message (Streaming)

2. 发送消息（流式）

This is the primary operation. It creates a thread and streams the agent's response.

Step 1: Create a thread

bash

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{"thread_id": "<uuid>", ...}

Step 2: Stream a run

bash

curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "lead_agent",
    "input": {
      "messages": [
        {
          "type": "human",
          "content": [{"type": "text", "text": "YOUR MESSAGE HERE"}]
        }
      ]
    },
    "stream_mode": ["values", "messages-tuple"],
    "stream_subgraphs": true,
    "config": {
      "recursion_limit": 1000
    },
    "context": {
      "thinking_enabled": true,
      "is_plan_mode": true,
      "subagent_enabled": true,
      "thread_id": "<thread_id>"
    }
  }'

The response is an SSE stream. Each event has the format:

event: <event_type>
data: <json_data>

Key event types:

```
metadata
```
— run metadata including
```
run_id
```
```
values
```
— full state snapshot with
```
messages
```
array
```
messages-tuple
```
— incremental message updates (AI text chunks, tool calls, tool results)
```
end
```
— stream is complete

Context modes (set via

context

Flash mode:

thinking_enabled: false, is_plan_mode: false, subagent_enabled: false

Standard mode:

thinking_enabled: true, is_plan_mode: false, subagent_enabled: false

Pro mode:

thinking_enabled: true, is_plan_mode: true, subagent_enabled: false

Ultra mode:

thinking_enabled: true, is_plan_mode: true, subagent_enabled: true

这是核心操作，会创建线程并流式返回Agent的响应。

步骤1：创建线程

bash

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
  -H "Content-Type: application/json" \
  -d '{}'

响应：

{"thread_id": "<uuid>", ...}

步骤2：流式运行

bash

curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "lead_agent",
    "input": {
      "messages": [
        {
          "type": "human",
          "content": [{"type": "text", "text": "YOUR MESSAGE HERE"}]
        }
      ]
    },
    "stream_mode": ["values", "messages-tuple"],
    "stream_subgraphs": true,
    "config": {
      "recursion_limit": 1000
    },
    "context": {
      "thinking_enabled": true,
      "is_plan_mode": true,
      "subagent_enabled": true,
      "thread_id": "<thread_id>"
    }
  }'

响应为SSE流，每个事件的格式如下：

event: <event_type>
data: <json_data>

关键事件类型：

```
metadata
```
— 运行元数据，包含
```
run_id
```
```
values
```
— 全量状态快照，包含
```
messages
```
数组
```
messages-tuple
```
— 增量消息更新（AI文本块、工具调用、工具返回结果）
```
end
```
— 流传输完成

上下文模式（通过

context

参数设置）：

极速模式：

thinking_enabled: false, is_plan_mode: false, subagent_enabled: false

标准模式：

thinking_enabled: true, is_plan_mode: false, subagent_enabled: false

专业模式：

thinking_enabled: true, is_plan_mode: true, subagent_enabled: false

旗舰模式：

thinking_enabled: true, is_plan_mode: true, subagent_enabled: true

3. Continue a Conversation

3. 继续对话

To send follow-up messages, reuse the same

thread_id

from step 2 and POST another run with the new message.

要发送后续消息，复用步骤2中得到的

thread_id

，携带新消息发起新的运行请求即可。

4. List Models

4. 列出模型

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/models"

Returns:

{"models": [{"name": "...", "provider": "...", ...}, ...]}

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/models"

{"models": [{"name": "...", "provider": "...", ...}, ...]}

5. List Skills

5. 列出技能

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/skills"

Returns:

{"skills": [{"name": "...", "enabled": true, ...}, ...]}

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/skills"

{"skills": [{"name": "...", "enabled": true, ...}, ...]}

6. Enable/Disable a Skill

6. 启用/禁用技能

bash

curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<skill_name>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

bash

curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<skill_name>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

7. List Agents

7. 列出Agent

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/agents"

Returns:

{"agents": [{"name": "...", ...}, ...]}

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/agents"

{"agents": [{"name": "...", ...}, ...]}

8. Get Memory

8. 获取内存

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/memory"

Returns user context, facts, and conversation history summaries.

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/memory"

返回用户上下文、事实信息和对话历史摘要。

9. Upload Files to a Thread

9. 向线程上传文件

bash

curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
  -F "files=@/path/to/file.pdf"

Supports PDF, PPTX, XLSX, DOCX — automatically converts to Markdown.

bash

curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
  -F "files=@/path/to/file.pdf"

支持PDF、PPTX、XLSX、DOCX格式，会自动转换为Markdown。

10. List Uploaded Files

10. 列出已上传文件

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"

bash

curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"

11. Get Thread History

11. 获取线程历史

bash

curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"

bash

curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"

12. List Threads

12. 列出线程

bash

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'

bash

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'

Usage Script

使用脚本

For sending messages and collecting the full response, use the helper script:

bash

bash /path/to/skills/claude-to-deerflow/scripts/chat.sh "Your question here"

See

scripts/chat.sh

for the implementation. The script:

Checks health
Creates a thread
Streams the run and collects the final AI response
Prints the result

如需发送消息并收集完整响应，可使用辅助脚本：

bash

bash /path/to/skills/claude-to-deerflow/scripts/chat.sh "Your question here"

具体实现可查看

scripts/chat.sh

，该脚本会：

检查健康状态
创建线程
流式运行并收集AI的最终响应
打印结果

Parsing SSE Output

解析SSE输出

The stream returns SSE events. To extract the final AI response from a

values

event:

Look for the last
```
event: values
```
block
Parse its
```
data
```
JSON
The
```
messages
```
array contains all messages; the last one with
```
type: "ai"
```
is the response
The
```
content
```
field of that message is the AI's text reply

流返回SSE事件，如需从

values

事件中提取AI的最终响应：

查找最后一个
```
event: values
```
块
解析其
```
data
```
字段的JSON内容
```
messages
```
数组包含所有消息，最后一个
```
type: "ai"
```
的消息即为响应
该消息的
```
content
```
字段就是AI的文本回复

Error Handling

错误处理

If health check fails, DeerFlow is not running. Inform the user they need to start it.
If the stream returns an error event, extract and display the error message.
Common issues: port not open, services still starting up, config errors.

如果健康检查失败，说明DeerFlow未运行，请告知用户需要先启动DeerFlow。
如果流返回错误事件，提取并展示错误信息。
常见问题：端口未开放、服务仍在启动中、配置错误。

Tips

小贴士

For quick questions, use flash mode (fastest, no planning).
For research tasks, use pro or ultra mode (enables planning and sub-agents).
You can upload files first, then reference them in your message.
Thread IDs persist — you can return to a conversation later.

快速提问可使用极速模式（速度最快，无规划流程）。
调研任务可使用专业或旗舰模式（启用规划和子Agent）。
你可以先上传文件，再在消息中引用这些文件。
线程ID会持久化存储，你可以后续回到对应对话继续交互。