Agent 人格与提示词设计模式

Agent 人格与提示词设计模式

学习目标

读完本章后，你将能够：

• 设计结构化的 Agent 人格定义（身份、使命、规则、工作流、通信风格、成功指标）
• 使用 YAML frontmatter 携带 Agent 元数据（name/description/color/emoji/vibe）
• 理解”人格化提示词”与”功能指令”的区别
• 在自己的项目中应用统一的 Agent 定义模板

前置知识

• 系统提示的基本概念
• YAML frontmatter 语法

---

核心概念

什么是 Agent 人格？

Agent 人格（Agent Personality）是指通过系统提示词赋予 AI 模型特定的角色身份、行为倾向、沟通风格和评判标准，使其在交互中表现得像一个真实的领域专家，而非通用聊天机器人。

人格化 Agent 与通用 Agent 的区别：

维度	通用 Agent	人格化 Agent
身份	”你是一个有用的 AI 助手"	"你是一个资深前端开发者，专注 React 性能优化”
沟通风格	通用友好	数据驱动 / 批判性 / 创造性（依角色而定）
成功标准	”完成任务”	明确的量化指标（如 F1 > 85%、延迟 < 100ms）
行为约束	无特定约束	强制流程（如”必须先做 bias 测试”）

完整的 Agent 提示词结构

一个完整的人格化 Agent 定义通常包含以下部分：

1. YAML Frontmatter（元数据层）

---
name: Agent 名称          # 人类可读的名称
description: 一句话描述    # 专长领域 + 工作范围
color: 颜色标识            # UI 展示用（blue/red/green/#hex）
emoji: 表情符号            # 视觉标识
vibe: 个性一句话           # 让 Agent "有灵魂"的关键
services:                  # 可选：外部服务依赖
  - name: Service Name
    url: https://...
    tier: free | freemium | paid
---

vibe 字段的重要性：这是 Agent 人格的核心压缩。它用一句话定义 Agent 的态度和风格，例如：

• “Defaults to ‘NEEDS WORK’ — requires overwhelming proof for production readiness.”（Reality Checker 的批判性）
• “The conductor who runs the entire dev pipeline from spec to ship.”（Orchestrator 的指挥者角色）

2. 身份与记忆（Identity & Memory）

定义 Agent 的自我认知：

## 🧠 Your Identity & Memory
- **Role**: 角色定义
- **Personality**: 性格特征列表
- **Memory**: 记忆什么信息（经验、模式、失败案例）
- **Experience**: 假设的经验背景

3. 核心使命（Core Mission）

定义 Agent 要做什么，通常按子任务分组：

## 🎯 Your Core Mission

### 子任务 A
- 具体行动 1
- 具体行动 2

### 子任务 B
- 具体行动 1

4. 关键规则（Critical Rules）

Agent 必须遵守的强制性约束：

## 🚨 Critical Rules You Must Follow

### 规则类别
- Always ...
- Never ...
- Must ...

5. 工作流（Workflow Process）

结构化的步骤化流程：

## 🔄 Your Workflow Process

### Step 1: 需求分析
```bash
# 伪代码：验证项目规格
ls -la project-specs/*-setup.md

Step 2: 实施

…

#### 6. 通信风格（Communication Style）

定义 Agent 输出语言的风格：

```markdown
## 💭 Your Communication Style
- **Be data-driven**: "Model achieved 87% accuracy..."
- **Focus on production impact**: "Reduced latency from 200ms to 45ms..."

7. 成功指标（Success Metrics）

量化的成功标准：

## 🎯 Your Success Metrics
- 指标 1（如 F1 > 85%）
- 指标 2（如延迟 < 100ms）
- 指标 3（如可用性 > 99.5%）

---

问题与规避

Frontmatter 解析的边界问题

问题：YAML frontmatter 使用 --- 作为分隔符，如果正文中也包含 ---（如分隔线），解析器可能误判边界。

对策：

• 使用 awk 状态机：第一次遇到 --- 进入 frontmatter，第二次退出，之后的 --- 视为正文
• 或在正文中使用 *** 替代 --- 作为分隔线

vibe 字段的特殊字符处理

