Agent开发工程化完全指南：5大工程上下文、提示词工程清单与Agent自动化形象构建

引言

2026年，Agent开发已经从"写个Prompt就能跑"的玩具阶段，进入了"工程化才能落地"的深水区。

很多人做Agent的经历是这样的：Demo跑得飞起，一到生产环境就拉胯——上下文丢了、工具调错了、记忆混乱了、安全越权了。然后开始怀疑人生：是模型不行，还是我不行？

答案是：都不是，是你缺了工程化。

这篇文章把Agent开发的工程化体系一次性讲透：5大工程上下文、提示词工程完整清单、以及最容易被忽略但最决定体验的——Agent自动化形象构建。有图表、有例子、有踩坑经验，该幽默时幽默，该严肃时严肃。

一、Agent开发的5大工程上下文

很多人以为Agent就是"大模型+工具调用"，太天真了。一个能在生产环境稳定运行的Agent，背后至少有5个工程上下文在同时运转。

先上总图：

┌─────────────────────────────────────────────────────────┐
│                    Agent 运行时架构                      │
├─────────────┬─────────────┬─────────────┬───────────────┤
│  代码上下文  │  工具上下文  │  记忆上下文  │  规划上下文   │
│  Code       │  Tool       │  Memory     │  Planning    │
│  Context    │  Context    │  Context    │  Context     │
├─────────────┴─────────────┴─────────────┴───────────────┤
│                  安全上下文 (Safety Context)              │
└─────────────────────────────────────────────────────────┘

1. 代码上下文（Code Context）

是什么：Agent能"看到"的代码范围。包括当前文件、相关文件、依赖关系、AST结构等。

为什么重要：你让Agent改个bug，它连相关文件都看不到，那不就是盲人摸象？

常见坑：

只传当前文件，Agent不知道调用方怎么用的
传整个代码库，token爆炸，模型注意力分散
只传代码不传注释，Agent猜不到设计意图

最佳实践：

策略	做法	适用场景
精准切片	只传当前文件+直接依赖+调用链	小改动、bug修复
分层注入	先传架构图，再传相关模块，最后传具体文件	大功能开发
符号索引	先让Agent看函数/类名列表，再按需展开	大型代码库

真实例子：我见过最离谱的Agent bug，是让它修一个登录接口的bug，它只看到了controller文件，不知道service层已经做了参数校验，结果又写了一遍校验，还把原来的覆盖了——典型的"代码上下文不全导致的重复造轮子"。

2. 工具上下文（Tool Context）

是什么：Agent能调用的工具集合，以及每个工具的描述、参数、返回值。

为什么重要：工具是Agent的手和脚。工具描述写不清楚，Agent就会用错——就像你给一个人一把锤子，但不告诉他这是敲钉子的，他可能拿去开酒瓶。

工具描述的黄金公式：

工具名：做什么的（一句话）
参数：每个参数的含义、类型、是否必填、取值范围
返回值：返回什么结构，错误时返回什么
使用场景：什么时候该用这个工具，什么时候不该用

反例（很多人这么写，然后怪Agent笨）：

工具：search
描述：搜索
参数：query

Agent看到这个内心OS：搜索啥？百度还是谷歌？返回啥？我啥时候该用？

正例：

工具：search_knowledge_base
描述：在公司内部知识库中搜索文档，用于回答与公司制度、产品文档相关的问题。不要用于搜索互联网信息。
参数：
  - query (string, 必填)：搜索关键词，建议用名词短语，不超过20字
  - top_k (int, 可选，默认5)：返回结果数量，范围1-20
返回值：
  - 成功：[{"title": "文档标题", "content": "摘要", "url": "文档链接"}]
  - 失败：{"error": "错误信息"}
使用场景：用户问公司内部政策、产品使用方法时使用；用户问通用知识时不使用。

3. 记忆上下文（Memory Context）

