AI Agent 工程实现：从七要素到七个关键决策点

最近连续帮两个团队排查 Agent 项目，问题出奇一致：大家把 AI Agent 做成了“会调用工具的聊天机器人”，模型一换、业务流程一加，系统立刻散架。我自己做 AI Agent 工程实现也有一段时间，踩了不少坑之后的体会是——Agent 能不能长期跑稳，靠的不是提示词写得天花乱坠，而是有没有把它的七个核心要素和七个关键决策点想明白。下面我会按这两条线走一遍：先对着要素看架构，再对着决策点做选型，最后用一个“自动发布消息”的场景把流程完整跑一遍。适合正在搭 Agent 的工程师、想在业务里落地 Agent 的产品同学，也适合想照着搭一个最小可运行系统的新手。

1. 先搞清楚：你要做的到底是不是一个 Agent

1.1 套壳应用和 Agent 的分界线

很多项目刚起步时，架构是这样的：用户输入一句话，程序把这句话拼进一个 Prompt，丢给大模型，拿到结果再返回。这不能叫 Agent，最多算套壳应用，或者说“带 Prompt 的接口中转站”。它和 Agent 之间有一条非常清楚的分界线：有没有形成“感知 → 推理 → 行动 → 观察反馈 → 再次推理”的闭环。

我习惯用一个类比：套壳应用是自动贩卖机，你投币，它掉饮料，交互一次结束。Agent 是厨师，接了订单之后要自己看食材、定步骤、开火、尝味道，发现淡了还会补盐，直到把菜做出来。自动贩卖机永远不需要知道自己缺了什么食材，厨师必须时刻感知当前状态并且修正自己的行为。工程实现上的差距也在这：套壳应用只需要一个请求/响应，Agent 服务需要一个能持续运行的循环，循环里每一步都要处理状态、工具调用和异常分支。

这个区别不是概念游戏。它直接决定了你后面要不要引入消息队列、要不要做记忆存储、要不要加人工确认节点。很多团队上来就“用 LangChain 搭个 Agent”，结果只是把一次模型调用换成了三次模型调用，真正的循环控制、状态管理和反馈链路完全没有。先想清楚自己到底要做哪一个，能省掉后面一大半返工。

1.2 Agent 的七要素，一一对应到工程模块

把 Agent 拆到不能再拆，业界讨论比较多的说法是七个核心要素。我按自己落地时的理解整理成下面这张表：

这七个要素不是并列的，它们组成一个环。大模型是大脑，规划和反思是它的思考方式，记忆是它的工作台，感知和工具是它的眼睛和手，行动是它最终做出的改变。工程落地的过程，本质上就是把上面每一个要素映射成一个可以独立测试、独立部署、独立观测的模块。

我见过很多失败的 Agent 项目，不是模型能力不够，而是少了一两个要素。最常见的两个坑：一是没有感知，Agent 只能被动等用户提问，不会主动响应外部事件；二是没有反思，Agent 做完一步就直接结束，哪怕结果明显是错的，它也照常输出“已完成”。这两个要素一旦缺失，无论模型多强，Agent 都跑不出真正的自动化闭环。

2. 工程落地第一步：把七要素挂到架构上

2.1 四层抽象，别让要素之间直接乱连

七要素之间天然有依赖关系，但工程实现里最忌讳的就是让它们互相直接调用。规划逻辑里直接写 Redis，工具代码里直接调模型接口，反思逻辑散落在各个工具内部，这种代码前期跑得通，一旦业务场景复杂起来，牵一发动全身。

我一般把七要素收敛到四层抽象：模型层、编排层、工具层、管控层。模型层只管大模型的调用与响应解析，对外提供统一的 chat 接口。编排层是核心，里面包含规划、记忆、反思，负责跑循环、维护状态。工具层把感知、工具、行动打包在一起，统一通过注册与调用的方式对外提供服务。管控层则负责安全、日志、Token 计数、熔断和人工兜底。

这样分层的理由很简单：Agent 的迭代速度非常快，模型要换、工具要加、流程要调。如果每个要素在代码里都是独立的插件点，换模型只动模型层，加工具只加工具层，调流程只改编排层，每一次变更的影响半径都被控制住了。我踩过最大的坑就是早期把所有逻辑写在一个 agent.py 里，结果每次改需求都要在几千行代码里找上下文位置，后来花了一整个迭代周期才拆干净。

