# Agent Definition Guide

> 创建、修改、删除或排查 DeterminFlow Agent Definition 时必须加载此技能；也适用于选择 agent_type、最小工具权限、Prompt 模板绑定、模型覆盖、Skill/Rule 可见分组、子会话可用性与 Workflow Agent 节点配置。

- Skill: `alikon-art/agent-definition-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alikon-art/agent-definition-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alikon-art/agent-definition-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alikon-art (https://skillmd.com/u/alikon-art)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alikon-art/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 并创建新会话验证。
- 删除内置或被引用类型：先迁移引用，再删除，最后做启动交叉校验。