企业官网建设流程全解析

网上关于 AI Agent 的文章多到数不过来，但大部分停留在概念层：什么是 Agent、Agent 和 Chatbot 的区别、Agent 的三种设计范式。看完这些你会有一种“懂了”的错觉，但一写代码就跪了。我自己的体会是，当你真要把一个 Agent 放到生产环境里让它干活——查库存、写日报、调度内部接口——你会立刻发现它变成一个分布式系统问题，而不是一个提示词问题。

这篇文章不聊概念，只聊实现。我过去两三年做了不下十版 Agent 项目，从早期用 Prompt 硬怼，到后来用 LangChain 拼积木，再到现在用 LangGraph 画状态图、把整套东西塞进异步队列里跑。折腾下来，真正决定一个 Agent 能不能落地的，不是模型选得多强，而是两个框架：七要素和七个决策点。前者告诉你要做齐哪些模块，后者告诉你在每个分岔路口怎么选。

这篇文章适合两类人：第一类是已经在用 LangChain 或自研框架写 Agent，但总觉得项目“跑得通，撑不住”的人；第二类是准备从零搭 Agent 服务，但不知道该从哪里下手的人。读完你能拿走的不只是概念，而是一份可以直接对照实行的工程检查清单。

1. 为什么搞懂 Agent 工程要先看“七要素”

1.1 七要素是 Agent 的“骨架”而不是“玩具”

很多同学第一次接触 Agent，是从 LangChain 的 agent executor 开始的：定义一个 prompt，挂几个工具，agent.run("帮我做某某事情")，完事。Demo 阶段这套流程非常爽，但一个典型 Agent 的内部构成绝对不止“模型 + 工具”这两块。如果你把 Agent 拆到足够细，会发现它一定包含七个部分：目标解析、记忆管理、策略规划、工具编排、动作执行、反馈评估、状态流转。

我为什么强调“七个”而不是“六个”或“五个”？因为传统教程经常把“反馈评估”和“状态流转”揉进“规划”里。这样做在概念上没问题，但在工程上会出大问题：你根本没法知道 Agent 在哪个环节卡住了，也没法单独给评估逻辑上强度。把七个要素当作七个独立的模块去设计，你的系统才能各自演进、各自测试、各自回滚。用一个不太恰当但好懂的类比：七要素就像一辆汽车的底盘、引擎、变速箱、转向、刹车、仪表盘和 ECU，缺一个，车能开但没法安全上路。

1.2 逐个拆解：每个要素对应什么工程问题

先放一张总表，方便对照。

看到这张表，你应该明白了一件事：七要素不是七种“高级功能”，而是七个你必须回答的工程问题。下面一个一个讲。

目标解析（意图理解）。这是入口，也是大多数人做得最糙的地方。很多 Agent 直接把用户的话原封不动丢进 prompt，靠模型“临场发挥”理解任务。这么做的问题在于：用户表达是模糊的，模型每次理解都可能有细微差别，而后面的规划、工具调用全部跟着飘。我在项目中一般会强制加一步结构化抽取：定义一个 TaskSpec 模型（包含 title、params、priority、限制条件），让模型先把它抽出来，再往后续流程传。这个环节多花几百个 token，能让整个 Agent 的稳定性上一个台阶。对话中用户说“帮我订明天下午的会议室”，解析结果应该是 {action: "book_meeting", datetime: "2024-xx-xxT14:00", room_count: 1, region: ""} 这样的结构化数据，而不是一段含糊的自然语言。

记忆管理。记忆要分两层看：短期工作记忆和长期知识记忆。短期记忆就是当前任务上下文，包括用户本轮说的内容、Agent 自己规划出来的步骤、工具执行的历史。长期记忆是跨会话的东西，比如用户习惯用哪种格式汇报、上次说的合同编号是多少。工程上，短期记忆用 Redis 存会话内状态，长期记忆用向量库按语义检索。注意，记忆不是把历史一股脑塞进去，而是要有预算、有策略：上下文窗口不够就先摘要再塞，检索不到相关内容就不要硬编造。

