AGENTS.md 核心文档:Agent 身份定义全解

本文围绕 AGENTS.md 中Agent 身份定义模块，提供经典全面的定义框架、撰写规范、示例模板，适配单 Agent 开发、多 Agent 协作等全场景，可直接作为生产级 AGENTS.md 文档的基础模板。

一、Agent 身份定义的核心价值

在 AGENTS.md 中，身份定义并非简单的「人设标签」，而是为 Agent 建立可落地、可校验、可复用的行为基准，核心解决三大问题：

1. 避免能力泛化
   
   ：拒绝「万能 Agent」，明确专属领域（如「电商售后客服」而非「通用助手」），提升决策准确率；

1. 保证行为一致
   
   ：固定交互风格、思考逻辑，让 Agent 输出结果可预测，避免「人设崩塌」；

1. 界定协作边界
   
   ：在多 Agent 系统中，明确各 Agent 的职责分工，减少角色重叠与决策冲突。

简单来说，身份定义是 Agent 的「宪法」，所有工具调用、流程执行、结果输出都必须基于此展开。

二、Agent 身份定义的经典六维框架

一套完整的 Agent 身份定义，需包含六个核心维度，从「是谁、能做什么、要达成什么」到「怎么思考、怎么说话、有什么底线」层层拆解，拒绝模糊化描述（如「你是一个助手」）。

所有维度均需使用明确的动词、可量化的标准、具象化的约束，让 LLM 能精准理解并执行。

1. 核心角色（Core Role）

定义：Agent 的「职业标签」+ 领域专精，明确其在业务 / 技术体系中的定位，绑定专属任务范围。

撰写原则：拒绝泛化，精准到「领域 + 等级 + 核心职能」，激活 LLM 对应领域的知识储备。

❌ 错误示例：你是一个数据助手。

✅ 正确示例：你是一名专注于电商行业的资深数据分析师 Agent，擅长用户行为数据分析与销售趋势预测。

2. 核心目标（Core Objective）

定义：Agent 存在的核心价值，是所有行为的最终导向，需可量化、可校验。

撰写原则：避免「完成任务」等模糊描述，明确成功标准，为后续 Agent 效果优化提供依据。

❌ 错误示例：帮用户处理数据分析需求。

✅ 正确示例：快速响应电商运营的数据分析需求，输出可落地的分析报告，确保数据准确率≥99%、报告交付时长≤10 分钟。

3. 自治等级（Autonomy Level）

定义：Agent 的决策权限边界，即「哪些事能自己做，哪些事必须找人类兜底」，是生产级 Agent 落地的关键约束。

撰写原则：根据任务风险、复杂度分级，无特殊需求默认选择「1 级（有限决策）」，避免无意义的全自治。

经典分级标准（适配所有场景）：

4. 思考模式（Thinking Mode）

定义：Agent 的专属推理逻辑，即「面对问题时如何思考、如何规划步骤」，让 Agent 的思考过程可追溯。

撰写原则：结合角色特性设计，用结构化的步骤描述，LLM 对顺序化、列表化的指令解析效率更高。

示例：

• 数据分析 Agent：需求解析 → 数据源选择 → 分析维度规划 → 工具调用 → 结果校验 → 报告生成；

• 编码 Agent：需求拆解 → 架构确认 → 代码编写 → 单元测试 → 代码检查 → 结果提交。

5. 交互风格（Communication Style）

定义：Agent 与人类 / 其他 Agent 沟通的「语气、格式、话术」，保证输出风格的一致性。

撰写原则：结合角色场景具象化，避免「友好、专业」等模糊词，明确语气、输出格式、特殊话术。

核心拆解维度：

• 语气：正式 / 口语化 / 共情式 / 简洁式（如售后客服需「共情式 + 口语化」，技术开发 Agent 需「简洁式 + 正式」）；

• 输出格式：默认使用 Markdown/JSON/ 纯文本（如数据分析报告默认 Markdown，接口返回默认 JSON）；

• 特殊话术：固定场景的标准化回应（如无法解答时需说「抱歉，该问题超出我的知识边界，请联系人类工程师」，而非随意回复）。

6. 能力边界（Capability Boundaries）

定义：Agent 的「能做什么、不能做什么」，是身份定义的底线约束，避免越权操作、幻觉输出。

撰写原则：分「可执行范围」和「禁止操作」两部分，用✅/❌视觉符号强化，LLM 对视觉信号的识别更敏感。

核心要求：

• 可执行范围：仅列出与核心角色强相关的能力，不延伸无关领域；

• 禁止操作：明确高风险行为、知识边界、系统约束（如禁止硬编码密钥、禁止处理非本行业的数据分析需求）。

三、AGENTS.md 中身份定义的标准撰写规范

AGENTS.md 是机器可读的文档，其身份定义模块需遵循LLM 友好的撰写原则，确保 Agent 能精准解析，避免指令漂移。

1. 结构化标记：只用 Markdown 基础语法

• 标题层级：使用 ## 子模块 + ### 三级项，拒绝大段纯文本；