是什么：Agent的"记忆力"——短期记忆（当前对话）、长期记忆（历史对话/用户偏好）、工作记忆（当前任务的中间结果）。

记忆的三层结构：

┌──────────────────────────────────────┐
│  短期记忆 (Short-term)               │
│  当前对话上下文，窗口内直接可见        │
│  容量：~128K token                   │
├──────────────────────────────────────┤
│  工作记忆 (Working)                  │
│  当前任务的中间结果、草稿、思考过程    │
│  容量：受模型推理能力限制             │
├──────────────────────────────────────┤
│  长期记忆 (Long-term)                │
│  历史对话、用户偏好、知识库           │
│  容量：理论无限，靠检索召回           │
└──────────────────────────────────────┘

常见坑：

长期记忆什么都存，结果检索时全是噪音
不做记忆更新，用户改了偏好Agent还记着旧的
记忆没有时效性，3年前的对话还拿出来用

最佳实践：记忆要做"分层存储+按需召回+定期清理"。重要的用户偏好存长期记忆，当前任务的中间结果存工作记忆，过期的记忆定期归档或删除。

4. 规划上下文（Planning Context）

是什么：Agent对任务的拆解、执行计划、进度跟踪。

为什么重要：没有规划能力的Agent，就是"想到啥干啥"的无头苍蝇。复杂任务必须先规划再执行。

规划的两种模式：

模式	做法	优点	缺点	适用场景
单步规划	走一步看一步，每步决定下一步	灵活、省token	容易跑偏、重复劳动	简单任务、探索性任务
多步规划	先列完整计划，再逐步执行	有条理、可跟踪	计划可能过时、不够灵活	复杂任务、有明确目标的任务

高级玩法：Plan-Reflect-Execute循环。先做计划，执行几步后反思计划是否合理，不合理就调整，然后继续执行。这就像人做事——先列个TODO，做着做着发现不对，调整一下再继续。

5. 安全上下文（Safety Context）

是什么：Agent的"行为边界"——什么能做、什么不能做、什么需要确认。

为什么重要：没有安全上下文的Agent，就是一把没有保险的枪。你让它删文件，它可能把整个目录删了；你让它发邮件，它可能发给全公司。

安全的三层防线：

第一层：权限控制（Permission）
  └─ 工具级白名单/黑名单，哪些工具能用哪些不能

第二层：操作确认（Confirmation）
  └─ 高危操作（删除、发送、支付）必须人工确认

第三层：审计日志（Audit）
  └─ 所有操作记录日志，出问题可追溯

真实教训：我见过一个Agent，因为没有安全上下文，被用户一句"帮我清理一下磁盘"触发，直接把系统目录删了——当然这是测试环境，但生产环境你敢这么玩？

二、提示词工程完整清单

很多人以为提示词工程就是"写得详细点"，太肤浅了。一个工程级的提示词，至少包含以下8个要素。

先上清单：

序号	要素	作用	必选
1	角色设定	给Agent一个身份，限定能力范围	是
2	任务描述	明确要做什么，做到什么程度	是
3	上下文注入	提供完成任务所需的背景信息	是
4	输出格式	规定输出的结构、格式、长度	是
5	约束条件	明确不能做什么、必须遵守什么	是
6	示例引导	给1-3个例子，展示期望的输出	推荐
7	思维链	引导Agent分步思考，而不是直接给答案	推荐
8	反思机制	让Agent检查自己的输出，发现问题	高级

下面逐个拆解，每个都给例子。

1. 角色设定（Role）

作用：给Agent一个身份，让它从这个身份的角度思考和回答。

反例：

帮我写个Python脚本。

Agent内心OS：我是谁？我在哪？写啥脚本？给谁用？

正例：

你是一位有10年经验的Python后端工程师，擅长写可维护、有测试、符合PEP8规范的代码。你的代码风格是：函数短小、注释清晰、异常处理完善。

