AI Agent 工程化交付：从 Demo 到生产的关键实践

1. 从“能跑通”到“能交付”：AI Agent 工程师的分水岭

我见过太多团队在 Agent 项目上栽跟头，不是因为模型选错了，也不是因为框架不够先进，而是卡在一个更朴素的问题上：Demo 跑得挺漂亮，一上生产就散架。你让 Agent 查个天气、写封邮件，它干得利索；你让它处理一个真实的客户工单、完成一次跨系统的数据核对、生成一份可以直接发给客户的报告，它就开始胡言乱语、丢步骤、编数据。这个落差，就是“调用模型”和“交付结果”之间的距离。

先把概念理清楚，因为热词里问得最多的就是这几个东西的区别。LLM（大语言模型）是一个函数，输入文本、输出文本，它本身没有记忆、没有手脚、没有目标感。AI 模型是个更宽泛的说法，图像模型、语音模型、推荐模型都算，LLM 只是其中一类。而AI Agent是在 LLM 外面套了一整套“感知—决策—行动—校验”的循环结构：它能调用工具、能读写外部状态、能根据执行结果调整下一步、能在失败时重试或求助。打个比方，LLM 是一个博学但只会动嘴的顾问，Agent 是给这个顾问配了手、配了眼睛、配了记事本、还配了一个会盯着他干活的监工。至于 DeepSeek，它属于 LLM 这一层，是一个具体的模型产品，你可以把它当作 Agent 的“大脑”来用，但它本身不是 Agent。

这个区分为什么重要？因为它直接决定了你的工作重心。如果你以为自己在做 Agent，实际上只是在做“调模型”，那你所有的精力都会花在 prompt 调优上，而真正让结果可交付的那些工程问题——状态管理、错误恢复、工具契约、输出校验——你一个都没碰。上线之后你会发现，prompt 调到再完美，也挡不住工具返回一个空值、挡不住网络超时、挡不住模型在第三步突然忘了第一步的约束。

我个人的判断标准很简单：一个 Agent 系统是否合格，不看它在顺境下表现多好，看它在逆境下能不能兜住。工具挂了怎么办？模型输出格式错了怎么办？用户中途改了需求怎么办？外部数据源返回了意料之外的字段怎么办？这些问题的答案，才是 Agent 工程师真正的价值所在。下面我会把这几年在 Agent 交付上踩过的坑、总结的方法，按“结果交付”这条主线拆开讲。

2. 结果交付的第一道坎：把“意图”翻译成“可执行的契约”

2.1 为什么大多数 Agent 失败在第一步

很多人做 Agent 的起点是写一个漂亮的 system prompt，把角色、能力、约束一股脑塞进去，然后指望模型“理解”用户想要什么。这个做法在单轮任务里勉强能用，一旦任务有多步、有分支、有外部依赖，就会暴露出一个根本问题：自然语言意图和可执行动作之间，缺少一层显式的契约。

什么叫契约？就是你把“用户想要什么”翻译成“系统要做什么”时，必须明确下来的那些东西：输入是什么格式、输出必须满足什么结构、中间可以调用哪些工具、每个工具的前置条件和后置效果是什么、失败时允许的重试策略是什么。这些东西如果只存在于 prompt 的模糊描述里，模型每次执行都会给你一点“惊喜”。

我踩过最典型的一个坑：做一个合同信息抽取的 Agent，prompt 里写了“请提取合同中的甲方、乙方、金额、签署日期”。测试集上准确率 90% 多，一上真实数据就崩。原因是真实合同里“金额”可能写成“合同总价”“价款”“人民币大写”，甚至分散在多个条款里；模型有时候返回一个数字，有时候返回一段描述，有时候干脆把“金额”和“税率”搞混。下游系统拿到这种参差不齐的输出，直接报错。

2.2 用结构化输出把“模糊”变成“确定”

解决这个问题的核心手段是强制结构化输出。不管你用哪个框架，最终都要让模型的输出落到一个明确的 schema 上。我的做法是分三层：

第一层，定义输出 schema。用 JSON Schema 或者 Pydantic 模型把每个字段的类型、必填性、取值范围写死。比如金额字段必须是number类型，日期必须是YYYY-MM-DD格式，枚举字段只能取预设的几个值。

第二层，在 prompt 里嵌入 schema 并给出正反例。不要只说“返回 JSON”，要把完整的 schema 贴进去，再给一两个正确示例和一个错误示例，明确告诉模型“字段缺失时填 null，不要编造”。

第三层，在代码侧做校验和修复。模型返回后，先用 schema 校验一遍，不通过就触发一次“修复调用”——把错误信息和原始输出一起喂回去，让模型修正。修复最多重试两次，两次还不行就降级到人工兜底。

