1. 半年卡壳到底卡在哪：AI Agent 从演示到落地的三道坎

去年秋天我接了一个内部工单系统的智能化改造，目标很明确：让 AI Agent 接管一部分重复性的工单分派和初步答复。Demo 阶段一切顺利，LangChain 串起来、工具调用跑通、本地测试准确率看着也不错。但真正往生产环境推的时候，整整半年时间，我几乎原地踏步。这段经历让我彻底明白一件事：AI Agent 的难点从来不在“能不能跑起来”，而在“能不能稳定地跑下去”。

如果你也在做 AI Agent 项目，大概率会遇到和我一样的三道坎。第一道是并发下的状态管理。Agent 和普通接口最大的区别在于它是有“记忆”的，多轮对话、工具调用的中间结果、任务分解的上下文，这些东西在单机测试时随便塞进内存就行，一旦并发上来，会话串号、上下文污染、内存暴涨全来了。第二道是工具调用的可靠性。Agent 要“下地干活”，就得调用外部 API、查数据库、发消息，任何一个环节超时或返回异常，整个推理链就断了，而大模型面对异常返回时经常“一本正经地胡说八道”。第三道是可观测性缺失。传统服务的日志和链路追踪到了 Agent 这里基本失效，因为你根本不知道模型为什么选了那个工具、为什么走了那条推理路径，出了问题只能靠猜。

这半年我踩的坑，本质上都是工程化的问题，而不是算法问题。模型能力其实早就够用了，缺的是把 Agent 当成一个正经后端服务来对待的那套方法论。这也是为什么我今年特别关注 iRTE2026 这类聚焦 AI Agent 工程实践的会议——单打独斗摸索半年的东西，可能别人一句话就点透了。下面我把这半年拆解出来的东西系统性地梳理一遍，从架构选型到并发扛压，从工具编排到可观测性，尽量讲透。

2. 拆解 AI Agent 的核心架构：别一上来就堆框架

2.1 先想清楚 Agent 的“大脑-手脚-记忆”三件套

很多人做 AI Agent 的第一个动作是打开文档找框架，LangChain、LangGraph、Spring AI、扣子，哪个火用哪个。我一开始也这样，结果就是被框架的抽象层绑架，出了问题根本不知道是哪一层的事。后来我强迫自己退回到最朴素的认知：一个 Agent 本质上就是“大脑 + 手脚 + 记忆”三件套。

“大脑”是大模型，负责推理和决策；“手脚”是工具集，负责和外部世界交互；“记忆”是状态管理，负责记住上下文和历史。任何框架都只是这三件套的不同封装方式。想清楚这一点之后，选型就不再是“哪个框架好”，而是“哪个框架对这三件套的封装最符合我的场景”。

比如 LangGraph 把 Agent 建模成状态图，节点是工具或模型调用，边是流转条件，这种显式建模对复杂多步任务特别友好，因为你能精确控制每一步的走向。而 Spring AI 更偏向把 Agent 能力嵌入到已有的 Java 微服务生态里，如果你团队本来就是 Spring 技术栈，用它做集成成本最低。扣子这类平台则把三件套都封装好了，适合快速验证想法，但深度定制时会受限。

我的建议是：先用最轻的方式把三件套跑通，再决定要不要上重框架。我后来重构时，核心调度逻辑是自己写的，只在工具编排和状态持久化上借用了 LangGraph 的部分能力，反而比全盘套框架清晰得多。

2.2 状态管理选型：内存、Redis 还是数据库

状态管理是 Agent 工程化里最容易被低估的一环。单机 Demo 时你把对话历史存成一个 list 就完事了，但生产环境要考虑：会话怎么隔离、历史怎么截断、并发怎么加锁、服务重启后状态怎么恢复。

我试过三种方案，各有适用场景。纯内存方案适合单实例、低并发的内部工具，实现最简单，但服务一重启状态全丢，而且没法水平扩展。Redis 方案是我最终采用的主力方案，用 session_id 作为 key，把对话历史和中间状态序列化存进去，天然支持多实例共享，还能设置 TTL 自动清理过期会话。数据库方案适合需要长期留存审计记录的场景，但读写延迟高，一般只用来做冷存储，热状态还是放 Redis。

