From 3b6622a41ec750e0886e31fe060f7a36cc98fd33 Mon Sep 17 00:00:00 2001 From: Battleplus <3559424769@qq.com> Date: Sun, 23 Aug 2026 21:01:09 +0800 Subject: [PATCH 1/3] fix(docs): update custom-agent docs to use required 'name' field The custom-agent docs described a 'display_name' field and an auto-derived slug, but POST /api/agents requires callers to provide 'name'. Updated all 4 affected pages (en/zh) to match the actual AgentCreateRequest contract. Closes #4942 --- .../src/content/en/application/agents-and-threads.mdx | 3 +-- frontend/src/content/en/harness/lead-agent.mdx | 2 +- .../src/content/zh/application/agents-and-threads.mdx | 9 ++------- frontend/src/content/zh/harness/lead-agent.mdx | 2 +- 4 files changed, 5 insertions(+), 11 deletions(-) diff --git a/frontend/src/content/en/application/agents-and-threads.mdx b/frontend/src/content/en/application/agents-and-threads.mdx index 3bf3a2bafb8..759bbd4c146 100644 --- a/frontend/src/content/en/application/agents-and-threads.mdx +++ b/frontend/src/content/en/application/agents-and-threads.mdx @@ -30,7 +30,7 @@ Custom agents are created and managed through: - **The App UI**: open the Agents section in the settings panel. - **The Gateway API**: `POST /api/agents` with the agent definition. -The slug (`name`) is automatically derived from the `display_name` and must be unique. The system checks for conflicts and appends a suffix if needed (`/api/agents/check`). +You provide a unique ASCII `name` matching `^[A-Za-z0-9-]+` (stored lowercase). Use `/api/agents/check` to verify availability before creation. Agent configuration is stored in `agents/{name}/config.yaml` relative to the backend directory. @@ -41,7 +41,6 @@ To restrict a custom agent to specific skills: ```yaml # agents/my-researcher/config.yaml name: my-researcher -display_name: My Researcher skills: - deep-research - academic-paper-review diff --git a/frontend/src/content/en/harness/lead-agent.mdx b/frontend/src/content/en/harness/lead-agent.mdx index 3da01bc4d95..7a72e4e1a91 100644 --- a/frontend/src/content/en/harness/lead-agent.mdx +++ b/frontend/src/content/en/harness/lead-agent.mdx @@ -132,7 +132,7 @@ Plan mode is appropriate for complex, multi-step tasks where showing incremental The same Lead Agent runtime powers both the default agent and any custom agents you create. A custom agent differs only in: -- its **name** (ASCII slug, auto-derived from `display_name`), +- its **name** (unique ASCII identifier, e.g. `data-analyst`), - its **system prompt** or agent-specific instructions, - which **skills** it has access to, - which **tool groups** it can use, and diff --git a/frontend/src/content/zh/application/agents-and-threads.mdx b/frontend/src/content/zh/application/agents-and-threads.mdx index df313465766..b8935027e48 100644 --- a/frontend/src/content/zh/application/agents-and-threads.mdx +++ b/frontend/src/content/zh/application/agents-and-threads.mdx @@ -39,7 +39,7 @@ DeerFlow 允许你创建多个具有不同专业领域的自定义 Agent。每 curl -X POST http://localhost:8001/api/agents \ -H "Content-Type: application/json" \ -d '{ - "display_name": "数据分析师", + "name": "data-analyst", "description": "专业的数据分析和可视化", "skills": ["data-analysis", "chart-visualization"] }' @@ -49,12 +49,7 @@ curl -X POST http://localhost:8001/api/agents \ ### Agent 名称和 Slug -创建 Agent 时，`display_name` 对用户显示，系统内部使用自动派生的 ASCII `slug`（`name` 字段）来标识 Agent。 - -- `display_name`：对用户显示的任意字符串（例如 "数据分析师"） -- `name`（slug）：用于 API 和文件路径的 ASCII 标识符（例如 `data-analyst`） - -如果派生的 slug 与现有 Agent 冲突，`/api/agents/check` 端点会建议一个唯一的替代名称。 +你需要提供一个唯一的 ASCII `name`，匹配 `^[A-Za-z0-9-]+`（存储时转为小写）。创建前可使用 `/api/agents/check` 验证名称是否可用。 ### Agent 存储 diff --git a/frontend/src/content/zh/harness/lead-agent.mdx b/frontend/src/content/zh/harness/lead-agent.mdx index 3a3c8ce284e..7a967c98a05 100644 --- a/frontend/src/content/zh/harness/lead-agent.mdx +++ b/frontend/src/content/zh/harness/lead-agent.mdx @@ -115,7 +115,7 @@ models: 相同的 Lead Agent 运行时同时为默认 Agent 和你创建的任何自定义 Agent 提供服务。自定义 Agent 的区别仅在于： -- 其**名称**（ASCII slug，从 `display_name` 自动派生） +- 其**名称**（唯一 ASCII 标识符，例如 `data-analyst`） - 其**系统提示**或 Agent 特定指令 - 它有权访问的**技能** - 它可以使用的**工具组** From fed6866842eeb7363bdeadf39cfe6926265dc0ee Mon Sep 17 00:00:00 2001 From: Battleplus <3559424769@qq.com> Date: Tue, 25 Aug 2026 10:08:38 +0800 Subject: [PATCH 2/3] docs: remove auto-slug claim --- frontend/src/content/en/application/agents-and-threads.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/content/en/application/agents-and-threads.mdx b/frontend/src/content/en/application/agents-and-threads.mdx index 759bbd4c146..7514232976b 100644 --- a/frontend/src/content/en/application/agents-and-threads.mdx +++ b/frontend/src/content/en/application/agents-and-threads.mdx @@ -19,7 +19,7 @@ The default agent is the Lead Agent with no custom configuration. It loads all g Custom agents are named variants of the Lead Agent. Each one can have: -- a **display name** and an auto-derived ASCII slug (the `name` used internally) +- a **name** (caller-provided unique slug identifier) and an optional **display name** for the UI - a specific **model** to use by default - a restricted set of **skills** (or all globally enabled skills if unspecified) - a restricted set of **tool groups** From 04abb16b551e70b050fe9ed87e6e34de65ada4a5 Mon Sep 17 00:00:00 2001 From: Battleplus <3559424769@qq.com> Date: Tue, 25 Aug 2026 12:42:10 +0800 Subject: [PATCH 3/3] docs: fix display_name -> description in agent creation docs --- frontend/src/content/en/application/agents-and-threads.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/content/en/application/agents-and-threads.mdx b/frontend/src/content/en/application/agents-and-threads.mdx index 7514232976b..09ac3e2f6ca 100644 --- a/frontend/src/content/en/application/agents-and-threads.mdx +++ b/frontend/src/content/en/application/agents-and-threads.mdx @@ -19,7 +19,7 @@ The default agent is the Lead Agent with no custom configuration. It loads all g Custom agents are named variants of the Lead Agent. Each one can have: -- a **name** (caller-provided unique slug identifier) and an optional **display name** for the UI +- a **name** (caller-provided unique ASCII slug, e.g. `data-analyst`) and an optional **description** - a specific **model** to use by default - a restricted set of **skills** (or all globally enabled skills if unspecified) - a restricted set of **tool groups**