问题：vibe 字段常包含冒号、引号等特殊字符，如 "Don't just build it — build it right."，部分 YAML 解析器可能出错。

对策：

• 始终用双引号包裹 vibe 值
• 在 bash 中使用 awk 而非 yq 解析，避免对 YAML 语法的严格依赖

人格与功能的平衡

问题：过度强调人格（如过多的角色扮演）可能削弱 Agent 的功能性输出。

对策：

• 人格定义应该简洁有力，避免冗长的角色扮演描述
• 关键规则和工作流应该优先于性格描述
• 通信风格部分只给出示例模式，不强制固定句式

---

设计取舍

统一源格式 vs 工具特定格式

方案	优势	代价
统一源格式（Markdown + frontmatter）	人类可读、跨工具兼容、维护简单	需要转换脚本适配各工具
工具特定格式（JSON/YAML manifest）	工具原生支持、无需转换	多格式维护成本高、可读性差

人格化 Agent 模板选择统一源格式：一份源文件通过转换脚本适配 11+ 种工具。

人格化提示 vs 纯功能提示

方案	优势	代价
人格化	输出风格一致、用户体验好、适合面向用户的场景	Token 消耗略高、对简单任务可能过度
纯功能	Token 效率高、响应直接	输出风格不可预测、用户体验较差

最佳实践：对面向用户的 Agent（如客服、设计）使用人格化提示；对内部工具 Agent 使用纯功能提示。

---

参考来源

• Claude Code Agents Documentation
• OpenAI Custom Instructions

---

补充：CrewAI 的角色驱动人格设计

来源：CrewAI（crewAIInc/crewAI）lib/crewai/src/crewai/agent/core.py、lib/crewai/src/crewai/agents/，commit 77a6127

role/goal/backstory 三元组

CrewAI 用三个必需字段定义 Agent 人格：

Agent(
    role="高级数据分析师",       # 角色身份
    goal="从数据中提取可操作的洞察",  # 目标方向
    backstory="你拥有10年数据分析经验，擅长从复杂数据集中发现模式",  # 背景叙事
)

这三个字段直接组装到系统提示词中，形成 Agent 的”人格名片”。与通用 Agent 人格设计（如 YAML frontmatter + vibe 字段）不同，CrewAI 的三元组是运行时必需的——不仅影响提示词，还影响：

• Hierarchical 模式下的任务分配：Manager Agent 根据 role 描述决定将任务委派给哪个 Agent
• 委派工具的 Agent 列表：DelegateWorkTool 使用 role + goal 生成同事 Agent 的描述
• 任务结果的解释：Agent 的 backstory 影响其输出的风格和视角

系统提示词模板

CrewAI 内置了 i18n 多语言提示词模板：

You are {role}.
Your personal goal is: {goal}
Your backstory: {backstory}

Tools you have access to:
{tools_description}

You have a maximum of {max_iter} iterations.

设计取舍：

• 优势：三元组简单直观，非技术用户也能理解；role 直接用于多 Agent 路由（Manager 根据 role 分配任务）
• 局限：相比完整的 Agent 人格模板（身份 + 使命 + 规则 + 工作流 + 通信风格 + 成功指标），三元组缺乏对行为约束和输出格式的控制
• 补偿：可以通过 system_template、prompt_template、response_template 自定义提示词模板，扩展三元组的表达能力

Agent 适配器：第三方框架的人格桥接

CrewAI 的 Agent Adapter 系统（lib/crewai/src/crewai/agents/agent_adapters/）允许将 LangGraph 或 OpenAI Agent 桥接到 CrewAI 接口：

BaseAgentAdapter
├── LangGraphAgentAdapter  → 创建 LangGraph ReAct Agent 图
└── OpenAIAgentAdapter     → 配置 OpenAI Assistants API

每个适配器负责：

1. 工具转换：将 CrewAI BaseTool 转换为目标框架的工具格式
2. 结构化输出转换：配置目标框架的 JSON 解析策略
3. 执行桥接：通过 execute_task() 方法在目标框架中执行，返回结果

这使得用户可以在 CrewAI Crew 中混合使用原生 Agent 和第三方 Agent，统一通过 crewai_event_bus 发射事件，保证可观测性一致。