给 Agent 写任务描述，不是在写更长的 Prompt

第一次用 Agents SDK 把 Agent 跑起来的那个下午，我盯着终端输出发了很久的呆。

我写的 instructions 是这样的："你是一个专业的市场调研专家，请帮用户调研竞品信息，语气要专业。"——标准的 ChatGPT Prompt 风格，用了好几年，从没出过问题。

然后 Agent 开始运行。它调用了 web_search，搜了一下，然后……停下来问我："请问您希望我重点关注哪些维度？"我回答了。它又搜了一次，又停下来："请问竞品范围是国内还是国外？"我又回答。就这样来来回回，30 步之后，它礼貌地说："我已经收集了一些基础信息，请问您希望我继续深入调研吗？"

报告？没有。结论？没有。工具调用了 12 次，什么都没干成。

那一刻我意识到：我不是 Prompt 写得不好，是我在用错误的方式跟一个完全不同的系统说话。

---

第一章：先搞清楚你在和什么东西说话

ChatGPT 是一个"对话伙伴"。你给它一个 Prompt，它给你一个输出，交互就结束了。你的 Prompt 只需要控制一次输出的质量——角色、语气、格式，这些就够了。

Agents SDK 2.0 的 Agent 是完全不同的东西。它会自主规划、调用工具、循环执行，在你看不见的地方做一连串决策，直到它认为任务完成或者遇到终止条件。你的 instructions 要控制的，是它整个运行期间的决策逻辑。

用一个比喻来打通这个认知差异：

给 ChatGPT 写 Prompt，像是点菜——你告诉服务员"来一份宫保鸡丁，少辣"，任务就结束了。

给 Agent 写任务描述，像是培训一个新员工——你要告诉他工作目标是什么、遇到什么情况该怎么处理、什么时候算做完了、哪些事情不能做。

新员工出错，你不知道是哪一步跑偏的；Agent 跑偏，同样如此。区别在于，新员工会来问你，而 Agent 会自己做决定——用你没有预料到的方式。

这张表是理解后续所有内容的基础。记住它。

---

第二章：我试了 5 种写法，逐一复盘

为了搞清楚"任务描述"到底怎么写，我用同一个任务场景（调研3个竞品并生成对比报告）测试了 5 种不同的写法，记录了每种写法的执行步数和跑偏方式。

写法① 照搬 ChatGPT Prompt 风格

agent = Agent(
name="research_agent",
instructions="你是一个专业的市场调研专家，请帮用户调研竞品信息，语气要专业。"
)

跑出来的结果：Agent 执行了 28 步，其中 18 步是在向用户提问。 跑偏方式：反复询问用户，不主动推进。 根因分析：角色扮演式的 Prompt 会让 Agent 进入"服务模式"——它认为自己的工作是"响应用户需求"而不是"完成一个任务"。没有明确的目标和终止条件，它就会一直等待指令，而不是主动执行。

---

写法② 只写目标，不写边界

instructions="帮我调研竞品并出一份完整的分析报告。"

跑出来的结果：执行了超过 40 步才被我手动终止。 跑偏方式：工具调用失控，越跑越深。 根因分析："完整"是一个没有边界的词。Agent 会不断尝试让报告"更完整"——搜更多资料、访问更多页面、分析更多维度。没有停止条件，它就不知道什么时候算"完成了"。

这是最常见的坑，也是最危险的：你以为它在努力工作，其实它在无限循环。

---

写法③ 步骤写得太细（伪代码式）

instructions="""
第1步：用 web_search 搜索竞品名称
第2步：访问搜索结果的前3个链接
第3步：提取价格信息
第4步：提取功能信息
第5步：生成对比表格
"""

跑出来的结果：在"第2步"遇到需要登录的页面时直接卡死，后续步骤全部跳过。 跑偏方式：遇到分支情况无法处理，直接中断或跳步。 根因分析：线性步骤无法处理现实世界的分支情况。Agent 不是代码解释器，它需要的是决策逻辑，而不是执行脚本。你写的越像伪代码，它就越脆——任何一个意外情况都会让整个流程崩掉。

---

写法④ 加了约束但逻辑矛盾

instructions="""
帮我快速完成竞品调研，速度要快。
每一步操作前都需要确认是否继续。
"""

