1. 从纯文本到多模态Agent 感知能力的质变节点过去两年里我一直在做 Agent 相关的开发工作从最早的纯文本对话机器人到后来接入工具调用再到现在处理图像、音频、视频等多模态输入整个技术栈的变化速度远超我最初的预期。这篇文章不是教程也不是什么系统性综述就是我在实际项目中踩过的坑、做过的取舍、以及一些反复验证后觉得值得分享的经验。如果你正在做 Agent 开发或者准备把大模型能力接入到自己的产品里这些内容应该能帮你少走一些弯路。先说多模态这件事。很多人觉得多模态就是让模型能看图这个理解太浅了。多模态的本质是感知通道的扩展它改变的不只是输入格式而是整个 Agent 的信息处理链路。我举个实际场景在一个文档处理 Agent 里用户上传了一张扫描件里面有表格、有手写批注、有印章。纯文本模型面对这种输入基本无能为力但多模态模型可以同时提取版面结构、文字内容和视觉标记这三类信息融合之后Agent 才能做出真正有价值的判断。1.1 多模态输入在 Agent 链路中的真实位置我在设计 Agent 架构时习惯把多模态处理放在感知层而不是理解层。这个区分很重要。感知层负责把原始输入图片、音频、PDF转成结构化表示理解层才负责语义推理和决策。为什么这样分因为多模态模型的输出往往是不稳定的——同一张图不同调用可能给出不同粒度的描述。如果你把多模态输出直接当作推理依据整个 Agent 的行为会变得不可预测。我的做法是多模态模型只负责看到了什么输出一份结构化的感知报告然后由文本模型基于这份报告做推理。比如处理一张商品图多模态模型输出的是主体是一双运动鞋颜色为黑白配色鞋面有网眼材质背景为纯白而不是直接让多模态模型判断这双鞋适合跑步还是休闲。后者交给文本模型结合知识库来做准确率和可控性都高得多。1.2 多模态带来的 Token 成本与延迟问题这是最容易被低估的问题。一张 1024x1024 的图片经过编码后占用的 Token 数量可能相当于几百甚至上千个文本 Token。如果你的 Agent 需要处理大量图片成本会迅速失控。我做过一个粗略的测算在一个日均处理 5000 张图片的 Agent 里如果每张图平均消耗 800 个视觉 Token光视觉部分的日消耗就是 400 万 Token这还不算后续推理的文本 Token。延迟方面更麻烦。多模态推理的耗时通常是纯文本的 3 到 8 倍具体取决于图片分辨率和模型架构。我试过在实时对话场景里直接调用多模态模型用户等待时间经常超过 5 秒体验很差。后来改成异步预处理 缓存的方案用户上传图片后Agent 先返回一个确认响应后台异步完成多模态解析把结果缓存起来等用户下一轮提问时直接命中缓存。这样用户感知到的延迟就降到了正常对话水平。注意多模态缓存要设计合理的失效策略。同一张图片在不同上下文里可能需要不同粒度的解析不能简单按图片哈希缓存。1.3 多模态与工具调用的协同设计多模态能力不是孤立的它必须和工具调用协同工作。我遇到过一个典型场景Agent 需要根据用户上传的图表截图去数据库里查询对应的数据。这里的链路是——多模态模型识别图表类型和坐标轴含义文本模型生成查询语句工具调用执行查询最后把结果和原图一起呈现给用户。这个链路里最容易出问题的是多模态输出的结构化程度。如果多模态模型只是给出一段自然语言描述后续的工具调用就很难精确匹配。我的经验是在多模态 Prompt 里强制要求输出 JSON 格式字段包括content_type、extracted_text、visual_elements、confidence等。这样后续处理链路可以直接解析不需要再做一次语义理解。2. Harness 工程Agent 稳定运行的隐形骨架Harness 这个词在 Agent 开发圈里越来越常见但很多人对它的理解还停留在测试框架的层面。实际上Harness 在 Agent 系统里的角色更像是运行时骨架——它负责编排模型调用、管理上下文、处理异常、控制流程。我见过太多 Agent 项目模型选得很好Prompt 也调得不错但一上生产就各种问题根源往往就是 Harness 层没设计好。2.1 Harness 到底解决什么问题用一个类比来说明如果把大模型比作发动机那 Harness 就是变速箱和底盘。发动机再好没有合适的传动系统车也跑不起来。Harness 要解决的核心问题包括上下文管理Agent 的多轮对话、工具调用结果、多模态感知报告这些信息如何组织、截断、压缩直接决定了模型能否做出正确决策。调用编排一次用户请求可能触发多次模型调用感知、推理、生成这些调用的顺序、依赖、并行策略需要统一管理。异常处理模型超时、返回格式错误、工具调用失败这些异常如果不在 Harness 层统一处理每个业务逻辑里都要写一遍代码会变得极其混乱。可观测性Agent 的决策过程是黑盒Harness 需要记录每一步的输入输出方便排查问题和优化效果。我在项目里把 Harness 设计成一个独立层业务逻辑只负责定义做什么Harness 负责怎么做和出错了怎么办。这个分层带来的最大好处是当模型版本升级或者 Prompt 调整时业务代码几乎不需要改动。2.2 上下文窗口的精细化管理策略上下文管理是 Harness 里最核心也最容易被做糙的部分。很多人就是简单地把历史消息拼在一起超长了就从头截断。这种做法在简单场景下能用但在复杂 Agent 里会出大问题。我的策略是分层上下文层级内容保留策略系统层角色定义、能力边界、输出格式要求始终保留不截断任务层当前任务的目标、约束、已完成步骤始终保留动态更新感知层多模态解析结果、工具返回数据按相关性排序保留 Top-N对话层历史对话消息滑动窗口 摘要压缩临时层中间推理结果、草稿用完即弃不进入下一轮这个分层的关键在于不同层级的信息有不同的生命周期。系统层和任务层是长期有效的感知层和对话层是中期有效的临时层是单次有效的。把它们混在一起管理就会出现该记的没记住该忘的没忘掉的情况。具体实现上我用一个 ContextManager 类来管理这些层级每层有独立的 Token 预算。当总预算超限时按优先级从低到高逐层压缩。对话层的压缩用摘要模型来做把多轮对话压缩成一段简短摘要保留关键信息。2.3 重试、降级与熔断Harness 的容错设计Agent 系统里模型调用失败是常态而不是异常。网络抖动、限流、模型过载这些都会导致调用失败。如果每次失败都直接抛给用户体验会非常差。我在 Harness 里设计了三层容错重试对于超时和限流类错误自动重试 2 到 3 次每次间隔指数退避。重试时要确保幂等避免重复执行有副作用的操作。降级如果重试仍然失败切换到备用模型或简化流程。比如多模态解析失败时降级为让用户手动描述图片内容。熔断如果某个模型或工具在短时间内连续失败超过阈值暂时切断对该依赖的调用直接走降级路径避免雪崩。这套机制听起来简单但实际落地时有很多细节。比如重试的间隔怎么定我的经验是初始间隔 1 秒每次翻倍最多重试 3 次。熔断阈值我设的是 60 秒内失败 5 次熔断后 30 秒进入半开状态试探一次。这些参数需要根据实际业务场景调整没有万能值。提示熔断状态要持久化不能只放在内存里。否则服务重启后熔断状态丢失可能瞬间打爆下游依赖。2.4 可观测性让 Agent 的决策过程可追溯Agent 最让人头疼的地方就是它为什么这么回答。没有可观测性排查问题基本靠猜。我在 Harness 里强制记录每次模型调用的完整信息输入 Prompt、输出内容、Token 消耗、耗时、模型版本、调用链 ID。这些数据我分成两个用途实时监控和离线分析。实时监控看的是成功率、延迟、Token 消耗趋势一旦异常就告警。离线分析看的是具体案例的决策链路用来优化 Prompt 和调整策略。这里有个经验调用链 ID 要贯穿整个请求生命周期。从用户发起请求到多模态解析、文本推理、工具调用、最终生成所有环节都用同一个 Trace ID 串联。这样排查问题时可以一键拉出完整链路不用在多个日志文件里来回翻。3. MCP 协议Agent 工具生态的标准化尝试MCPModel Context Protocol是最近被讨论得比较多的一个话题。简单说它试图定义一套标准协议让 Agent 和外部工具之间的交互有章可循。我在项目里接入了 MCP 之后最大的感受是它解决的不是技术问题而是协作问题。3.1 MCP 要解决的核心痛点在没有 MCP 之前每个 Agent 框架都有自己的工具定义方式。LangChain 有一套Semantic Kernel 有一套各家云厂商的 Agent 平台又各有一套。结果是你为一个框架写的工具换一个框架就得重写。工具提供方也很痛苦要适配多个框架维护成本极高。MCP 的思路是定义一个中间层协议工具提供方只需要实现 MCP ServerAgent 侧只需要实现 MCP Client双方通过标准协议通信。这样工具就可以跨框架复用生态才能起来。我用一个实际例子来说明价值。我们内部有一个知识库检索服务之前为三个不同的 Agent 项目分别写了三套适配代码。接入 MCP 之后只需要维护一个 MCP Server三个项目都能用。维护成本直接降了三分之二。3.2 MCP Server 的实现要点与常见坑实现一个 MCP Server 看起来简单但有几个坑我踩过第一个坑是工具描述的粒度。MCP 要求每个工具提供名称、描述、参数 schema。描述写得太粗模型不知道怎么用写得太细又容易和别的工具混淆。我的经验是描述里要包含什么时候用这个工具和什么时候不要用这比单纯描述功能更重要。第二个坑是错误处理。MCP 协议定义了错误返回格式但很多实现只是简单抛异常。模型收到一个模糊的错误信息往往不知道怎么处理。我现在的做法是错误信息里包含错误类型和建议的下一步操作让模型能自主决策是重试、换工具还是告知用户。第三个坑是超时控制。MCP 调用是跨进程甚至跨网络的超时设置不合理会导致 Agent 卡死。我的设置是单个工具调用超时 10 秒整个 MCP 会话超时 30 秒。超时后返回明确的超时错误让 Harness 层决定是否重试。3.3 MCP 与多模态、Harness 的三角关系这三者不是独立的而是相互支撑的。我画一个简单的依赖关系Harness 是调度中心它决定什么时候调用多模态模型什么时候调用 MCP 工具什么时候直接生成回复。多模态是感知输入它把非文本输入转成结构化信息供 Harness 决策。MCP 是能力扩展它让 Agent 能调用外部工具突破模型自身能力的边界。在实际项目里这三者的协作流程通常是用户输入可能包含图片→ 多模态解析 → Harness 判断意图 → 如果需要外部数据通过 MCP 调用工具 → 工具返回结果 → Harness 整合信息 → 模型生成最终回复。这个流程里Harness 的编排逻辑决定了整个系统的上限。我见过一些项目多模态和 MCP 都接入了但 Harness 层只是简单串行调用结果延迟高、成本高、效果还不好。优化 Harness 的编排策略往往比换更强的模型收益更大。4. 实战中的取舍一个多模态 Agent 的完整落地复盘前面讲了很多原理和设计这一节我用一个实际项目来串一遍。这个项目是一个面向内部团队的文档助手 Agent需要处理用户上传的 PDF、图片、表格并结合内部知识库回答问题。项目从立项到上线大概用了两个月中间经历了几次架构调整。4.1 第一版架构为什么失败第一版架构很直接用户上传文件 → 多模态模型解析 → 把解析结果和问题一起发给文本模型 → 返回答案。听起来没问题但上线后问题很多。首先是解析质量不稳定。同一份 PDF有时候解析出完整的表格结构有时候只给出零散的文字。原因是多模态模型对复杂版面的理解本身就有波动。其次是上下文爆炸。一份 20 页的 PDF 解析出来的文本可能有上万字加上知识库检索结果上下文直接超限。最后是无法处理追问。用户看完答案后追问细节Agent 因为上下文已经被截断完全接不上。这一版跑了大概两周用户满意度很低我们决定推倒重来。4.2 第二版引入 Harness 分层与 MCP 工具化第二版的核心改动是引入 Harness 分层和 MCP 工具化。Harness 层负责文件解析任务的异步调度、上下文的分层管理、多轮对话的状态维护。具体来说用户上传文件后Harness 立即返回正在解析的状态后台异步调用多模态模型。解析结果按页面、按段落结构化存储而不是拼成一大段文本。MCP 工具化方面我们把知识库检索、文档片段查询、表格数据提取都封装成 MCP 工具。Agent 不再一次性把所有信息塞进上下文而是按需调用工具获取相关信息。这样上下文占用大幅降低而且信息更精准。多模态解析也做了调整。不再让多模态模型输出自由文本而是要求输出结构化 JSON包含页面编号、内容类型、文本内容、位置信息。这样后续可以按页、按段检索而不是全文塞入。这一版上线后效果明显改善。但还有优化空间主要是延迟和成本。4.3 第三版缓存、并行与降级的精细化第三版主要做工程优化。缓存策略多模态解析结果按文件哈希缓存同一文件多次上传不重复解析。知识库检索结果按查询语义缓存相似查询命中缓存。这两项缓存把平均响应时间从 8 秒降到了 3 秒左右。并行化Harness 里把可以并行的调用拆开。比如多模态解析和知识库预检索可以并行不用等解析完再检索。并行之后端到端延迟又降了大概 30%。降级策略多模态解析失败时降级为提示用户手动输入关键信息。知识库检索超时时降级为基于模型自身知识回答并标注未检索到内部资料。这些降级路径保证了即使部分依赖出问题Agent 仍然可用。4.4 上线后的真实数据与经验教训上线三个月后我拉了一些数据日均处理请求 1200 次左右多模态解析成功率 94%知识库检索成功率 98%端到端 P95 延迟 4.2 秒用户满意度评分 4.1/5。几个教训值得记录第一不要追求一次性完美解析。多模态解析有波动是正常的关键是 Harness 层要能处理这种波动。我们的做法是解析置信度低于阈值时主动向用户确认关键信息而不是硬着头皮往下走。第二MCP 工具的数量要克制。一开始我们封装了十几个工具结果模型经常选错工具。后来精简到 5 个核心工具每个工具的描述写得更精确工具选择准确率从 70% 提升到了 92%。第三上下文管理要动态调整。固定 Token 预算在不同场景下效果差异很大。我们后来改成根据任务复杂度动态分配预算简单问答少给上下文复杂分析多给上下文整体效果更好。第四可观测性投入要前置。我们第一版没做可观测性排查问题极其痛苦。第二版补上之后很多问题从猜变成了看数据效率完全不一样。5. 一些关于 Agent 开发的个人体会做 Agent 开发这两年我最大的感受是模型能力在快速提升但工程能力才是决定产品上限的关键。同样的模型不同的 Harness 设计、不同的上下文管理、不同的工具编排效果可能差好几倍。多模态、Harness、MCP 这三个东西看起来是三个独立的技术点实际上是一个整体。多模态扩展了感知边界MCP 扩展了行动边界Harness 则是把这两者协调起来的调度中枢。任何一个环节薄弱整个 Agent 的表现都会受限。如果你刚开始做 Agent 开发我的建议是先把 Harness 层做扎实。不要急着接多模态也不要急着接一堆工具。先把上下文管理、异常处理、可观测性这三件事做好后面加什么能力都会顺很多。反过来如果 Harness 层是凑合的后面每加一个能力都是在给自己挖坑。另外不要迷信更强的模型解决一切。我见过太多项目模型换了一茬又一茬效果提升却很有限因为瓶颈根本不在模型而在工程架构。把 Harness 做好把上下文管理做精细把工具描述写清楚这些事情的投入产出比远高于换模型。最后说一个我踩过的坑不要在没有可观测性的情况下上生产。Agent 的行为太复杂了没有完整的调用链路记录出了问题根本无从下手。宁可晚上线一周也要把日志和监控做起来。这个投入后面会十倍百倍地回报你。
