AI Agent工程化：从脚本到可交付的Agent发行版

最开始做 AI Agent 的时候，我犯过所有新手都会犯的错：在 Notebook 里堆提示词，写死 API Key，本地跑通以后截图发到群里就当交付了。直到有一次，同事把同样一批代码部署到测试环境，跑出完全不一样的结果——不是因为环境差异，而是因为其中一部分逻辑依赖我本地的历史对话缓存。那一刻我才意识到，Agent 项目必须像 Linux 发行版一样，被当成一个独立的、可交付的完整系统来设计。

这篇分享不讲概念空话，只讲怎么把 Agent 从脚本升级成发行版：Profile 怎么做、组件怎么拆、生产部署怎么推，以及我在真实项目中踩过的坑。适合两类人看：一类是刚跑通 Agent Demo、准备往工程化方向走的开发者，另一类是已经在做 Agent 产品、但被配置混乱和部署问题反复折磨的团队。

1. 为什么是"发行版"而不是"一个 Agent 脚本"

"发行版"这个词是从 Linux 世界借来的。但很多人只是把它当成了一个营销噱头，真正理解它意味着什么的并不多。

1.1 从 Ubuntu 说起：发行版的本质是"可交付的完整形态"

Ubuntu、Debian、Fedora 这些 Linux 发行版，没有哪个是重新写了内核的。它们做的是另外一件事：把内核、GNU 工具链、包管理器、桌面环境、软件仓库、升级机制、默认配置这些散落的东西，整合成一个普通用户下载后就能开箱即用的整体。内核还是那个内核，但发行版决定了一个用户拿到手的到底是一堆源码包，还是一个能启动的桌面系统。

Agent 发行版的逻辑是一模一样的。把一个开源框架 clone 下来，这只是内核；把它变成一个业务能用的系统，你还需要解决一堆背后的问题。我自己的映射关系是这样的：

• LLM 模型 = 内核
• Agent 编排器 = init 系统，负责拉起整个运行循环
• Skill 工具集 = 发行版仓库里的应用软件
• Profile 配置体系 =/etc目录下的配置文件和默认策略
• Memory 记忆系统 = 用户数据目录，需要持久化、隔离、清理
• 部署与运维方案 = 升级机制和社区支持渠道

注意一个容易被忽略的点：发行版更偏重"软件包管理和升级机制"。iOS 和 Android 都是操作系统，但 iOS 不叫发行版，因为用户没法在系统层面自由地管理组件版本和切换组件来源。Agent 发行版之所以叫发行版，核心是它必须具备可组合、可版本化、可替换的组件管理能力。你今天的"发行版"里用的是 DeepSeek 的模型，明天换成一个开源的本地模型，应该只是 Profile 里一个字段的变更，而不是重写整个系统。

1.2 "套壳 Agent"和"Agent 发行版"的分界线

很多项目自以为在做发行版，其实就是个套壳：一段写死的系统提示词，加上一次 API 调用，包了一层接口。套壳和发行版之间有非常明显的分界线，我一般用下面这张表去判断：

判断标准其实非常朴素：如果改一个提示词需要动代码，那就是脚本；如果改一个提示词只需要换一个配置文件，这才是发行版的起点。

1.3 什么项目才值得做成发行版

不是所有 Agent 项目都值得往发行版方向做。我自己有三个标准，三个都满足才值得投入：

1. 你会长期维护它，至少超过一个季度，而且会有功能迭代。
2. 有别的人或其他系统要消费它，可能是业务方、是 API 调用方、是下游系统。
3. 业务对它有稳定性要求，错误会产生实际成本，哪怕只是客服响应时长增加。

反过来，如果只是做一个探索性实验、一份一次性的分析报告，或者只是周末写着玩，真的不需要上发行版。过度工程化也是一道坎。

2. 先拆零件：LLM、Agent、Memory、Skill、MCP 到底怎么分工

要构建发行版，先得把零件认全。很多项目做不好，就是因为把 Agent 等同于 LLM，以为在 API 请求里加几句 system prompt 就是一个 Agent 系统。这是对组件边界最深刻的一个误解。

2.1 LLM 只是引擎，不是整车

先厘清几个概念的关系。AI 模型是最大的集合，涵盖视觉、语音、决策、生成等各类模型；LLM 是其中的一大类，专门指以语言为核心能力的大模型；而 Agent 是基于 LLM 构建的完整系统，它要调用模型，但模型本身不是 Agent。