跑出来的结果：Agent 在"快速执行"和"每步确认"之间反复横跳，执行效率极低。 跑偏方式：两个互相矛盾的指令让 Agent 陷入决策混乱。 根因分析：Agent 会尝试同时满足所有约束，当约束互相冲突时，它的行为变得不可预测。你以为你在"加保险"，其实你在制造噪音。

---

写法⑤ 结构化任务描述（最终方案）

agent = Agent(
name="research_agent",
instructions="""
Goal
收集指定公司的公开竞品信息，生成结构化对比报告。
成功标准：报告包含至少3个竞品、覆盖价格/功能/用户评价三个维度。

Boundary
仅使用 web_search 和 browse_url 工具
单次任务最多执行 15 步，超出则输出已有结果并终止
不得访问需要登录的页面

Tool Policy
优先用 web_search 定位信息源，再用 browse_url 获取详情
同一 URL 不重复访问

Output Contract
以 Markdown 表格输出，最后附 200 字以内的总结判断
"""
)

跑出来的结果：平均 11 步完成任务，输出格式符合预期。 跑偏方式：几乎没有。偶尔在信息不足时会输出"部分结果+说明"，行为合理。

---

把 5 种写法的平均执行步数做个直观对比：

写法①（角色扮演式）    ████████████████████████████  28步（大量无效询问）
写法②（只有目标）      ████████████████████████████████████████  40+步（手动终止）
写法③（伪代码式）      ██████████  10步（但中途卡死，任务未完成）
写法④（矛盾约束）      ████████████████████████  24步（低效横跳）
写法⑤（结构化）        ███████████  11步（任务完成，输出正确）

数字不是重点，趋势才是：前四种写法要么跑太多步、要么跑偏、要么卡死，只有结构化写法在步数合理的情况下稳定完成了任务。

---

第三章：最佳写法拆解——四个模块缺一不可

写法⑤的核心是结构化任务描述，分为四个模块，每个模块解决一个具体问题。

Goal（目标）：说清楚"成功"长什么样

不要写："帮我做市场调研" 要写："生成包含至少3个竞品、覆盖价格/功能/用户评价三个维度的对比报告"

区别在于：前者描述的是过程，后者描述的是可验证的完成状态。Agent 需要知道什么情况下可以停下来，而不是一直跑。

Boundary（边界）：告诉它什么时候该停

边界是最容易被忽略的模块，也是最重要的。它包含两类信息：

终止条件：最多执行多少步、信息不足时怎么处理
禁止清单：哪些操作不允许做

没有边界的 Agent 就像没有刹车的车——它会一直往前跑，直到撞墙。

Tool Policy（工具策略）：告诉它工具怎么用

Agent 有多个工具可以调用时，它需要知道优先级和使用规则。否则它可能会用低效的方式完成任务，或者重复调用同一个工具。

这个模块的关键词是"优先"和"禁止"——给它清晰的选择逻辑，而不是让它自己猜。

Output Contract（输出约定）：定义最终交付物

这是最容易理解但最常被省略的模块。你需要告诉 Agent：

输出格式是什么（Markdown 表格？JSON？纯文本？）
验收标准是什么（字数限制？必须包含哪些字段？）

没有输出约定，Agent 会用它认为"合理"的格式输出——而这个格式可能和你的下游系统完全不兼容。

---

第四章：两个场景的完整对比示例

场景一：自动调研并汇总行业报告

ChatGPT Prompt 版：

你是一位专业的行业分析师，请帮我调研AI写作工具市场，
重点关注主要玩家、市场规模和发展趋势，语气要专业客观，
输出一份完整的行业报告。

Agent 任务描述版：

## Goal
调研AI写作工具市场，输出结构化行业报告。
成功标准：覆盖至少5个主要产品、包含市场定位/核心功能/目标用户三个维度、
有明确的趋势判断结论。

Boundary
仅使用公开可访问的信息源
最多执行 20 步，超出则基于已有信息生成报告
不访问需要付费或登录的内容

Tool Policy
先用 web_search 获取产品列表和市场概况
再用 browse_url 深入获取各产品详情
每个产品最多访问 2 个页面

Output Contract
输出格式：
1. 市场概览（200字以内）
2. 产品对比表格（产品名/定位/核心功能/目标用户/价格区间）
3. 趋势判断（300字以内，需给出明确结论而非罗列现象）

两个版本放在一起，差异一目了然：ChatGPT 版在描述"我想要什么感觉"，Agent 版在定义"什么叫做完成了"。

---

场景二：多步骤数据清洗任务

ChatGPT Prompt 版：