策略规划。规划是 Agent 最像“智能”的一个环节，但也是最容易失控的一环。把任务拆成多个行动点时，常见的毛病是拆得没头没尾——模型先规划出 5 步，执行到第 3 步发现前置条件没满足，后面全乱。我现在的做法是“规划 + 动态微调”：规划阶段只做粗粒度步骤，执行过程中每完成一步，都让评估节点重新看一遍“剩余计划是否仍然成立”，不成立就重新规划。ReAct 是这种思路的简化版，Plan-and-Execute 是强化版，二者没有绝对优劣，关键看你愿意为“动态性”付出多少 token。

工具编排。工具是 Agent 的手脚，工具编排更像一份“岗位说明书”。你在给模型定义工具时，每一条 Function Schema 都决定模型会不会正确使用它。工具命名要动词开头、描述要写清楚触发条件、参数要列全必填和可选。我见过最典型的失败案例：工具描述写得太长太绕，模型干脆选一个名字看着像的工具去调，结果传了一堆不存在的参数。把工具描述当成“接口文档”来写，而不是“散文”，是工具编排的第一步。同时，工具列表不要做太大，5~10 个以内的白名单通常比 50 个全量列表更稳定，后者会让模型频繁误选。

动作执行。动作执行看起来最没技术含量——就是发 HTTP 请求嘛。但这里恰恰是生产事故高发区。原因很简单：LLM 返回的是“我想要调 create_order 接口，参数是 ...”，但真正发请求的是你的代码。代码这一层必须自己做三件事：超时控制、幂等控制、异常归一化。否则 Agent 会觉得“我调了接口但没收到响应”，然后反复重试，把外部系统打爆。动作执行层我还要补一句：所有带副作用的操作（写库、发消息、下单）都建议先走一个“执行计划确认”，要么人工审批，要么做幂等键，二选一，不能裸奔。

反馈评估。这个环节我经常听到的质疑是“有必要吗？模型又不会检查自己的错误”。但工程上恰恰相反：不检查模型，模型就会拿着幻觉出来的“成功”结果继续往下走。反馈评估有两层：硬校验和软校验。硬校验用代码判断，比如“接口是否返回 200”、“订单号是否生成”、“文件是否存在”；软校验用 LLM 自评，比如“这个总结是否覆盖了原始文档的所有章节”。合理的架构是硬校验放前面，软校验放后面，硬校验不过就直接重试或终止，别浪费一次 LLM 自评的机会。

状态流转。状态流转是整个 Agent 的“总导演”。它的职责只有一个：根据当前状态决定下一步去哪。是继续执行下一步，还是回到规划节点，还是进入人工审批，还是结束任务？这个逻辑必须是一个显式的状态机，不能散落在各段代码的 if-else 里。我在 LangGraph 里会把每个节点当成一个有名字的 state，把“什么时候跳转”画成条件边。这样做的最大好处是：你可以从外部控制 Agent 的执行节奏，比如强行暂停、限流、注入人工意见，而这些能力正是生产环境最需要的。

1.3 七要素之间的串行与循环关系

七要素不是一条笔直的流水线。目标解析和记忆管理是每次任务启动时的“前置加载”；策略规划、工具编排、动作执行、反馈评估会形成一个循环；状态流转则像一条虚线贯穿整个循环，所有节点都向它汇报、由它决定方向。

放一个图景化的理解方式：把 Agent 想象成一个外卖骑手。用户下单（目标解析）；他先调出地图上自己常走的路线（记忆管理）；在出发前看一眼订单里有几个餐品、有没有顺路单（策略规划）；骑车出门，遇到路口选择走哪条路（工具编排）；实际骑行、等红灯、爬楼梯（动作执行）；送到后检查餐品是否齐全、顾客签没签收（反馈评估）。如果发现有一杯洒了，他会决定是重买、联系顾客、还是直接返回店里（状态流转）。你会发现，骑手的每个环节单独抽出来都可以测试、可以优化，而整个配送流程的质量，取决于它们在循环里配合得怎么样。

还有很关键的一点：七要素各自需要不同的“稳定性策略”。目标解析不稳定就用 Schema 和少量示例框住；动作执行不稳定就加超时和重试；反馈评估不稳定就多用硬校验。你在设计每个要素时，都要问自己一句话：这个环节如果输出错了，我的系统能检测出来吗？