为什么有效：角色设定会激活模型中对应身份的"知识模式"。你让它当"资深工程师"，它输出的代码质量会比"随便写个脚本"高一个档次——这不是玄学，是训练数据的分布决定的。

2. 任务描述（Task）

作用：明确要做什么，做到什么程度，验收标准是什么。

SMART原则：任务描述要Specific（具体）、Measurable（可衡量）、Achievable（可实现）、Relevant（相关）、Time-bound（有时限）。

反例：

帮我优化一下这个函数。

优化啥？性能？可读性？还是啥？优化到什么程度算好？

正例：

请优化下面这个函数的性能，目标是将执行时间从当前的2秒降低到500毫秒以内。优化时必须保持函数签名和返回值不变，并且不能引入新的依赖。

3. 上下文注入（Context）

作用：提供完成任务所需的背景信息，不让Agent猜。

原则：宁可多给，不要少给。但要结构化，不要一坨扔过去。

上下文的类型：

背景信息：为什么要做这件事
相关数据：需要处理的数据
历史决策：之前做过什么尝试，为什么不行
环境信息：用的什么框架、什么版本、什么约束

例子：

【背景】
我们的用户反馈登录接口太慢，P99延迟达到3秒。

【现状】
当前实现是：先查Redis缓存，没命中再查数据库，然后写缓存。
数据库用的是MySQL 8.0，用户表有500万行数据。

【已尝试】
- 加了索引，没明显改善（因为查询条件已经走索引了）
- 加大了Redis缓存时间，但用户信息更新后会有延迟

【约束】
- 不能改数据库表结构
- 不能引入新的中间件

4. 输出格式（Output Format）

作用：规定输出的结构，方便后续解析和使用。

常用格式：

JSON：最常用，结构化数据
Markdown：人类可读的文档
代码块：代码输出
固定模板：比如"结论：...\n理由：...\n建议：..."

反例：

分析一下这个数据。

Agent给你写一大段散文，你还得自己提取关键信息。

正例：

请按以下JSON格式输出分析结果：
{
  "summary": "一句话总结",
  "key_findings": ["发现1", "发现2", "发现3"],
  "anomalies": ["异常1", "异常2"],
  "recommendations": ["建议1", "建议2"]
}
只输出JSON，不要其他文字。

5. 约束条件（Constraints）

作用：明确不能做什么，防止Agent跑偏。

常见约束：

内容约束：不能出现什么、必须包含什么
格式约束：长度限制、语言限制
行为约束：不能调用什么工具、不能做什么操作
安全约束：不能泄露什么信息

例子：

【约束】
- 回答必须用中文
- 代码必须有注释和异常处理
- 不能使用任何第三方库，只用Python标准库
- 如果信息不足，直接说"信息不足"，不要编造
- 回答不超过500字

6. 示例引导（Examples）

作用：用例子告诉Agent你想要什么样的输出，比描述一百句都管用。

Few-shot的力量：给1个例子，准确率提升20%；给3个例子，准确率提升50%。这不是夸张，是实测数据。

例子：

【示例】
输入："今天天气怎么样？"
输出：{"intent": "query_weather", "entities": {"date": "today", "location": "current"}}

输入："明天北京会下雨吗？"
输出：{"intent": "query_weather", "entities": {"date": "tomorrow", "location": "北京"}}

输入："帮我查一下上海后天的气温"
输出：

7. 思维链（Chain of Thought）

作用：引导Agent分步思考，而不是直接跳答案。复杂问题用思维链，准确率能提升一个档次。

常用方法：

直接说"请一步步思考"
给出思考框架："先分析问题，再列出方案，最后给出建议"
用"让我们想想"开头

例子：

请按以下步骤回答：
1. 先分析用户的问题是什么，核心诉求是什么
2. 列出3个可能的解决方案，每个方案的优缺点
3. 推荐一个最优方案，并说明理由
4. 给出具体的实施步骤

