1. Agent 为什么难落地先搞懂七要素和七个决策点AI Agent 这个词现在有多烫手已经不需要我多说了。从技术标配到业务指标人人都想上一个 Agent 项目。但真谈工程实现很多人会撞上一堵墙demo 跑得通的东西一碰并发、一碰长任务、一碰第三方工具立刻原形毕露。我这一年多落地过好几个基于 FastAPI、LangGraph 的 Agent 服务也翻过 Rust 自研和 Spring AI 的文档对“AI Agent 工程实现”这件事有些实打实的体会这篇就来交个底。为什么用“七要素 七个决策点”这个框架来拆原因很简单Agent 项目的失败很少是因为模型不够聪明更多是因为团队对 Agent 系统的组成没有完整认知又在每个选型岔路口上做了不合适的决定。七要素解决“这个系统到底由什么构成”的解剖问题七个决策点解决“每一步到底该怎么选”的落地问题。打个比方七要素是一张完整的零件清单七个决策点是装配车间的工序卡。两者合在一起才是一个能复现的 Agent 工程。1.1 为什么是七要素加七个决策点我把 Agent 拆成七要素不是教科书定义而是基于调试和排障的实际归纳。你去翻网上的 Agent 项目代码结构五花八门但仔细看缺的零件就那么几样模型调用、提示词、工具、记忆、规划、循环、护栏。七个决策点则是照着团队例会上的提问总结出来的用哪个框架、哪个模型、什么编排方式、并发怎么办、上下文塞不下怎么办、工具挂了怎么办、上线之后怎么监控。把这两套东西放在一起看才算把“AI Agent 工程实现”这个命题做实了。1.2 这篇内容适合谁适合三类人被 Agent 项目折磨的后端工程师想从 demo 走向生产的算法工程师以及正在做技术选型的技术负责人。默认你有 Python 基础、调过至少一个大模型 API但不需要你有 LangGraph 或 LangChain 经验我会从零带你走一遍。文里的代码可以直接抄但更希望你理解它背后的取舍。2. Agent 的七要素拆开零件看本质2.1 推理内核LLM 是大脑但只是半个大脑任何 Agent 都绕不开 LLM它是决策和生成的核心。但工程上一定要明确一点LLM 不等于 Agent。模型只负责“给下一步动作打分”真正让 Agent 跑起来的是外面这一圈状态管理和工具调用逻辑。选推理内核时不光看知识量和推理能力更要看指令遵循能力、函数调用能力、输出格式稳定性。我实测过一个很常见的坑某个模型在对话里表现不错但一旦塞给它 15 个工具定义它就开始乱选工具。这类问题换 prompt 很难完全解决换模型反而立竿见影。所以说模型是大脑但只是半个大脑另一半是工程系统。2.2 指令与上下文Prompt 是 Agent 的运行规则Prompt 不是给模型的“一段话”而是 Agent 的操作系统配置。System Prompt 里应当写清楚四件事角色与目标、可用工具及其边界、输出格式和协议、异常时的兜底策略。工程上不要把 Prompt 写死在代码里我会把 Prompt 拆成模板加配置角色在 YAML 里工具描述在工具函数旁边异常话术单独维护。这样改 Prompt 不用动代码发版成本低很多。另外工具描述质量往往被低估。你给工具写“查询天气”三个字模型不知道什么时候该用写成“仅当用户询问未来天气时使用历史天气请调用另一个工具”调用准确率立刻不一样。这大概是我在 Agent 工程里花时间最划算的一笔投入。2.3 工具集Agent 的双手与眼睛工具是 Agent 感知世界和改变世界的接口。工程上工具层要做三件事协议统一、权限隔离、可观测记录。协议统一指每个工具都定义好输入输出 JSON Schema权限隔离指工具默认最小权限比如只读文件、白名单域名可观测记录指每次调用都有 trace参数和结果都入库。我见过只给 Agent 挂一个“执行任意 Python 函数”工具的项目确实开发快但一个越权调用就能把整条链路搞垮。工具数量也要克制理想情况活跃工具控制在 10 个以内模型在 20 个工具里做选择时错误率会明显上升。2.4 记忆系统短期上下文和长期知识分开管记忆是 Agent 和“无状态问答”最大的区别之一但也最容易做成灾难。很多人理解的记忆是“把历史和资料全塞进上下文”这在真实业务里活不过一天token 和延迟都会爆炸。我习惯把记忆分成三层对话窗口放最近几轮消息摘要层把过期的对话压缩成一段概述检索层放需要时才去查询的知识库。生活里也很像工作台只放当前要用的东西抽屉放常用的文件书架放不常用但可以查的资料。工程上的实现重点是上下文管理器所有节点都从一个地方取消息片段而不是各自往 prompt 里拼。拼着拼着上下文就废了。2.5 规划器从一步一答到任务拆解简单 Agent 每轮只做一次思考和一次工具调用复杂任务则需要先拆解目标。规划器的实现思路大体分两种ReAct 风格是一边推理一边执行灵活但对长任务容易迷失方向Plan-and-Execute 风格是先产出计划再逐步执行适合流程清晰、步骤较多的任务。工程上我不建议一上来就上复杂规划。先把“单轮思考加工具调用”跑通积累失败案例再去加拆解和反思节点。每加一层规划延迟和 token 开销都会翻倍这个账要心里有数。2.6 执行循环Action 与 Feedback 的回合制Agent 的核心运行机制是一个循环模型给动作工具给反馈反馈再喂回模型直到拿到最终答案或达到终止条件。工程上这个循环有三个必须控制的点最大轮数、单轮工具结果长度、总 token 预算。最大轮数我会根据任务复杂度设成 6 到 10防止模型在错误工具上反复打转单轮工具结果返回前会做截断避免一条巨长日志把上下文塞满总 token 预算一旦超限直接停止并返回已经生成的部分结果而不是让用户无限等待。轮数的控制不是代码里加一个 if 那么简单它需要排查和调参是 Agent 工程排障的高频区。2.7 成本与安全护栏容易忽略的第七要素前面六要素解决“能不能跑”的问题第七要素解决“敢不敢上线”的问题。我把护栏拆成四块成本上限、权限控制、内容安全、故障兜底。成本上限指的是单次会话的 token 预算和单用户频率限制很多 Agent 项目挂在对账单上权限控制指的是工具和数据的访问边界Agent 不知道什么该碰所以你要替它踩刹车内容安全指的是对输入输出做敏感信息识别和脱敏故障兜底指的是备用模型、降级话术、超时熔断。现实里这四块都不会出现在演示里但没有一块生产事故迟早来找你。3. 七个决策点工程化落地的选择岔路口3.1 框架选型LangGraph、Spring AI、Rust 还是可视化平台框架选型大概是最让人纠结的决策点。LangGraph 把状态机、节点、边显式化对复杂流程友好Python 生态最成熟Spring AI 适合 Java 存量团队能复用 Spring 全家桶Rust 自研 Agent 运行时性能极佳、并发能力强但生态和迭代速度是硬伤扣子这类可视化平台适合快速出原型和业务方自助搭应用但私有化部署、复杂编排、与内部系统打通都比较受限。我的决策原则很简单看团队现有堆栈和维护能力。Python 后端就用 LangGraphJava 后端就老实 Spring AI别为了时髦引入一个没人能维护的组件。路线适合场景主要风险LangGraphPython 团队、复杂流程、需快速迭代版本迭代快需锁版本Spring AIJava 存量团队、复用微服务体系社区生态相对浅Rust 自研高性能调度层、攻坚场景开发成本高、生态弱可视化平台原型验证、业务自助定制化、私有化受限3.2 模型选型与 token 成本不是越强越好模型选型的常见误区是“越贵越聪明越聪明越好”。真实业务里模型选型是成本、延迟、能力三者之间的平衡。同样一个 Agent不同环节完全可以搭配不同模型规划节点用强模型保证质量信息抽取和结构化整理用便宜快模型降低成本。工程上要对每次任务的 token 消耗做统计并按任务类型做成本基线。还有一个常被忽略的指标函数调用稳定性。你拿自己的 50 条典型请求做一次回归看看模型在复杂工具描述下的正确率这比排行榜上的分数更有说服力。网上很多人问“ai agent token 是什么意思”其实在工程语境里token 不只是计费单位更是你设计上下文策略和并发策略的基本单位。3.3 编排范式ReAct、Plan-and-Execute 还是状态机编排范式决定了你拿什么控制 Agent 的复杂度。只有“一问一工具”的简单场景用 ReAct 就能跑涉及多分支、条件跳转、人工确认、循环审批的就必须上显式的状态机。用状态图的好处是所有状态可观测、可回放、可单点测试。我给客服工单 Agent 做过一个图意图识别节点之后分三条边分别进入查询、填报、转人工三条子链每条子链内部再循环调用工具。这种图结构即使用 LangGraph 也是先画图再写代码而不是在代码里靠 if 硬撑。控制流越显式越容易调试。3.4 并发与性能Agent 到底怎么扛并发这是热词榜里常客因为 Agent 并发和普通接口并发完全不是一个难度。普通接口一次请求可能一次数据库查询就返回了Agent 一次请求要多次模型调用还可能嵌套多次工具调用端到端经常 5 到 20 秒。这意味着同样 QPS 下底层模型 API 承受的压力是普通请求的好几倍。我的做法入口层用 FastAPI 的异步接口用全局信号量控制同时进行的 Agent 任务数模型调用层再单独做限流和重试工具调用层做超时熔断。实测下来信号量比无脑开线程池可控得多至少不会把模型 API 打爆。另外一个隐藏瓶颈是工具 API很多 Agent 并发崩在第三方工具限流上。3.5 上下文与记忆策略窗口用完怎么办上下文窗口是 Agent 工程里最像“内存管理”的问题。窗口用完方案无非四种截断最省成本但丢信息摘要压缩能保留大意但可能丢细节检索增强要维护向量库和索引适合知识密集场景按需丢弃则依赖元数据筛选适合结构化会话。我倾向的组合是最近消息全量保留中间过程做摘要知识库按需检索插入。工程上我会给每条消息打上会话 ID、角色、时间、来源标签由统一模块按当前节点需求取用。没有这个统一模块每个开发都往 prompt 里塞东西上下文一定会失控。3.6 工具安全与失败恢复工具调用失败是常态工具调用失败不是异常分支而是主流程的一部分。外部 API 会超时、返回垃圾数据、限流、鉴权失效模型也可能拿错误参数去调工具。工程上要把工具调用包装成统一的执行器对可重试错误做指数退避对不可重试错误返回结构化报错给模型让它调整策略重新尝试。安全层面不能让模型直接执行白名单之外的命令文件路径要约束在沙箱目录敏感操作要设人工确认。我见过太多把精力花在 prompt 上、却对工具网关不做防护的项目最后模型被 prompt 注入一引导整个服务器成了跳板。工具网关永远是最后一道防线。3.7 部署、可观测性与评估上线只是开始Agent 上线之后如果没有可观测性就真的是盲盒了。部署本身很简单难的是三个配套评估集、追踪、复盘。评估集是一批带标准答案的真实任务每次改 prompt、换模型、调工具描述都拿它跑一遍回归防止“修好这个坏那个”。追踪把每个节点的输入输出、token 数、耗时、工具调用参数全部记录下来问题发生时能复现整条链。复盘是对失败会话做聚类持续改进。我把这三件事看成 Agent 从玩具走向生产力的分水岭值得在项目一开始就作为基础设施投入。4. 实操基于 FastAPI LangGraph 的最小可用 Agent4.1 工程结构与依赖准备先给工程定个简单的目录结构agent-demo/ ├── app/ │ ├── main.py # FastAPI 入口 │ ├── agent.py # LangGraph 图定义 │ ├── tools.py # 工具函数 │ └── memory.py # 上下文管理 ├── config.yaml └── requirements.txt依赖方面我的准入门槛是fastapi、uvicorn、pydantic、langgraph、langchain-core、以及你用的模型 SDKOpenAI 风格用 openai或 langchain-openai。这里提醒一句LangGraph 版本迭代很快API 出现过不少变化建议在 requirements.txt 里锁住大版本别每次部署都被升级坑一遍。代码示例里我用的是 0.2 系列写法阅读时注意对照你自己的版本。4.2 状态与工具定义在 LangGraph 里状态是图节点之间传递的唯一载体。我通常用 TypedDict 定义状态from typing import TypedDict, Annotated, Literal from operator import add class AgentState(TypedDict): messages: Annotated[list, add] remaining_steps: int tool_results: list这里的 messages 用了 add 归约每次节点输出都会追加到列表。remaining_steps 用来控制最大轮数。工具层面先用最简单的方式定义两个工具from langchain_core.tools import tool tool def get_server_time() - str: 返回当前服务器时间的字符串用户询问时间时使用。 from datetime import datetime return datetime.now().isoformat() tool def calculate(expression: str) - str: 计算简单的数学表达式例如 (35)*2。 try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as e: return f计算失败: {e}这里还是要强调calculate 用 eval 只是为了示例生产环境千万别这么写要么用受限解析器要么别提供这种危险工具。工具描述我会写得尽量明确告诉模型什么时候用、什么时候别用。4.3 构建状态图与执行循环LangGraph 的核心是节点和边我用一个典型的 ReAct 循环来实现from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0) tools [get_server_time, calculate] llm_with_tools llm.bind_tools(tools) def agent_node(state: AgentState): resp llm_with_tools.invoke(state[messages]) return {messages: [resp], remaining_steps: state.get(remaining_steps, 10) - 1} def tools_node(state: AgentState): last_message state[messages][-1] results [] for tool_call in last_message.tool_calls: tool_name tool_call[name] tool_args tool_call[args] for t in tools: if t.name tool_name: results.append(t.invoke(tool_args)) break return {messages: [{role: tool, content: \n.join(str(r) for r in results)}]} def should_continue(state: AgentState) - Literal[tools, end]: last state[messages][-1] if not hasattr(last, tool_calls) or not last.tool_calls: return end if state.get(remaining_steps, 10) 0: return end return tools graph StateGraph(AgentState) graph.add_node(agent, agent_node) graph.add_node(tools, tools_node) graph.set_entry_point(agent) graph.add_conditional_edges(agent, should_continue, {tools: tools, end: END}) graph.add_edge(tools, agent) compiled graph.compile()这段代码看着短但里面藏着两个关键设计条件边负责判断要不要继续循环remaining_steps 确保模型陷入工具调用循环时能及时退出。如果把 should_continue 里的剩余步数判断去掉模型很可能在同一个工具上反复调用直到撞上框架的递归上限这是我踩过的坑。4.4 封装成 FastAPI 接口图编排好之后外面套一层 HTTP 接口就简单了from fastapi import FastAPI from pydantic import BaseModel app FastAPI(titleagent-demo) class ChatRequest(BaseModel): session_id: str message: str class ChatResponse(BaseModel): answer: str tracer: dict app.post(/chat, response_modelChatResponse) async def chat(req: ChatRequest): initial_state { messages: [{role: user, content: req.message}], remaining_steps: 10, tool_results: [], } result await compiled.ainvoke(initial_state) answer result[messages][-1].content return ChatResponse(answeranswer, tracer{steps: len(result[messages])})注意我把 compiled.ainvoke 放在 async 函数里是因为 FastAPI 在等待期间不会阻塞事件循环能让出资源给其他请求。对大多数模型 API 来说网络 IO 是主要耗时异步接口比同步线程池更合适。但 ainvoke 本身如果内部有阻塞代码就需要确认 SDK 的异步实现别调了一个假异步。4.5 并发控制、重试与 token 监控接口能跑只是第一步要扛住多用户并发必须加三道闸。第一道是全局并发闸import asyncio semaphore asyncio.Semaphore(20) app.post(/chat_limited, response_modelChatResponse) async def chat_limited(req: ChatRequest): async with semaphore: return await chat(req)信号量值通常根据模型 API 的 QPS 上限和后端工具接口的承受能力来估算。比如模型 API 每分钟允许 1000 次请求你平均一个 Agent 任务要调用 10 次模型那并发 Agent 任务数最好控制在 100 以内再留出 20% 余量除以单会话调用次数得到比较稳妥的信号量初值。第二道是模型调用层的重试和退避不要用简单 while retry至少加个指数退避import random import time def call_with_retry(func, max_retries3): for attempt in range(max_retries): try: return func() except Exception: if attempt max_retries - 1: raise time.sleep(min(2 ** attempt random.uniform(0, 1), 8))第三道是 token 监控每次调用模型时把 usage 记录下来任务结束时做汇总。建议把每轮 token 数写进 tracer用来做成本预估和告警。上生产前我会先压测 200 个并发任务观察三个指标端到端 P95 延迟、模型 API 429 出现次数、工具调用超时率。Agent 扛并发的本质不是堆机器是控制每一层的资源消耗。5. 常见问题与排查技巧实录5.1 上下文爆掉窗口超限与递归错误症状一报错提示超过模型的 context window症状二LangGraph 抛出 RecursionError 超过递归上限。这两个问题表面不同根源却很像循环轮数没控制住或每个节点都在往状态里塞消息导致状态越来越大。排查步骤先看剩余轮数有没有耗尽再看每条消息和工具结果是不是都被截断到合理长度最后看是不是某个工具返回了超长文本。这里有个技巧给工具结果设置一个字符上限比如 2000 字符超长就截断并在末尾加省略标记模型通常能接受。5.2 工具调用死循环现象最典型的是模型反复调用同一个工具每次传入几乎相同的参数。原因通常是工具返回的结果没有让模型得到“这个方案走不通”的信号或者工具描述让模型误以为必须调用它。处理方法在工具描述里写明“当……时不要调用”在 should_continue 里加去重判断检测到本轮调用历史里已有相同参数就提前终止把递归上限调低一点让失败尽早暴露。我曾经在一个项目里遇到模型把“查询天气”调用重复了 30 次白白浪费大量 token最后是加了一个简单的工具调用去重才止住。5.3 并发一高就超时或报 429429 是模型 API 限流最常见的信号但排查时不要只盯着模型 API。我遇到过一个案例前端并发一高模型 API 没报错反而是内部工具接口先崩了因为工具接口没有做限流。正确排查顺序是先看 Agent 任务的入口并发再看模型 API 调用频次再看工具 API 的响应时间和错误率最后看数据库连接池。解决方案按优先级排入口信号量降并发、模型调用加退避重试、工具调用加熔断和缓存、必要时做任务队列削峰。如果你发现加了机器并发反而更差那多半是下游 API 先到瓶颈了。5.4 模型输出 JSON 不稳定需要结构化输出时模型偶尔返回不合法 JSON这在真实项目里非常正常。我的处理分三层第一层优先用模型供应商的 function calling 或 JSON mode让模型直接产出结构化对象第二层对返回结果做轻量清洗比如去掉前后缀和注释再解析第三层解析失败就把错误信息回填给模型让它尝试修复。如果修复两三次仍然失败果断结束并人工处理别让模型无限重试。如果某种模型频繁输出不合法 JSON换一个函数调用更稳定的模型往往比继续调 prompt 更省事。5.5 Rust、Spring AI、可视化平台的选型答疑这里把网上问最多的三个方向统一聊一下。Rust 写 Agent 运行时优势是高并发、低资源占用、内存安全适合做网关或调度层问题是开发效率低大模型相关的库迭代又太快用来做业务 Agent 会很辛苦。Spring AI 的价值在于 Java 团队不需要再维护一套 Python 服务和现有微服务体系能直接打通代价是生态深度和社区案例不如 Python 阵营丰富。扣子这类可视化平台我建议用在验证原型、给业务方做自助工具一旦要深度定制、私有化部署、精细控制上下文和工具权限还是回代码更稳。选型时拿自己的业务场景过一遍别被热词带跑。5.6 踩坑之后才明白的几条铁律最后写几条我自己的体会不保证普适但应该能帮你少走弯路。第一条先把最小闭环跑通再加规划、反思、记忆这些花活。第二条给系统装好评估和追踪再上线评估可以简单到只有几十条用例但一定要有。第三条把失败会话当资源每次修 bug 都是往评估集里加样本的过程几个月后你会感谢当时的记录。第四条调试 Agent 时把模型每一步的推理、动作、工具结果都打成结构化日志看起来麻烦实际是救命的。我见过太多人花几天时间猜模型为什么答错最后发现只是某个工具返回值解析错了。