2.2 模块清单：七要素最终会变成哪些代码

纸上谈兵半天，不如直接看目录结构。一个标准的 Agent 服务，拆完模块之后大概是这个样子：

agent_service/ ├── runtime/ # 编排层：跑 ReAct / Plan-and-Execute 循环 ├── schema/ # 状态、消息、工具调用的数据结构定义 ├── memory/ # 工作记忆、摘要记忆、向量召回 ├── tools/ # 工具注册、参数校验、权限校验 ├── gateways/ # 感知接入：webhook、MQ、定时器 ├── actions/ # 行动执行器：发布、发送、建单 ├── observer/ # 日志、trace、token 计数、指标 └── config/ # 模型、预算、轮次上限等配置

这个目录结构不是拍脑袋定的，它对应的是七要素里每一块的工程职责。runtime 对应规划和反思，schema 是支撑所有模块的公共协议，memory 对应记忆，tools 和 actions 对应工具与行动，gateways 对应感知，observer 对应管控。

新手最容易忽略的是 schema 和 observer。没有 schema，工具返回的数据格式就会越来越乱，最后模型解析不到关键字段；没有 observer，Agent 跑坏了你都不知道是第几步、调了哪个工具、花掉了多少 Token。我后面排查问题时的经验是：超过一半的 Agent 故障，最后都是靠 observer 里的 trace 日志定位出来的，而不是靠肉眼盯模型输出。

2.3 最容易做歪的一环：反思

七要素里我最想单独拎出来说的是反思，因为它看起来最简单，做起来最容易假。很多团队的反思逻辑只是往 Prompt 里加了一句“请检查你的回答是否合理”，这不算反思，这只是让模型给自己打分。模型在同一个上下文里自评，很容易出现“我觉得没问题”的盲区。

真正有用的反思必须接到外部反馈上。要么是工具返回的错误码，要么是规则引擎的校验结果，要么是人工审核的评分，至少也得是二次调用一个独立的评判模型对结果做交叉验证。我在一个内容生成 Agent 里就是这么做的：Agent 写完文案，不是直接发布，而是先过一个敏感词和格式校验规则，再让一个更便宜的小模型从客观角度打分，分低了就回到规划环节重新写。加了这层之后，发布内容的合格率肉眼可见地涨了。

反思层的工程实现不需要很复杂，关键是它必须是一个真实的反馈信号源，并且要接到编排层的循环控制上。没有反馈就不循环，不循环就是个一次性生成器，配不上“Agent”这个名字。

3. 七个决策点：搭建 Agent 时的关键拍板

3.1 决策点一：模型选型别只看排行榜

模型是 Agent 的大脑，但不是排行榜越靠前就越适合你。对于 Agent 场景，真正要看的指标有三个：函数调用稳定性、上下文窗口的利用效率、以及成本/延迟的综合表现。

函数调用稳定性是排第一的。Agent 核心动作是通过工具调用来完成的，模型能不能严格按 JSON Schema 输出参数、能不能在多个工具之间正确选择，直接决定了循环能不能走下去。有的模型聊天很厉害，但工具调用格式经常出错，在 Agent 场景里就是灾难。我实测下来的经验是：小参数模型在简单任务上完全够用，但一旦工具数量超过五个，就明显能感觉到调用准确率下降，这时候要么换更强的模型，要么简化工具粒度。

上下文窗口也要算细账。不是说模型支持 128K 上下文，你就可以随意往里面塞。上下文越长，推理延迟越高，单次调用成本也越高。而且实际用时你会发现，记忆压缩、工具描述和中间结果会快速吃掉上下文空间。选型时按峰值用量估算，而不是按宣传的上限估算，这个习惯能帮你省下不少钱。

3.2 决策点二：循环范式选 ReAct 还是 Plan-and-Execute

Agent 主循环怎么写，是第二个必须拍板的决策点。目前工程上最常见的两种范式是 ReAct 和 Plan-and-Execute，它们各有各的适用场景。

