Skip to Content
DeerFlow

Agent 与线程

🤖

Agent 是配置单元——它们定义了一组能力。线程是对话实例，带有持久化状态和历史记录。

自定义 Agent

DeerFlow 允许你创建多个具有不同专业领域的自定义 Agent。每个 Agent 使用 DeerFlow Harness 相同的 Lead Agent 运行时，但具有不同的：

  • 模型（例如为一个 Agent 使用 GPT-4o，为另一个使用 Claude）
  • 系统提示和指令
  • 技能（例如专注于数据分析的 Agent 只加载数据分析技能）
  • 工具访问（通过工具组）

创建自定义 Agent

以下两种方式都要求在 config.yaml 中设置 agents_api.enabled: true。管理 API 默认关闭，并且只应在可信边界内开放。

通过界面

  1. 打开 DeerFlow 应用。
  2. 点击侧边栏中的 Agents（Agent 管理）。
  3. 点击 New Agent（新建 Agent）。
  4. 填写名称、描述和配置。
  5. 保存——Agent 立即可用，无需重启。

通过 API

curl -X POST http://localhost:8001/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-analyst",
    "description": "专业的数据分析和可视化",
    "skills": ["data-analysis", "chart-visualization"]
  }'

Agent 名称

创建 Agent 时，需要提供在每位用户范围内唯一的 ASCII name。该名称用于 API、路由和文件路径，必须匹配 ^[A-Za-z0-9-]+$，后端会以小写形式存储它。

创建 Agent 前，可以调用 /api/agents/check?name={name} 验证名称并检查它是否可用。

Agent 存储

使用默认的 agent_storage.backend: file 时，自定义 Agent 配置按用户存储在 {base_dir}/users/{user_id}/agents/{name}/config.yaml 中，其中 {base_dir} 是 DEER_FLOW_HOME（默认值为 backend/.deer-flow）。旧的 {base_dir}/agents/{name}/ 布局仅作为尚未执行 backend/scripts/migrate_user_isolation.py 的安装的只读回退路径。使用 agent_storage.backend: db 时，定义会改为存储在共享 SQL 数据库中；它要求 database.backend: sqlite 或 database.backend: postgres。使用 backend/scripts/migrate_agents_to_db.py 迁移已有的文件后端定义。

使用文件后端时，你可以直接编辑这些文件；更改会在下一次 Agent 调用时自动加载，无需重启。

线程生命周期

线程是对话及其所有相关状态的完整封装：消息历史、产出物、待办列表和检查点数据。

创建

线程在你发送第一条消息时创建。线程 ID 是自动生成的 UUID（由前端生成），用于标识所有后续请求中的对话。

执行

每次你发送消息，LangGraph 从最新检查点恢复线程状态，运行 Lead Agent，并更新状态。流式事件在 Agent 工作时发送到浏览器。

线程持久化配置

DeerFlow 在每次 Agent 轮次后自动保存线程状态。使用持久化后端时，这允许：

  • 在服务器重启后恢复线程。
  • 在长时间间隔后继续对话。
  • 在出现问题时重放或从特定时间点恢复。

database 配置控制线程状态和应用数据的默认持久化后端：

# SQLite（本地开发和单用户部署）
database:
  backend: sqlite
  sqlite_dir: .deer-flow/data
 
# Postgres（生产环境和多用户部署）
# database:
#   backend: postgres
#   postgres_url: $DATABASE_URL
#
# run_events:
#   backend: db

旧的 checkpointer 配置仍然兼容，用于 LangGraph 状态持久化；如果配置了它，会优先于 database 的检查点设置。新的部署应优先使用 database。

线程数据目录

每个线程在 .deer-flow/threads/{thread_id}/ 下有一个专用目录：

.deer-flow/threads/{thread_id}/
  user-data/
    uploads/     ← 用户上传的文件
    outputs/     ← Agent 生成的产出物
    workspace/   ← 会话工作文件

删除线程会移除其检查点数据，但用户数据目录会单独管理（取决于删除配置）。

恢复线程

线程以其持久化状态自动恢复。从侧边栏选择任何过往线程即可从停止处继续——Agent 会记住所有消息和产出物。

工作区使用运维与排障
Last updated on
简介