2. 七个决策点：工程实现的真正分水岭

七要素回答的是“Agent 由什么构成”，但从设计到落地，你还会连续面对七个决策：状态编排怎么选、并发模型怎么搭、Token 怎么控制、工具边界怎么划、记忆存哪里、出错了怎么查、部署怎么兜底。我不太喜欢把这些叫“最佳实践”，因为它们本质上是 trade-off——没有绝对的答案，只有适不适合你的业务形态。下面逐个说。

2.1 决策点一：状态编排——选图还是选链

这是你写代码前第一个要拍板的事。Chain（链）是最简单的编排方式，线性地按照“A 执行完就 B，B 执行完就 C”跑。它天然适合流程固定的任务，比如“先把消息做个意图分类，再根据分类调不同 prompt 生成回复”。但 Agent 的核心特征是非线性：执行完工具调用后，你没法预先知道下一步是继续调工具、回到规划重新拆，还是直接结束。如果你用 Chain 硬表达这种逻辑，代码会变成屎山一样的 if-else 嵌套。

Graph（图）把每个处理步骤声明成节点，把跳转关系声明成边，运行时根据条件边走边跳。LangGraph、Temporal、自研状态机都是这一类。我自己从 LangChain 的 AgentExecutor 迁到 LangGraph 之后，最大的变化不是性能，而是整个执行流程变得可观测、可暂停、可回放。图中的每个节点都能单独调试，条件边就是明确的业务规则。

可以做一张对比表：

顺带说一句，最近看到不少人讨论“基于 Rust 语言写 Agent runtime”。Rust 做 Agent 的 runtime 层确实很香，性能好、并发能力强，但 LLM 生态还是 Python 最全，工具库最多。我的建议是：别为了炫技把整个 Agent 都用 Rust 重写，更实际的做法是让 Rust 做网关和队列，核心 Agent 逻辑留在 Python 生态里，两边用 gRPC 或 HTTP 通信。

2.2 决策点二：并发模型——Agent 到底怎么扛并发

“AI Agent 怎么扛并发”是我被问得最多的问题，也是最容易答偏的问题。先说 Agent 工作负载的两个特点：第一，单次任务耗时长，从几秒到几十秒不等，因为中间要多次调用 LLM 和外部工具；第二，它是典型的 IO 密集型任务，CPU 占用不高，但外部 API 的响应时间完全不可控。这两个特点决定了，你不能用传统的“线程池 + 同步阻塞”思路去扛，而要考虑“异步化 + 队列化”。

我推荐的主力架构是三层分离：接入层、任务层、执行层。接入层用 FastAPI 这类异步框架，收到请求后只干一件事——往 Redis Stream 里丢一条任务消息，然后立刻返回一个 task_id。任务层是一组 Worker 进程，从 Stream 里消费消息，真正运行 Agent 的状态图。执行层负责具体的外部调用（LLM API、内部服务、数据库）。这样做的好处是：API 层的吞吐量不再受 Agent 执行时间影响，你想扩并发的时候，加 Worker 就行，而不是在请求线程里干等。

并发参数怎么定？经验法则是“看 LLM 服务端的 QPS 配额，而不是看你服务器的 CPU”。比如你的模型 API 配额是 5 QPS，那你的 Worker 数量最多开到 5~8 个，同时用信号量把并发 LLM 调用数限制在 5 以内，超出的请求等在队列里。盲目开 50 个 Worker 只会疯狂触发 429，然后所有任务一起超时。还有一点很多人忽略：每个 Worker 内部要对 LLM 调用做超时设置，连接超时 3 秒，读取超时 60 秒，别让一个卡的请求把 Worker 占死。如果业务允许，最好再加一层“轻模型预分类 + 重模型执行”的双模型路由，把简单请求分流到便宜且快的小模型上，成本能省一半不止。

2.3 决策点三：Token 消耗与上下文治理

