Skip to content

fix(docs): update custom-agent docs to use required 'name' field #4969

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Battleplus wants to merge 3 commits into
base: main
Choose a base branch
from
+6 −12
Open

fix(docs): update custom-agent docs to use required 'name' field #4969

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b6622a
fix(docs): update custom-agent docs to use required 'name' field
Battleplus Aug 23, 2026
fed6866
docs: remove auto-slug claim
Battleplus Aug 25, 2026
04abb16
docs: fix display_name -> description in agent creation docs
Battleplus Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions frontend/src/content/en/application/agents-and-threads.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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**
Expand All @@ -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.
Comment thread
Battleplus marked this conversation as resolved.

@willem-bd willem-bd Aug 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Restore the regex end anchor in both translations

Both replacement paragraphs document ^[A-Za-z0-9-]+, omitting the actual trailing $. Without the end anchor, the documented expression accepts strings that merely begin with valid characters—for example, data_analyst matches the valid prefix—while _validate_agent_name rejects the complete value. Since this PR is correcting the API contract, please use ^[A-Za-z0-9-]+$ in both the English and Chinese pages.


Agent configuration is stored in `agents/{name}/config.yaml` relative to the backend directory.

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/content/en/harness/lead-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 2 additions & 7 deletions frontend/src/content/zh/application/agents-and-threads.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
}'
Expand All @@ -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` 验证名称是否可用。

@willem-bd willem-bd Aug 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Restore the regex end anchor in both translations

Both replacement paragraphs document ^[A-Za-z0-9-]+, omitting the actual trailing $. Without the end anchor, the documented expression accepts strings that merely begin with valid characters—for example, data_analyst matches the valid prefix—while _validate_agent_name rejects the complete value. Since this PR is correcting the API contract, please use ^[A-Za-z0-9-]+$ in both the English and Chinese pages.


### Agent 存储

Expand Down
2 changes: 1 addition & 1 deletion frontend/src/content/zh/harness/lead-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ models:

相同的 Lead Agent 运行时同时为默认 Agent 和你创建的任何自定义 Agent 提供服务。自定义 Agent 的区别仅在于：

- 其**名称**（ASCII slug，从 `display_name` 自动派生）
- 其**名称**（唯一 ASCII 标识符，例如 `data-analyst`）
- 其**系统提示**或 Agent 特定指令
- 它有权访问的**技能**
- 它可以使用的**工具组**
Expand Down
Loading