这里有个关键细节：状态不能无限增长。Agent 多轮对话下来，历史消息会越来越长，直接全塞给模型既费 token 又容易超出上下文窗口。我的做法是维护一个滑动窗口，只保留最近 N 轮完整对话，更早的历史做摘要压缩后存起来。摘要本身也是一次模型调用，所以要控制频率，我一般每积累 10 轮触发一次压缩。

# 状态管理的核心逻辑示意 class AgentStateManager: def __init__(self, redis_client, max_turns=10): self.redis = redis_client self.max_turns = max_turns def get_context(self, session_id): raw = self.redis.get(f"agent:session:{session_id}") if not raw: return {"history": [], "summary": ""} state = json.loads(raw) # 滑动窗口：只取最近 max_turns 轮 state["history"] = state["history"][-self.max_turns:] return state def append(self, session_id, message): state = self.get_context(session_id) state["history"].append(message) # 超过阈值触发摘要压缩 if len(state["history"]) > self.max_turns * 2: state = self._compress(state) self.redis.setex( f"agent:session:{session_id}", 3600, json.dumps(state) )

注意：Redis 存状态时一定要设 TTL，否则会话数据会无限堆积。我见过有团队忘了设过期时间，跑了一个月 Redis 内存直接爆掉。

2.3 工具层的抽象：让 Agent 的“手脚”可插拔

工具层设计的好坏，直接决定了 Agent 能扩展多少能力。我一开始是把每个工具写成一个独立函数，然后在 prompt 里硬编码工具描述，结果每加一个工具就要改 prompt、改调度逻辑，维护成本极高。

后来我改成注册式工具管理：每个工具定义成一个带元数据的对象，包含名称、描述、参数 schema、执行函数。Agent 启动时扫描注册表，自动生成工具描述注入 prompt，调度时根据模型返回的工具名去注册表里找对应执行函数。这样加新工具只需要写一个类并注册，其他全自动。

# 工具注册的抽象设计 class Tool: name: str description: str parameters: dict # JSON Schema 格式 def execute(self, **kwargs) -> str: raise NotImplementedError class ToolRegistry: def __init__(self): self._tools = {} def register(self, tool: Tool): self._tools[tool.name] = tool def get_schemas(self): # 自动生成给模型看的工具描述 return [ { "name": t.name, "description": t.description, "parameters": t.parameters } for t in self._tools.values() ] def invoke(self, name, args): tool = self._tools.get(name) if not tool: return f"错误：工具 {name} 不存在" try: return tool.execute(**args) except Exception as e: # 关键：异常要转成模型能理解的文本，而不是直接抛 return f"工具执行失败：{str(e)}"

这里有个我踩过的坑：工具执行异常千万不要直接往上抛。因为异常一旦抛出，整个推理链就断了，模型没有机会自我修正。正确做法是把异常信息包装成一段文本返回给模型，让它知道“这个工具失败了，原因是 XXX”，模型往往能据此换个思路或者换个工具重试。这个设计让我的 Agent 在工具不稳定时的成功率提升了将近 40%。

3. 并发这道坎：AI Agent 怎么扛住真实流量

3.1 为什么 Agent 的并发比普通接口难搞

普通 REST 接口是无状态的，来一个请求处理完就释放，水平扩展加机器就行。但 Agent 是有状态的，而且一次请求的处理时间可能是普通接口的几十倍——因为中间要经历多轮模型调用和工具调用。这就导致两个问题：连接占用时间长和资源消耗不可预测。

我实测过，一个中等复杂度的 Agent 任务，从接收请求到返回结果，平均耗时 8 到 15 秒，其中模型调用占了 70% 以上。如果同步处理，一个实例撑死也就扛几十个并发。更麻烦的是，模型调用的延迟波动很大，有时候 2 秒返回，有时候 20 秒还在转，这种不确定性让传统的线程池配置完全失效。