“AI Agent token 是什么意思”这个热词，说明很多人卡在了理解成本模型上。Token 是模型处理文本的最小单位，粗略理解成“字/词片段的编号”，API 计费按 token 算，模型输入和输出都会消耗。Agent 之所以比普通 Chatbot 烧钱，是因为它多轮迭代：每次循环都要把系统提示、历史记录、工具描述、工具执行结果拼在一起发给模型，再生成下一步的决策文本。一个看起来简单的“查库存并写报告”任务，底层可能消耗几千甚至上万 token。

工程上控制 token 成本，我有几条实操原则：

• 给每个 Agent 任务设 token 预算上限，执行到预算边界仍然没完成，就强制转人工或走降级流程。
• 系统提示词和工具描述要“瘦身”，能写 50 字的不要写 200 字。模型每次循环只见得到这些字，它们直接影响输入成本。
• 工具返回结果必须截断。很多外部接口返回几十 KB JSON，全塞进上下文不仅烧钱，还会把重要指令挤出上下文窗口。
• 上下文滚动摘要：对话超长时，将早期对话压缩成摘要再回填，保留关键事实，丢到冗余过程。
• 长期记忆走向量检索，只把 Top-3 到 Top-5 的相关片段放回上下文，而不是把用户三个月的历史全部塞进去。

我算过一笔账：用某个主流小模型，一次 Agent 任务如果消耗 1 万 token 输入加 2 千 token 输出，成本大概在几厘到几分钱人民币之间。看起来不多，但如果你每天跑一万个任务，那这就是真金白银。所以越早做 token 治理，后面越省心。

2.4 决策点四：工具接入的权限边界

给 Agent 接工具，看起来是“加接口”的问题，实际上是“划权限”的问题。传统服务是代码调接口，权限在代码里写死；Agent 是模型决定调哪个接口，这等于把一个“不可完全预测”的决策者放进了权限系统里。所以工具接入必须遵循三条原则：

• 白名单制。Agent 只能调用你显式列出的工具，绝不提供“通配”式的动态工具加载。工具 Schema 由开发者在代码里定义，不由模型生成。
• 最小权限。给 Agent 的工具只保留完成业务必需的操作。查库存可以做，改库存单价就坚决不开。敏感数据脱敏后再进工具返回值。
• 参数强校验。模型生成的 tool_call 参数必须经过 Pydantic 校验，不合法直接拒绝，而不是带病执行。这一点很多团队会忽略，结果就是 Agent 传了个“部门=研发部（正确）”，但时间格式却是“明天下午”，后端接口直接 500。

高危动作必须有人工审批位。比如发消息、下单、删除数据这类操作，在状态图上加一个“等待确认”节点，模型把参数生成好，人点了确认才真正执行。这不是给 Agent 添麻烦，而是给自己留退路，尤其是涉及内容平台自动发布、对外通知这种场景，技术能做和该不该做是两回事，一定要遵守平台规则和合规要求。

2.5 决策点五：记忆持久化的选型

记忆选型要分短期和长期两套方案，千万别一套走天下。短期记忆要的是低延迟、快读写，我习惯用 Redis 存会话状态。每个会话一个 key，value 里存当前任务、已执行步骤、中间结果摘要，过期时间设成几小时。Agent 的图每走完一个节点，就把状态通过 checkpoint 机制写回 Redis。这样服务重启，任务也能从上次断点恢复。

长期记忆要的是语义检索，主流方案是向量数据库。选型上，Qdrant、Milvus、pgvector 都行。如果你们团队已经用了 PostgreSQL，我建议直接用 pgvector，少一个组件，维护成本低。向量库负责存“长期偏好、历史决策、业务知识片段”，写入时机一般是在 Agent 成功完成任务后，由后处理管线把关键信息抽出来做 embedding。检索时只取 Top-K 相关片段，回填进提示词。

记忆还有一个反直觉的点：记忆不是越多越好。相关度低的历史片段在上下文里反而会对模型形成干扰，让它更频繁地跑偏。所以记忆写入前要做价值判断——这件事以后还会用到吗？没有价值的信息，丢掉比记住更省钱。

2.6 决策点六：可观测性与全链路追踪