经常有人问"DeepSeek 属于哪个"，答案很清楚：DeepSeek 是模型供应商，它提供的是 LLM 模型本身，类似 OpenAI 提供 GPT 系列、Anthropic 提供 Claude 系列。DeepSeek 也有支持 Agent 编排的 API 格式，也定义了工具调用的接口规范——但如果你只是调用它的 API 做文本生成，那它就是一个 LLM；如果你构造了"规划-工具调用-记忆读写"的循环，才是在构建 Agent。也可以这样理解：发动机不是汽车，提供发动机的品牌也不等于造出了整车。DeepSeek 从来没有替你把"如何拆解任务、如何调用业务系统"这件事做了，这部分永远是 Agent 发行版的活儿。

2.2 Agent 编排器：调度中枢的核心职责

Agent 编排器是发行版里最容易被忽视、但绝对是最关键的组件。它做的事情包括：拆解用户目标、生成执行步骤、决定什么时候调用哪个 Skill、把工具返回的结果反馈回给模型、管理多轮对话的上下文状态、在需要时读写 Memory。

如果你不用现成的编排框架，想自己实现，那核心循环就是四步：观察→思考→行动→反馈。观察当前状态和用户输入，思考下一步该做什么，行动是调用工具或生成回复，反馈则是把行动结果重新喂回给模型。这个循环跑得顺不顺，决定了 Agent 是像个正常人一样解决问题，还是像个复读机一样只会说"我需要更多信息"。

我用过一个开源编排框架做企业内部的工单支持 Agent，最深的体会是：框架本身不产生价值，真正产生价值的是你对这个循环的控制程度——你允许多少轮工具调用、怎样防止模型陷入死循环、工具报错之后是重试还是把问题转给人工，这些策略才是发行版的核心资产。

2.3 Skill、Memory、MCP：发行版里的三大基础设施

Skill、Memory、MCP 这三样东西，很多人混着讲，但它们其实解决的是完全不同的问题。

Skill 是 Agent 的"手"，是它可以执行的工具函数。一个 Skill 通常包含名称、描述、参数结构和一个执行函数。关键点在于：工具描述写得清不清楚，直接决定模型会不会正确调用。我见过太多"模型明明有工具却不用"的案例，排查到最后都是工具描述写得太模糊。

Memory 是 Agent 的"仓库"，解决的是跨会话的状态保持问题。短期记忆就是当前会话的上下文，长期记忆可能是 Redis 里的用户偏好、向量数据库里的历史对话摘要。Memory 的核心难点不是存储，而是读写策略——什么时候写入、什么时候检索、检索多少条、冲突时听谁的。

MCP（Model Context Protocol）是 Agent 的"插座"，它是让模型通过标准协议访问外部数据源的一套规范。你不需要知道你的知识库是存放在 MySQL 里还是 Elasticsearch 里，只要把那边的数据包装成一个 MCP Server，Agent 这边就能以标准化方式去查询。它还处在快速发展期，但思路我非常认可：把连接外部世界的接口标准化，让发行版可以对接任意数据源，而不是每次对接一个新系统就要重新写一遍胶水代码。

举个具体的例子。我在做一个内部知识库问答 Agent 时，用户的提问先被编排器理解，然后通过 MCP 去内网文档服务里检索相关内容，把检索结果放进上下文，再用一个"工单创建"的 Skill 去帮用户自动建工单。整个过程里，模型只是负责理解和生成，检索靠 MCP，执行动作靠 Skill，跨会话记住用户身份靠 Memory。每一层干好一件事，发行版才不会在长大后变成一团浆糊。

3. Profile 定制：把"角色设定"变成工程化配置

Profile 是整个发行版的灵魂。我理解的 Profile 远不止是"系统提示词文件"，它应该是把角色人设、模型参数、技能权限、记忆策略、外部连接全部打包在一起的一套配置体系。这才是标题里"从 Profile 定制"的真正分量。

3.1 Profile 文件应该长什么样

先给一个我在企业支持场景下用过的 Profile 结构，这是经过几次重构后的版本：

meta: name: support-agent version: 1.4.0 entry: app.main:agent model: provider: deepseek name: deepseek-chat temperature: 0.3 top_p: 0.9 max_tokens: 2048 role: name: "IT 支持专员" system_prompt: | 你是企业 IT 支持专员。你的工作目标是在最短时间内解决员工 在办公网络、账号权限、软件安装等方面的问题。 要求： 1. 回答前先判断是否需要查询内部知识库。 2. 自己不确定时，必须明确回复"需要人工确认"，不得编造。 3. 所有涉及敏感权限的操作，必须先征求用户确认。 skills: - name: ticket.search enabled: true permission: read-only - name: ticket.create enabled: true permission: write - name: account.lock enabled: false memory: type: redis ttl_days: 7 namespace: prod-support mcp: servers: - name: internal-doc endpoint: http://mcp-doc.internal:3000/mcp scopes: [read]