ReAct 是边想边做。模型每一步先观察当前状态，决定调用哪个工具，看到工具结果后再继续推理。它的优势是动态调整能力强，适合开放式任务，比如“帮我整理这份文档并生成周报”。风险是容易跑偏、容易绕圈，模型的每一步都依赖上一步的结果，一旦中间某一步出错，后续可能跟着错。

Plan-and-Execute 是先计划后执行。模型先把整个任务拆成步骤清单，然后按部就班执行。它的优势是流程清晰，适合步骤固定的业务，比如“每天定时抓取库存数据、生成报表、发送邮件”。劣势是计划一旦定完，中途很难根据新情况大改，如果任务本身有很多不确定性，执行到一半可能整个计划作废。

我的建议是：业务任务优先考虑 Plan-and-Execute，探索型任务用 ReAct，复杂场景可以混合使用。实践中，我会让 Agent 先输出计划，再由一个校验器判断计划是否可执行，执行过程中每一步再结合 ReAct 小循环动态调整。这样既保持了计划感，又没有放弃灵活性。

3.3 决策点三：记忆做分层，别一股脑塞上下文

记忆是最容易被人低估的要素。很多人把“对话历史全部塞进上下文”当成记忆，这在对话轮次少的时候没问题，一旦任务长达几十步，上下文立刻膨胀，Token 消耗飙升，模型还会被旧信息干扰。

我习惯把记忆分成三层。工作记忆是当前任务内的上下文，跟着循环走，存在运行时里；情景记忆是历史任务的摘要，存在 Redis 或数据库里，比如“用户上周已经确认过活动方案”；语义记忆是结构化的知识，存在向量库里，比如“公司产品手册的核心卖点”，需要时用相似度召回。召回之后还要做重排，控制塞进上下文的片段数量和长度。

这里给个具体计算，你就能理解为什么记忆策略会影响成本。假设一个 Agent 任务执行 10 轮循环，每轮模型请求携带 3000 Token 历史，加上 2000 Token 的工具描述和输入，光看着就是 10 × 5000 = 50000 Token。如果做了摘要记忆，把历史压到 1000 Token，再把工具描述精简到 800 Token，每轮只需要 1800 Token，总量直接降到 18000。同一个任务，成本差将近三倍。做 Agent 不做记忆压缩，等于白扔钱。

3.4 决策点四：工具集设计，给 Agent 立规矩

工具决定了 Agent 能做多少事，也决定了它能闯多大的祸。工具设计的第一原则是控制粒度。一个“发布内容”的大工具，内部包含了改文案、审核、定时、发通知，看起来省事，但 Agent 一旦调用就会把整条链路全部触发，中途没有任何干预点。我更建议拆成“生成草稿”“提交审核”“执行发布”“通知结果”四个小工具，每一步都能单独校验和插人工节点。

工具描述也很关键。模型是靠描述来理解工具用途的，描述写得模糊，Agent 就不知道该在什么时候调用哪个工具。我见过最典型的例子：工具名叫 process_data，描述写“处理数据”，模型根本不知道这个工具是清洗数据还是去重数据。后来把描述改成“对输入表格按 ID 去重并保留最新版本，输出清洗后的 CSV”，调用准确率立马上来了。

权限设计是另一个容易忽略的点。每个工具都应该有独立的权限标签，比如“只读”“需人工确认”“高危操作”。自动发消息这种外部副作用强的工具，权限上至少要有个开关，默认不允许 Agent 直接执行，必须走人工确认节点。给 Agent 立规矩，本质上就是给工具设边界。

3.5 决策点五：单 Agent 不够再上多 Agent

多 Agent 这两年很火，但工程上的坑比收益多。多 Agent 系统里，每个 Agent 有自己的上下文和记忆，Agent 之间要通信、要共享状态，消息格式要约定，还得处理重复调用和死锁。我见过很多团队为了“架构先进”强行上多 Agent，结果光协调 Agent 之间的状态就花了三倍开发时间。

我的判断标准很简单：单个 Agent 能不能胜任？如果任务边界模糊但流程可控，就先用单 Agent 加记忆和工具解决。只有出现两种明确情况时才考虑多 Agent：一是任务天然可以并行拆解，比如同时调研三个竞品然后汇总；二是不同环节需要完全不同的专长和提示词策略。即便上多 Agent，也建议采用“主控 Agent 派发、工作 Agent 执行”的星型结构，避免 Agent 之间网状通信。