Agent 系统的排查难度，比普通后端高一个数量级。普通后端是“请求打进去，响应返出来”，出问题最多查个日志；Agent 是“一个请求进去，中间可能循环了五六次，每次循环都有模型生成、工具调用、状态跳转”，任何一个环节出错，表象可能都差不多——任务失败、超时、结果不对。没有一套全链路追踪，你会像在黑盒子里找一根断掉的线。

我的做法是在 Agent 的 State 里加入 trace_id，每个节点执行时都携带着它。节点开始时记录时间戳、token 数、输入摘要；结束时记录输出摘要、决策原因。工具调用这一步，要把原始请求和原始响应完整落盘，越详细越好，很多问题只有看到原始返回才能定位。有条件上 LangSmith 这类工具的是少数，我更多时候是自建一张 agent_trace 表，把每个节点一条记录串起来。排查问题时按 trace_id 拉出整条链路，看哪一步输入、哪一步输出、哪一步跳转异常。

这里提醒一句：prompt 是影响一切的上游变量。我遇到过“昨天还能跑，今天全挂”的诡异问题，最后发现是某个 prompt 模板被同事改了一个字。所以所有 Agent 配置——prompt 模板、工具 Schema、模型参数、状态图版本——都要纳入版本管理，trace 里也要记录当时的版本号。否则你看到的 trace 是一堆没有对照系的随机快照。

2.7 决策点七：部署形态与稳定性兜底

Agent 服务部署上没有太多新东西，但有几个坑比较典型。第一个坑是“把状态放在内存里”。LangChain 早期示例都会把 conversation memory 放在进程内存里，开发很爽，一重启全没。生产环境必须把 checkpoint 和会话状态外置到 Redis 或 Postgres，具体放在哪个节点、哪个条件边，图的状态才能跨进程存活。

第二个坑是失败重试策略写得过于粗暴。Agent 里会遇到三种不同的失败：LLM API 失败（服务端 5xx、限流）、工具调用失败（接口超时、参数被拒）、流程失败（模型规划出错、评估不通过）。不能都用同一套重试逻辑。LLM 失败可以带指数退避重试 2~3 次；工具失败要看是否是幂等接口，只有幂等的才能重试；流程失败与其重试，不如换个策略重新规划。

第三个坑是部署时没有降级预案。Agent 毕竟依赖外部模型服务，模型服务故障、配额超限、网络抖动，都会让整个业务停摆。我的习惯是给关键业务保留一条“无 Agent 的人工流程”或“固定规则流程”，Agent 健康检查不过时就自动降级切换。这个兜底方案看着不高级，但真出事了能救命。版本控制也要纳入 CI/CD：prompt 模板、工具 Schema、Agent 状态图定义都要作为配置参与发布，不能热改线上配置，不然出问题没法回滚。

3. 一套可落地的参考实现：FastAPI + LangGraph + Redis 队列

前面说了这么多框架性的东西，很多同学可能想要一套能直接抄的骨架。下面我以自己目前在用的“FastAPI + LangGraph + Redis Stream 队列”为例，把架构、关键代码和参数选择完整过一遍。这套结构不绑定特定模型，OpenAI、Claude、各家国产模型的接口都能接。

3.1 整体架构与选型理由

整个服务分成四层：

• API 接入层：FastAPI 提供异步 REST 接口，接收任务后立即生成 task_id，把任务写入 Redis Stream，返回“已受理”。用户轮询或通过 WebSocket 获取进度。
• 任务队列层：Redis Stream 充当任务缓冲，消费者组由 N 个 Worker 组成，天然支持多 Worker 并发消费、断线重试和 pending 消息处理。
• Agent 执行层：每个 Worker 内部用 LangGraph 运行状态图，节点的 checkpoint 写入 Redis，模型调用统一走一个带超时和限流的 LLM 封装。
• 存储层：Redis 存会话状态与短期记忆，PostgreSQL（加 pgvector）存长记忆和任务结果。

选型理由很简单：FastAPI 的异步能力让接入层轻快；Redis Stream 比 Celery 轻，没有 broker 中间件重依赖；LangGraph 的画图式编排让我不用手写大量状态机胶水代码。这套组合能支撑每秒几十到几百的任务提交量，瓶颈通常在 LLM API 配额而不是服务本身。如果你对性能要求再高，可以在门口再加一层 Nginx 或 API Gateway，把不同业务的 Agent 路由到不同的 Worker 池。