你是数据处理专家，请帮我清洗这份 CSV 数据，
去除重复项、处理空值、统一格式，要专业细致。

Agent 任务描述版：

instructions="""
Goal
清洗输入的 CSV 数据文件，输出可直接用于分析的干净数据集。
成功标准：无重复行、关键字段无空值、日期字段统一为 YYYY-MM-DD 格式。

Boundary
只处理明确指定的字段，不修改其他列
删除操作前必须记录被删除的行数
如果空值比例超过 30%，停止处理并报告异常，不强行填充

Tool Policy
优先使用 read_file 读取数据，用 python_executor 处理
处理完成后用 write_file 输出，不覆盖原始文件

Output Contract
输出两个文件：
1. cleaned_data.csv（清洗后的数据）
2. cleaning_report.txt（处理日志：原始行数、删除行数、修改字段统计）
"""

注意第二个场景里的这一条边界："如果空值比例超过 30%，停止处理并报告异常，不强行填充"——这是一个典型的异常处理约定。没有这条，Agent 可能会用 0 或均值填充大量空值，悄悄把你的数据质量搞坏，你还以为它做完了。

---

文中的代码示例都可以直接在 API 环境里跑。如果你还没有顺手的 API 接入点，推荐用 [api.884819.xyz](https://api.884819.xyz)——兼容 OpenAI 格式，Agents SDK 2.0 直接接，省去换接口的麻烦，专注调你的任务描述就行。新用户注册即送体验 token，国产模型（Deepseek/千问等）完全免费，没有月租，按量付费。

---

第五章：三个反直觉原则

总结完方法论，有三个原则值得单独说——因为它们都和直觉相反。

原则一：越模糊的目标，Agent 越会"自作聪明"

很多人以为给 Agent 留白是在给它"发挥空间"。实际上，模糊的目标只会让它在你没预料到的方向上自由发挥。

Agent 不会因为你说"做得完整一点"就知道你真正的优先级是什么。它只会用它认为合理的方式填满这个空白——而这个"合理"，往往不是你想要的。

越模糊，越失控。越清晰，越可控。

原则二：约束不是限制，是给 Agent 的安全网

写约束时，很多人会有一种心理障碍：觉得限制太多会让 Agent "发挥不出来"。

这个想法完全反了。约束是让 Agent 在正确的范围内高效执行的前提，而不是在阻止它做事。就像给新员工划定职责范围，不是在限制他的能力，而是在帮他知道"什么是我该做的"。

没有约束的 Agent，就像没有职责边界的员工——它会把时间花在你不需要的事情上，还以为自己很努力。

原则三：好的任务描述应该能让另一个人类读懂并执行

这是最实用的自检标准：把你写的任务描述给一个不了解背景的同事看，他能不能照着执行？

如果不能，说明你的描述里有歧义、有缺失、或者有矛盾。可读性即可控性——能被人类清晰理解的任务描述，才能被 Agent 准确执行。

这个标准还有一个好处：它迫使你用自然语言而不是技术术语来描述任务，而自然语言的表达往往比伪代码更能被 Agent 正确理解。

---

写在最后

回到开头的那个下午。现在我知道，那个"反复询问、什么都没干成"的 Agent 并没有出错——它只是在忠实地执行我给它的指令：一个没有目标、没有边界、没有终止条件的角色设定。

学会给 Agent 写任务描述，本质上是在学习如何清晰地表达一个可执行的目标。 这个能力和 AI 无关，它是一种基本的系统思维——把一个模糊的意图，拆解成可验证、可执行、有边界的任务规格。

这个能力在 AI 时代会越来越值钱。不是因为你要天天写 instructions，而是因为当你能精确描述一个任务的时候，你对这个任务本身的理解，就已经比大多数人深了一层。

---

说到任务描述，还有一个坑我没展开——当你有多个 Agent 协作的时候，任务描述之间怎么"对齐"，才不会让 Agent A 的输出变成 Agent B 的噩梦？ 这个问题比单 Agent 复杂得多：A 的 Output Contract 要和 B 的 Goal 精确匹配，否则信息在传递过程中会悄悄失真，而你很难发现问题出在哪一层。

下篇专门聊这个。

---

本文由8848AI原创，转载请注明出处。关注8848AI，带你从零开始学AI。

#AI教程 #AgentsSDK #Prompt技巧 #AI工具 #8848AI #人工智能 #AI开发 #大模型应用