alikon-art 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 并创建新会话验证。
- 删除内置或被引用类型：先迁移引用，再删除，最后做启动交叉校验。