这个 YAML 里每一块都有它的意义。meta是发行版的元信息，必须包含版本号，这是后面做 Profile 演进和回滚的基础。model段决定用哪个供应商、哪个模型、哪些采样参数。role段是角色定义，包含系统提示词和行为约束。skills段是技能挂载列表，每个技能都要标注权限。memory段定义记忆存储的形态。mcp段连接外部数据源。

我坚持用 YAML 而不是直接写 Python 字典，理由是：配置必须能脱离代码被人的眼睛审查。业务方的合规同事看不懂 Python，但能看懂 YAML；每次变更 Profile 都可以走代码评审，但配置文件的 diff 比代码 diff 容易理解得多，这在实际协作里节省了大量沟通成本。

3.2 技能绑定与权限最小化

我觉得这是 Profile 定制里最容易被低估的事情：不要把所有工具都挂给模型。

权限最小化有两个层面的收益。第一是降低误操作概率，模型在模糊场景下会倾向于"尝试执行"而不是"询问确认"，如果它手上没有危险工具，就天然没有误操作的可能。第二是节省 token，每多挂一个工具，工具定义描述就会多占用输入上下文的额度，而且模型在决策时也会多一分选择负担。

所以在 Profile 里，我建议每个技能都要写明permission字段。只读操作和写操作必须分开，高风险的写操作默认enabled: false，需要场景才手动打开。前段时间我们遇到过一次事故：Agent 把工单状态给写错了，原因就是配置里给了模型一个 "工单状态修改" 的工具，而模型在用户表达模糊时用了这个工具。后来我们直接把这类写操作改成默认禁用，需要操作时必须让用户明确说"帮我改"，才在 Profile 里开通。

还有一个细节：Skill 描述要在 Profile 层写得足够精确。模型靠名称和描述判断该不该用某个工具，描述写得太泛，就一定会在不该用的时候用。比如ticket.create的描述我一开始写的是"创建工单"，后来改成"当用户反馈问题且该问题需要其他团队处理时，创建工单并设置处理优先级"，调用准确率提升很明显。

3.3 上下文窗口的预算管理

上下文窗口是有上限的，而 Agent 的每次调用都在往里塞东西。如果不做预算管理，很容易出现两种情况：请求直接超出上下文上限而报错，或者因为历史记录太多而把关键指令挤出了有效窗口。

我习惯在 Profile 里设定一套预算分配比例，以 32k 上下文窗口为例：

这套比例不是拍脑袋定的，是对应各业务场景的需求。系统提示词必须完整保留，所以占比小但优先级高；外部检索内容对回答质量影响很大，但检索结果经常塞进一大堆无关片段，所以对这部分要做上限控制，超了要截断。历史对话是最容易膨胀的部分，我的做法是：每次打开的会话长度有限制，超过限制就把前面的对话做摘要后压缩进系统提示词。

执行预算管理的核心不是"算准了才调用"，而是在 Profile 里提前设好每个部分的上限，由代码强制执行，而不是指望模型自己控制。我会在配置里写明max_search_tokens: 6000、max_history_turns: 20，超过就裁剪、就摘要、就丢弃，绝不手软。

3.4 多环境 Profile 隔离

开发、测试、生产环境的 Agent 不可能共用同一个 Profile。最典型的例子：开发环境你就该用便宜的小模型，生产环境用更强的模型；开发环境的 MCP 指向 mock 服务，生产环境指向真实知识库；开发环境的 Memory 可以随便写，生产环境必须走独立的命名空间。

我的做法是把 Profile 拆成两层：一层是profile.base.yaml，存放所有环境共享的配置，比如系统提示词、技能定义、权限约束；另一层是profile.{env}.yaml，存放环境相关的配置，比如模型 provider、MCP endpoint、Memory 命名空间。启动时通过环境变量APP_ENV决定加载哪套组合，再对环境变量做展开（${REDIS_URL}之类）。

这样做的价值在发布当天就能感受到。你不需要小心翼翼地在生产环境改模型参数，因为生产 Profile 是独立文件；你也不需要担心开发环境的实验性配置污染生产数据，因为 Memory 的 namespace 早就分开了。

4. 生产部署全流程：从开发机到生产环境

