简介《Building Applications with AI Agents》是OReilly Media出版的PDF电子书面向有软件开发基础、想掌握智能代理与多代理系统设计的开发者内容兼顾原理与落地。资源包为单个PDF文件体积仅558KB轻量便携无需解压即可直接阅读目前已有436人学习下载。作为早期发布版本书中公开了技能与编排章节围绕代理技能、任务编排、环境感知与决策机制展开并结合自动化服务、智能调度、网络安全等场景介绍多代理协作方法。同时保留完整目录框架可预览记忆、监控、保护等未发布章节帮助读者把握全书知识脉络。书中还涉及开源许可与知识产权合规说明提醒实践者使用代码示例时遵守相关规定对于想在正式版发布前提前熟悉智能代理开发思路的读者是一份实用性较强的参考资料。1. Building Applications with AI Agents从“自动回复”到“自动执行”的关键一跃收到标题为 Building Applications with AI Agents 这类的技术资料我习惯先把一件事想清楚AI Agent 应用和我平时写的接口加提示词程序到底差在哪。早期我做过不少“看起来像智能体”的东西——用户说一句模型答一句顶多套个检索再拼进提示词。那本质上仍是请求响应模式模型没有目标、没有工具、没有试错回路遇到需要多步操作的任务就原形毕露。真正值得按 Agent 思路构建的应用应该具备三个特征能自主拆解目标能调用外部工具获取新信息能根据执行结果决定下一步动作。它适合的任务域也很明确流程不确定、需要查证或操作外部系统、单次提示词无法覆盖全部路径的场景。如果你只是做问答、摘要、文本改写那用普通提示词流程反而更省。这篇文章会把这类应用的架构选型、最小可复现实现、参数设置和踩坑经验完整拆一遍新手能照着落代码熟手可以跳过基础部分直接看参数和边界。2. 智能体应用的核心架构先从“规划-执行”循环说起2.1 规划器-执行器模式拆开“思考”和“行动”反而更可控我最早做 Agent 时犯过一个典型错误在一个提示词里塞满所有约束希望模型一次性输出“完整的执行计划加最终答案”。结果模型经常在计划里写得头头是道执行层面完全对不上号。后来我意识到生产可用的 Agent 几乎都跑在一个循环上模型先基于当前状态推理决定调用哪个工具拿到工具结果后再推理如此往复直到能给出最终答案。这个模式常被称为规划器-执行器循环也叫 ReAct 式思考核心是把“思考”和“行动”拆成交替的两个步骤。为什么拆开反而更可控因为模型每次只做两件事根据上下文决定下一步动作或者给出最终答复。这个决策面的缩小显著降低了提示词互相打架的概率。另一个好处是可观测性。在循环的每一轮你都能记录“模型选了哪个工具、传了什么参数、工具返回了什么”事后排查时能把完整的事件链拉出来回放。相比之下让模型一口气输出计划加执行结果你只能看到最终答案中间错了也不知道错在哪一步。规划器和执行器的职责边界也需要提前划清。我的习惯是规划器只负责工具选择和参数生成不负责直接拼最终答案执行器只负责真实调用工具并返回结构化结果不替模型做判断。举个常见例子用户要求“查一下某股票当前价格并判断是否值得买入”。规划器会先后选择查询价格工具和查询财务指标工具执行器把两次的真实返回数据交给模型模型在拿到全部数据后才生成判断。如果让模型在没拿到数据前就编一个“建议买入”那这个 Agent 就退化成纯吹牛应用了。2.2 工具层的边界策略哪些能力不该交给智能体工具是 Agent 能力的边界也是最大的风险源。同样的模型推理能力接一个只读查询工具和接一个可写删除工具生产风险完全不在一个量级。我一般按三层安检来定义工具边界参数校验、权限校验、返回校验。任何工具在被模型调用前必须先过这三关。参数校验解决的是“模型传错参数”的问题。模型生成工具参数时偶尔会搞错字段类型或遗漏必填项工具端必须做严格校验而不是直接透传给底层服务。权限校验解决的是“模型越权”的问题。读类操作可以放开写类操作必须加管控常见的做法是写操作走人工审批通道。返回校验解决的是“工具结果污染上下文”的问题。工具返回原始数据经常带着大量无用字段直接塞回上下文容易干扰后续推理我一般会先把返回裁剪成精简结构再回传。还有个容易被新手忽略的边界不要让 Agent 直接操作数据库或操作系统。工具层的设计原则是把原子能力封装成“模型能理解、结果能被验证”的服务接口。例如一个发送通知的工具输入是接收人、标题、正文返回是发送状态而不是让模型去拼 SQL 或执行 Shell 命令。封装得越干净后续做权限控制、审计、评测就越简单。工具数量也不是越多越好模型在十几个工具里做选择时准确率会明显下降我一般控制在一个智能体核心工具不超过 10 个超过就考虑拆子智能体。3. 跑通最小可复现的智能体应用核心循环和状态管理3.1 最小决策循环用工具调用封装模型的每一步选择这里给出一个最简但完整可运行的 Agent 循环骨架。它不去依赖任何特定框架只用一个支持工具调用的模型接口核心逻辑不到五十行方便你理解每一步在干什么。实际生产时再替换成你所在团队统一封装好的客户端。# agent_core.py import json MAX_STEPS 8 # 最大循环轮数防止死循环 # 定义暴露给模型的工具清单 TOOLS_SCHEMA [ { name: query_product_stock, description: 查询某个商品的实时库存。, parameters: { type: object, properties: { sku_id: {type: string, description: 商品编码} }, required: [sku_id] } }, { name: submit_order, description: 提交订单生成订单号。, parameters: { type: object, properties: { sku_id: {type: string}, quantity: {type: integer} }, required: [sku_id, quantity] } } ] def call_model(history, tools): # 调用具备工具调用能力的模型服务 # 返回结构统一为 # {type: tool_call, name: 工具名, arguments: {...}} # 或 {type: final, content: 给用户的最终回答} # 不同模型服务的返回格式有差异这里做一次适配 response your_model_client.chat(history, toolstools) return response def execute_tool(name, arguments): 工具执行层校验参数、执行、裁剪返回结果 if name query_product_stock: # 实际开发中替换为真实库存服务调用 raw {sku_id: arguments.get(sku_id), stock: 25, unit: 件} return {sku_id: raw[sku_id], stock: raw[stock]} # 裁剪无用字段 if name submit_order: # 写操作类工具生产环境需过人工审批 return {order_id: SO2025001, status: created} return {error: funknown tool: {name}} def run_agent(user_request): history [{role: user, content: user_request}] for step in range(MAX_STEPS): reply call_model(history, TOOLS_SCHEMA) if reply[type] tool_call: # 记录模型选择方便追踪 print(f[step {step}] call {reply[name]}({reply[arguments]})) observation execute_tool(reply[name], reply[arguments]) history.append({role: assistant, content: f调用工具{reply[name]}}) history.append({role: tool, name: reply[name], content: json.dumps(observation, ensure_asciiFalse)}) else: return reply[content] return 已达到最大执行轮数未能完成用户请求。 if __name__ __main__: print(run_agent(查询 SKU10023 的库存如果大于 10 件就提交一个数量为 2 的订单))这段代码的核心设计有三个。第一个是MAX_STEPS上限这是防死循环的保底手段任何 Agent 循环都不能没有这个数。第二个是工具执行层execute_tool与模型调用层分离模型只负责决策工具和参数真实调用永远走固定函数参数校验和结果裁剪都在这一层做。第三个是history里同时保存模型发言和工具返回每轮循环模型都能看到“自己做过什么、结果是什么”。注意工具返回被json.dumps序列化后以tool角色加入对话这符合多数模型服务对工具调用的格式要求。3.2 记忆与状态管理不让 Agent 在第五轮突然失忆最小循环跑通后你很快会遇到一个分水岭上下文窗口被工具返回撑爆。每轮工具调用都会往历史里追加内容五轮之后可能就已经塞了几千 token再往后模型要么忽略早期信息要么直接报超长错误。我处理这个问题的办法是分层记忆把对话历史分成固定短期窗口、滚动摘要和持久业务状态三部分。# memory_manager.py from collections import deque class AgentMemory: def __init__(self, max_recent_messages10): self.recent deque(maxlenmax_recent_messages) # 最近消息窗口 self.summary # 早期消息的滚动摘要 self.biz_state {} # 业务状态不喂给模型 def push(self, message): self.recent.append(message) def compact(self, lmm_conversation): 当 recent 接近窗口上限时把最早的若干轮压成摘要 overflow list(self.recent)[:-4] # 保留最近4条原始消息 self.recent deque(list(self.recent)[-4:], maxlenself.recent.maxlen) if overflow: segment \n.join(f{m[role]}: {m[content]} for m in overflow) self.summary your_llm_summarize(self.summary \n segment) def build_prompt_state(self): 把记忆拼装成传给模型的状态 state [] if self.summary: state.append({role: system, content: f历史摘要{self.summary}}) state.extend(list(self.recent)) return state这里的关键是把“模型上下文”和“业务状态”分开。业务状态如订单号、用户身份、权限等级不应该反复让模型记忆而是放在biz_state里由代码维护需要时再注入提示词。我在生产里见过很多翻车现场都是因为把状态全部堆给模型模型在长对话后开始混淆数据甚至把 A 订单的信息回答到 B 订单上。防止失忆的第一准则凡是代码能存的状态绝不让模型替你在上下文里记。滚动摘要的触发时机也值得注意。我一般不在每次 push 后立即压缩而是当 recent 队列即将溢出时才做一次摘要本身用独立的一次总结调用生成不占用主对话循环的 token 预算。这个频率既控制了成本又避免每轮都做摘要导致上下文结构频繁变化。还要给摘要加上时间标记比如“截至第 6 轮的状态摘要”避免模型把历史摘要当成当前现实。3.3 从单智能体到多智能体用路由替代硬编码调度当业务方开始要求“一个助手既能查物流、又能走售后、还能做数据分析”时很多人第一反应是把所有工具全塞给一个 Agent。我的经验是工具超过十几个模型选择准确率就会显著下滑这时候该考虑拆多智能体用路由层分派任务。# router.py def route_to_agent(user_message): 基于意图分类把消息分发给对应子智能体 prompt f 你是一个任务路由员。根据用户的第一轮请求判断该交给哪个专职智能体。 可选智能体 - aftersale_agent退货、退款、维修、投诉 - logistics_agent查物流、修改配送地址、预约配送时间 - analysis_agent销售数据分析、趋势报表、异常指标归因 只输出智能体名称不要输出任何解释。 用户请求{user_message} route_name call_router_model(prompt).strip() if route_name not in [aftersale_agent, logistics_agent, analysis_agent]: return default_agent return route_name # 各智能体内部仍然跑 3.1 的最小循环只是工具清单不同 agents { aftersale_agent: build_agent(tools[create_return_order, query_refund_status]), logistics_agent: build_agent(tools[query_express, modify_address]), analysis_agent: build_agent(tools[query_sales_overview, query_product_rank]), } def dispatch(user_message, user_context): agent_name route_to_agent(user_message) # 注意这里不做二次确认路由结果默认可信 # 生产环境中建议在路由后再做一次关键词兜底检查 return agents[agent_name].run(user_message, user_context)路由拆分的收益在意图差异大的场景下特别明显。售后和物流虽然都涉及订单但工具集几乎没有重叠拆开后每个子智能体只需维护五个左右工具模型选择准确率明显提升。要注意拆分的粒度如果子智能体之间大量共用同一个工具拆分反而增加调用延迟和路由自身出错的风险。我一般只在“工具集合重叠小于三成”时才拆。路由层本身不需要太强的推理能力不需要让路由模型具备多步思考一个精简的分类提示词就够了。路由出错时的兜底也要提前设计当路由模型给出的名称不在候选列表里必须落到默认智能体而不是直接报错。另一个细节是路由结果要写入日志方便后续统计各智能体的流量占比和失败率这些数据会直接影响你下一轮的工具调优方向。4. Agent 应用的参数与评测把“感觉好用”变成“可比较的指标”4.1 值得调整的参数清单别在玄学参数上浪费时间Agent 应用的参数确实有“玄学”成分但真正值得调整的其实就几项。先把常见参数列成表再逐项说明我的调整逻辑。参数常见范围影响面我的调整习惯temperature0 到 1.0工具选择的确定性工具调用场景设 0.1 到 0.2生成总结时提到 0.7max_iterations3 到 15单次任务的循环次数上限默认 8工具链比较长的任务调到 12top_p0.1 到 1.0采样范围基本不动保持模型默认工具响应超时5 秒到 30 秒外部接口卡住时拖慢整个循环读操作 10 秒写操作 30 秒并允许重试一次上下文保留条数6 到 20 条记忆窗口大小默认 10 条配合滚动摘要temperature 是我调整最频繁的参数。做工具调用时模型的“选择”必须稳定temperature 过高会导致同样的输入两次调用选了不同工具尤其是相近描述的工具更容易选错。我见过团队把 temperature 设成 0.9 后Agent 在查库存和查价格两个工具之间反复横跳足足浪费了五轮循环。把温度压到 0.1 到 0.2 后问题立刻消失。但如果模型在生成最终回答时需要组织一段分析性话语低温度会让表达过于生硬所以我的做法是主循环低温度最终回答单独用一次高温度调用生成。max_iterations 不是越大越好。轮数越多token 成本越高且上下文中累积的错误信息也越多。我判断标准是一个正常的业务任务理想状态应该在 3 到 5 轮完成如果某个任务经常跑到 10 轮以上说明要么工具设计不合理要么提示词没有把决策路径约束清楚。此时优先调工具描述而不是盲目提高循环上限。还有一个容易被忽略的参数是工具响应超时外部接口一旦慢整个 Agent 循环就卡死在等待上用户体感极差。我的做法是每个工具单独配置超时和重试策略读操作不重试直接降级返回空结果写操作才允许有限重试。4.2 评测集与基线拿什么证明 Agent 不是“这次运气好”Agent 应用最让人头疼的是“改一处提示词另一个场景的准确率悄悄掉了”。要控制这种退化必须建立固定的评测基线我通常从一份 30 到 50 条的任务样本集开始。样本覆盖的维度包括不同用户意图、不同工具组合路径、边界输入如空参数或超长文本、以及用户中途修改需求的场景。每条样本标注三样东西期望的工具调用顺序、期望的最终答案、可接受的最低完成轮数。评测不是简单的对答案我按两个维度打分。第一维度是工具选择正确率即模型每一步调用的工具是否符合预期。第二维度是答案质量这个比较主观我用 0 到 2 分制0 分是答非所问或编造数据1 分是答案没大错但缺少关键信息2 分是准确完整且来源可核实。每轮改动后跑一遍全量样本记录两个维度的平均值。如果工具选择正确率明显下滑但答案分反而上升说明改动了约束导致模型走了别的路径需要仔细确认是不是误中了其他正确解。评测基线还要包含一个容易漏的部分回归比较。我一般会把上一版模型的评测结果存成 JSON 文件改动后跑新版两份结果逐条 diff。重点看哪些样本从 2 分掉到了 0 分这类“回归样本”是定位问题的金线索。有一次我调整了路由提示词结果查物流的样本全部正常但售后样本集体掉分原因就是路由模型把“申请退款”误判成了分析类请求。没有回归比较这种问题很难靠肉眼发现。4.3 三个观察指标执行成功率、平均轮数、单次成本评测之外生产环境还要盯三个可量化的指标。第一个是执行成功率定义为“Agent 在 max_iterations 内正常产出最终回答并且不报错”的比例。第二个是平均轮数衡量每完成一个任务平均需要多少轮循环这个值直接反映工具设计和提示词约束是否高效。第三个是单次成本用模型输入输出 token 总量乘单价计算它和控制轮数是两个角度但互相影响。这三个指标放在一起看才有意义。假设执行成功率稳定在 95%但平均轮数从 5 涨到 9说明模型虽然能完成但路径变绕了可能是在某些工具选择上反复试错。再结合单次成本如果同时上涨就要重新审视工具描述是否过于模糊或者拆分的智能体是否边界不清。我是把每个任务的日志里加上步骤计数和 token 统计按天汇总这三个指标低于阈值就触发告警。告警不一定要立刻回滚但至少能逼你去翻那个任务的完整轨迹而不是等用户投诉。5. AI Agent 应用的五类常见故障现象、原因、解决5.1 模型凭空捏造工具返回值现象Agent 在没有真实调用工具的情况下直接“给出了”商品的库存数或订单状态而且数据看起来像模像样。排查日志时发现对应工具并没有执行记录但最终回答里出现了具体数值。原因模型在上下文信息不足时倾向于“补全”缺失信息这是生成模型的通病。多数情况下是因为工具调用的返回结果没有以结构化形式回传给模型或者 Agent 循环在工具调用失败后没有把失败原因明确告诉模型模型就只能编一个合理答案。解决工具执行结果必须走独立通道回传并标记为“工具返回”角色同时返回结构里加上success字段失败时明确写error原因。在最终回答层再加一道校验凡是涉及动态数据的答案必须有对应的工具调用记录否则丢弃模型输出并触发重试。我还会在提示词里强制加一句“不要猜测工具返回中没有出现的数据”虽然是软约束但在低温度下有效。5.2 Agent 陷入工具调用死循环现象同一轮对话里模型反复调用同一个工具参数几乎一样回报的结果也一致但模型就是不结束。日志里循环次数触顶用户等待超时。原因最常见是模型对某个返回值不满意希望通过重复调用拿到“更好的结果”但工具本身是确定性返回重复多少次都一样。另一个原因是终止条件不清晰模型没有收到“何时应该停止调用工具”的明确指令。解决循环上限是必须的保底但不能只靠它。我在系统提示词里增加两条约束一是“同一个工具在参数相同的情况下连续调用两次后必须停止并基于已有信息回答”二是“当工具返回结果已经足够回答用户问题时直接生成最终答案不要继续调用”。同时增加一个判断逻辑如果检测到连续两步的工具调用完全相同代码强制中断循环并进入最终回答阶段。5.3 长对话后忘记最初的用户意图现象用户开始时要求查询某商品库存中间聊了几句别的话题Agent 在最终回答里只回应了后段内容完全没有提最初的需求。原因对话历史太长后早期用户消息的权重被大量工具返回和新消息稀释。模型没有机制自动记住“原始目标”它只看到最近几十条消息自然以最新消息为主。解决把用户原始请求单独提取出来常驻在系统提示词的最顶部并标记为“原始目标任务”。在每一轮工具调用前都会把当前动作与原始目标做一次对齐检查。更稳妥的做法是配上业务状态存储把“本次任务要达成的目标”放在biz_state里如果当前推理方向偏离目标就注入一条提醒让模型回到正轨。5.4 多智能体拆分后反而更慢更贵现象把单 Agent 拆成路由加三个子智能体后任务完成率没有提升平均轮数和 token 消耗反而大幅增加。每个子智能体都在做重复的目标拆解和上下文加载。原因任务本身复杂度不够或子智能体之间的工具重叠度过高。路由层多了一次模型调用加上子智能体各自维护独立对话历史同样的信息被重复处理成本自然上去了。解决拆分之前先做工具重叠度分析把两个子智能体的工具列表做交集如果超过三成就不拆。其次路由层用的模型不需要和子智能体用同一个档次选择一个更轻量的模型做分类即可。最后子智能体的对话历史不要全量传递路由层只传用户原始请求和必要的业务状态避免子智能体重复理解已经处理过的上下文。5.5 改一个提示词隐藏的回归问题爆发现象上周某次改动后测试全通过这周在线上发现某个少见的请求路径频繁失败。翻日志发现是上上周调整工具描述时影响了该路径的工具选择但当时评测样本没有覆盖这种场景。原因评测样本数量太少没有覆盖边界输入和低频路径。Agent 应用的输入空间远大于传统后端接口样本集再大也有盲区。解决建立“线上失败样本回流”机制每周把线上失败的请求加入评测集重新跑一遍回归。同时在评测集里增加“对抗样本”比如空输入、歧义输入、多条件冲突输入这些样本的价值不在于它们出现的频率而在于能提前暴露模型在异常输入下的行为倾向。回归评测跑得越勤线上出问题的概率越低这是我最看重的一道防线。6. 生产级 Agent 应用的三件套轨迹日志、人工护栏、灰度对比把 Agent 从 Demo 推到生产我每次都会先补三件东西完整的事件轨迹日志、写操作的人工审批通道、以及新旧版本的灰度对比机制。这三样不依赖任何特殊框架纯靠工程习惯就能落地。轨迹日志的关键是记录“模型的每一步决策”。我在循环里每次调用工具前都会写一条结构化日志包含会话 ID、轮次、模型选择的工具、传入的参数、工具返回结果截断快照、耗时和时间戳。这不仅是排查问题用的更是后续做评测样本回流的原始素材。有个习惯我坚持了很久任何线上 Agent 任务出问题第一件事不是急着改提示词而是把完整的轨迹日志拉出来按步回放先看清楚模型在哪一步跑偏再动手修。修完后把这条轨迹的输入永久加入评测集防止它再次回归。人工护栏主要针对写操作。具体做法是把工具分成只读和可写两类可写工具在真正执行前先返回一个“待确认”状态由代码层的审批接口推送给人。审批通过后再执行真实调用并把审批人、审批时间、结果一并写进轨迹日志。这个设计会让部分用户流程多一步确认但换来的安全性是值得的。线上出过不止一次“模型误会用户意图直接发起写操作”的事故从此所有写操作一律默认过人工。灰度对比是我最后一个习惯。新版本 Agent 不直接全量上线而是先切 1% 到 5% 的真实流量运行一段时间后对比新旧版本在三个核心指标上的表现执行成功率、平均轮数、单次成本。这里有个容易踩的坑不要只看总成功率要按请求类型分层对比。有一次新版本整体成功率反而更好但拆开看是查物流的样本大幅提升掩盖了售后场景的小幅退化。分层对比后才能发现这种结构性偏移。灰度期间还要安排人工抽看新版本的轨迹日志指标只能告诉你“好不好”轨迹能告诉你“为什么好、为什么不好”。这三件套做完Agent 应用才算真正进入可运维状态。我在这类项目上吃过不少亏早期以为模型调用封装好就能上线结果线上翻车时手里连一份像样的轨迹日志都没有只能靠猜。现在我的原则很简单没有轨迹回放能力的 Agent 不上线没有人工审批的写操作不上线没有灰度对比的改动不上线。这几点做到了Agent 应用的生产事故率会低很多。希望这些经验和踩坑总结能帮到你。本文还有配套的精品资源点击获取