我的解决思路是全链路异步化 + 任务队列削峰。请求进来后不直接处理，而是丢进队列立即返回一个 task_id，客户端通过轮询或 WebSocket 拿结果。后端用异步 worker 消费队列，每个 worker 内部对模型调用和工具调用都用异步 IO，这样单个 worker 在等待模型返回时可以去处理别的任务，资源利用率大幅提升。

3.2 异步编排的落地细节与踩坑

异步化说起来简单，做起来坑不少。第一个坑是异步上下文传递。Agent 处理过程中要不断读写会话状态，如果每个异步函数都自己去连 Redis，连接池很快就被打满。我的做法是在任务开始时创建一个上下文对象，把 Redis 连接、工具注册表、配置这些都挂上去，整个任务生命周期内复用。

第二个坑是超时控制。模型调用和工具调用都必须设超时，而且要有兜底逻辑。我一开始没设超时，结果有个工具因为下游服务挂了，卡了整整 60 秒，把 worker 全占满了。后来我给每个调用都设了超时，模型调用 30 秒、工具调用 10 秒，超时后返回一个明确的错误信息给模型，让它决定下一步。

# 异步任务处理的核心结构 async def process_task(task_id, user_input, session_id): ctx = await create_context(session_id) try: # 模型调用带超时 response = await asyncio.wait_for( call_llm(ctx, user_input), timeout=30.0 ) # 如果模型要求调用工具 while response.tool_calls: for call in response.tool_calls: result = await asyncio.wait_for( ctx.registry.invoke(call.name, call.args), timeout=10.0 ) ctx.history.append({"tool": call.name, "result": result}) response = await asyncio.wait_for( call_llm(ctx, None), timeout=30.0 ) await save_result(task_id, response.content) except asyncio.TimeoutError: await save_result(task_id, "处理超时，请重试") finally: await ctx.cleanup()

第三个坑是并发写同一会话。同一个用户可能连续发多条消息，如果两条消息同时处理，会话状态就会错乱。我的做法是给每个 session_id 加一把分布式锁，同一会话的任务串行执行，不同会话并行。锁的粒度要控制好，太粗会影响吞吐，太细又起不到保护作用。

3.3 压测数据与容量估算

光说方案不够，得有数据支撑。我用 Locust 做了一轮压测，配置是 4 核 8G 的容器，异步 worker 数量设为 20。测试结果如下：

从数据能看出，并发到 200 以后响应时间开始明显恶化，成功率也下降了。瓶颈主要在模型调用的速率限制上，而不是我们自己的服务。所以容量估算的核心是先摸清模型 API 的 QPS 上限，再反推自己能扛多少并发。如果模型侧限制是 20 QPS，那你服务端再能扛也没用，得靠队列把请求排队消化。

提示：压测时一定要用真实的模型调用，不要 mock。mock 出来的数据毫无参考价值，因为真实模型调用的延迟分布和失败率跟 mock 完全不是一回事。

4. 工具编排与“让 AI 真的下地干活”

4.1 从“能调用”到“调得对”：工具描述的学问

工具能调用只是第一步，让模型在正确的时机调用正确的工具才是难点。我发现工具描述的质量直接决定了调用准确率。一开始我写的工具描述很随意，比如“查询订单”，结果模型经常在不该查订单的时候去查。后来我把描述改成了场景化的说明，明确写出“什么时候该用这个工具”。

举个例子，同样是查询工具，我改成：“当用户询问订单状态、物流进度、预计送达时间时使用此工具。参数 order_id 必须是用户提供的订单号，如果用户没有提供订单号，不要调用此工具，而是先向用户询问。”这样一改，误调用率直接降了一半。

另外，工具数量不宜过多。我试过一次性给模型挂 20 多个工具，结果模型选择困难，经常选错。后来我按业务场景把工具分组，每次只给模型暴露当前场景相关的 5 到 8 个工具，准确率明显提升。这就像你给一个人递工具，一次递一把他清楚该用哪个，一次递二十把他反而懵了。