这里顺便说一句 Rust。热词里很多人在聊“基于 Rust 的 AI Agent”，Rust 的并发能力和内存安全确实非常适合做高吞吐的 Agent 运行时，生态里也有 rig 之类的框架在成熟。但选型要看瓶颈在哪，我见过一个团队用 Rust 重写了整个 Agent 循环，最后发现性能瓶颈在大模型 API 的延迟上，耗时的大头在网络，根本不在 CPU。工程上成熟的做法是 Python 快速迭代业务，Rust 聚焦在真正需要高并发的网关层或调度层。

3.6 决策点六：接口形态，异步任务才是常态

Agent 不是瞬时函数，一个任务可能跑几十秒甚至几分钟，对外接口如果做成同步 HTTP 请求，调用方会一直挂着等结果，体验差不说，还容易把服务线程池打满。工程上的标准做法是：接口接收请求后，立刻返回一个 task_id，Agent 在后台异步执行，执行完成后通过回调或轮询通知结果。

消息队列在这个环节里是标配。任务进来先丢到 Redis Stream 或 RabbitMQ，Worker 消费后执行 Agent 循环，状态实时写到存储里。前端或调用方拿 task_id 查询进度，进度可以细化到“正在生成文案”“正在等待人工审核”“发布完成”。这样用户随时能看到 Agent 干到哪一步了，出了故障也能定位到具体环节。

感知层同样要走异步。Agent 需要主动感知的外部事件，比如定时任务、Webhook 回调、新的消息进来，都是通过事件总线路由到对应 Agent 的。不要为了省事直接在 Webhook 里跑 Agent 循环，那样一个慢请求就可能把事件源拖垮。我的习惯是：所有入口都转成事件，所有事件都进队列，所有 Agent 都通过异步任务执行，这条规则在工程上几乎不会错。

3.7 决策点七：Token、成本与可观测性，上线前定死

最后这个决策点最容易被忽略，却是上线之后第一个来找你的问题。Token 成本在 Agent 场景里不是线性的，每一次循环都会累加历史，工具描述也会反复占用上下文。一个“自动发布消息”的 Agent，跑一次完整任务消耗三五万 Token 是非常正常的，如果没有预算控制，一个失控的死循环就能烧掉大量费用。

我给自己定了几条成本规则：所有 Agent 任务必须设置最大循环次数和单任务 Token 预算，超了就熔断；模型调用前把不需要的历史丢弃，精简工具描述；每次循环记录 Token 消耗明细，按任务维度聚合统计。预算控制不能靠人盯，要在代码里强制实现。

可观测性比成本更基础。每个 Agent 任务从进入系统开始就要分配一个 trace_id，所有日志、工具调用、模型请求、Token 数都挂在这个 trace_id 下面。出了问题，拿着 trace_id 就能还原整个执行过程。没有这套东西，Agent 调试约等于黑盒猜谜，这在第五章会细讲。顺带说一句，云厂商的 Agent 白皮书里也有类似观点：Agent 首先是一个系统问题，而不是一个模型问题，我深以为然。

4. 实操：一个能跑通的“自动发布消息”Agent

4.1 场景与七要素映射

理论讲再多，不如一个能跑的场景。我选一个大家经常提到、但很少有文章讲清楚工程细节的案例：内容运营团队需要一个 Agent，每天定时从素材库挑选内容、改写成适合新媒体平台的文案、提交人工审核，审核通过后自动发布，发布完成后把结果记录下来。

先把这个场景映射到七要素上。大模型负责文案改写和步骤选择；规划逻辑是固定的四条：取素材、改文案、等审核、发布；记忆要记住哪些素材已经用过，避免重复；工具层有三个关键工具：list_pending_materials、submit_review、publish_post；感知层是每天上午十点的定时触发器；行动层是最终执行发布的 Worker；反思层是发布接口返回的结果校验，失败了要记录原因并进入重试或人工处理。

这个场景规模不大，但覆盖了七要素的全部内容，非常适合当作新手练手的模板。它不依赖复杂框架，用 Python 加一个简单的任务队列就能实现。

4.2 技术选型：Python/Django 还是 Rust