3.2 核心代码：定义 Agent 状态图

先定义状态。AgentState 是一个 TypedDict，所有节点都往里面写入字段。这里我用 LangGraph 的 Annotated 语法表示 messages 是累加式的：

from typing import TypedDict, Annotated import operator from langgraph.graph import StateGraph, END class AgentState(TypedDict): task_id: str user_input: str task_spec: dict # 目标解析产物 plan: list[str] # 规划步骤列表 current_step: int tool_results: dict # 工具执行结果 trace: list[dict] # 全链路 trace done: bool error: str | None

然后定义五个节点，分别是 parse → plan → act → evaluate → reflect，reflect 根据评估结果跳回 plan 或输出结果：

def parse_node(state: AgentState) -> AgentState: # 调用 LLM 把 user_input 转成结构化 task_spec ... def plan_node(state: AgentState) -> AgentState: # 基于 task_spec 和记忆生成 plan ... def act_node(state: AgentState) -> AgentState: # 执行 plan[current_step] 对应的工具 ... def evaluate_node(state: AgentState) -> AgentState: # 检查工具结果，更新下一步策略 ... def reflect_node(state: AgentState) -> AgentState: state["done"] = True return state builder = StateGraph(AgentState) builder.add_node("parse", parse_node) builder.add_node("plan", plan_node) builder.add_node("act", act_node) builder.add_node("evaluate", evaluate_node) builder.add_node("reflect", reflect_node) builder.add_edge("parse", "plan") builder.add_edge("plan", "act") builder.add_edge("act", "evaluate") def should_reflect(state: AgentState): if state["done"]: return "finish" return "reflect" builder.add_conditional_edges( "evaluate", should_reflect, {"finish": "reflect", "reflect": "plan"} ) builder.add_edge("reflect", END) agent_graph = builder.compile()

这个图里真正的“智能”在 evaluate 节点：它会根据工具结果判断当前步骤是否成功，成功就推进 current_step，不成功就返回 plan 重新规划。注意 should_reflect 里的条件跳转，你要在外层做好循环上限控制，避免图跑成死循环。实际工程里我会在状态里加一个 loop_count，当它超过 5 时强制走 reflect 结束。

3.3 核心代码：FastAPI 接入层 + Redis Stream 队列

再给接入层和队列的代码。接入层尽量轻，收到请求就入队：

import uuid import json from fastapi import FastAPI import redis.asyncio as redis app = FastAPI() r = redis.from_url("redis://localhost:6379") @app.post("/api/agent/run") async def run_agent(req: dict): task_id = str(uuid.uuid4()) payload = {"task_id": task_id, "user_input": req["user_input"]} await r.xadd("agent_tasks", {"payload": json.dumps(payload)}) return {"task_id": task_id, "status": "queued"} @app.get("/api/agent/status/{task_id}") async def get_status(task_id: str): data = await r.hgetall(f"task:{task_id}") return {"task_id": task_id, "status": data.get("status", "running")}

Worker 端的消费循环也很简单，用 xreadgroup 读 Stream，每读一条任务就重新进 Agent 图：

while True: items = await r.xreadgroup( "agent_workers", "agent_consumer", {"agent_tasks": ">"}, count=1, block=5000 ) if not items: continue for stream, messages in items: for message_id, data in messages: task = json.loads(data[b"payload"]) await run_agent_graph(task) await r.xack("agent_tasks", "agent_workers", message_id)

这套代码正好体现“API 层秒回，Worker 慢慢干活”的异步思想。前端收到 task_id 后轮询状态接口，或者用 WebSocket 推送，用户感知到的是“Agent 正在思考”，实际底层是一堆 Worker 在处理。

3.4 并发与限流参数实测

最后分享一组我在一个内部信息整理 Agent 上实际跑出来的参数。模型用了一个中等价位的通用模型，QPS 配置上限 5，于是 Worker 数量设为 6，同时用 asyncio.Semaphore(5) 限制并发 LLM 调用数。每个 LLM 调用的超时设置为 connect_timeout=3s、read_timeout=60s；工具调用的超时按接口特点分别设置，查类接口 10s，写类接口 30s。Redis Stream 的 pending 长度超过 1000 时触发告警，说明消费能力跟不上提交速度。

