agent-definition-guide

# 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`。 ## 修改前检查 1. 用 `list_agent_types` 或 `GET /api/agent-definitions/config` 读取当前定义。 2. 用 `GET /api/tools` 获取真实工具名，不根据文档或旧配置猜测。 3. 用 `GET /api/prompt-templates` 确认 `prompt_template` 存在。 4. 搜索 Workflow、Cron 与调用方对目标 `agent_type` 的引用，评估删除或改名影响。 5. 先决定最小职责，再分配最小工具白名单；不要从 `['*']` 开始缩减。 ## 核心字段 | 字段 | 说明 | |---|---| | `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 已支持。 ## 权限设计 按照一个职责一个类型设计： 1. 列出完成职责所必需的读工具。 2. 仅在任务确实需要修改状态时加入写工具。 3. 对命令执行、外部网络、资源管理等高影响工具单独论证。 4. 用 `disallowed_tools` 表达临时或环境级额外禁用，不用它掩盖过宽白名单。 5. 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 并创建新会话验证。 - 删除内置或被引用类型：先迁移引用，再删除，最后做启动交叉校验。