from pydantic import BaseModel, Field, ValidationError from typing import Optional import json class ContractInfo(BaseModel): party_a: str = Field(description="甲方全称") party_b: str = Field(description="乙方全称") amount: Optional[float] = Field(default=None, description="合同金额，单位元") sign_date: Optional[str] = Field(default=None, pattern=r"\d{4}-\d{2}-\d{2}") def extract_with_repair(raw_text: str, max_retry: int = 2) -> ContractInfo: prompt = build_prompt(raw_text, ContractInfo.model_json_schema()) for attempt in range(max_retry + 1): output = call_llm(prompt) try: data = json.loads(output) return ContractInfo(**data) except (json.JSONDecodeError, ValidationError) as e: if attempt == max_retry: raise prompt = build_repair_prompt(raw_text, output, str(e)) raise RuntimeError("unreachable")

这段代码看起来简单，但它把“模型可能出错”这件事变成了系统设计的一部分，而不是靠运气。交付结果的前提，是承认模型不可靠，然后用工程手段把不可靠性关进笼子里。

2.3 工具契约：比 prompt 更重要的东西

Agent 和普通 LLM 应用最大的区别是它会调用工具。而工具调用的质量，几乎完全取决于你给工具定义的契约是否清晰。我见过太多人写工具描述时只写一句“查询用户信息”，然后模型就懵了：传什么参数？返回什么结构？查不到怎么办？

一个好的工具契约应该包含：功能一句话说明、参数名和类型、每个参数的含义和示例值、返回值的结构、可能的错误码、以及调用时的注意事项。这些信息要同时出现在两个地方——给模型看的 tool description 里，和给代码用的函数签名里。两者必须一致，否则模型以为传的是user_id，代码里接的是uid，这种低级错误在联调阶段能耗掉你一整天。

提示：工具描述里的示例值非常关键。模型对示例的敏感度远高于对抽象描述的理解。与其写“用户ID，字符串类型”，不如写“用户ID，例如 'u_10086'”。一个具体的例子能消除大量歧义。

3. 状态与记忆：Agent 交付结果时最容易丢的东西

3.1 多步任务里，模型为什么会“失忆”

Agent 处理一个多步任务时，每一步的输入输出都在变化。如果每一轮都把完整历史塞给模型，token 会爆炸；如果只塞最近几轮，模型就会丢掉早期的重要约束。这就是所谓的“上下文漂移”——走到第五步的时候，模型已经忘了第一步用户说的“预算不能超过 5000”。

我做过一个采购比价的 Agent，任务流程是：解析需求 → 搜索供应商 → 抓取报价 → 比价 → 生成推荐。测试时发现，到了比价环节，模型经常推荐一个超出预算的选项。排查后发现，预算约束是在第一轮用户输入里给的，但比价环节的 prompt 里只带了最近两轮的对话，预算信息早就被挤出去了。

3.2 显式状态机比“让模型自己记”靠谱得多

解决办法不是加大上下文窗口，而是把关键状态从对话历史里抽出来，显式管理。我的做法是维护一个结构化的 state 对象，里面存放任务的所有关键信息：用户约束、已完成步骤、中间结果、待办事项。每一轮调用模型时，把 state 序列化后作为独立字段传入，而不是混在对话历史里。

class AgentState(BaseModel): user_constraints: dict = Field(default_factory=dict) completed_steps: list[str] = Field(default_factory=list) intermediate_results: dict = Field(default_factory=dict) pending_step: Optional[str] = None retry_count: int = 0 def build_step_prompt(state: AgentState, current_input: str) -> str: return f""" 当前任务状态： - 用户约束：{json.dumps(state.user_constraints, ensure_ascii=False)} - 已完成步骤：{state.completed_steps} - 中间结果：{json.dumps(state.intermediate_results, ensure_ascii=False)} - 当前待执行：{state.pending_step} 本轮输入：{current_input} 请基于以上状态执行当前步骤，并返回结构化结果。 """

这样做的好处是，状态是代码可控的，不会因为对话轮次增加而丢失。而且当任务失败需要重试时，你可以精确地回滚到某一步，而不是从头再来。Agent 的可靠性，很大程度上取决于你对状态的控制粒度。

3.3 长期记忆和短期记忆要分开处理

短期记忆就是当前任务的 state，任务结束就丢弃。长期记忆是跨任务的知识，比如用户偏好、历史交互摘要、领域知识库。这两者的存储和检索策略完全不同。短期记忆要求强一致、低延迟，放内存或 Redis 就行；长期记忆要求可检索、可更新，通常用向量库加结构化存储。