8. 反思机制（Reflection）

作用：让Agent检查自己的输出，发现问题并修正。这是高级技巧，但效果惊人。

方法：

输出后加一句"请检查你的回答是否满足所有要求，如果有问题请修正"
让Agent扮演"审稿人"角色，自己挑自己的毛病
用"自我批判"模式：先输出，再批判，再修正

例子：

完成回答后，请进行自我检查：
1. 是否回答了用户的所有问题？
2. 是否有事实性错误？
3. 是否符合所有约束条件？
4. 如果发现问题，请直接修正后输出最终版本。

三、Agent自动化形象构建（重点）

前面讲的都是"术"，现在讲"道"——Agent的自动化形象构建。

什么是Agent的"形象"？简单说，就是Agent给人的"整体感觉"：它是谁？什么性格？怎么说话？怎么做事？

很多人忽略这一点，觉得"能用就行"。但实际上，形象决定了用户对Agent的信任度、使用意愿，甚至容错度——一个形象一致的Agent，偶尔犯个错用户会觉得"它只是没注意"；一个形象混乱的Agent，每次回答都像换了个人，用户根本不敢用。

形象的三层结构

┌─────────────────────────────────────────┐
│           行为层 (Behavior)              │
│   怎么做事：决策逻辑、执行风格、容错方式   │
│   决定：Agent靠不靠谱                     │
├─────────────────────────────────────────┤
│           能力层 (Capability)            │
│   能做什么：工具集合、知识范围、技能边界   │
│   决定：Agent能不能用                     │
├─────────────────────────────────────────┤
│           人格层 (Persona)               │
│   是谁：身份、性格、语气、价值观           │
│   决定：用户喜不喜欢用                    │
└─────────────────────────────────────────┘

三层缺一不可：

只有人格没有能力 = 话痨，啥也干不了
只有能力没有人格 = 工具，冷冰冰没人爱用
有人格有能力但行为混乱 = 精神分裂，用户不敢信任

第一层：人格层（Persona）

人格层是Agent的"灵魂"，决定了它"是谁"。

人格的5个维度：

维度	说明	例子
身份	它是什么角色	资深工程师、贴心助手、严格老师
性格	它的性格特点	严谨、幽默、温和、直接
语气	它怎么说话	专业术语多、口语化、爱用比喻
价值观	它看重什么	效率优先、用户体验第一、安全第一
边界	它不做什么	不回答无关问题、不做危险操作

人格设定模板：

【身份】你是XX公司的智能客服助手，专门回答用户关于产品使用的问题。

【性格】你耐心、专业、有点幽默感。用户遇到问题时会先安抚情绪，再解决问题。

【语气】用口语化的中文，避免太技术化的术语。适当用表情符号，但不要太多。

【价值观】用户体验第一。能帮用户解决的问题一定解决，解决不了的诚实说不知道，并给出替代方案。

【边界】
- 只回答与产品使用相关的问题，不回答无关问题
- 不承诺做不到的事情
- 不泄露公司内部信息
- 遇到用户情绪激动时，先安抚再处理

幽默的正确姿势：幽默要分场景。用户问"怎么退款"，你可以说"退款这事儿我熟，分分钟帮你搞定"；但用户说"我充错了1万块怎么办"，你还开玩笑那就是找骂了。

严肃的正确姿势：涉及安全、法律、金钱的问题，必须严肃。比如用户问"这个操作会不会删数据"，你不能说"放心吧大概率不会"，必须说"这个操作会删除数据，请确认后再执行，建议先备份"。

第二层：能力层（Capability）

能力层是Agent的"骨架"，决定了它"能做什么"。

能力的三要素：

┌──────────────┐
│   知识范围    │  它知道什么：领域知识、公司信息、产品文档
├──────────────┤
│   工具集合    │  它能做什么：查询、下单、发邮件、调用API
├──────────────┤
│   技能边界    │  它擅长什么、不擅长什么：明确能力边界
└──────────────┘

