# 模块 8：自定义 Agent：把稳定角色做成资产

<div class="mt-6 text-sm">

自定义 Agent 不是另起一套 Prompt。

它把一个稳定的职责、可用工具、默认指令和交付边界封装为可选择的角色，让每次任务不必从“你是谁、能做什么”重新说明。

</div>

<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">职责固定</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">工具受控</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">指令稳定</div>
<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">结果可验</div>
</div>

<!--
逐字稿：自定义 Agent 的本质是稳定角色配置，不是再写一份更长的说明。它把职责、默认指令、可用工具和交付边界固定下来，让任务启动时不必重复解释角色应该做什么。当前项目事实仍然必须在运行时提供，不能写死在角色里。

本机 Trae CN 3.3.70 已包含“自定义智能体”的创建、配置和工具选择界面。产品内置文案明确支持 Agent 名称、用途说明、参数提示、模型和可访问工具。

本模块不重复第三天“单 Agent / 多 Agent”的概念，而是把自定义 Agent 作为一份可维护的运行时资产来拆解。
-->

---

# 它和其他资产分别解决什么？

<div class="mt-5 text-xs">

| 资产 | 固化的内容 | 不承担的内容 |
|---|---|---|
| Rule | 必须遵守的长期约束 | 多步任务编排 |
| Prompt | 一类提问的输入输出结构 | 角色权限与默认工具 |
| Checklist | 固定遗漏点 | 源码分析与方案判断 |
| Skill | 多步工作流、资源与停止条件 | 对话入口的默认身份 |
| 自定义 Agent | 角色、指令、模型和工具边界 | 某个任务的项目事实 |

</div>

<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
自定义 Agent 负责“谁来做、能做什么”；Skill 负责“这类任务按什么流程完成”。
</div>

<!--
逐字稿：这张表的重点是职责不能混。Rule 保存长期约束，任务上下文契约保存一类任务的输入输出，Checklist 保存固定遗漏点，Skill 保存工作流，Agent 保存角色和工具边界。Agent 负责谁来做、能做什么，但不应把所有规则和项目事实复制进自己身上。

这个边界非常关键。Agent 不应该把 Rule、Prompt 和 Skill 的正文全部复制进去，否则会产生多份相互漂移的知识。

Agent 是入口和角色；Skill 是任务工作流；Rule 和检查单仍然是可独立更新的资产。
-->

---

# 一个自定义 Agent 的配置契约

<div class="mt-5 text-xs">

```md
---
name: 状态变更审查
description: 分析状态写入、资源副作用与验证边界。
argument-hint: "变更目标、相关源码、测试或 diff"
model: <当前环境允许的模型>
tools: <仅选择完成该职责所需的工具>
---

先提取事实；证据不足时列出缺口；
不修改代码；输出影响链路、方案比较、验证项和待确认事项。
```

</div>

<div class="mt-6 grid grid-cols-2 gap-3 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">标头：让 Trae 识别角色、入口与能力边界</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">正文：让 Agent 在任务中保持判断与交付边界</div>
</div>

<!--
逐字稿：一个可维护 Agent 至少要有两层契约。标头让系统识别角色、输入提示和工具范围，正文规定取证方式、输出格式和停止条件。这里的示例设置为只读分析，是为了先建立事实和边界，再决定是否进入实施，不让 Agent 一开始就拥有不必要的写权限。

这是字段示意，不承诺某个模型名或工具 ID。Trae 内置帮助文字说明：名称用于 UI 展示；description 说明职责与使用时机；argument-hint 描述期望输入；model 指定 Agent 运行模型；tools 决定可访问的工具集。

该示例特意设置为“只分析、不修改”，因为从真实案例中抽取资产时先要建立可验证事实，不能直接执行写入操作。
-->

---

# 固定配置与运行时输入必须分开

<div class="mt-5 text-xs">

| 固定在自定义 Agent 中 | 每次任务重新提供 |
|---|---|
| 角色名称与职责范围 | 本次变更目标 |
| 先取证、后判断的工作原则 | 相关目录、文件、diff、日志 |
| 可用工具与停止条件 | 当前状态、字段、接口与权限事实 |
| 结构化输出要求 | 实际执行过的测试或验证结果 |
| 引用哪些 Rule / Skill | 本次允许与禁止的改动范围 |

</div>

<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
把项目路径、字段名和历史结论写死在 Agent 中，会让它离开原项目后继续错误复用。
</div>

<!--
逐字稿：Agent 中只放稳定的角色配置，项目事实必须每次重新提供。角色职责、最小授权、输出结构和停止条件可以固定；本次目录、字段、diff、测试结果和允许修改范围必须随任务更新。否则 Agent 会把上一项目的路径和结论误用到新任务中。

可以把自定义 Agent 理解为“稳定角色配置”，而不是项目知识库。项目事实必须作为运行时上下文输入；这是避免 Agent 把旧项目结论套到新项目上的根本原则。
-->

---

# 什么时候不该创建自定义 Agent？

<div class="mt-5 text-xs">

| 需求 | 更合适的做法 | 原因 |
|---|---|---|
| 只要一句固定约束 | Rule | 不需要独立角色 |
| 只生成一段固定格式文本 | Prompt / Command | 无需工具与长期指令 |
| 只核对少数固定项 | Checklist | 无需自主检索判断 |
| 只有一次临时排查 | 普通对话与任务记录 | 长期复用价值不足 |
| 需要稳定职责、工具边界和结构化交付 | 自定义 Agent | 角色本身有重复价值 |

</div>

<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
“每个任务一个 Agent”会造成角色泛滥、说明重复和难以维护。
</div>

<!--
逐字稿：并不是所有任务都值得创建自定义 Agent。固定规则用 Rule，固定格式输出用任务上下文契约或 Command，少数检查项用 Checklist，一次性排查用普通任务记录。只有职责稳定、需要独立工具边界并且能够结构化交付时，创建 Agent 才有长期价值。

资产化的核心依然是识别重复。自定义 Agent 的适用条件是角色稳定且需要独立工具边界；不是因为一个提示词写得很长，就应该升级为 Agent。
-->