压测结果：每秒提交 50 个任务，API 层几乎无压力，P99 响应在 50ms 以内；Worker 侧因为有队列缓冲和限流，模型服务没有出现 429，任务失败率从原来没限流时的 15% 降到了 2% 以内。这个数据不一定适合所有人，但思路是一致的：限流一定要做在调用模型的前面，而不是等 API 返回 429 再慌。

4. 实战中的常见问题与排查真相

4.1 问题速查表：Agent 工程踩坑清单

我在多个项目里反复踩过的坑，整理成一张速查表，适合贴在工位上：

这几点看着都很基础，但每一个都是我真实摔出来的。你如果正在调自己的 Agent，建议先对着这张表自查一遍，大概率能少走一半弯路。

4.2 三个真实踩坑记录：细节复盘

第一个坑来自一个文档总结 Agent。当时我给 Agent 接了一个“读取文件内容”的工具，直接把整个文档塞进上下文，结果文档一长，摘要指令被挤出上下文窗口，Agent 开始乱调用其他工具，搞出一堆无效操作。后来我在工具层加了预处理：超过 3000 字的文档先截断并做一次粗摘要，再作为工具结果返回。注意这里的关键不是“截断”本身，而是在管道里安排了一个“文档预处理节点”，把工具的原始返回永远控制在一个安全阈值以内。

第二个坑是并发限流。项目上线前压测，50 个并发任务一进来，模型 API 直接 429，然后所有任务连锁超时。排查后发现问题很简单：10 个 Worker 同时调用同一个模型 API，而配额只有 5 QPS。加上 asyncio.Semaphore(5) 之后，多余的请求在 Worker 内部排队，不再打到模型服务。这个调整只花了 20 分钟，失败率就下来了。这里我想强调：限流不是可有可无的“性能优化”，而是 Agent 服务的“生存底线”。

第三个坑比较隐蔽——幂等。一个邮件发送 Agent，在评估节点判断“发送成功”后仍认为任务未完成，于是重新调用发送工具，把同一封邮件发了三遍。最后在工具层加了幂等键：每次发送任务先生成一个 send_id，邮件服务端按 send_id 去重，重复调用直接返回“已存在”。同时把评估规则改成“已发送且 send_id 唯一”，从两个方向杜绝重复执行。凡是 Agent 会调用的写操作工具，我都建议加上幂等键，这比任何 prompt 约束都可靠。

4.3 自动化场景的边界提醒

结合热门搜索词说一句。很多人想拿 Agent 做内容平台自动发布、自动回复、甚至自动交易。技术上这些都能实现，但我要非常明确地说一句：技术能力强不等于可以突破平台规则和合规底线。内容平台的自动化行为、金融市场的实盘自动交易，都有严格的使用条款和监管要求，任何个人或团队在部署这类场景前都应当先确认合规性和平台规则。如果你对这些场景感兴趣，更合理的做法是先在模拟环境、白名单范围内做研究和实验，把 Agent 的稳定性打磨好，再考虑是否、以及如何进入真实业务。这条边界不守住，再强的 Agent 也会变成事故。

把七要素和七个决策点想清楚之后，我做 Agent 的方式发生了本质变化。以前写一个 Agent，我会直接开写代码，把 prompt、工具、模型调用糊在一起；现在我会先拿一张纸把七个要素画出来，再把七个决策点一个个过一遍：状态用什么编排、并发怎么限流、token 怎么治理、工具划到哪一步、记忆放哪里、trace 记什么、部署怎么兜底。这个过程看着繁琐，但它能把 Agent 从“会跑的 Demo”变成“能上班的工程系统”。

最后再分享一个个人体会：Agent 的工程实现没有银弹。同样的七要素，你做简历筛选 Agent 和做内部知识库问答 Agent，每个决策点的答案都不一样。别迷信某个框架或某个架构图，把每个决策点背后的 trade-off 想明白，你才能在自己的业务场景里做对选择。这句话是我踩了无数坑之后最想说的。