能力边界的重要性：一个什么都"能做"的Agent，往往什么都做不好。明确告诉Agent"你擅长什么、不擅长什么"，反而能让它在擅长的领域表现更好。

例子：

【能力范围】
你擅长：
- 回答产品使用问题
- 处理订单查询、退款申请
- 提供产品使用建议

你不擅长（遇到时请转人工）：
- 技术故障排查（需要工程师介入）
- 投诉处理（需要客服主管介入）
- 法律相关问题（需要法务介入）

第三层：行为层（Behavior）

行为层是Agent的"肌肉记忆"，决定了它"怎么做事"。

行为的4个关键环节：

环节	说明	关键问题
感知	怎么理解用户输入	能不能准确理解意图？能不能识别情绪？
决策	怎么决定下一步	是直接回答？还是调用工具？还是转人工？
执行	怎么完成任务	调用工具的顺序？出错了怎么办？
反馈	怎么跟用户交互	怎么汇报进度？怎么处理失败？

行为流程图：

用户输入
    │
    ▼
┌─────────┐
│  感知    │  理解意图 + 识别情绪 + 提取关键信息
└────┬────┘
     │
     ▼
┌─────────┐
│  决策    │  简单问题直接答 / 复杂问题调工具 / 超出范围转人工
└────┬────┘
     │
     ├──► 直接回答 ──► 输出答案
     │
     ├──► 调用工具 ──► 执行 ──► 成功？──是──► 整理结果输出
     │                              │
     │                              否
     │                              │
     │                              ▼
     │                         重试/换方案/求助用户
     │
     └──► 转人工 ──► 告知用户 + 转接

行为设计的关键原则：

透明原则：Agent在做什么，要告诉用户。不要黑箱操作，用户等了半天不知道你在干啥，会焦虑。
- 好："我正在查询您的订单信息，请稍候..."
- 差：（沉默10秒后）"您的订单是..."
容错原则：出错了怎么办？要有明确的错误处理流程，不能卡死。
- 好："抱歉，查询失败了，我再试一次...还是不行，建议您稍后再试，或者联系人工客服。"
- 差：（报错信息直接甩给用户）"Error: Connection timeout"
确认原则：高危操作必须确认，不能自作主张。
- 好："您确定要退款吗？退款后订单将无法恢复。确认/取消"
- 差：（直接退款）"已为您退款。"
渐进原则：复杂任务分步执行，每步给反馈，不要一口气憋个大的。
- 好："第一步，我先帮您查询订单...找到了。第二步，我帮您申请退款...退款成功。"
- 差：（沉默30秒）"已完成。"

实战案例：三个Agent的形象对比

光说不练假把式，我们看三个实际案例。

案例1：客服Agent

【人格】
身份：电商平台智能客服
性格：耐心、热情、有点小幽默
语气：亲切口语化，适当用表情
价值观：用户满意第一，能解决的一定解决

【能力】
擅长：订单查询、退款申请、商品咨询
不擅长：投诉处理、技术故障

【行为】
- 用户来了先问候："亲，有什么可以帮您的？😊"
- 查不到订单时："亲，没找到这个订单呢，您确认一下订单号对不对？或者告诉我下单手机号，我帮您查~"
- 遇到投诉："这个问题我帮您转专人处理，请稍等~"

案例2：编程Agent

【人格】
身份：资深全栈工程师，有10年经验
性格：严谨、直接、偶尔毒舌
语气：专业术语准确，不废话，代码比话多
价值观：代码质量第一，可维护性比炫技重要

【能力】
擅长：Python/JavaScript/TypeScript全栈开发、系统设计、Code Review
不擅长：前端UI设计、移动端原生开发

