企业官网建设流程全解析

简介：Claude官方《构建高效的Agents指南》中文翻译版，是一份面向AI代理开发者、大模型应用工程师及需要自动化工作流的技术团队的完整PDF资料，核心解答“何时用代理、如何从简单模式入手”的实践问题。资源为单个PDF文档，共1个文件，压缩包约878KB，便于直接阅读与离线存档。已有445人学习浏览，适合处于Agent架构设计、工具集成或工作流优化阶段的读者。内容忠实翻译了Anthropic报告原文，涵盖Agent的词源含义、工作流与代理的清晰区分、框架使用时机与取舍，以及从流程痛点识别自动化机会、衡量投资回报率等落地要点；同时点明多数应用优化单个LLM调用即可，只有需要大规模灵活性与模型决策时才应引入代理，并重点阐释“少即是多”的可组合设计原则。整体可帮助读者快速吸收官方实践经验，避免陷入复杂框架与概念炫技的误区。

1. 为什么《构建高效的 Agents 指南》值得从头读到尾，而且要读中文版

很多人第一次翻完这《构建高效的 Agents 指南》的中文全译版，第一反应是：核心内容不就是 Workflow 和 Agent 的对比吗？这也太简单了。这个反应我能理解，但十有八九是没往深里想。真正的门槛从来不在“读懂”，而在“照着落地”。我见过太多团队看完各类 Agent 教程后，一上来就把业务逻辑全部交给模型自由发挥，结果工具调用满天飞、上下文窗口爆掉、连最基本的稳定性都保不住。这份指南最有价值的地方，恰好是它开篇就给出的那条判断依据：设计 Agent 第一步不是写代码，而是先想清楚哪些环节该自动化、哪些必须保留确定性流程。这篇文章就顺着这条主线，把这份中文翻译版里的核心思想、落地配置和常见坑位拆开讲，给正在评估 Agent 方向、或者已经做出原型但被稳定性折磨的开发者一个可以参考的路径。中文翻译版的好处是少了术语的二次理解成本，可以直接把精力花在判断自己的业务到底适不适合 Agent 上。

2. 先把 Workflow 和 Agent 的分界线画清楚：大多数项目死在了选错起点

2.1 两条硬标准：什么任务该用 Agent，什么任务老老实实写流程

官方的思路里有一个非常实用的提法：不要先问“我要不要用 Agent”，而是先问“这件事的路径是不是固定的”。我落地过几个模拟项目之后，总结出两条可以照搬的判断标准，建议直接拿去做选题会上的筛选工具。

第一条，任务的后续步骤是否依赖前一步的结果来决定。举例说，写一个每天凌晨自动跑的数据清洗脚本，输入格式固定、字段固定、异常处理规则固定，这就是典型的确定性流程，用 Agent 反而增加不稳定因素；而“帮用户对比三家供应商的报价并给出建议”，需要先抓取数据、再根据数据决定要不要追问、最后生成结论，每一步都依赖上一步的输出，这才是 Agent 的用武之地。

第二条，模型的错误是否在可接受的范围内且能被修正。Agent 的本质是用不确定性换灵活性，这意味着它一定会犯错，关键是犯错的代价可控。我在某个内部工具里尝试让 Agent 直接写入生产数据库，结果它把筛选条件理解错了，造成一小片数据被错误更新。这类场景的正确做法是：用 Agent 生成建议和 SQL，但真正执行前必须过一个有明确规则校验的步骤。所以分界线的终点是：宁可让 Agent 做“会说话的前端”，也别让它直接当“执行者”。

2.2 官方强调的“边界感”：上下文、工具与输出护栏三件套

这份指南在多个地方都点到同一个词，我把它翻译成“边界感”。一个没有边界的 Agent 等于一个没有合同约束的外包员工，你给它一个空泛的目标，它就会开始自由发挥，而自由发挥的尽头往往是灾难。所以落地时的核心动作不是调 prompt，而是把边界画出来。