我见过有人把两者混在一起，结果就是每次调用都要检索一大堆无关的历史，既慢又不准。分开处理，按需注入，是记忆管理的基本原则。具体来说，短期 state 每轮必带，长期记忆只在相关步骤按需检索 top-k 条注入。

4. 错误恢复：决定 Agent 能不能上生产的关键能力

4.1 把失败当成常态来设计

Demo 阶段大家默认一切顺利，生产阶段一切都不顺利。工具会超时、API 会限流、模型会返回垃圾、外部数据会缺字段。如果你的 Agent 没有为这些情况设计恢复路径，那它就是一个随时会炸的定时炸弹。

我的经验是，在写第一行 Agent 代码之前，先列一张失败清单：这个任务可能在哪一步失败？每步失败的原因有哪些？每种原因对应的恢复策略是什么？这张清单比任何架构图都重要。

4.2 重试不是万能药，要区分“可重试”和“不可重试”

很多人一遇到失败就无脑重试，结果浪费了大量 token 和时间，问题依然存在。重试的前提是失败原因是暂时性的。网络超时可以重试，参数格式错重试一百次也没用，得先修参数。我的做法是在错误处理层加一个分类器：暂时性错误（超时、限流、临时不可用）走重试；永久性错误（参数非法、权限不足、数据不存在）走修复或降级；未知错误走兜底。

class ErrorCategory(Enum): TRANSIENT = "transient" PERMANENT = "permanent" UNKNOWN = "unknown" def classify_error(exc: Exception) -> ErrorCategory: if isinstance(exc, (TimeoutError, RateLimitError)): return ErrorCategory.TRANSIENT if isinstance(exc, (ValueError, PermissionError, KeyError)): return ErrorCategory.PERMANENT return ErrorCategory.UNKNOWN def handle_failure(exc, state, step): category = classify_error(exc) if category == ErrorCategory.TRANSIENT and state.retry_count < 3: state.retry_count += 1 return RetryAction(backoff=2 ** state.retry_count) if category == ErrorCategory.PERMANENT: return RepairAction(hint=str(exc)) return FallbackAction(reason="unknown_error")

4.3 降级路径要提前设计好

不是所有失败都能恢复。当重试和修复都失败时，Agent 需要一个体面的降级方案。降级不是“报错退出”，而是“用次优方案完成任务，并明确告知用户哪些部分没做到”。比如比价 Agent 抓不到某个供应商的报价，降级方案是：基于已有数据给出推荐，并标注“供应商 X 报价未获取，建议人工确认”。用户能接受不完美的结果，但不能接受一个假装完美的错误结果。

5. 从“单 Agent”到“多 Agent 协作”的取舍

5.1 什么时候该拆，什么时候不该拆

热词里“多智能体”出现频率很高，但我要泼一盆冷水：大多数任务不需要多 Agent。多 Agent 带来的协调成本、通信开销、状态同步复杂度，往往超过它带来的收益。我见过一个团队把简单的文档摘要任务拆成“读取 Agent + 摘要 Agent + 校验 Agent”，结果延迟翻了三倍，错误率反而上升，因为三个 Agent 之间的信息传递又引入了新的失真点。

判断标准很简单：如果子任务之间是串行且强依赖的，用单 Agent 加状态机就够了；如果子任务可以并行、且各自需要不同的工具集和 prompt 策略，才考虑拆。比如一个“市场调研”任务，需要同时查竞品、查舆情、查财报，这三块互不依赖，拆成并行 Agent 就合理。

5.2 多 Agent 协作的核心是“接口”而不是“智能”

一旦决定拆，重点就不是让每个 Agent 多聪明，而是让它们之间的接口多清晰。每个 Agent 的输入输出必须是结构化的、可校验的。A Agent 的输出直接作为 B Agent 的输入时，中间要有一层 schema 校验，防止 A 的格式变化把 B 搞崩。

我通常会在 Agent 之间加一个“消息总线”层，所有跨 Agent 的通信都走统一的消息格式，带上来源、目标、类型、payload、时间戳。这样任何一个 Agent 出问题，都能快速定位是哪个环节产生的脏数据。

5.3 别让 Agent 之间“自由对话”

有些框架鼓励 Agent 之间用自然语言自由交流，看起来很酷，实际上很难调试。两个 Agent 聊着聊着就跑偏了，你根本不知道哪句话导致了错误决策。我的建议是：Agent 之间的通信尽量结构化，只在确实需要协商的场景才用自然语言，并且限制轮次。能用一个字段传的信息，不要用一段话。

6. 交付结果的最后一公里：可观测性与评估

6.1 没有 trace，就没有交付

