Skip to Content
FacetX

Agent 与线程

🤖

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

自定义 Agent

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

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

创建自定义 Agent

通过界面

  1. 打开 FacetX 应用。
  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 '{
    "display_name": "数据分析师",
    "description": "专业的数据分析和可视化",
    "skills": ["data-analysis", "chart-visualization"]
  }'

Agent 名称和 Slug

创建 Agent 时，display_name 对用户显示，系统内部使用自动派生的 ASCII slug（name 字段）来标识 Agent。

  • display_name：对用户显示的任意字符串（例如 “数据分析师”）
  • name（slug）：用于 API 和文件路径的 ASCII 标识符（例如 data-analyst）

如果派生的 slug 与现有 Agent 冲突，/api/agents/check 端点会建议一个唯一的替代名称。

Agent 存储

自定义 Agent 配置存储在 backend/agents/{name}/config.yaml 中。你可以直接编辑这些文件——更改在下次 Agent 调用时自动加载。

线程生命周期

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

创建

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

执行

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

线程持久化配置

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

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

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

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

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

线程数据目录

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

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

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

恢复线程

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

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