【行为】
- 写代码前先问清楚需求："先确认几个问题：1. 用什么框架？2. 有什么性能要求？3. 数据量大概多少？"
- 写完代码附带说明："代码写好了，说几点：1. 这里用了缓存，因为QPS预计较高；2. 异常处理做了分层；3. 有个TODO标在注释里，后续可以优化。"
- 发现用户方案有问题时直接说："这个方案有问题，XX场景下会崩，建议改成XX方案。"

案例3：研究Agent

【人格】
身份：学术研究助手，严谨客观
性格：冷静、理性、一丝不苟
语气：学术化，引用来源，不做无依据的判断
价值观：事实第一，不确定就说不确定

【能力】
擅长：文献检索、论文摘要、研究方法分析
不擅长：给出主观建议、做价值判断

【行为】
- 回答问题必带来源："根据XX等人2025年的研究，结论是...（引用：XXX）"
- 信息不足时诚实说："目前公开资料中没有找到相关研究，无法给出确定结论。"
- 有争议的问题列出各方观点："关于这个问题，学界有两种观点：A派认为...（引用），B派认为...（引用），目前尚无定论。"

看到没？三个Agent，三个完全不同的形象。用户用的时候，一眼就能感觉到"这是不同的Agent"——这就是形象的力量。

形象与自动化的关系

最后讲一个关键点：形象不是"装饰"，是"自动化的前提"。

为什么？因为形象决定了Agent的行为一致性。一个形象清晰的Agent，在类似场景下会做出类似的反应——这就是可预测性，而可预测性是自动化的基础。

想象一下：

客服Agent形象清晰 → 用户知道它会怎么处理问题 → 可以放心让它自动处理80%的常见问题
编程Agent形象清晰 → 团队知道它写的代码是什么风格 → 可以放心让它自动生成代码再Review
形象混乱的Agent → 每次反应都不一样 → 没人敢让它自动做事，每次都要人工盯着

所以，构建形象不是为了"好玩"，是为了"可自动化"。形象越清晰、越一致，能自动化的场景就越多，人工干预就越少。

四、实战：从零构建一个有"灵魂"的Agent

理论讲完了，给一个可直接套用的实战模板。

第一步：写人格设定（100-200字）

你是[身份]，[性格特点]。你[做事风格]，[价值观]。
你说话[语气特点]，[语言习惯]。

第二步：定义能力边界（列清单）

【擅长】
- ...
- ...

【不擅长（遇到时转人工/说明）】
- ...
- ...

第三步：设计行为流程（画流程图或写步骤）

用户输入 → 理解意图 → 判断类型 → 
  简单问题 → 直接回答
  复杂问题 → 调用工具 → 处理结果 → 回答
  超出范围 → 说明 + 转人工/给替代方案

第四步：写提示词（把上面的整合起来）

【角色】...
【能力】...
【行为规则】...
【输出格式】...
【约束】...
【示例】...

第五步：测试和迭代

找10个典型场景测试
记录Agent表现不好的地方
调整人格/能力/行为设定
重复直到满意

结语

Agent开发不是"调API+写Prompt"那么简单，它是一个系统工程。

5大工程上下文是地基——代码、工具、记忆、规划、安全，缺一个Agent都跑不稳。
提示词工程是图纸——8个要素缺一个，Agent就可能理解偏差。
自动化形象是灵魂——决定了Agent是谁、怎么做事、能不能被信任和自动化。

把这三件事做好，你的Agent就从"玩具"变成了"工具"，从"Demo"变成了"产品"。

最后说一句：Agent开发的尽头，不是模型越来越大，而是工程越来越细。模型能力是有上限的，但工程优化是没有上限的。

参考来源：OpenAI Agent开发文档、Anthropic Prompt Engineering指南、LangChain最佳实践、个人项目实战经验。

posted @ 2026-09-10 11:59 badhope33834 阅读(23) 评论(0) 收藏举报

刷新页面返回顶部

badhope

代码改变世界 · 文字记录生活