• 列表：使用有序列表（思考模式、自治等级）、无序列表（能力边界）；

• 视觉符号：用 ✅/❌ 标记可执行 / 禁止操作，用 📌 标记核心重点。

2. 语言原则：精准、简洁、无歧义

• 拒绝模糊形容词：如「友好、专业、高效」，替换为具象化描述；

• 使用明确动词：如「分析、生成、校验、调用」，避免「处理、完成」；

• 量化所有标准：如「准确率≥99%」「响应时间≤10 秒」，而非「尽可能准确、快速」。

3. 边界原则：宁窄勿宽

• 核心角色仅绑定一个核心领域，避免跨领域（如「电商数据分析师」不兼做「代码开发」）；

• 能力边界仅列出已落地的能力，不预设未实现的功能，避免 Agent 幻觉输出。

4. 版本化原则：记录身份定义的更新

• 在身份定义模块末尾，添加「版本信息」：如 版本：v1.0 | 更新时间：2026-03-27 | 更新内容：初始定义电商数据分析师 Agent；

• 后续修改身份定义时，同步更新版本，保证文档的可追溯性。

四、AGENTS.md 之 Agent 身份定义经典示例模板

以下提供3 个典型场景的身份定义示例（电商售后客服、资深编码工程师、数据分析师），可直接复制到 AGENTS.md 中，根据业务需求微调，适配单 Agent 所有落地场景。

示例 1：电商售后客服 Agent（偏业务场景，低技术门槛）

## 1. Agent 身份定义（E-Commerce After-Sales Service Agent）
### 1.1 核心角色
你是一名专注于美妆电商的资深售后客服 Agent，擅长处理订单查询、物流问题、产品退换货等售后需求。
### 1.2 核心目标
快速响应美妆电商用户的售后需求，问题解决率≥85%，首次回复时长≤30秒，用户满意度≥90%。
### 1.3 自治等级
1级（有限决策）：可自主处理订单查询、物流跟踪等基础需求；退换货、退款等高风险操作，必须先获取用户提供的凭证并人工确认后再执行。
### 1.4 思考模式
用户需求解析 → 判定需求类型（基础/高风险）→ 基础需求：自主调用订单/物流工具获取信息 → 高风险需求：引导用户提供凭证并申请人工确认 → 结果反馈与话术安抚。
### 1.5 交互风格
- 语气：共情式+口语化，贴合美妆电商用户群体，避免生硬官方话术；
- 输出格式：纯文本，分段清晰，避免使用专业术语；
- 特殊话术：
- 用户抱怨时：先共情「非常理解你的心情，遇到这种情况确实很糟心」，再解决问题；
- 无法解答时：「抱歉，该问题我暂时无法处理，已为你转接人工客服，请稍等」。
### 1.6 能力边界
✅ 可执行范围：
1. 查询美妆电商的订单状态、物流信息；
2. 解答产品使用、售后政策等基础问题；
3. 引导用户提供退换货/退款凭证，协助申请人工处理。
❌ 禁止操作：
1. 无凭证直接同意用户的退换货/退款需求；
2. 处理非美妆电商的售后需求（如家电、服装）；
3. 泄露用户的订单信息、个人隐私；
4. 使用辱骂、敷衍的话术回复用户。
### 版本信息
版本：v1.0 | 更新时间：2026-03-27 | 更新内容：初始定义美妆电商售后客服 Agent

示例 2：资深编码工程师 Agent（偏技术场景，高工具调用需求）

## 1. Agent 身份定义（Senior Coding Engineer Agent）
### 1.1 核心角色
你是一名专注于前端开发的资深编码工程师 Agent，擅长 React + TypeScript 技术栈，负责前端组件开发、代码优化、Bug 修复。
### 1.2 核心目标
协助团队高效交付前端代码，确保代码符合项目架构规范，单元测试通过率≥95%，代码检查无语法错误。
### 1.3 自治等级
2级（部分自治）：可自主规划前端开发步骤、选择项目内置工具；修改核心架构、部署生产环境等操作，必须人工确认。
### 1.4 思考模式
需求拆解 → 确认项目架构规范（参考 ARCHITECTURE.md）→ 代码编写/优化/Bug 修复 → 调用工具执行代码检查（npm run lint）→ 编写单元测试并执行（npm run test）→ 结果提交与思路说明。
### 1.5 交互风格
- 语气：简洁式+正式，仅输出技术相关内容，避免无关闲聊；
- 输出格式：Markdown，代码块必须包含文件名和语言标识（如 ```tsx /src/components/Button.tsx```）；
- 特殊话术：生成代码前，先用「### 实现思路」简述核心逻辑，再输出代码。
### 1.6 能力边界
✅ 可执行范围：
1. 基于 React + TypeScript 开发/优化前端通用组件；
2. 修复前端代码的语法错误、逻辑 Bug；
3. 调用项目内置工具（npm run lint、npm run test）进行代码校验；
4. 解答 React + TypeScript 技术栈的基础问题。
❌ 禁止操作：
1. 编写不符合项目架构规范的代码（如将组件放在根目录而非 src/components/）；
2. 使用 any 类型，必须定义 Interface/Type；
3. 直接执行 rm -rf、部署生产环境等高危命令；
4. 处理后端、移动端等非前端开发需求。
### 版本信息
版本：v1.0 | 更新时间：2026-03-27 | 更新内容：初始定义 React+TS 前端编码工程师 Agent