这个场景我推荐 Python 生态。原因不复杂：业务逻辑以 IO 为主，大量时间花在模型 API 和平台接口调用上，Python 的开发效率和生态成熟度优势明显。Django 在这里扮演的是控制面和数据面的角色，用它写任务模型、素材表、发布记录表，再配合 Celery 处理异步 Agent 任务，一个团队三五天就能把骨架搭起来。

Rust 在这个场景里没有发挥空间。它是性能敏感的运行时语言，适合承担高频、低延迟、资源紧张的任务，比如网关层做限流和路由、消息队列的消费端做高吞吐处理。如果你的业务是“每天跑上千个 Agent 任务的调度中台”，那 Rust 可以考虑；如果只是几十个内部任务，硬上 Rust 只会拖慢迭代速度。选型先看瓶颈，不要为了热门技术而选型。

4.3 Agent 主循环与 Django 任务集成

下面给一个最简版本的 Agent 运行时，重点在循环控制，它足够帮你理解 Agent 的骨架。生产环境里我会在这个基础上去加追踪、限流和人工确认。

class AgentRuntime: def __init__(self, llm, tools, memory, max_turns=8): self.llm = llm self.tools = {tool.name: tool for tool in tools} self.memory = memory self.max_turns = max_turns def run(self, task): messages = self.memory.build_messages(task) for turn in range(self.max_turns): response = self.llm.chat(messages, tools=list(self.tools.values())) if response.tool_calls: for call in response.tool_calls: result = self.execute_tool(call) messages.append(result) self.observer.record(call, result) # 记录 trace continue return response.content raise AgentLoopError(f"exceeded max_turns={self.max_turns}") def execute_tool(self, call): tool = self.tools.get(call.name) if not tool: return {"error": f"unknown tool: {call.name}"} if not tool.check_permission(): return {"error": "permission denied, need human confirm"} return tool.run(**call.arguments)

在 Django 侧，把 Agent 任务交给 Celery 异步执行，接口先返回 task_id。

@app.task(bind=True, max_retries=3) def run_publish_agent(self, request_id, task_payload): agent = build_agent_for_publish() try: result = agent.run(task_payload) return {"status": "done", "result": result} except AgentLoopError as exc: self.retry(exc=exc, countdown=60)

注意 Celery 的 max_retries 和 Agent 内部的 max_turns 是两个独立的熔断点。前者管任务级故障，后者管循环失控，缺一个都可能让任务卡死。工具注册时，我给发布工具加上了 permission 字段，默认要求人工确认，这正是第四章里讲的权限边界落地。

@tool_registry.register( name="publish_post", description="将已经通过审核的草稿发布到目标平台", schema={ "type": "object", "properties": { "draft_id": {"type": "string", "description": "已审核草稿 ID"} }, "required": ["draft_id"] }, permission="human_confirm_required" ) def publish_post(draft_id): return content_api.publish(draft_id)

这个工具强依赖前置的审核动作，Agent 拿不到审核通过的草稿 ID，就无法执行发布。把业务约束直接编码进工具的参数和权限里，比在提示词里反复叮嘱“一定要先审核”可靠得多。

4.4 部署、幂等和权限配置

部署环节我建议用 Docker 打包，至少把三个环境变量暴露出来：AGENT_MAX_TURNS 控制循环次数，AGENT_TOKEN_BUDGET 控制单任务 Token 预算，AGENT_MODEL 控制模型名。这样上线后不用改代码就能调整 Agent 的行为。

幂等设计是这个场景最容易踩的坑。Agent 循环有重试机制，模型在工具调用失败后可能会用相同的参数重试同一个发布操作，如果发布接口不幂等，就会出现一条内容被发布两次的事故。解决办法是给每个任务生成唯一的 request_id，发布工具执行前先检查本次操作是否已经处理过，处理过就直接返回上一次的结果。幂等键是大模型时代最基础的工程保障，宁可多写几行代码，也要堵住重复执行的漏洞。

权限配置上，发布工具建议做成“只申请草稿-发布权限，不持有素材修改权限”。Agent 一旦拥有过大的权限边界，一次工具调用出错就可能造成越权操作。测试环境默认把权限设为 all_deny，需要哪个工具开放就往白名单里加，比默认全放再补救要安全得多。

5. 常见问题与排查技巧实录

