| name | agent-definition-guide |
| description | 创建、修改、删除或排查 DeterminFlow Agent Definition 时必须加载此技能；也适用于选择 agent_type、最小工具权限、Prompt 模板绑定、模型覆盖、Skill/Rule 可见分组、子会话可用性与 Workflow Agent 节点配置。 |
| metadata | {"display_name":"agent-definition-guide","version":"1.0.1","author":"system","category":"general","priority":50,"workflow_only":false} |
Agent Definition 指南
先区分三个概念
- Agent Definition 定义一种可复用 Agent 类型，事实源是
config/agents_config.json。
- Prompt Template 定义该类型使用的系统提示词 sections，事实源是
config/prompts_config.json。
- Workflow Agent 节点只是引用
agent_type，不会复制 Agent Definition。
修改 Prompt 时加载 prompt-template-guide；修改 Workflow 节点时加载
workflow-guide。
修改前检查
- 用
list_agent_types 或 GET /api/agent-definitions/config 读取当前定义。
- 用
GET /api/tools 获取真实工具名，不根据文档或旧配置猜测。
- 用
GET /api/prompt-templates 确认 prompt_template 存在。
- 搜索 Workflow、Cron 与调用方对目标
agent_type 的引用，评估删除或改名影响。
- 先决定最小职责，再分配最小工具白名单；不要从
['*'] 开始缩减。
核心字段
| 字段 | 说明 |
|---|
description | 明确何时选择此类型，供主 Agent 和 UI 判断 |
prompt_template | prompts_config.json 中的模板 key |
tools | null 表示仅通信工具，['*'] 表示全部可用工具，数组表示白名单 |
disallowed_tools | 在白名单基础上继续剔除 |
model | 可选模型覆盖；空值继承父 Agent |
model_params | thinking、reasoning、temperature、top_p、stream timeout 等覆盖 |
max_turns | 最大工具轮次，不是质量目标 |
system_prompt_template | 追加到基础 Prompt 的类型级指令 |
include_skills / include_rules | 是否注入运行时 Skills / Rules |
visible_skill_group_ids / visible_rule_group_ids | 限制可见资源组 |
copy_main_workspace | null 继承全局设置，布尔值显式覆盖 |
available_for_sub_session | 是否允许用户或主 Agent 创建该类型的子会话 |
extension_options | Plugin 提供的扩展配置；必须符合对应 Plugin 契约 |
所有 Sub Agent 都会先应用全局禁用列表。目前 create_sub_session、
check_sub_progress 与 delete_session 不会因 tools=['*'] 而重新获得。
操作面
| 操作 | API |
|---|
| 读取配置 | GET /api/agent-definitions/config |
| 新建 | POST /api/agent-definitions |
| 更新 | PUT /api/agent-definitions/{agent_type} |
| 删除 | DELETE /api/agent-definitions/{agent_type} |
| 重载 | POST /api/agent-definitions/reload |
优先使用 Web 或 API。只有 API 未暴露目标字段且任务明确要求修改项目配置时，才编辑
config/agents_config.json，随后调用 reload。不要在运行时绕过配置管理器写内存对象。
新增 API 支持 agent_type、description、tools、disallowed_tools、model、
max_turns、system_prompt_template、copy_main_workspace、extension_options 与
model_params。更新 API 还支持可见 Skill/Rule 分组和 prompt_template。未暴露字段需要
项目配置变更和对应测试，不能假装 API 已支持。
权限设计
按照一个职责一个类型设计：
- 列出完成职责所必需的读工具。
- 仅在任务确实需要修改状态时加入写工具。
- 对命令执行、外部网络、资源管理等高影响工具单独论证。
- 用
disallowed_tools 表达临时或环境级额外禁用，不用它掩盖过宽白名单。
- Workflow 节点若需要
complete_node_task 或 reject_upstream，由节点开关控制，
不把它们错误地当作普通 Agent Definition 白名单。
Prompt 与模型绑定
prompt_template 必须存在；删除模板前先迁移全部 Agent Definition 引用。system_prompt_template 只放该 Agent 类型特有的短指令；通用结构放 Prompt Template。model 和 model_params 是覆盖层。没有明确原因时继承默认值，避免配置漂移。model 始终使用 provider_id:model_name；不要在 Agent Definition 中写
provider_type。Provider Adapter 会按该实例的类型领取 model_params 中支持的字段。max_turns 太低会截断任务，太高会放大循环成本；根据工具步骤设置并通过真实任务验证。
验收清单
- reload 成功，
list_agent_types 能看到预期定义。
prompt_template 与工具名全部存在。- 最小工具集能完成代表性任务，越权工具不可见。
available_for_sub_session=false 的内部类型不会出现在可创建类型中。- 新建子会话验证 Prompt、workspace、Skill/Rule 可见性和模型配置；已有会话不作为验证对象。
- 删除或改名后不存在 Workflow、Cron、Prompt 或测试中的悬空引用。
常见错误
tools=[] 与 tools=null 语义不同：空数组没有普通工具，null 保留通信工具语义。tools=['*'] 仍受全局禁用列表约束。- 只创建 Agent Definition、不创建同名 Prompt Template：使用显式已有模板即可；二者不要求同名。
- 修改配置后只看文件：必须 reload 并创建新会话验证。
- 删除内置或被引用类型：先迁移引用，再删除，最后做启动交叉校验。