4.2 多步任务的编排：串行、并行还是图

简单任务一次工具调用就搞定，但真实业务往往是多步的。比如“帮我查一下上个月的销售数据，生成报表，然后发给张经理”，这里面有查询、生成、发送三个步骤，而且有依赖关系。

我试过三种编排方式。串行编排最简单，模型一步步来，每步结果作为下步输入，但慢。并行编排适合无依赖的步骤，比如同时查多个数据源，能省时间，但需要模型能识别出哪些步骤可以并行。图编排是 LangGraph 那种方式，把整个流程画成状态图，节点之间的流转条件显式定义，最灵活也最可控，但开发成本高。

我的经验是：先用串行把流程跑通，识别出瓶颈后再针对性优化。大部分场景串行就够了，真正需要并行的场景没那么多。我那个工单系统最后就是串行编排，因为工单处理本身就有严格的先后顺序，强行并行反而容易出错。

4.3 工具失败的降级与重试策略

工具调用失败是常态，网络抖动、下游限流、参数错误都会导致失败。我的策略是分级处理：可重试的错误（如超时、限流）自动重试 2 次，重试间隔指数退避；不可重试的错误（如参数错误、权限不足）直接把错误信息返回给模型，让它决定是换个工具还是向用户澄清。

这里有个细节：重试要在工具层做，不要交给模型。因为模型不知道哪些错误可重试，让它来决定重试策略既慢又不靠谱。我在工具执行器里内置了重试逻辑，对特定的异常类型自动重试，模型完全无感知。

async def invoke_with_retry(tool, args, max_retries=2): for attempt in range(max_retries + 1): try: return await tool.execute(**args) except (TimeoutError, RateLimitError) as e: if attempt == max_retries: return f"工具 {tool.name} 多次重试后仍失败：{str(e)}" await asyncio.sleep(2 ** attempt) # 指数退避 except Exception as e: # 不可重试的错误直接返回 return f"工具 {tool.name} 执行失败：{str(e)}"

5. 可观测性：Agent 出问题时你怎么知道

5.1 传统监控为什么在 Agent 场景失效

传统服务的监控看的是 QPS、延迟、错误率这些指标，链路追踪看的是请求经过了哪些服务。但 Agent 的问题往往不是“服务挂了”，而是“服务正常但结果不对”。模型可能选错了工具、推理路径跑偏、或者对工具返回的结果理解错了，这些在传统监控里完全看不出来。

我遇到过最诡异的一次：Agent 连续几天给用户回复了错误的信息，但所有监控指标都正常，错误率是 0，因为从系统角度看请求都成功返回了。后来排查发现是模型对某个工具返回的 JSON 格式理解有偏差，把字段搞混了。这种问题只能靠记录完整的推理链路才能发现。

5.2 记录什么：推理链路的完整快照

我现在对每个 Agent 任务都会记录一份完整的执行快照，包括：用户输入、每一轮模型的输入 prompt 和输出、每次工具调用的名称参数和返回结果、最终回复、总耗时和 token 消耗。这些数据存到 Elasticsearch 里，方便检索和分析。

有了这份快照，排查问题就简单多了。用户反馈结果不对，我直接按 session_id 查出完整链路，一眼就能看出是哪一步出了问题。是模型选错工具，还是工具返回异常，还是模型理解错了，清清楚楚。

# 执行快照的记录结构 trace = { "task_id": task_id, "session_id": session_id, "user_input": user_input, "steps": [ { "type": "llm_call", "input_tokens": 1250, "output": "我需要查询订单...", "tool_calls": [{"name": "query_order", "args": {"id": "123"}}], "latency_ms": 2340 }, { "type": "tool_call", "name": "query_order", "args": {"id": "123"}, "result": "{\"status\": \"shipped\"}", "latency_ms": 156 } ], "final_output": "您的订单已发货", "total_latency_ms": 5820, "total_tokens": 3420 }

5.3 用数据驱动 Agent 的持续优化

