1. 从单模态到多模态Agent 感知能力的质变1.1 为什么多模态不是锦上添花而是刚需过去两年我一直在做 Agent 相关的开发最开始接触的都是纯文本场景——用户输入一段话模型理解意图调用工具返回结果。这个链路跑通之后我以为 Agent 的核心难点就是工具调用的准确率和上下文管理。直到我接手了一个需要处理图片、PDF 扫描件和表格截图的项目才发现纯文本 Agent 的天花板有多低。举个很实际的例子用户发来一张设备故障的照片问这个问题怎么处理。纯文本 Agent 只能回复请描述一下您看到的现象而多模态 Agent 可以直接识别出设备型号、故障指示灯的闪烁模式、屏幕上的错误代码然后结合知识库给出针对性的排查步骤。这个体验差距不是一点半点而是能用和好用之间的鸿沟。多模态能力给 Agent 带来的变化我总结为三个层面感知层Agent 不再只依赖文字输入而是能看到图片、听到语音、读懂图表。这意味着很多原本需要人工转述的信息现在可以直接被 Agent 理解。推理层当 Agent 同时接收到文字和图像信息时它可以做跨模态的交叉验证。比如用户说这个按钮点不动同时发来一张截图Agent 可以对比用户描述和截图中的实际 UI 状态判断是按钮被遮挡了还是真的失效了。交互层多模态让 Agent 的输出也不再局限于文字。它可以生成标注图、流程图、甚至直接操作界面并截图反馈形成看-想-做-展示的完整闭环。1.2 多模态 Agent 的典型架构拆解我在实际项目中用过几种不同的多模态 Agent 架构这里分享一个比较通用的设计思路。整个系统可以分成四个核心模块输入预处理模块负责把各种格式的输入统一成模型能吃的格式。图片要处理分辨率和格式PDF 要拆页并区分文本层和图像层音频要转文字或者直接送进支持语音的模型。这个模块看起来简单但实际踩坑最多——比如有些 PDF 的文本层是乱码必须走 OCR有些图片的 EXIF 方向信息会导致模型识别错误。模态路由模块决定哪些内容走哪个模型。不是所有任务都需要多模态大模型有时候先用一个轻量级的图像分类模型判断图片类型再决定是否调用多模态大模型能省不少成本。我的经验是简单分类和检测用专用小模型复杂理解和推理才上多模态大模型。上下文组装模块把多模态信息组织成模型能理解的格式。这里的关键是模态对齐——文字描述和图片内容要在语义上对应起来。比如用户说左边那个红色的你就要确保模型知道左边和红色指的是图片中的哪个区域。我通常会在图片上叠加坐标信息或者在文字中嵌入区域引用。输出后处理模块把模型的输出转换成实际可用的形式。多模态模型的输出可能是文字、坐标框、或者结构化的 JSON需要根据下游任务做适配。比如做 UI 自动化时模型输出的坐标要转换成实际的点击操作做文档理解时输出的结构化数据要入库。1.3 实操中的坑与经验注意多模态模型的 token 消耗远高于纯文本模型。一张 1024x1024 的图片在不同模型上可能消耗 500-2000 个 token 不等。做成本预估时一定要把图片的 token 消耗算进去。我踩过的一个大坑是图片分辨率与识别精度的平衡。最开始为了省钱把图片压缩到 512x512 再送给模型结果模型经常识别错小字和细节。后来改成动态分辨率——根据图片内容复杂度决定压缩比例文字多的图片保持高分辨率纯场景图可以适当压缩。这个策略让识别准确率提升了将近 30%成本只增加了 15%。另一个经验是多模态缓存的利用。很多模型支持对图片部分做缓存如果同一张图片在对话中被多次引用缓存可以显著降低成本。我在做长对话 Agent 时会把用户上传的图片做哈希相同图片直接命中缓存避免重复计费。2. Harness 工程Agent 的脚手架到底该怎么搭2.1 Harness 的本质是什么Harness 这个词在 Agent 开发圈里越来越常见但很多人对它的理解还停留在测试框架的层面。我的理解是Harness 是 Agent 的运行时环境和控制层它负责管理 Agent 的生命周期、工具调用、状态流转和错误处理。你可以把它想象成 Agent 的操作系统——模型是 CPUHarness 是内核工具是外设驱动。为什么 Harness 这么重要因为一个能跑 demo 的 Agent 和一个能上生产的 Agent差距就在 Harness 上。Demo 阶段你只需要把 prompt 写好、工具接上、跑通流程就行。但生产环境要考虑工具调用失败了怎么重试模型输出格式不对怎么修复多轮对话的状态怎么管理并发请求怎么隔离这些都是 Harness 要解决的问题。我见过很多团队把 Harness 的逻辑散落在业务代码里结果就是每加一个新工具就要改一堆地方每处理一种新错误就要加一层 if-else。好的 Harness 应该是可配置、可扩展、可观测的。2.2 一个可落地的 Harness 设计我目前用的 Harness 架构分成五层从下往上依次是执行层负责实际调用模型和工具。这一层要处理超时、重试、限流这些基础能力。我的做法是给每个工具调用都包一层装饰器统一处理异常和日志。重试策略用指数退避但要注意不是所有错误都值得重试比如参数校验失败重试多少次都没用只有网络超时和限流才需要重试。状态层管理 Agent 的运行时状态。包括对话历史、工具调用记录、中间结果、错误信息等。我用的是一个状态机模型每个状态有明确的进入和退出条件。这样做的好处是调试时能清楚看到 Agent 卡在哪一步而不是面对一堆日志发呆。编排层决定下一步做什么。这是 Harness 的核心逻辑通常是一个循环模型输出 - 解析动作 - 执行工具 - 更新状态 - 再调模型。编排层要处理的关键问题是终止条件——什么时候认为任务完成了我的经验是设置三重保险模型明确输出完成信号、达到最大轮次限制、或者连续 N 轮没有实质性进展。观测层负责记录和展示 Agent 的运行过程。这一层经常被忽视但实际调试时极其重要。我会记录每个步骤的输入输出、耗时、token 消耗并且支持回放。有了这个排查问题时可以像看录像一样一步步回看而不是靠猜。接口层对外暴露能力。包括同步调用、流式输出、异步任务等不同模式。这一层要做的是把内部复杂的编排逻辑包装成简单的接口让业务方不用关心 Harness 内部的细节。2.3 Harness 开发中的关键决策决策一用现成框架还是自研我的建议是如果团队有持续投入的能力自研 Harness 更可控。现成框架虽然上手快但遇到定制需求时改起来很痛苦。我自研的 Harness 核心代码不到 2000 行但完全贴合业务需求维护成本反而更低。决策二工具调用是同步还是异步这取决于工具的特性。查询类工具通常同步调用耗时长的任务如文件处理、批量操作应该异步化。我的做法是给每个工具标注预期耗时超过阈值的自动走异步通道通过回调或轮询获取结果。决策三状态存在内存还是持久化短对话可以放内存长对话和需要断点续传的场景必须持久化。我用的是内存 Redis 的混合方案热数据在内存定期快照到 Redis服务重启后能从最近的状态恢复。实操心得Harness 的日志一定要结构化。我早期用纯文本日志排查问题时要在几万行里 grep效率极低。后来改成 JSON 格式每个步骤有唯一的 trace_id配合简单的查询工具排查效率提升了一个数量级。3. MCP 协议工具生态的通用插座3.1 MCP 解决了什么问题在没有 MCP 之前每接一个新工具都要写一套适配代码。A 工具的 API 是 RESTful 的B 工具是 gRPC 的C 工具是命令行调用D 工具是数据库查询。每个工具的认证方式、参数格式、返回结构都不一样Agent 要调用它们就得为每个工具写专门的胶水代码。这种模式下工具越多维护成本越高而且工具很难在不同 Agent 之间复用。MCP 的出现改变了这个局面。它定义了一套标准协议工具提供方按照协议暴露能力Agent 按照协议调用工具。就像 USB 接口统一了外设连接一样MCP 统一了 Agent 和工具的交互方式。我第一次用 MCP 接工具时最大的感受是终于不用为每个工具写适配层了。MCP 的核心概念包括Server工具提供方暴露资源和工具能力ClientAgent 侧负责连接 Server 并调用能力ResourceServer 暴露的数据如文件、数据库记录ToolServer 暴露的可执行操作如查询、写入、计算PromptServer 预定义的提示模板方便 Client 快速使用3.2 MCP 的接入实操接入一个 MCP Server 的流程比想象中简单。以我最近接的一个文件管理 Server 为例整个过程分三步第一步配置连接。MCP 支持多种传输方式本地工具通常用 stdio远程工具用 HTTP 或 WebSocket。配置文件里指定 Server 的启动命令或地址Client 启动时自动连接。{ mcpServers: { file-manager: { command: node, args: [/path/to/file-server.js], env: { WORKSPACE: /data/workspace } } } }第二步发现能力。连接成功后Client 可以查询 Server 暴露了哪些资源和工具。这个过程是动态的Server 可以随时增减能力Client 不需要重新配置。第三步调用工具。调用时传入工具名和参数Server 执行后返回结果。MCP 定义了标准的错误格式Client 可以统一处理。我实测下来接入一个标准 MCP Server 的时间从原来的半天缩短到半小时以内。更重要的是接好的 Server 可以在不同 Agent 项目之间复用边际成本几乎为零。3.3 MCP 使用中的注意事项注意一权限控制。MCP Server 暴露的能力可能很敏感比如文件写入、数据库操作。一定要在 Server 侧做好权限校验不能只依赖 Client 的约束。我的做法是给每个工具标注风险等级高风险工具需要额外的确认流程。注意二超时和重试。MCP 调用本质上是网络调用要考虑超时和失败的情况。我在 Client 侧统一设置了超时时间超时后根据工具类型决定是否重试。查询类工具可以重试写入类工具要谨慎避免重复写入。注意三版本兼容。MCP 协议还在演进中不同版本的 Server 和 Client 可能存在兼容性问题。我的经验是锁定版本升级前先在测试环境验证。生产环境的 Server 和 Client 尽量保持版本一致。踩坑记录有一次我升级了 Client 版本结果发现新版本对某个字段的格式要求变了导致所有工具调用都失败。排查了半天才发现是版本不匹配。从那以后我在配置文件里显式锁定版本号升级走灰度流程。4. 多模态 Harness MCP 的协同实战4.1 三者如何配合单独看多模态、Harness、MCP每个都是独立的技术点。但真正发挥威力的是三者结合。我举一个实际项目的例子来说明。项目背景是做一个智能文档处理 Agent用户上传各种格式的文档PDF、图片、扫描件Agent 需要理解内容、提取信息、执行后续操作如入库、生成报告、发送通知。多模态负责理解。文档进来后先用多模态模型识别内容。PDF 走文本提取 图像识别双通道图片走 OCR 视觉理解表格走专门的表格识别模型。识别结果统一成结构化数据。Harness 负责编排。整个流程是一个复杂的状态机接收文档 - 识别类型 - 提取内容 - 校验完整性 - 执行操作 - 反馈结果。每一步都可能失败Harness 负责重试、降级、错误处理。比如识别失败时Harness 会尝试用备用模型重新识别校验不通过时会触发人工审核流程。MCP 负责连接外部能力。文档处理需要用到很多外部工具OCR 服务、数据库、消息队列、报表生成器。这些工具都通过 MCP 接入Agent 不需要关心它们的具体实现只需要按协议调用。4.2 性能优化的实战经验这个项目上线后我做了几轮性能优化分享几个有效的策略策略一并行化。文档的多个处理步骤之间没有严格依赖关系时可以并行执行。比如图片识别和文本提取可以同时进行最后合并结果。我用 Harness 的并行编排能力把整体处理时间缩短了 40%。策略二分级处理。不是所有文档都需要最高精度的处理。我先用一个轻量级模型做快速分类简单文档走快速通道复杂文档才走完整流程。这个策略让平均处理时间下降了 60%而准确率只损失了不到 2%。策略三缓存复用。相同或相似的文档经常重复出现。我对文档内容做指纹相同指纹直接返回缓存结果。对于相似文档缓存中间结果如识别出的文本避免重复调用模型。策略四异步化。耗时长的操作如大文件处理走异步通道用户提交后立即返回任务 ID处理完成后通过回调通知。这样用户不用等待体验更好。4.3 错误处理与降级方案多模态 工具调用的链路很长出错是常态。我的错误处理原则是每一层都要有降级方案确保整体可用。故障环节可能原因降级方案图片识别失败图片模糊、格式不支持转人工审核或提示用户重新上传模型调用超时网络问题、模型负载高切换备用模型或降低精度要求工具调用失败服务不可用、参数错误重试、切换备用工具、跳过非关键步骤状态丢失服务重启、存储故障从最近快照恢复或重新开始流程输出格式错误模型幻觉、解析失败用规则引擎修复或重新生成实操心得降级方案一定要提前设计不能等出问题了再想。我在项目初期就画了一张故障树列出所有可能的故障点和对应的降级策略后来每次出问题都能快速定位和处理。5. 常见问题与排查技巧实录5.1 多模态相关问题问题模型识别图片中的文字时经常出错特别是小字和特殊字体。排查思路先确认图片分辨率是否足够。我的经验是文字高度低于 20 像素时大部分模型的识别准确率会明显下降。解决方案是预处理时检测文字区域对文字区域做超分辨率放大。另外特殊字体可以尝试用专门的 OCR 模型通用多模态模型对艺术字体的识别能力有限。问题多模态模型的输出不稳定同样的图片两次识别结果不一样。这是模型的随机性问题。解决方案是降低 temperature 参数或者对关键任务做多次识别取多数结果。我在做票据识别时会跑三次识别取置信度最高的结果准确率能提升 5-8 个百分点。问题图片 token 消耗太大成本失控。优化策略动态分辨率、图片缓存、分级处理。另外不是所有任务都需要多模态大模型简单的图像分类用专用小模型就够了。我做过统计把 60% 的简单任务分流到小模型后整体成本下降了 70%。5.2 Harness 相关问题问题Agent 陷入死循环反复调用同一个工具。这是编排层的终止条件没设计好。我的解决方案是设置三重限制最大轮次、最大工具调用次数、连续无进展检测。连续无进展的定义是连续 N 轮的状态变化小于阈值。检测到无进展时强制终止并返回当前结果。问题工具调用失败后重试导致重复操作。这是幂等性问题。解决方案是给每个操作生成唯一 ID工具侧做幂等校验。对于不支持幂等的工具重试前先查询状态确认上次操作是否已生效。问题长对话的上下文管理困难模型经常忘记之前的内容。解决方案是分层上下文管理近期对话保留完整内容远期对话做摘要压缩。关键信息如用户偏好、任务目标单独存储每轮都注入。我用的是滑动窗口 关键信息锚点的方案效果不错。5.3 MCP 相关问题问题MCP Server 连接不稳定经常断开。排查方向网络问题、Server 崩溃、心跳超时。我的做法是加自动重连机制重连失败时降级到本地缓存或提示用户。另外Server 侧要做好资源管理避免内存泄漏导致崩溃。问题工具描述不清晰模型不知道怎么调用。MCP 工具的描述很重要要写清楚功能、参数、返回值、使用场景。我的经验是描述要具体避免模糊词汇。比如查询数据不如根据用户 ID 查询订单列表返回订单号、金额、状态。问题多个 MCP Server 的工具名冲突。解决方案是加命名空间前缀。我在 Client 侧统一给工具名加上 Server 标识避免冲突。同时在给模型展示工具列表时也要带上命名空间让模型知道该调哪个。5.4 综合排查速查表现象可能原因排查步骤解决方案Agent 无响应模型调用卡住、死循环查看 Harness 日志确认当前状态设置超时强制终止识别结果错误图片质量差、模型不适配检查输入图片换模型测试预处理图片切换模型工具调用失败参数错误、服务不可用查看工具日志确认错误码修复参数重试或降级成本异常高token 消耗大、重复调用统计 token 消耗分析调用链优化 prompt加缓存输出格式错误模型幻觉、解析 bug检查原始输出验证解析逻辑修复解析加校验6. 一些个人体会做 Agent 开发这两年最大的感受是技术选型要务实不要追新。多模态、Harness、MCP 都是好技术但不是所有场景都需要。我见过一些团队明明做的是纯文本任务非要上多模态结果成本翻倍、效果没提升。也见过一些团队工具就三五个非要搭一套复杂的 Harness维护成本比收益还高。我的建议是从实际需求出发缺什么补什么。纯文本够用就先做纯文本工具少就先手动接等规模上来了再考虑 MCP。技术是手段不是目的。另外Agent 开发中调试和观测的重要性怎么强调都不为过。我花在 Harness 观测层上的时间可能比写业务逻辑还多。但这是值得的——没有好的观测出了问题就是盲人摸象有了好的观测排查效率能提升好几倍。最后分享一个小技巧建立自己的测试用例库。每次遇到 bug修复后把复现用例加进去。时间长了这个库就是你的护城河。我现在的用例库有几百个 case每次改代码跑一遍能挡住 90% 的回归问题。这个习惯看起来笨但实际效果非常好。