1. 先交代背景：这个 Agent 项目是怎么来的，以及前两周踩的认知坑
去年年中我接到一个任务，要给内部业务做一个能自动处理工单的 Agent。当时团队里没有一个正经写过 Agent 的，我们以为这跟写个接口差不多：调大模型，让它按 JSON 输出，然后执行函数。结果第一版跑了一周就废了——模型经常答非所问、上下文越来越长、工具调用偶发报错，最离谱的一次，一个循环任务愣是让 Agent 来回跑了二十几分钟才被我们手动停掉。
从那次之后我开始认真梳理这件事。前前后后做了三个不同方向的 Agent 项目，一个面向工单自动流转，一个做数据分析问答，还有一个做内网资源调度。做到第二个项目时，我发现很多问题和解法是重复的，于是抽了一个晚上把我当时踩过的坑整理了一遍，提炼出 14 个设计决策。这 14 个决策不是什么高深理论，都是我自己实打实调过 bug、改过架构之后总结出来的东西。第三个项目落地时，我把这些决策固化成了一个通用内核，后面所有新 Agent 项目都能在上面快速搭起来。
1.1 第一周犯的最蠢的错误：把 Agent 当成一个函数来写
老手一看就懂，但当时我们是真的踩了。我们把整个 Agent 流程写成了run(input) -> output的函数，状态存在内存里，工具调用直接进程内执行。Demo 跑得非常顺，因为测试用例都是设计好的，模型只要按部就班调用两三个工具就能成功。但一放到真实环境就暴露了：用户的问题是多变的，Agent 需要来回试、需要推理失败路径、需要中间状态可恢复，而进程内实现天然不具备这些能力。
这个教训后来变成了决策一的核心依据：Agent 不能当函数写，必须当有状态的服务写。哪怕第一版很简单，状态、事件、日志的出口也得独立出来，否则后面排查问题极其痛苦。
1.2 看到热搜词“Agent 架构”搜出来的东西有多乱
那段时间我去搜“Agent 架构”，能搜出来一堆框架对比、路线图、万字长文，但真正解决我问题的内容很少。LangChain、Dify、CrewAI 这些大框架各有各的抽象，概念术语满天飞。我不是说它们不好，而是说，对于一个不知道自己要什么的新手来说，上来就选框架其实更累。我当时做了一个选择：不依赖任何重型框架，自己用一个非常薄的调度内核。事实证明这个选择让我在后面迭代时几乎没被框架锁死过。热搜词里的“Agent 框架与编排”那一类内容，大多是介绍编排工具，真正靠谱的编排往往是你自己写的那几十行核心循环。
2. 14 个设计决策（上）：内核骨架的八个关键决定
这一节我按当时的决策顺序来讲，尽可能还原当时的思考场景。你会看到有些决策看起来特别简单，但背后对应的坑非常深。
2.1 决策一：消息协议先行，而不是函数签名先行
第一版系统里，工具之间的信息传递用的是 Python 函数返回字典，Agent 和大模型之间的对话用的是字符串。问题就出在两个接口没有统一，模型调工具时经常会说"我需要查一下订单数据，调 get_order 接口"，但工具执行后返回的格式和模型理解的不一致，导致模型经常胡编字段名。
后来我把所有交互统一定义成一类消息格式：一条消息必须有type、sender、recipient、payload这四个字段，像信封一样套着走。大模型的输出、工具的返回值、系统内部的事件，全部都转换成这个消息格式。这算是我 14 个决策里最基础、也最受益的一个。
{ "type": "function_call", "sender": "agent.pm", "recipient": "tool.order", "message_id": "msg_8382aa", "payload": { "function_name": "get_order", "arguments": {"order_id": "ORD-2024-0014"} } }内核内置一个消息路由，根据recipient把消息丢给对应模块。这个设计后来让日志排查简单了很多：整个系统的运行过程就是一条消息链，每一环都有据可查。前期多花半天写消息规范，后面省了无数的联调时间。
2.2 决策二：状态必须外置，且可恢复
前面我提过，第一版把状态存在内存里，进程一重启就没救了。这个坑在真实项目里表现得非常一致：Agent 跑一个多步骤任务，跑到第五步挂了，前面四步全部作废。你必须让 Agent 支持断点续跑，否则哪怕只是发布代码重启了一下，正在跑的业务就断了。
实现上不要自己去啃复杂的状态机，我用的就是一个state.db（SQLite 就够），里面存三张表：session（会话概要）、context（期间上下文快照）、checkpoint（步骤执行记录）。Agent 每执行完一个原子步骤就写一条 checkpoint，重启时读取最近一个 checkpoint 继续跑。
2.3 决策三：沙箱隔离不要等出事故再补
“沙箱”这两个字在热搜词里出现了很多次，但当年我是付出了钱和时间代价的。当时写了一个脚本 Agent，它需要执行一段 Python 代码处理数据。开发时我以为只是做数据清洗，结果有一次模型生成的正则表达式里出了问题，直接把一个临时目录的旧文件误删了一部分。幸亏删的只是测试数据，但那次之后，我立了一个铁律：凡是 Agent 要执行的任何外部代码，一律放到沙箱里。
沙箱我用的是 Docker 加docker run --network none --read-only，底层镜像只有一个最小 Python 环境。你要执行代码，先写好脚本文件，然后挂载进容器，跑完拿走输出。网络直接禁掉，只留 stdout 和文件输出。模型生成代码我再信任，也不直接在本机跑。真出过事就知道，这一步不能省。
2.4 决策四：记忆分两层，不要试图把全部历史塞进上下文
做 Agent 的都知道，上下文窗口有上限，但很多人还是一股脑把所有对话历史往里面塞。我试过，在上下文超过窗口大小之后，模型的表现会急剧下滑，它开始忘掉前面的指令，甚至开始重复之前的工具调用。这个现象，做 agent 的同学应该都见过，就跟 RPC 报错很像，不是你两端都有 bug，而是中间有个东西在磨损。
我的方案是两层记忆：
- 短期记忆：最近 N 条消息，保留完整原文。
- 长期记忆：把超过阈值的历史消息用一次摘要模型压缩成结构化摘要，存向量库，需要时按相关性检索。
要注意，摘要不是简单把内容“概括”就行。我让摘要模型按固定维度输出：已完成步骤、当前目标、未决事项、用户偏好、环境限制。这个结构化摘要很有用，关键字匹配和向量相似度都能直接命中。比如用户曾经说过“以后订单报表不用带支付渠道”，这条偏好会被摘要归纳进“用户偏好”字段，后续 Agent 在生成 SQL 时能自动避坑。
2.5 决策五：工具注册表一定要带参数 Schema 校验
大部分 Agent 框架都允许你注册函数，然后在模型调用时把函数的 description 塞给模型。但我发现很多项目的问题恰好出在没有对模型生成的参数做严校验。模型可能把订单日期写成"2024-13-40"，也可能把金额传成字符串，如果你直接把这个参数填进 SQL 或 HTTP 请求里，后端一定会报错。
我在内核里搞了一个工具注册表，每个工具声明自己的参数 JSON Schema。模型调用工具时，先走一遍 JSON Schema 校验，不合法就返回一条invalid_arguments消息，模型看到后会重新生成参数。这个设计表面上是给模型添麻烦，实际是帮模型尽早认清错误。用jsonschema库实现非常快，一个装饰器的事。
@tool_registry.register( name="create_order_note", description="为订单添加一条内部备注", schema={ "type": "object", "properties": { "order_id": {"type": "string", "pattern": "^ORD-[0-9]+$"}, "note": {"type": "string", "maxLength": 500} }, "required": ["order_id", "note"] } ) def create_order_note(order_id: str, note: str): ...2.6 决策六：编排器与执行器分离，不要让一个 Prompt 干所有事
做 Agent 的人容易陷入一个误区：希望用一个大 Prompt 让模型自己完成“理解→拆解→执行→归纳”。我试过，像“你是一个智能助理”这种大而全的玩法，在 10 步以内的简单任务上确实能跑，但只要任务复杂度上来就必崩。原因是模型的注意力被分散了，它一边要推理任务路径，一边要生成工具参数，一边还要记住用户要求，三个目标互相争抢。
所以我把 Agent 分成两层：
- 编排层（Planner）：负责把用户请求拆解成子任务清单，只关心“下一步做什么”，不关心每步怎么做。
- 执行层（Executor）：负责跑具体的子任务，只关心“这一步怎么调到工具”，不关心全局路径。
编排层调用模型时，上下文里包含任务目标、当前子任务列表、已完步骤，没有工具调用的细节；执行层调用模型时，上下文里包含当前子任务的详细要求、相关工具说明，没有任务全局信息。分开之后，两者的准确率都明显提升。
2.7 决策七：循环上限不是拍脑袋定的，是根据工具耗时的量级算的
先给一个真实数据：我最早发现 Agent 卡在循环里，是它反复尝试失败的工具调用，每次重试间隔 2 秒，结果 20 多次都不成功。原因不是模型蠢，是业务接口当时在升级返回了 503，模型一直以为是自己参数传得不对，于是一遍遍微调重试。
我后来给内核设计了两个约束：
- 单轮能力上限：单个子任务最多执行 K 次工具调用，超了就上报失败。
- 总执行预算：整场会话最多执行 M 次工具调用，超了就触发终止。
K 和 M 的取值依赖工具平均耗时。如果工具平均耗时 5 秒，K 设为 8，M 设为 40，差不多是 5 分钟级别的预算；如果是慢工具，预算还要往下调。宁可让任务失败并告知用户，也别让它空转浪费钱和时间。
2.8 决策八：高风险操作必须人审，不能只依赖模型的“自我判断”
很多 Agent 设计文章会强调“给模型加一些安全规则”，听起来很对，但实在太天真。模型不是不遵守规则，而是在复杂的工具环境里，它经常会错误地判断“这个操作是否有风险”。有一次模型为了查询一个订单的状态，打算调用“删除测试数据”接口——它认为该接口能返回更全的订单信息。逻辑上看，这当然是个安全错误，但模型就是把“删除”和“测试数据”组合到了同一个工具调用里。
从那以后，凡是有写操作、有删除操作、有高于一定金额的转账类操作，内核都会强行插入一步human_confirmation。模型必须先输出要执行的操作内容，系统挂起，等审核人在后台点“允许”或“拒绝”。这个机制在业务端看起来会慢一些，但保住了系统的底线。
3. 14 个设计决策（下）：运行期才会遇到的六个真问题
前面八个决策是在开发、联调阶段就能想清楚的。接下来六个是我把 Agent 放到线上，让它长期跑业务时踩出来的，每一个都伴随过诡异的现象。
3.1 决策九：完整轨迹必须可回放，日志要按“事件流”而不是按“文本段”记录
第一版系统里，我把 Agent 的每一步记录成一段文本，类似18:02:03 Agent 调用了工具 get_order，看起来清晰，但一旦要调试某个问题，你就得靠眼睛去翻文本，翻得头大。后来我改成把每一步记录成结构化事件流，每一条是一个事件对象，包含step、message_id、parent_id、type、duration_ms、token_cost、prompt_summary。
回放时按parent_id排序，就可以把一次 Agent 的运行过程重演一遍。最实用的功能是“看模型在某一步看到了什么上下文”。比如用户投诉 Agent 结果不对，我可以直接定位到出错的步骤，把那一刻的 prompt 和模型输出调出来，看清楚是上下文遗漏，还是参数错误，还是模型本身判断失误。排障效率至少提升三倍。
3.2 决策十：模型调用可靠性比模型聪明更重要，重试要分层
大模型接口在我实际使用中，隔三差五会出现超时、5xx、连接中断，这个比模型答错还讨厌，因为它会卡住整个任务流。我在内核里做了一套三级重试：
- 第一级：直接重试一次，间隔 1 秒。
- 第二级：指数退避重试，间隔 2 秒、4 秒、8 秒，最多三次。
- 第三级：切换备用模型或备用部署点，用另一个供应商的同等级模型顶一次。
热词里有一条“ai agent token 是什么意思”，我觉得背后其实是个成本问题。每次重试都会消耗 token，第三级切换模型更是可能让 token 费用翻倍，所以要给每一层重试加上限额，不能无限重。我实际跑下来，80% 的接口故障在第二级重试内就能恢复，第三级很少触发，但一旦触发，就值得加一条报警。
3.3 决策十一：上下文压缩不是按“窗口大小倒推”，而是按“信息密度”压缩
我知道很多项目会在上下文达到 80% 的时候，简单粗暴地把最老的消息裁掉。这个做法问题很大，因为最老的消息里往往包含用户最初的需求偏好，裁掉之后再跑几轮，模型可能就忘了用户到底要什么。
我给内核加了个“压缩器”：它不是按时间删，而是先把消息集合做一次语义压缩。关键是压缩时保留四类信息：用户的人设性指令（如“不要解释，直接给结论”）、里程碑指令（如“这个项目优先级是 P0，三天内必须交付”）、未关闭的疑问、未完成步骤。压缩后的摘要 + 最近 20 条消息一起构成新的上下文。实测这个方案能让会话时长从原本只能支撑 20 轮延长到 60 轮左右，模型的真实可用程度没有明显下降。
3.4 决策十二：工具失败不能只重试，要告诉模型“失败在哪一步、为什么失败”
第一版里，工具失败就是抛一个异常字符串，比如Exception: DB connection error。模型拿到这个异常，只会尝试换个参数再调。后来我发现更好的做法是把失败结构化：返回给模型的消息里要包含failed_tool、error_code、error_message、suggestion。
举个例子：
{ "type": "tool_error", "payload": { "failed_tool": "query_database", "error_code": "DB_TIMEOUT", "error_message": "查询超过3秒未返回", "suggestion": "给查询增加LIMIT 10，或改用count先确认数据量" } }模型看到 suggestion 后，往往能主动调整策略而不是死磕同一个参数。这个设计本质上不是让模型更聪明，而是给它更好的“反馈信号”。
3.5 决策十三：测试要“造失败”，不能只测“顺利路径”
这一点我一定要强调，因为绝大多数从零做 Agent 的人都会吃亏。大家写测试用例时，下意识都是测试正常流程：输入一个合法问题，Agent 顺利调用工具得到答案。这当然重要，但更该测的是各种失败路径：工具返回空数据时 Agent 会不会瞎编？模型连续两次调用参数不合法时会不会循环？用户中途改需求怎么办？上下文快写满了怎么办？
我在内核里做了一个“失败注入测试”机制，类似模拟故障演练。固定场景：工具接口返回 500、工具超时、数据库锁、模型生成 JSON 违规。每次发版前跑一遍这些场景，有了这套回归测试，我才敢大规模切换模型参数。没做这套之前，每次调一个 prompt 都心惊胆战。
3.6 决策十四：配置与代码分离，不同环境的 Agent 行为可以不同
最后一个决策看着简单，但实操中特别容易被人忽略。Agent 的 prompt、工具白名单、上下文阈值、沙箱镜像版本、模型参数这些配置，如果有人写死在代码里，那每换一个环境就得改一遍代码，极其容易出问题。我把这些全部收进一份 YAML 配置文件，内核启动时读取。这样同一个内核，在 dev 环境可以放开调试日志、在 staging 环境可以用测试工具、在 prod 环境才挂上正式供应链工具。
配置和代码分离还有一个好处：产品经理不需要懂代码，也能根据业务需要调 prompt、调工具开关。后期团队扩张时，这个让协作顺畅很多。
4. 通用内核为什么会“通用”：封装边界与注册机制
做完第三个项目后我回头看，发现第一个项目里我写的 80% 代码，在第二个和第三个项目里都在重复。既然重复，那就干脆抽成一个通用内核。所谓“通用”，并不是一个无所不包的框架，而是边界非常清晰的五个组件。
- 消息总线：任何模块之间的通信都走消息信封。
- 工具注册中心：按 Schema 注册、校验、路由工具调用。
- 状态管理：统一管理 session、context、checkpoint。
- 上下文工程：短期记忆、长期摘要向量库、压缩器。
- 安全与预算：沙箱、人审闸口、重试、上限预算。
4.1 内核的接口设计：只暴露两类核心 API
我刻意把内核的对外 API 收敛成两个面：agent.serve()和agent.register_tool()。前者启动一个 Agent 实例并监听消息循环，后者把工具变成可被 Agent 调用的资源。
from atk_agent_core import Agent from tools.order_tools import create_order_note, get_order_info from tools.approval_tools import ask_for_approval agent = Agent( name="order_agent", config="configs/order_agent.yaml", model="gpt-4o-mini", ) agent.register_tool(get_order_info) agent.register_tool(create_order_note) agent.register_tool(ask_for_approval) agent.serve()这段代码只有十几行，但它能跑起来一个真正可用的 Agent，原因就在于所有复杂的决策逻辑（记忆压缩、失败反馈、预算控制、沙箱执行、日志回放）都已经在内核里实现了。接入新业务时，你要做的只是写自己的工具函数，然后注册进去。
4.2 为什么我不把所有工具都拿到内核里“统一实现”
这是我被问得最多的一个问题。明明工具注册中心这么方便，为什么不把订单、库存、翻译、OCR 这些通用能力都统一做好？
原因很简单：工具是业务的，内核是通用的。如果我把订单工具写进内核，那这个内核就对“订单”有了莫名的亲和性，换到别的项目时就会胶着。内核里只有“工具被调用的机制”，没有“工具本身”。这种边界上的克制，是通用性的真正来源。
5. 四种复利，复的是什么：从复用中真正拿到的东西
这一节回应标题里“四种复利”的部分。所谓复利，不是一个金融概念，而是说，我把内核建好之后，每做一个新项目，它不是从零开始，而是踩在我的既有经验上起跳。主要体现在四个方面。
5.1 代码复利：每新项目少写 60% 以上的基建代码
第一个项目里，光消息路由、状态持久化、上下文压缩、工具调用校验这些基建代码，我自己写了大概 4000 多行。到第二个项目，这些注册进去就行。到第三个项目，新增代码里大概只剩两类：新的工具函数和新的配置 YAML。
最直观的数字是：第一个 Agent 项目从立项到可用花了大约 6 周，第二个缩短到 2 周，第三个 5 天跑通 POC。不是因为我手速变快了，而是那些容易出问题的地方全被内核兜住了。
5.2 认知复利：团队新成员入职第三周就能独立接 Agent 项目
传统 Agent 项目新成员要学的东西很杂：模型调优、工具链、提示词、状态设计、安全控制。而用这个内核，新成员只需要理解“消息信封”和“工具 Schema”两个概念，就能独立开发新的工具并接入项目。这不是我吹，内部分别入职了两个同事做 Agent 需求，都用不到一个月就上手交付了。
原因是内核把复杂的逻辑黑盒化了，然后把需要人接触的部分收敛到极小。人只要会写业务工具函数、会调注册接口，剩下的事内核接管。
5.3 资产复利：日志、测试用例、调参经验是越攒越值钱的
日志和测试用例这些资产，在单次项目里可能只是“工程文件”，但沉淀下来就成了下一轮的调参素材。我之前说过，我搞了一套失败注入测试，这套测试从一个 Agent 扩展到全部 Agent。任何一次修改如果导致某个项目测试失败，我会立刻知道。
还有调参经验也是复利的。比如什么场景下应该把温度调到 0.1、什么场景下不要给模型主动发送“你是一名精准助手”这种大而空的提示，这些经验都固化在配置文件的注释里，后面的人不用重新踩。
5.4 业务复利：需求响应速度变快，团队能做的新业务变多
最后一点是给管理者看的。做完了通用内核之后，我们团队对外承接 Agent 需求的能力显著提高。以前一个客户提一个流程自动化的需求，我们要评估“能不能做”，现在往往直接评估“做出来要多久、需要订哪些工具”。需求响应快了，客户体验自然就上去了。
而且因为这些 Agent 共享同一套运维监控和日志规范，维护成本是分摊的。跑 5 个 Agent 和跑 10 个 Agent，新增的运维压力远比想象中少。这种业务上的复利，是通用内核最直接的红利。
6. 可以复制的落地路线：如果你的项目也要从零做 Agent
写到这里，估计很多人已经在想，自己团队如果也打算从零搞 Agent，该怎么迈出第一步。我会建议按这个顺序推进，而不是一上来就冲去买框架或者抄别人的架构。
6.1 第一步：先写一个 200 行的硬编码流程，不调任何大模型
不要直接上 Agent，先用最死板的规则把流程跑起来。比如你要做一个工单分类工具，先用 if-else 加关键词匹配，让它能对一小批合规则的数据工作。这一步的目的不是交付，而是让你把你的业务流程吃透：有哪些输入、哪些步骤、哪些输出、哪些分支需要决策。
6.2 第二步：把决策点替换成模型调用
业务已经盘清楚了，就把那些真正需要动态决策的节点替换成模型调用。比如说，关键词匹配无法覆盖的工单分类，在这个节点交给模型。替换之后做一次小批量真实数据回放，把准确率、速度、成本都记下来。这一步的作用是验证大模型在你的场景里到底行不行。
6.3 第三步：引入工具注册表和消息信封
模型能决策之后，开始接入工具。我当时是先写了一个极简的消息循环，然后注册两个工具，一个查数据一个写备注，跑通一个完整闭环。先不要做状态持久化、不要做沙箱、不要做记忆压缩。做得越简单越好，因为这一版的目的是打通链路，任何一步出错你都好定位。
6.4 第四步：逐步补齐可靠性组件
链路通了，再开始按优先级补组件。我的建议顺序是：先补状态外置，因为断点续跑是一切稳定性的基础；再补工具 Schema 校验，因为我们踩过参数错误的坑；再补预算控制和循环上限；最后再考虑沙箱。沙箱虽然重要，但对内网数据类 Agent 来说，优先级可以往后放一点，先把功能跑对。
6.5 第五步：跑通一个全流程后再考虑通用内核
如果你同时要接三五个业务，这时候抽通用内核才有价值。只做一个业务就急着造内核，很容易抽象过度，把不存在的问题也抽象进去了。我的经验是，至少做过两个不同场景的 Agent 后，再回头抽公共部分，那抽出来的东西才是真正能沉淀的。
7. 最后再分享两个容易被忽略的小经验
一个是给 Agent 的每一项工具调用都绑定一个最小权限原则。很多工具接口权限很大，比如“查询订单”可以查所有状态，“生成报表”可以导出全量数据。如果 Agent 直接调这些原生接口，安全风险极高。我建议在每个工具函数里做一层“权限裁剪”，模型只能看到它业务上最需要的那部分字段。
第二个是要给 Agent 的运行轨迹加一个“人性化回放界面”。排查一个问题时，能直观看到模型每一步在想什么、为什么选这个工具，比看一百行 JSON 日志快得多。我后来基于事件流做了一版简单的 Web 回放，前端加一个时间轴就够，但对团队效率的提升非常明显。
从零做 Agent 没有捷径，但是很多坑前人已经踩过了。希望我这份 14 个设计决策的总结，能帮你少走一段我走过的弯路。