Profile 定制再好，部署不落地都是纸上谈兵。这一节我讲部署过程中真正决定成败的几个节点，以及我实际使用的落地方案。

4.1 本地调试：把单次运行变成可复现流程

开发 Agent 最痛苦的事情是"明明跑通了一次，但不知道会不会再跑通"。因为 LLM 的生成有随机性，同一套配置对同一输入可能给出不同结果。所以第一步是建立"可复现调试"的习惯。

我的做法是维护一组固定测试样本（fixture）：把真实业务场景整理成十到二十个输入，每个输入附带期望的输出要求，比如"必须给出工单编号""必须引导用户补充权限等级"。每次改了 Profile，先跑这组 fixture，人工检查输出的稳定性。同时把这些 fixture 录制下来的请求和响应原样存档，以后排查问题的时候可以直接回放。

这里有一个重要原则：调试 Agent 时不要只盯着 prompt，要从 Profile 变化、模型版本、上下文内容三个维度去定位问题。有时候输出不对，不是 Prompt 写错了，而是 Profile 里模型参数变了，或者某一轮检索结果把模型带偏了。

4.2 自动化测试：不只是测 prompt

Agent 的测试体系拆成三层，每一层有各自的重点。

第一层是单元测试，针对 Skill 和编排逻辑。测试工具函数在给定参数时是否正确执行、权限校验是否生效、配置文件是否通过 schema 校验。注意 Profile 是 YAML 文件，里面的字段在启动时可能就会拼错、漏写，必须从上到下做一遍 schema 校验，我一般用 Pydantic 做配置模型的声明和校验，这层测试能挡住大部分低级错误。

第二层是集成测试，针对 MCP 数据源和 Memory 存储。验证接口连通性、返回格式、超时处理。集成测试最好在独立环境跑，用真实的知识库副本而不是线上库，否则很容易把脏数据写进生产环境。

第三层是评估测试（Eval），针对输出质量。LLM 的输出没有"对不对"的标准答案，所以我用一套评分规则去评估关键指标：回答是否包含必要信息、是否沿用所需格式、是否出现幻觉式表述。初期可以人工打分，后面可以引入 LLM 作为裁判，但要注意裁判模型与业务模型分开，避免评估结果被同一个模型的偏好左右。

4.3 容器化构建与发布

容器化是发行版"可交付"的必经之路。直接用一份我线上的 Dockerfile 结构：

FROM python:3.12-slim as builder WORKDIR /app COPY pyproject.toml requirements.lock ./ RUN pip install --no-cache-dir -r requirements.lock FROM python:3.12-slim WORKDIR /app COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages COPY app ./app COPY profiles ./profiles ENV PYTHONPATH=/app \ APP_ENV=production EXPOSE 8080 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

这里有个细节值得强调：运行时镜像和构建镜像分开，而且运行时镜像里不要放源码仓库的.git目录、不要放本地缓存、不要放模型文件。Agent 发行版的镜像应该只包含代码、依赖、Profile 配置文件三样东西，越小越好拉，越好回滚。模型本身走远程 API，或者挂载独立模型服务，不要打进应用镜像。

镜像版本标签我用 Git revision 加语义化版本，例如1.4.0-3f8a2c9。每次发布都能精确追溯这个镜像对应哪次代码提交、哪个 Profile 版本。

还需要一个健康检查端点。Agent 服务不能只看进程还在不在，还要看依赖是否健康。我会实现两个级别的探针：

@app.get("/readyz") async def readyz(): # 检查 LLM API 连通性、MCP Server 连通性、Memory 服务连通性 return {"status": "ready"} @app.get("/healthz") async def healthz(): return {"status": "alive", "revision": GIT_REVISION}

K8s 或者容器平台按这个探针轮询，只有/readyz返回 ready 才会放流量进来。

4.4 线上可观测性与快速回滚

Agent 系统的可观测性比普通 Web 服务更复杂，因为你既要看系统运行状态，还要看"模型在想什么"。我的日志规范是输出结构化的 JSON 事件，每个事件都带trace_id贯穿一次完整的用户请求，从用户输入到每次工具调用到最终回复，全部串在同一个trace_id下。

{"ts":"2025-06-12T10:00:00Z","level":"info","event":"agent.call","trace_id":"ab12cd34","profile":"support-agent:1.4.0","kv":{"model":"deepseek-chat","prompt_tokens":5200,"completion_tokens":320,"cost_usd":0.0127,"duration_ms":840}}