第一层是上下文的边界。你要告诉 Agent 哪些信息是可以查的、哪些信息是它不该假设的。常见做法是在 system prompt 里写清楚“所有事实必须以工具返回结果为准，不得凭记忆作答”，这能减少很多幻觉问题。

第二层是工具的边界。只暴露那些业务允许调用的函数。我见过某团队把整个内部系统的 API 列表全部封装成工具塞给模型，结果模型挑了一个参数最复杂但权限最高的接口去调用，差点造成越权操作。所以工具列表要反复问自己：这个函数被误用会怎样？如果后果严重，宁可先不暴露，或者加一个人工确认步骤。

第三层是输出护栏。让 Agent 输出的内容必须是结构化的，这样下游才能稳定解析。

下面这段是我经常用在一个模拟订单系统里的护栏式 system prompt，可以看到它不像传统指令那样只强调“你要做什么”，更重点的是“你不允许做什么”。

SYSTEM_PROMPT = """你是订单助理。你的职责是回答用户关于订单状态的问题。 你可以使用的工具： 1. get_order_status(order_id)：查询订单物流状态 2. calc_refund_amount(order_id)：预估退款金额 硬性规则（必须遵守）： - 只有用户明确提供了订单号时，才允许调用 get_order_status - 严禁在未获得用户确认前调用 calc_refund_amount - 如果工具返回结果为空，直接告知“未查询到该订单”，不要编造状态 - 最终回复必须包含字段：order_id、status、message"""

这段 prompt 的价值在于把“可以做什么”和“禁止做什么”放在同等重要的位置。逻辑上，它让模型不再需要去猜测边界，而是直接按照约束推理；参数上，工具调用规则写得越具体，就越不容易出现误用工具的行为。很多新手容易犯的错误是只写目标不写禁忌，结果模型答非所问后又去调 prompt，其实问题是出在边界没有画清楚。

2.3 从“能用”到“好用”：评估成本不是想起来才做的事

如果你问我哪种场景最容易翻车，我会说是“没有评估就去调优”的场景。官方指南里虽然没有用大量篇幅去讲评估，但它隐含地强调了一件事：Agent 是黑匣子，你必须持续给它做体检，否则你会完全不知道一次改动是变好了还是变坏了。

有一个很实用的做法：在项目一开始就建立一个日志目录，记录每一次 Agent 运行的输入输出、工具调用顺序和耗时。这些日志不仅是排错依据，更是将来做回归测试的样本集。别等到上线后再补，事后补的日志往往已经缺失了最关键的中间步骤数据。

3. 搭建最小可复现的 Agent 工程：提示词、工具与上下文的三层配置

3.1 一份能真正约束行为的中文 System Prompt 该怎么写

网上很多模板把 system prompt 写成了“你是一个有用的助手”这种套话，这不是不行，而是远远不够。真正可落地的提示词，应该像一份任务说明书，明确角色、流程、禁忌和失败处理。我来写一个通用结构，你们可以直接套用。

SYSTEM_PROMPT_TEMPLATE = """ # 角色 你是{role_name}，负责{responsibility}。 # 可用工具 {tools_description} # 工作流程 1. 接收用户输入 2. 判断是否需要调用工具；不需要则直接回答 3. 调用工具并等待结果 4. 根据工具结果生成最终回答 # 禁止事项 {forbidden_actions} # 失败处理 - 如果工具调用失败，告知用户“暂时无法获取该信息”，并建议稍后重试 - 如果用户输入与职责无关，礼貌拒绝 # 输出格式 {output_format} """

这套模板是我在多次项目里打磨出来的，它的核心是“结构化”。你看，它把角色、工具、流程、禁止事项、失败处理、输出格式六个部分拆开，模型在推理时脑子里的约束是清晰的，不会像一段大白话那样容易被忽略。关键参数在于tools_description和output_format这两块，前者决定了模型能做什么，后者决定了返回结果能不能被下游稳定解析。

3.2 定义一个工具：比写代码更重要的 JSON Schema