Agent 系统最让人头疼的是“它为什么这么干”。用户投诉结果不对，你打开日志一看，只有最终输出，中间的决策过程一片空白。这时候你根本无从排查。可观测性不是可选项，是交付的必需品。

我的做法是给每一步都打 trace：输入是什么、模型返回什么、调用了哪个工具、工具返回什么、state 怎么变的、耗时多少、token 消耗多少。这些 trace 汇总起来，你就能完整回放一次任务执行。市面上有现成的 tracing 工具，但核心是你要在代码里埋点，而不是指望框架自动帮你搞定一切。

@dataclass class StepTrace: step_name: str input_snapshot: dict model_output: str tool_calls: list[dict] state_before: dict state_after: dict latency_ms: int token_usage: dict error: Optional[str] = None def traced_step(step_fn): def wrapper(state, *args, **kwargs): trace = StepTrace(step_name=step_fn.__name__, ...) try: result = step_fn(state, *args, **kwargs) trace.state_after = state.model_dump() return result except Exception as e: trace.error = str(e) raise finally: persist_trace(trace) return wrapper

6.2 评估不能只看最终结果

很多人评估 Agent 只看“最终答案对不对”，这远远不够。一个任务最终成功了，但中间调了 20 次工具、重试了 8 次、花了 5 分钟，这种成功在生产环境是不可接受的。评估要分层：最终结果准确率、步骤成功率、平均重试次数、平均延迟、token 成本。这几个指标要一起看，才能判断一个 Agent 是否真的可交付。

我通常会建一个回归测试集，覆盖正常场景、边界场景、异常场景。每次改动 prompt 或工具后，跑一遍回归，看各项指标有没有退化。没有回归测试的 Agent 开发，就是在裸奔。

6.3 人工兜底不是失败，是设计的一部分

最后说一个心态问题。很多工程师觉得 Agent 需要人工兜底是“没做好”，其实恰恰相反。在当前的模型能力下，完全无人值守的 Agent 只适用于极窄的场景。大多数生产级 Agent 都是“人机协作”模式：Agent 处理 80% 的常规情况，剩下 20% 的疑难或高风险情况转人工。关键是要把转人工的触发条件设计好——置信度低于阈值、涉及高风险操作、连续失败超过次数，这些都应该自动升级。

把人工兜底设计好，比追求 100% 自动化更现实，也更能交付真正有价值的结果。用户要的不是“全自动”，是“问题被解决”。

7. 一些关于工具选型和团队协作的实在话

7.1 框架选型：别被“全家桶”绑架

现在 Agent 框架层出不穷，Python 有 LangChain、LlamaIndex，Java 有 Spring AI，还有各种低代码平台。我的建议是：先用最薄的抽象把核心循环跑通，再按需引入框架。很多框架为了通用性做了大量封装，出问题时你根本不知道是哪一层在捣鬼。我见过团队用某个框架的 AgentExecutor，结果工具调用的参数被框架悄悄改了一层，排查了两天才发现。

如果你用 Java 技术栈，Spring AI 的抽象相对克制，适合企业级集成；如果用 Python，LangGraph 的状态机模型比早期的 Chain 更可控。但无论用哪个，核心逻辑要能脱离框架独立测试，这是底线。

7.2 团队里谁该做 Agent 工程师

热词里有人问“AI Agent 工程师”和“算法工程师”“运维工程师”的区别。我的观察是，Agent 工程师更像是一个“全栈问题解决者”：要懂模型的能力边界，要会写工程代码，要理解业务场景，要能做数据校验，要会设计评估方案。它不需要你训模型，但需要你知道模型什么时候会骗你；它不需要你搭集群，但需要你知道工具超时该怎么退避。

如果你是从后端转过来的，你的工程能力是优势，补一补 prompt 工程和评估方法就能上手；如果你是从算法转过来的，你对模型的理解是优势，补一补状态管理和错误处理就能落地。这个岗位的核心竞争力，是“把不确定的东西变得可交付”的能力。

7.3 一个练手项目的建议

如果你想练手，别一上来就做“全能助手”。选一个边界清晰、结果可验证的小任务，比如“根据给定的商品链接，抓取价格和库存，生成一份比价表”。这个任务包含了 Agent 的核心要素：工具调用、结构化输出、错误处理、结果校验。把它做到能在真实网站上稳定跑 100 次不出错，比做十个花哨的 Demo 都有价值。

我在带新人的时候，第一周就让他们做这个，做完基本就理解了 Agent 交付的全部痛点。工具会挂、页面会变、数据会缺、格式会乱，这些真实世界的脏东西，才是 Agent 工程师的日常。把这些处理好了，你交付的就不是一个“能聊天的模型”，而是一个“能干活的结果”。