1. 为什么“调用模型”只是起点“交付结果”才是分水岭我做了几年 AI 应用落地见过太多团队在同一个坑里反复摔跤Demo 跑得飞起一上生产就露馅。问题出在哪绝大多数人把 AI Agent 工程师的活儿理解成了“调通 API”。调通 API 确实只要半天但让 Agent 在真实业务里稳定交付结果可能需要半年。这个区别就像“会开车”和“能跑长途货运”的区别。会开车是基础但跑货运要考虑油耗、路线规划、货物安全、突发天气、车辆保养、成本核算。AI Agent 工程师的核心竞争力恰恰在后者。1.1 一个真实的翻车案例去年我参与过一个客服工单自动分类项目。团队里有个小伙子两天就把模型调用跑通了用户输入工单内容模型返回分类标签准确率在测试集上有 87%。大家觉得稳了直接上线。结果第一周就炸了。线上真实工单里混着大量口语化描述、错别字、中英文夹杂、甚至还有用户直接粘贴的聊天记录截图 OCR 文本。模型开始胡言乱语把“退款申请”分到“技术故障”把“账号被盗”分到“产品咨询”。更致命的是有些工单模型返回了格式错误的 JSON下游系统直接解析失败整个流程卡死。这个小伙子犯的错就是把“调用模型”当成了终点。他没有做输入清洗、没有做输出校验、没有做异常兜底、没有做置信度阈值控制、没有做人工复核通道。这些东西才是 AI Agent 工程师真正要解决的问题。1.2 “交付结果”到底包含什么我总结下来一个能交付结果的 AI Agent 系统至少包含以下层次层次调用模型交付结果输入处理直接拼接 prompt清洗、归一化、敏感信息脱敏、多模态对齐模型调用单次请求重试、降级、缓存、并发控制、成本控制输出处理直接返回文本结构化解析、格式校验、置信度过滤、兜底策略业务闭环无人工复核、反馈回流、效果监控、持续迭代工程保障无日志追踪、链路监控、灰度发布、回滚机制你看调用模型只占其中一小格。剩下的全是工程活儿。1.3 谁需要关注这个区别如果你正在做以下事情这篇文章就是写给你的从 0 到 1 搭建 AI Agent但不想只停留在 Demo 阶段负责企业级 AI Agent 应用平台需要保证稳定性和可维护性做 FDE 解决方案工程师需要向客户交付可用的 AI 系统带团队做 AI Agent 开发需要建立工程规范面试 AI Agent 相关岗位想搞清楚面试官到底在考什么接下来我会从架构设计、核心细节、实操过程、问题排查四个维度把“交付结果”这件事拆开讲透。2. 整体架构设计从“能跑”到“能扛”的思路拆解2.1 为什么不能“一个函数调到底”很多新手写 AI Agent就是一个函数接收输入拼 prompt调模型返回结果。这在 Demo 阶段没问题但生产环境会死得很惨。原因很简单生产环境的输入是不可控的模型输出是不可控的网络是不可控的下游系统也是不可控的。四个不可控叠加系统必然崩溃。我的做法是把整个流程拆成多个独立环节每个环节只做一件事环节之间通过明确定义的数据结构通信。这样任何一个环节出问题都能快速定位、替换、降级。2.2 分层架构的具体设计我通常把 AI Agent 系统分成五层接入层负责接收请求、鉴权、限流、请求去重。这一层不碰模型只做流量治理。预处理层负责输入清洗、格式归一化、敏感信息脱敏、多模态内容对齐。比如用户上传的图片先做 OCR音频先做转写然后统一成文本格式。编排层这是核心。负责决定调用哪个模型、用什么 prompt、是否需要多轮推理、是否需要调用外部工具、是否需要多 Agent 协作。后处理层负责输出解析、格式校验、置信度评估、兜底策略。如果模型输出不合格这一层要能拦截并触发重试或降级。反馈层负责记录日志、收集用户反馈、监控效果指标、触发模型迭代。这一层是系统持续进化的关键。2.3 编排层的设计取舍编排层是最容易过度设计的地方。我见过有人一上来就搞多 Agent 协作、复杂的状态机、动态规划结果调试成本极高效果还不一定好。我的建议是从单 Agent 加工具调用开始遇到瓶颈再升级。具体来说先用一个主 Agent 加几个工具函数比如搜索、计算、数据库查询把业务流程跑通。当发现单 Agent 处理复杂任务时容易迷失、或者不同子任务需要不同 prompt 策略时再拆成多 Agent。拆多 Agent 的时候我推荐用“主管-工人”模式一个主管 Agent 负责理解任务、拆解步骤、分配子任务多个工人 Agent 各自负责一个具体子任务。主管 Agent 不直接调用模型做具体工作只做调度。这种模式的好处是职责清晰每个 Agent 的 prompt 可以针对性优化调试时也容易定位问题。2.4 模型选型的考量模型选型不是“哪个最强用哪个”而是“哪个最合适用哪个”。我通常从四个维度评估能力匹配度任务需要什么能力是文本理解、代码生成、数学推理、还是多模态不同模型在不同任务上表现差异很大。成本按 token 计费的模型要估算平均每次请求的 token 消耗乘以日均请求量算出月成本。有些模型单价低但输出啰嗦实际成本反而高。延迟实时交互场景对延迟敏感可能需要用更小的模型或者流式输出。异步批处理场景则可以接受更高延迟。稳定性API 的可用性、限流策略、错误码规范这些都要提前摸清楚。我的经验是主力模型选一个能力均衡的再配一个轻量模型做简单任务降级再配一个备用模型做故障切换。这样既有成本优化又有容错能力。2.5 数据流设计数据流设计的原则是每一步的输入输出都要可追溯、可回放。我通常会在每个环节记录结构化日志包含请求 ID、时间戳、环节名称、输入摘要、输出摘要、耗时、状态码。这样出问题时可以通过请求 ID 把整条链路串起来看。日志里不要记录完整的用户输入和模型输出因为可能包含敏感信息。我一般只记录摘要和哈希值需要详细内容时再通过安全通道调取。3. 核心细节解析那些决定成败的关键环节3.1 输入清洗垃圾进垃圾出输入清洗是很多人忽略的环节但它直接决定模型输出的质量。我通常做以下几件事去除无关字符比如多余的空格、换行、特殊符号、HTML 标签。这些字符会干扰模型理解还可能被恶意利用来做 prompt 注入。统一格式日期统一成 ISO 格式金额统一成数字加币种地址统一成结构化字段。这样模型更容易理解输出也更容易解析。处理错别字和口语化表达可以用规则加模型的方式做归一化。比如“咋整”归一成“怎么办”“牛批”归一成“很好”。这一步能显著提升模型理解准确率。敏感信息脱敏手机号、身份证号、银行卡号、邮箱等在送入模型前要替换成占位符。模型返回后再替换回来。这既是合规要求也能防止模型把敏感信息写进日志。注意脱敏和还原的映射关系要存在安全的地方不能和日志放在一起。3.2 Prompt 设计不是写作文是写合同Prompt 设计的本质是“和模型签订一份合同”你告诉它输入是什么、输出应该是什么格式、有哪些约束条件、遇到不确定的情况怎么处理。我写 prompt 通常包含以下部分角色定义一句话说明模型扮演什么角色。比如“你是一个客服工单分类助手”。任务描述清晰说明要做什么。避免模糊词汇比如“分析一下”就不如“判断以下工单属于哪个分类”。输入格式说明输入数据的结构。如果有多个字段用明确的标记分隔。输出格式这是最重要的部分。我通常要求模型输出 JSON并给出 schema。比如{ category: 退款申请 | 技术故障 | 产品咨询 | 账号问题 | 其他, confidence: 0.0 到 1.0 之间的浮点数, reason: 简短说明分类理由 }约束条件比如“如果无法确定分类category 填‘其他’confidence 填 0.5 以下”。示例给两到三个输入输出示例覆盖典型情况和边界情况。示例比长篇描述更有效。实操心得prompt 不是越长越好。我见过有人写了两千字的 prompt模型反而抓不住重点。我的经验是核心约束不超过十条示例不超过三个总长度控制在五百字以内。3.3 输出解析不要相信模型会乖乖听话即使你在 prompt 里明确要求输出 JSON模型也可能返回带 markdown 代码块的 JSON、带解释文字的 JSON、甚至格式错误的 JSON。所以输出解析必须做容错。我的解析流程通常是先尝试直接 JSON 解析失败则尝试提取代码块中的内容再解析再失败则用正则表达式提取关键字段再失败则触发重试用更严格的 prompt 重新请求重试仍失败则走兜底策略比如返回默认值并标记人工复核每一步失败都要记录日志方便后续分析模型输出的常见问题模式。3.4 置信度控制知道模型什么时候不靠谱模型输出的置信度不一定是校准过的但可以作为参考。我通常设置两级阈值高置信度阈值比如 0.85。高于这个值直接采纳结果。低置信度阈值比如 0.6。低于这个值直接走人工复核。中间区间可以走二次验证比如用另一个模型重新判断或者用规则引擎交叉验证。阈值的选择需要根据业务容忍度来定。如果错误代价高就提高高置信度阈值如果人工成本高就降低低置信度阈值。上线后要根据实际效果持续调整。3.5 工具调用的设计AI Agent 和普通模型调用的区别之一就是可以调用外部工具。工具调用的设计要注意几点工具描述要清晰模型根据工具描述来决定是否调用、怎么调用。描述要说明工具的功能、输入参数、输出格式、适用场景。参数校验要严格模型生成的参数可能格式错误、类型错误、甚至包含恶意内容。调用工具前必须校验。调用结果要处理工具可能返回错误、超时、空结果。这些情况都要有对应的处理逻辑。调用次数要限制防止模型陷入循环调用要设置最大调用次数和超时时间。3.6 多轮对话的状态管理多轮对话场景下状态管理是个难点。我通常把对话状态分成三类会话状态整个对话共享的上下文比如用户身份、历史摘要。轮次状态当前轮次的输入输出比如用户最新消息、模型最新回复。任务状态如果对话涉及多步任务需要记录任务进度、已完成步骤、待完成步骤。状态存储我推荐用 Redis 加数据库的组合Redis 存热状态保证低延迟读取数据库存冷状态保证持久化和可追溯。4. 实操过程从零搭建一个能交付结果的 AI Agent4.1 环境准备与依赖安装我以 Python 技术栈为例因为生态最成熟。核心依赖包括pip install fastapi uvicorn redis sqlalchemy pydantic httpx tenacityfastapi提供 HTTP 接口uvicornASGI 服务器redis状态存储和缓存sqlalchemy数据库 ORMpydantic数据校验httpx异步 HTTP 客户端用于调用模型 APItenacity重试库模型调用我推荐用官方 SDK 或者兼容 OpenAI 格式的客户端这样切换模型时改动最小。4.2 项目结构设计我通常这样组织代码agent_project/ ├── app/ │ ├── main.py # 入口 │ ├── config.py # 配置 │ ├── api/ │ │ ├── routes.py # 路由 │ │ └── schemas.py # 请求响应模型 │ ├── core/ │ │ ├── preprocess.py # 预处理 │ │ ├── orchestrator.py # 编排 │ │ ├── postprocess.py # 后处理 │ │ └── feedback.py # 反馈 │ ├── models/ │ │ └── client.py # 模型客户端 │ ├── tools/ │ │ └── registry.py # 工具注册 │ └── utils/ │ ├── logger.py # 日志 │ └── security.py # 脱敏 ├── tests/ └── requirements.txt这种结构的好处是每个环节独立方便单元测试和替换。4.3 模型客户端的封装模型客户端要处理几件事重试、超时、降级、成本记录。import httpx from tenacity import retry, stop_after_attempt, wait_exponential class ModelClient: def __init__(self, api_key, base_url, model_name, timeout30): self.api_key api_key self.base_url base_url self.model_name model_name self.timeout timeout retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max10)) async def call(self, messages, temperature0.1, max_tokens1000): async with httpx.AsyncClient(timeoutself.timeout) as client: response await client.post( f{self.base_url}/chat/completions, headers{Authorization: fBearer {self.api_key}}, json{ model: self.model_name, messages: messages, temperature: temperature, max_tokens: max_tokens } ) response.raise_for_status() return response.json()重试策略用指数退避避免雪崩。超时设置要合理太短容易误判太长会拖垮整个链路。4.4 预处理环节的实现预处理的核心是清洗和归一化。我通常写一个管道把多个处理函数串起来class Preprocessor: def __init__(self): self.steps [ self.remove_html, self.normalize_whitespace, self.mask_sensitive, self.normalize_text ] def process(self, text): for step in self.steps: text step(text) return text def remove_html(self, text): import re return re.sub(r[^], , text) def normalize_whitespace(self, text): import re return re.sub(r\s, , text).strip() def mask_sensitive(self, text): import re text re.sub(r\d{11}, [PHONE], text) text re.sub(r\d{18}, [ID], text) return text def normalize_text(self, text): replacements {咋整: 怎么办, 牛批: 很好} for k, v in replacements.items(): text text.replace(k, v) return text脱敏映射要单独存储返回时再还原。4.5 编排环节的实现编排环节我推荐用状态机的方式把流程定义成状态和转移class Orchestrator: def __init__(self, model_client, tools): self.model_client model_client self.tools tools self.max_steps 5 async def run(self, user_input, context): messages self.build_messages(user_input, context) for step in range(self.max_steps): response await self.model_client.call(messages) content response[choices][0][message][content] tool_call self.parse_tool_call(content) if tool_call: result await self.execute_tool(tool_call) messages.append({role: assistant, content: content}) messages.append({role: user, content: f工具返回{result}}) else: return content return 任务步骤过多已终止最大步数限制是防止模型陷入循环。工具调用解析要容错解析失败就当普通回复处理。4.6 后处理环节的实现后处理的核心是解析和校验class Postprocessor: def parse_json(self, text): import json, re try: return json.loads(text) except json.JSONDecodeError: pass match re.search(rjson\s*(.*?)\s*, text, re.DOTALL) if match: try: return json.loads(match.group(1)) except json.JSONDecodeError: pass match re.search(r\{.*\}, text, re.DOTALL) if match: try: return json.loads(match.group(0)) except json.JSONDecodeError: pass return None def validate(self, data, schema): from pydantic import BaseModel, ValidationError try: return schema(**data) except ValidationError as e: return None解析失败要触发重试或兜底不能直接返回错误给用户。4.7 反馈环节的实现反馈环节记录每次请求的完整链路用于后续分析和迭代class FeedbackCollector: def __init__(self, db): self.db db def record(self, request_id, stage, input_summary, output_summary, latency, status): self.db.insert({ request_id: request_id, stage: stage, input_summary: input_summary, output_summary: output_summary, latency: latency, status: status, timestamp: time.time() })记录摘要而不是完整内容既保护隐私又节省存储。4.8 部署与监控部署我推荐容器化用 Docker 打包Kubernetes 编排。关键配置包括副本数至少两个保证高可用资源限制CPU 和内存要留余量防止模型调用时内存暴涨健康检查定期检查模型 API 连通性日志收集统一收集到日志平台方便检索监控指标我通常关注指标说明告警阈值请求成功率成功请求占总请求比例低于 95%平均延迟端到端响应时间超过 5 秒模型调用失败率模型 API 调用失败比例超过 5%解析失败率输出解析失败比例超过 3%人工复核率走人工复核的请求比例超过 20%这些指标要持续观察发现异常及时排查。5. 常见问题与排查技巧实录5.1 模型输出格式不稳定这是最常见的问题。同一个 prompt模型有时返回纯 JSON有时返回带解释的 JSON有时返回 markdown 代码块。排查思路先看日志里模型返回的原始内容统计格式分布。如果格式错误率超过 5%说明 prompt 需要优化。解决方法在 prompt 里明确说“只返回 JSON不要任何其他文字”给出严格的 JSON schema用 few-shot 示例展示正确格式后处理做多层解析容错设置重试机制重试时用更严格的 prompt5.2 模型调用超时模型 API 偶尔会超时尤其是高峰期。排查思路看日志里的延迟分布区分是模型本身慢还是网络问题。解决方法设置合理的超时时间我一般设 30 秒用重试机制指数退避准备备用模型主模型超时后切换对延迟敏感的场景用流式输出先返回部分结果5.3 成本失控模型调用成本容易失控尤其是请求量大的时候。排查思路统计每次请求的平均 token 消耗乘以日均请求量算出月成本。对比预算看是否超标。解决方法优化 prompt减少不必要的 token简单任务用轻量模型加缓存相同输入直接返回缓存结果设置单用户调用频率限制监控 token 消耗设置告警5.4 多轮对话上下文丢失多轮对话场景下模型可能忘记之前的对话内容。排查思路检查上下文拼接逻辑看是否正确传递了历史消息。解决方法维护完整的消息列表每次请求都带上上下文过长时做摘要压缩关键信息提取成结构化字段单独存储用会话 ID 关联多轮请求5.5 工具调用参数错误模型生成的工具调用参数可能格式错误、类型错误、缺少必填字段。排查思路记录每次工具调用的参数和结果统计错误类型。解决方法工具描述里明确参数类型和格式调用前做参数校验校验失败时把错误信息返回给模型让它重新生成设置最大重试次数防止无限循环5.6 常见问题速查表问题可能原因排查方法解决方案输出格式错误prompt 不明确看原始输出优化 prompt加解析容错调用超时网络或模型慢看延迟分布重试备用模型流式输出成本过高token 消耗大统计 token优化 prompt缓存限流上下文丢失拼接逻辑错误检查消息列表维护完整上下文摘要压缩工具参数错误模型理解偏差记录参数参数校验错误反馈重试置信度低任务难度高看置信度分布人工复核二次验证并发上不去资源瓶颈看资源使用率扩容异步处理队列效果波动模型更新或数据漂移对比历史指标监控告警定期评估模型切换5.7 独家避坑技巧技巧一灰度发布。新 prompt 或新模型上线前先切 5% 流量观察指标正常再逐步扩大。我见过直接全量上线导致事故的案例。技巧二请求去重。相同用户短时间内重复提交相同内容直接返回缓存结果。这能显著降低模型调用量。技巧三降级预案。主模型不可用时自动切换到备用模型或规则引擎。降级后的效果可能差一些但至少系统可用。技巧四人工复核通道。低置信度结果自动进入人工复核队列复核结果回流作为训练数据。这既能保证质量又能持续优化模型。技巧五定期评估。每周抽一批线上请求做人工评估对比模型输出和人工判断计算准确率、召回率等指标。发现下降及时排查。技巧六版本管理。prompt、模型配置、工具定义都要版本化每次变更记录变更内容和原因。出问题时可以快速回滚。技巧七压力测试。上线前做压力测试模拟峰值流量看系统能否扛住。我一般按预估峰值的 1.5 倍来测。技巧八成本预算。给每个用户或每个业务线设置成本预算超预算自动降级或限流。防止个别用户刷爆成本。6. 从工程师到结果交付者的能力升级6.1 思维方式的转变调用模型的思维是“我发一个请求模型返回一个结果”。交付结果的思维是“用户有一个需求我要保证这个需求被可靠地满足”。这两种思维的差异体现在很多细节上。比如调用模型的思维会问“这个模型支持多长上下文”交付结果的思维会问“上下文超长时我怎么压缩、怎么降级、怎么保证关键信息不丢失”。再比如调用模型的思维会问“这个模型准确率多少”交付结果的思维会问“准确率不达标时我怎么兜底、怎么人工介入、怎么持续优化”。6.2 必备技能清单一个能交付结果的 AI Agent 工程师需要具备以下技能工程能力熟悉后端开发、API 设计、数据库、缓存、消息队列、容器化部署。模型能力理解模型原理、prompt 工程、上下文管理、工具调用、多 Agent 协作。数据能力会做数据清洗、数据标注、效果评估、A/B 测试。业务能力理解业务场景、用户需求、成本约束、合规要求。运维能力会做监控、告警、日志分析、故障排查、容量规划。这些技能不需要每项都精通但至少要能覆盖整个链路。6.3 面试中如何体现“交付结果”的能力如果你在面试 AI Agent 相关岗位面试官问“你做过什么 AI Agent 项目”不要只说“我调用了某某模型实现了某某功能”。要说业务场景是什么用户需求是什么系统架构怎么设计的为什么这么设计遇到了哪些问题怎么排查和解决的效果指标是什么怎么监控和优化的成本是多少怎么控制的如果重做一次会怎么改进这样面试官才能看出你是一个能交付结果的工程师而不是一个只会调 API 的脚本小子。6.4 团队协作中的角色定位在团队里AI Agent 工程师往往需要和产品、算法、后端、运维、业务方多方协作。和产品协作时要能把业务需求翻译成技术方案也要能指出哪些需求技术上不可行或成本过高。和算法协作时要能理解模型的能力边界也要能反馈线上效果数据帮助算法优化。和后端协作时要能定义清晰的接口和数据格式也要能处理各种异常情况。和运维协作时要能提供监控指标和告警规则也要能快速定位和解决线上问题。和业务方协作时要能解释技术限制也要能收集反馈持续迭代。6.5 持续学习的方向AI Agent 领域变化很快新模型、新框架、新工具层出不穷。我的学习方法是跟紧主流模型更新关注主流模型的能力变化、价格调整、API 更新。研究开源框架看主流 Agent 框架的设计思路取其精华。动手做小项目每学一个新东西就做一个小项目验证。光看文档记不住动手做一遍就懂了。参与社区讨论看别人的踩坑经验避免重复踩坑。定期复盘每个月复盘自己做过的项目总结哪些做得好、哪些可以改进。我个人在实际操作中的体会是AI Agent 工程师这个岗位技术只是一部分更重要的是对业务的理解和对结果的负责。一个能交付结果的工程师价值远高于一个只会调用模型的工程师。这个差距在职业发展的中后期会越来越明显。最后再分享一个小技巧每次上线新功能前我都会问自己三个问题——如果模型挂了怎么办如果输出错了怎么办如果用户量涨十倍怎么办能把这三个问题回答清楚系统基本就能扛住生产环境了。