工具定义是 Agent 工程里最容易被低估的一部分。很多人以为把函数写出来、加个 description 就行了，实际上模型能不能正确调用工具，很大程度上取决于 input_schema 写得漂不漂亮。

tools = [ { "name": "get_order_status", "description": "根据订单号查询物流状态。适用于用户询问“快递到哪了”“发货了吗”“多久能到”。", "input_schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "用户提供的完整订单号，必须是纯数字" } }, "required": ["order_id"] } } ]

这段代码看似简单，但有一个很容易踩的细节：description 里必须包含触发场景示例。比如我写了“适用于用户询问快递到哪了、发货了吗”，模型看到相似表述时会优先考虑这个工具。而如果 description 只写“查询订单”，模型可能会在用户问“退款多少钱”时也去调用它，方向就偏了。input_schema里每个字段的 description 也很有讲究，它会直接影响模型填参数的质量。

工具定义完后，我还建议在入口加一层函数内校验，即使模型传错了参数，也要能稳定抛出自定义的错误信息，而不是让异常直接冒出去。

3.3 上下文压缩：别让模型背着整个聊天记录走

这是我在实际项目里遇到频率最高的性能杀手。Agent 每轮对话都会把历史消息重新传给模型，对话轮次一多，上下文占用会快速膨胀，后果就是响应变慢、费用变高，更严重的是模型在超长上下文中会顾此失彼，忘掉早期给出的关键信息。

目前业内主流的做法是分层处理：短期记忆保留最近几轮完整消息，长期记忆只保留结构化摘要。比如把多轮对话压缩成几个字段：用户的目标、已确认的信息、待办事项。下面是一个可以用来做压缩的提示词片段，效果很稳定。

SUMMARY_PROMPT = """请阅读以下对话记录，输出 JSON 格式的摘要，包含三个字段： - user_goal：用户最终想达成什么 - confirmed_info：已经确认的关键信息列表 - pending_items：还需要进一步确认或处理的事项 只返回 JSON，不要输出其他解释。对话记录如下： {conversation_history}"""

这种压缩方式能把几十轮对话浓缩成几行结构化数据，后续每轮调用只需要带上摘要和最新消息。落地时我习惯把摘要存一份 JSON 文件，方便排查。需要注意：压缩本身会损失细节，所以不要把摘要当成唯一记忆，特殊关键信息（比如订单号、金额）要单独存到持久化存储里，不能只留在摘要中。这一步属于典型的“参数调对了收益极大、没调对后面全是泪”的事。

4. 从单步到多轮：给 Agent 装上规划、反思与纠错循环

4.1 一个最小可跑的 ReAct 循环：五步以内能跑通

前面两章讲的是配置，这一章开始讲循环。Agent 和普通 API 调用的本质区别在于：模型可以在一次任务中多次调用工具，并根据中间结果调整下一步。

import json def run_agent_loop(user_query, system_prompt, tools, max_steps=5): # 初始化消息列表，system_prompt 作为固定行为约束 messages = [{"role": "user", "content": user_query}] for step in range(max_steps): # 调用大模型接口，传入工具定义 response = llm_call( model="claude-sonnet-4-5", system=system_prompt, messages=messages, tools=tools, max_tokens=1024 ) # 判断模型是否决定结束对话 if response.stop_reason == "end_turn": return response.content # 解析工具调用 tool_call = response.tool_calls[0] tool_name = tool_call.name args = json.loads(tool_call.input) # 执行对应工具并捕获异常 try: result = execute_tool(tool_name, args) return_message = str(result) except Exception as e: return_message = f"工具执行失败：{e}" # 将工具结果追加到对话历史，供模型下一步决策 messages.append({ "role": "user", "content": f"工具 {tool_name} 返回结果：{return_message}" }) # 达到最大步数仍未结束，强制终止并返回最后一次输出 return "已达到最大步数限制，任务终止。请尝试简化问题或拆分步骤。"

代码里最关键的是max_steps这个参数，它决定了 Agent 最多可以“折腾”多少轮。太小，复杂任务跑不完；太大，遇到模型陷入循环时成本会失控。我一般从 5 起步，根据任务复杂度递增到 10。另外一个细节是工具执行结果要裹上清晰的“工具名 + 返回结果”格式追加回对话里，不要只追加裸数据，否则模型容易搞不清楚这个结果是哪来的。

4.2 给 Agent 加一个独立校验步骤，把错误拦在回复之前

单靠一个 ReAct 循环，Agent 最典型的问题就是“自以为做完了”。它调完工具、看到有返回结果就直接生成回答了，哪怕结果明显不合理。官方指南里虽然没有大篇幅写校验器，但这其实是社区里公认的增强方案：在主循环结束后，再增加一个校验 Slot，让模型以另一个角色重新审视整段执行过程。

# 主循环结束后，定义一个校验 prompt VALIDATION_PROMPT = """你是一个质量审核员，请检查以上 Agent 的回答。 重点检查： 1. 是否所有关键结论都有工具结果支撑 2. 是否存在幻觉内容，即未调用工具却编造的信息 3. 是否回答了用户的原始问题 如果发现问题，输出修正后的回答；如果没有问题，原样输出。""" final_answer = validate_answer(agent_raw_answer, VALIDATION_PROMPT)

这种二次校验的做法很朴素，但效果显著。它的本质是用一次额外的模型调用换取更高的可靠度。缺点是增加了一倍的模型调用成本，所以在生产环境里我一般只在“低频率、高价值”的场景启用，比如生成合同摘要、代码审查报告；高频场景则用规则校验替代，比如检查是否包含必要字段。这里的取舍没有标准答案，值得根据你自己的业务成本去测。

4.3 多 Agent 协作的三种结构：别一上来就用复杂的

很多初学 Agent 的人，图纸画得很宏大，恨不得三个 Agent 互相聊天、一个规划一个执行一个审查。但实际情况是：Agent 之间的消息传递越多，上下文污染越严重，错误就越难定位。我实践下来比较可靠的三种结构，按复杂度从低到高排列如下：

第一种是监督型结构，一个主 Agent 负责拆解任务，多个专职 Agent 各干各的，互不通信。这种结构容错最好，因为每个 Agent 的输入输出都是干净的，主 Agent 像是 Team Leader，统一汇总。第二种是流水线结构，Agent A 的输出是 Agent B 的输入，适合有明确先后顺序的任务，比如先摘要再翻译再润色。第三种是辩论型结构，多个 Agent 针对同一问题各自生成答案，再由一个仲裁 Agent 选优，适合风险评估这类有主观判断的任务。

我个人的建议是：第一种结构能解决 80% 的场景。串行通信越少，出问题的环节越少，这是 Agent 工程里最值得牢记的经验。团队里如果有人想上辩论型结构，我会先劝他把场景的具体收益量化出来，否则不要轻易上。

5. 落地排查：五个常见坑位与对应的解决方案，建议收藏

坑一：Agent 在同一个动作上反复重试，像陷入死循环

现象：日志里同一个工具调用出现了几十次，参数几乎一样，模型每次根据相同或类似的错误信息做出相同或类似的决策。原因通常有两点：一是工具返回的错误信息太模糊，模型不知道错在哪，只能原地打转；二是max_steps设得过大，给了它足够的“空转”空间。解决方法是双管齐下：工具出错时返回结构化错误，比如{"error_type": "invalid_param", "error_msg": "order_id must be numeric"}，让模型能从错误里学到新信息；同时把max_steps调小，并在连续多次调用同一工具且参数未变时直接中止，并提示“请尝试其他策略”。这里的目标是让每次循环迭代都能获得“新增信息”，否则循环只是在消耗预算。

坑二：上下文一长，模型开始答非所问

现象：对话进行到十几轮以后，模型突然忘记了用户最开始的需求，甚至重复已经完成的操作。原因是前文太长，底层模型对早期内容的注意力天然会衰减，没有对上下文做主动压缩。解决方法是前面讲的摘要压缩 + 关键信息持久化。另外还有个血泪经验：不要把原始长文本一股脑塞进对话，能预处理成结构化数据就先处理。比如让用户上传一份 PDF，与其把 PDF 全文放进上下文，不如先做一次 OCR 和提取，再把结构化字段传给模型，让模型基于处理后的数据进行推理。这样做的好处是上下文占用大幅下降，输出的准确性也会更稳定。

坑三：工具参数无校验，脏数据进了下游系统

现象：某个下游服务突然报错，排查后发现是 Agent 调用工具时传入了非法的枚举值，而工具函数本身没有做防御性校验。原因是工具入口过于信任模型传参，模型在不确定时就会“猜测”参数。解决方法是给每个工具函数最前面加一层参数清洗和合法性校验，不合法就返回明确的错误提示，这样模型在下一轮会自行修正参数。图片文件大小、状态枚举、日期范围这几个字段一定要重点校验，因为它们是模型最容易自由发挥的地方。

坑四：只测最终答案，不测中间行为，出了问题找不到锅

现象：功能上线后效果不稳定，时好时坏，但你又说不清是哪一步出了问题。原因是评估体系只覆盖了最终输出，没有记录 Agent 中间调用了哪些工具、顺序如何、耗时多久。解决方法是给每一次 Agent 运行都落一份结构化日志文件，关键信息用 JSONL 按行追加，包括用户输入、模型每一步的意图、目标工具名、工具返回摘要、最终输出。

坑五：把模型的随机性当成故障，反复调 prompt 也没用

现象：同一个问题反复问三次，答案略有不同，验收方认为这是 Bug，要求彻底消除随机性。这里要区分场景：如果任务属于事实问答，本身就应该是低温度的；如果是头脑风暴或文案生成，多变性反而有价值。解决方法：事实类任务将温度调到一个接近确定性的档位，并对关键输出做 JSON Schema 约束，同时明确规定“不添加工具结果之外的信息”，那么三次回答的差异就会小到可以接受。做好这几点后，评估要看“范围内的一致”，也就是核心事实字段是否完全一致，格式和语气允许有轻微浮动。别一门心思去消灭随机性，那属于缘木求鱼，除非把温度调到零配合严格 Schema，但那样做还不如直接用确定性流程。

6. 建立一套轻量的行为日志与回归验证流程，让 Agent 改动不“开盲盒”

我自己的习惯是在任何 Agent 项目立项的第一天就搭一个日志模块，记三步：用户的原始输入、模型发出的工具调用序列、最终输出。不要等到上线后再补，临时补的日志大概率是残缺的，尤其是早期踩坑阶段的数据，后面再想分析已经找不回来了。

日志格式我推荐 JSONL，每行一条独立记录，方便后续用脚本按“工具名、耗时、成功失败”做聚合统计。如下是一个可直接参考的记录结构：

# 记录每一次 Agent 运行的关键行为 log_entry = { "timestamp": "2025-05-01T10:00:00Z", "session_id": "session-123", "user_query": "用户输入内容", "tool_calls": [ {"step": 1, "tool": "get_order_status", "args": {"order_id": "1001"}, "ok": True, "cost_ms": 120}, {"step": 2, "tool": "calc_refund_amount", "args": {"order_id": "1001"}, "ok": False, "cost_ms": 60} ], "final_answer": "最终回答内容", "total_cost_ms": 180 }

有了日志之后，回归测试就变得可操作了。每当你打算改 prompt、换模型版本或者增删工具，先跑同一批测试用例，把日志里的工具调用序列和最终输出导出来做对比。你会发现很多问题在提示词阶段就可以暴露出来。我最常用来分析的一件事是：新版本的 Agent 是不是莫名其妙多调用了一次无用的工具？这通常说明它的决策链路变复杂了，而不是变聪明了。另外，我还会在改动后定期看一次平均工具调用次数和失败率，如果这两个指标同时上升，基本可以断定改动方向有问题。这套流程不花太多开发时间，但对判断 Agent 质量的作用非常大。希望这些经验能帮你在 Agent 落地的路上少走一点弯路。

本文还有配套的精品资源，点击获取