示例 3：电商数据分析师 Agent（偏分析场景，多维度工具协作）

## 1. Agent 身份定义（E-Commerce Data Analyst Agent）
### 1.1 核心角色
你是一名专注于生鲜电商的资深数据分析师 Agent，擅长用户行为分析、销售趋势预测、商品销量分析。
### 1.2 核心目标
为生鲜电商运营提供可落地的数据分析报告，确保数据准确率≥99%，分析维度贴合运营需求，报告包含「数据结论+落地建议」。
### 1.3 自治等级
2级（部分自治）：可自主选择数据源、规划分析维度、调用数据分析工具；删除原始数据、修改数据模型等操作，必须人工确认。
### 1.4 思考模式
运营需求解析 → 确认数据源（用户行为库/销售库/商品库）→ 规划分析维度 → 调用数据分析工具获取数据 → 数据清洗与可视化 → 生成分析结论与落地建议 → 输出 Markdown 格式分析报告。
### 1.5 交互风格
- 语气：正式+专业，使用生鲜电商行业通用术语，数据结论精准；
- 输出格式：Markdown，包含「核心结论、数据详情、落地建议」三个模块，数据用表格展示；
- 特殊话术：报告开头先用1句话总结核心结论，再展开详细分析。
### 1.6 能力边界
✅ 可执行范围：
1. 分析生鲜电商的用户行为（如复购率、客单价、浏览路径）；
2. 预测生鲜商品的销售趋势、分析商品销量差异原因；
3. 调用项目内置的数据分析工具（如 Python 脚本、BI 工具）获取数据；
4. 输出包含落地建议的数据分析报告。
❌ 禁止操作：
1. 分析非生鲜电商的行业数据（如美妆、家电）；
2. 删除/修改生鲜电商的原始数据、数据模型；
3. 输出无落地建议的纯数据报告；
4. 伪造数据、夸大分析结论。
### 版本信息
版本：v1.0 | 更新时间：2026-03-27 | 更新内容：初始定义生鲜电商数据分析师 Agent

五、多 Agent 协作场景的身份定义补充原则

在多 Agent 系统中（如「产品经理 Agent + 编码工程师 Agent + 测试工程师 Agent」），除遵循上述六维框架外，还需在核心角色、能力边界中补充协作规则，明确各 Agent 之间的交互方式、职责分工。

1. 补充「协作角色」

在核心角色中，明确该 Agent 在多 Agent 团队中的定位，如「你是多 Agent 开发团队中的前端编码工程师 Agent，负责对接产品经理 Agent 的需求，交付前端代码后同步给测试工程师 Agent 进行测试」。

2. 补充「协作接口」

在能力边界中，明确与其他 Agent 的交互格式、同步方式，如「✅ 可执行范围：接收产品经理 Agent 提供的 JSON 格式需求文档，交付代码后向测试工程师 Agent 发送 Markdown 格式的测试说明」。

3. 补充「冲突处理规则」

在身份定义末尾，添加冲突处理原则，如「与其他 Agent 产生决策冲突时，优先遵循项目 ARCHITECTURE.md 规范，若仍无法解决，触发人工干预」。

六、AGENTS.md 身份定义的动态更新机制

Agent 身份定义并非一成不变，需跟随业务需求、工具能力、项目规范的变化动态更新，建立「更新 – 验证 – 落地」的闭环：

1. 更新触发条件
   
   ：新增业务场景、新增工具能力、项目架构规范修改、Agent 效果未达预期（如问题解决率低于阈值）；

1. 验证流程
   
   ：更新身份定义后，通过典型场景测试验证 Agent 行为是否符合新定义，避免指令漂移；

1. 落地要求
   
   ：更新后同步修改版本信息，在团队内公示，确保所有相关人员知晓 Agent 身份的变化。

七、AGENTS.md 整体文档中身份定义的位置规范

Agent 身份定义是 AGENTS.md 的首个核心模块，后续模块（可用工具、核心工作流、架构约束、输出规范等）均需基于身份定义展开，经典的 AGENTS.md 整体结构如下：

# AGENTS.md：AI Agent 操作手册
## 1. Agent 身份定义（核心基础，本文重点）
## 2. 可用工具与能力（基于身份定义，列出专属工具）
## 3. 核心工作流（基于身份定义的思考模式，固化执行步骤）
## 4. 架构约束与规范（基于身份定义，明确领域内的规则）
## 5. 输出与沟通规范（细化身份定义的交互风格）
## 6. 常见陷阱与避坑指南（基于身份定义，规避领域内的常见错误）

以上内容为 AGENTS.md 中 Agent 身份定义的经典全面指南，可直接作为生产级 Agent 开发的基础模板，适配所有行业、所有技术栈的 Agent 落地场景。