5.1 Token 爆炸、上下文污染，怎么排查

Agent 跑着跑着，单次请求的 Token 数突然涨得很高，这是最常见的故障之一。排查思路分两步：先看是历史累积导致的，还是工具描述过大导致的。打开 trace 日志，看最后一次模型请求的 Token 明细，如果历史消息占了大头，就是记忆策略没生效；如果系统提示和工具描述占了大头，就是工具集设计得太臃肿。

上下文污染的典型表现是：Agent 在后面的步骤里引用了前面步骤里的旧数据，导致决策错误。比如它明明已经在第二步刷新了库存数据，却在第五步引用了第一步的旧库存来生成报表。对策是给关键步骤打“数据版本标签”，每次工具返回数据时带上时间戳，模型推理时优先采用版本最新的数据。这个规则最好写进系统提示词，并在工具返回值里格式化好，两条腿走路才稳。

Token 相关的问题，我的排查顺序永远是：先看 observer 的聚合统计，再看单次 trace 的明细，最后才去看模型输出内容。顺着数据找问题，不要靠猜。

5.2 工具调用失败与循环卡死

模型输出了不合法的 JSON 参数，导致工具解析失败，这是 Agent 开发初期最频繁的错误。不少团队的做法是让模型重试一次，但模型往往会在同一个地方犯同样的错。更可靠的做法是三层防护：第一层，代码里做 JSON Schema 校验，不合法就直接返回结构化错误给模型，而不是抛异常；第二层，写一个小的修复器，对常见的 JSON 格式问题做正则级修补；第三层，连续失败超过两次就触发人工处理或切换到备选工具。

循环卡死又是另一种局面。Agent 在同一个工具调用上反复循环，每次结果都差不多，但始终不进入下一步。这通常是因为工具返回的错误信息不够明确，模型看不懂为什么失败，只能尝试同样的操作。解决方法是让工具返回错误时带上“失败原因和建议的替代步骤”，给模型一个明确的转向信号。同时配合 max_turns 熔断，避免无限烧钱。

排查这类问题有个技巧：把 Agent 的每次循环输入输出按 turn 打印出来。循环卡死时，对比前后两个 turn 的模型思考逻辑，一眼就能看出它在哪个环节转圈，然后针对性优化工具返回信息。

5.3 Agent 黑盒问题的调试方法

Agent 不像普通接口，输入输出中间隔着一长串推理和工具调用过程，出了问题很难复现。我的调试习惯是三层定位法。第一层看 trace_id 对应的全链路日志，确认是模型问题、工具问题还是编排问题。第二层做输入回放，把某个任务的历史消息序列完整保存下来，再让模型按相同输入重新推理，比较输出是否稳定。第三层才是改提示词或调参数。

这里要特别强调 trace 的颗粒度。每一轮循环不仅要记录模型返回的最终文本，还要记录模型思考过程中的工具调用意图、工具入参、工具返回结果、Token 消耗、耗时。信息越全，回放时越能还原现场。我见过一套只记录最终结果的日志系统，出了问题只能看到“Agent 失败”，完全没法定位，这种日志没有价值。

实践里我还会在每个任务的内部循环里埋一个“检查点”，每完成三个关键步骤就固化一次状态到数据库。这样即使任务中途崩溃，也能从最近的检查点恢复，不需要整个任务重跑。Agent 的恢复能力和可观测性，是它能否长期在业务里稳定运行的决定因素。

6. 关于工程实现的几点私货

我一直觉得 Agent 工程实现里，真正的难点不在“让模型更聪明”，而在“让系统更闭环”。七要素里的规划、记忆、反思，每一项都是工程问题；七个决策点里的成本、权限、可观测性，每一项都决定系统能不能长期存活。模型可以换，框架可以换，但环没闭合，Agent 就只是个华丽的函数而已。

最后分享一个我亲身验证过的小技巧：每准备给 Agent 加一个新工具，先做一次“工具调用成本预算”。数一数这个工具的描述要占多少 Token，预计会被调用多少次，错误率大概多少，需要几分钟人工兜底。算完这笔账，你会自然而然地把工具描述写短、把权限边界收紧、把异常分支补齐。这一步，比任何架构理论都更能让你做出健壮的 Agent。