快照数据积累起来之后，价值就大了。我每周会做一次分析，看几个关键指标：工具调用准确率（模型选的工具对不对）、任务完成率（用户问题是否被解决）、平均推理轮数（是不是绕了弯路）。这些指标能直接指导优化方向。

比如我发现某个工具被误调用的频率特别高，就去优化它的描述；发现某类问题的推理轮数明显偏多，就去补充 few-shot 示例；发现某些场景 token 消耗异常，就去精简 prompt。这种数据驱动的优化，比拍脑袋改 prompt 有效得多。半年下来，我的 Agent 任务完成率从最初的 62% 提升到了 89%，靠的就是这套可观测性体系。

6. 技术选型的取舍：Rust、Spring AI 还是 Python 生态

6.1 不同语言栈做 Agent 的真实差异

关于用什么语言做 Agent，社区里争论一直很多。我用过 Python 和 Java 两套栈，也研究过 Rust 方案，说说真实感受。

Python 生态是目前最成熟的，LangChain、LangGraph、各种模型 SDK 都是一等公民，开发效率最高。但 Python 的并发模型是短板，GIL 限制了多线程性能，高并发场景得靠异步 IO 或者多进程。如果你的 Agent 并发量不大，Python 完全够用；如果要扛高并发，就得在架构上多花心思。

Java 生态以 Spring AI 为代表，优势是能无缝融入已有的微服务架构，事务、监控、配置管理这些基础设施都是现成的。如果你的团队本来就是 Java 栈，用 Spring AI 做 Agent 集成成本最低。缺点是 AI 相关的库更新没那么快，有些新特性要等。

Rust 生态性能最好，内存安全，适合对延迟和资源占用极度敏感的场景。但生态还在早期，很多轮子要自己造，开发效率低。除非你有极致的性能需求，否则现阶段不太建议用 Rust 做主力。

6.2 我的混合选型方案

最后我采用的是混合方案：核心调度和状态管理用 Java（Spring Boot），模型调用和工具编排用 Python 微服务。Java 侧负责接收请求、管理会话、任务队列，Python 侧专注做 Agent 的推理编排。两边通过 gRPC 通信，各取所长。

这个方案的好处是，Java 侧的基础设施成熟稳定，能扛住高并发；Python 侧的 AI 生态丰富，开发迭代快。坏处是架构复杂了，多了一层服务间通信的开销和运维成本。所以这个方案适合有一定规模的团队，小团队还是建议统一用 Python，简单直接。

7. 半年踩坑换来的几条硬经验

回过头看这半年，技术上的东西其实都能查到，真正值钱的是那些踩过坑才知道的经验。第一条：不要迷信框架，先把三件套想清楚。框架是帮你省事的，不是帮你思考的，架构没想明白就上框架，只会把问题藏得更深。

第二条：并发问题要在架构设计阶段就考虑，不要等出问题再补。我一开始就是同步处理，等到线上扛不住了才重构异步，代价很大。如果你预判 Agent 会有一定并发量，一开始就按异步 + 队列的架构来设计。

第三条：可观测性不是可选项，是必选项。Agent 的黑盒特性决定了你必须能看清它每一步在干什么，否则出了问题就是抓瞎。宁可前期多花两天把链路记录做好，也不要后期花两周去猜问题出在哪。

第四条：工具描述和 prompt 是要持续迭代的，不是一锤子买卖。上线只是开始，后面要靠数据不断优化。我现在的习惯是每周看一次执行快照，找出 top 3 的问题场景针对性优化，积少成多，效果很可观。

至于 iRTE2026，我关注它是因为这类会议往往能听到一线团队的真实实践，而不是厂商的宣传。AI Agent 这个领域变化太快，闭门造车半年，不如去现场跟同行碰一碰，看看别人在并发、编排、可观测性上是怎么做的。有些坑别人已经踩过了，听一耳朵就能省下自己几个月的时间。这大概就是我做 AI Agent 这半年最深的体会：技术可以自己啃，但经验最好别自己攒。