第 3 章 · Agent 深入：角色设计方法论
本章目标：掌握 role / goal / backstory 三要素的提示词工程原理，学会用 max_iter、max_rpm、max_execution_time 等参数防止 agent 失控，并建立一套可复用的角色设计检查清单。
3.1 role / goal / backstory 到底去了哪里
很多教程只说"这三个字段定义角色"，但不解释机制。实际上 CrewAI 会把它们组装进 agent 的系统提示词：role 决定模型"是谁"，goal 决定"要达成什么"，backstory 提供背景与行为风格。模型后续所有决策（怎么拆解任务、用不用工具、输出什么风格）都受这三段文本约束。
import os
from crewai import Agent, LLM
deepseek = LLM(
model="openai/deepseek-chat",
base_url="https://api.deepseek.com/v1",
api_key=os.getenv("DEEPSEEK_API_KEY"),
)
analyst = Agent(
role="数据质量审计员",
goal="找出数据报表中的口径不一致和异常值，并按严重程度分级",
backstory=(
"你在金融行业做了 12 年数据治理，"
"对'同一个指标两种算法'零容忍。"
"你输出结论时永远附带证据行号。"
),
llm=deepseek,
)三要素的分工可以概括为：
- role：职位名。要具体到"能想象出这个人的日常动作"，避免"助手""专家"这类空泛词；
- goal：可判定的目标。最好包含"产出什么 + 质量标准"，而不是"尽力做好"；
- backstory：性格与约束的载体。行业经验、口头禅、红线规则都写在这里，是注入领域知识的最佳位置。
3.2 好角色与坏角色的对比
同一个"写周报"需求，两种写法：
# ❌ 反例：三要素全是正确的废话
bad_agent = Agent(
role="助手",
goal="写好周报",
backstory="你是一个乐于助人的 AI。",
llm=deepseek,
)
# ✅ 正例：具体、可判定、有风格约束
good_agent = Agent(
role="SaaS 团队周报撰写人",
goal=(
"把本周的原始工作记录整理成一页周报："
"进展（3-5 条）、风险（0-3 条）、下周计划（3 条），"
"每条以动词开头，不超过 40 字"
),
backstory=(
"你在咨询公司受过金字塔原理训练，"
"痛恨'推进了''持续优化'这类没有信息量的表述；"
"如果原始记录缺少数据支撑，你会明确标注[待补充]。"
),
llm=deepseek,
)差异的根源：goal 里的数字与结构给了模型可执行的模板，backstory 里的红线给了模型拒绝编造的许可。模型非常擅长遵守明确规则，前提是规则真的明确。
3.3 执行控制参数：防止 agent 跑飞
Agent 是自主循环的：思考 → 行动 → 观察循环往复。不设防的循环 = 烧钱 + 超时。官方提供四个关键闸门：
| 参数 | 默认值 | 作用 |
|---|---|---|
max_iter | 20 | 思考-行动循环的最大轮数，到顶后强制给出当前最优答案 |
max_execution_time | None | 单任务最长执行秒数，超时中止 |
max_rpm | None | 每分钟最大请求数，防止触发供应商限流 |
max_retry_limit | 2 | 出错时的最大重试次数 |
careful_agent = Agent(
role="合同风险审查员",
goal="逐条检查合同条款，输出风险清单",
backstory="十年法务经验，只依据文本证据下结论。",
llm=deepseek,
max_iter=15, # 审查任务 15 轮足够，防止无限纠结
max_execution_time=300, # 最长 5 分钟
max_rpm=10, # 三方模型限流保护
max_retry_limit=3, # 网络抖动多试一次
verbose=True,
)常见坑
max_iter 设太小（如 2）会让复杂任务"没想完就被打断"，输出明显变差。经验值：简单转换类任务 5–10，研究/审查类 15–25。如果经常撞到 20 上限，先怀疑任务描述不清导致 agent 迷茫，而不是无脑调大。
3.4 协作与调试相关参数
team_player = Agent(
role="初级分析师",
goal="完成分配的数据整理工作，遇到不确定的问题向同事求助",
backstory="入职一年的分析师，勤奋但经验有限。",
llm=deepseek,
allow_delegation=True, # 允许把子问题委派给 crew 里的其他 agent
verbose=True, # 打印完整思考/行动/观察日志
cache=True, # 相同工具调用走缓存，省钱省时（默认开启）
respect_context_window=True, # 上下文超限时自动摘要压缩（默认开启）
)allow_delegation：在 hierarchical 模式或多 agent crew 中，允许该 agent 发起委派。给"下级"角色开启、给"终审"角色关闭，可以形成清晰的汇报链；verbose=True：调试期必开。日志里的 Thought / Action / Observation 三段正是理解 agent 行为的窗口；respect_context_window=False时，超限会直接报错而不是自动摘要——适合"宁可失败不可失真"的场景。
3.5 角色设计检查清单
写完一个 Agent，过一遍这五问：
- role 是否具体到能想象出具体工作动作？（"内容审校编辑" ✔ "助手" ✘）
- goal 是否包含可判定的产出与格式标准？
- backstory 是否写入了领域知识或行为红线？
- max_iter / max_execution_time / max_rpm 是否按任务复杂度设置？
- 是否需要委派权？方向是否符合组织层级直觉？
3.6 本章小结
- role/goal/backstory 被组装进系统提示词，是角色扮演的全部依据；
- 好角色 = 具体 role + 可判定 goal + 带约束的 backstory；空泛词是输出平庸的头号原因；
max_iter/max_execution_time/max_rpm/max_retry_limit是防失控四闸门，默认值并非最优，要按任务调；allow_delegation控制委派权，verbose是调试第一工具，cache与respect_context_window保持默认即可。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. Agent 的 role/goal/backstory 最终作用于什么？
2. agent 反复纠结、迟迟不产出最终答案，最应该先调的参数是？
3. 关于 allow_delegation=True，正确的理解是？
4. respect_context_window=True（默认）的含义是？
🛠️ 动手实践
- 为"客服工单分类员"写出完整三要素（role/goal/backstory），要求 backstory 中包含两条明确的行为红线。
- 找出你上一章写的某个 agent，把空泛表述全部替换为带数字、带格式的可判定描述，重跑对比输出。
- 分别用 max_iter=3 和默认值 20 跑同一个研究型任务，观察输出完整度差异并记录结论。
角色立住了，接下来看任务怎么写才能榨出高质量输出。