这套日志解决了两个痛点：第一是成本核算，每次调用的 token 数和费用都精确记录，月底对账不再靠感觉；第二是问题定位，用户反馈"回复不对"的时候，我能精确回放那一次调用用了哪些工具、检索到了什么内容、模型回复了什么，而不是靠猜。

发布策略上，我强烈建议做灰度。先在预发环境把新 Profile 跑一天，观察调用成功率和成本指标；再在线上放一小部分流量（比如 5%），观察有没有明显劣化；确认没问题再全量。回滚方案必须在发布前就准备好——上一版的镜像 tag 和配套的 Profile 版本提前记录在案，出问题一条命令切回去，而不是现场翻历史记录找旧配置。

5. 我踩过的坑：发行版真正稳定运行后才知道的事

这一节写的都是真实项目里踩过的坑，有些坑是我花了两三周才爬出来的，希望你能少走弯路。

5.1 模型供应商切换的隐藏成本

项目初期我用的是一个海外模型供应商，后来因为成本和合规考虑，想换成一个国内模型。表面上只改model.provider一个字段，实际下去全是坑：不同模型的系统提示词敏感度不一样，有些模型对"你是一个客服"这种简单人设没问题，但换一个模型可能就需要你用更细节的方式定义角色边界。工具调用格式也不同，有的模型支持 function calling，有的模型用得不好会出现工具参数瞎编。采样参数含义有差异，temperature在 A 模型取值范围是 0-1，在 B 模型可能是 0-2。

我的建议是：在 Profile 层做一个轻量的模型适配器，把"取模型参数"这块用统一接口封装起来，底层差异在适配器里消化掉。同时建立模型对比评估集，切换模型之前用同一组测试样本在两边各跑一遍，用事实数据说话，而不是凭感觉判断谁强谁弱。

5.2 记忆持久化带来的数据管理问题

Memory 是 Agent 里面最麻烦的组件，不是说技术上难，而是它带来了数据层面的复杂问题。共享 Memory namespace 会串号，用户 A 的历史信息可能被用户 B 的 Agent 检索到；记忆没有时间衰减，过期的偏好一直在干扰当前对话；还有数据合规问题，用户明确提出"忘掉我之前说的话"，你的系统真的能删干净吗。

我现在设计的 Memory 策略是：每个租户独立 namespace，用户的短期记忆和长期记忆分开存储，长期记忆写入前必须经过摘要模型，把原始对话压缩成结构化偏好；TTL 到期自动清理；明确提供"遗忘"操作，删除用户相关的所有记忆键值。这些规则在 Profile 里都写明，不能靠模型自觉。

5.3 版本兼容矩阵：Profile 与框架/模型版本的配套关系

这是一个直到现在很多团队都没意识到的问题。Profile 版本不是独立的，它和 Agent 框架版本、模型版本是强耦合的。我遇到过案例：升级了一次编排框架之后，旧的 Profile 里一个参数名被新框架废弃了，结果 Agent 的 Tool 调用一直失败，但错误信息不明显，排查了很久。

所以我在发布清单里强制要求记录一个兼容矩阵：

每次升级框架之前，先在预发环境跑一遍 Profile 校验，确认所有字段和默认值都兼容再谈上线。

5.4 成本失控：上下文越长越贵

最后讲一个所有 Agent 项目都要面对的现实问题：成本。LLM 的计费按 token 算，Agent 的每一次工具调用、每次 MCP 检索、每轮历史对话，都会把 token 数量往上推。一个没有上下文预算管理的 Agent，单次对话的成本可能会是普通聊天请求的五到十倍。

我们早期没有做预算控制时，一个月 token 费用高得惊人。后来上了三层控制：Profile 级限制上下文各组成部分的 token 上限，请求级跟踪每次调用的 token 消耗并设置超阈值告警，月度级按部门/应用维度的成本报表。只有把成本指标纳入观察体系，你才有动力去做上下文精简、做历史摘要、做检索结果的粗排过滤，而这些恰恰是让 Agent 发行版在真实业务里长期活下去的关键。

最后分享一点个人的体会。维护自己的 Agent 发行版，其实很像维护一个开源项目——关键不是一开始写了多少代码，而是把配置、测试、部署、回滚这套流程真正固定下来。如果你现在正从零开始做 Agent 项目，我建议你从一个小而真实的任务入手，第一天就把 Profile 独立出来，加上健康检查和结构化日志。这些基础工作看起来很不起眼，但它们决定了这个项目是只能跑通一次的脚本，还是一个能交付、能升级、能长期迭代的发行版。