多模态Agent架构实战：Harness编排与MCP工具接入

1. 从一次翻车现场说起：为什么我要重写这套 Agent 架构

去年下半年，我接手了一个内部知识助手项目，需求听起来很朴素：让模型能看懂用户上传的截图、PDF 里的表格，还能调用几个内部系统查数据。当时我的第一反应是"这不就是多模态加 Function Calling 嘛"，于是拍脑袋定了个方案——用一个大模型扛下所有，图片走视觉编码，工具调用走原生 function call，上下文全塞进一个超长 prompt。

结果上线第一周就被打脸。用户传了一张带表格的报销单截图，模型把金额识别成了另一列的数字；调用内部查询接口时，参数格式偶尔对不上，模型还会"自信地"编一个不存在的字段名；最要命的是，当对话轮次超过十几轮，前面调过的工具结果全被挤掉了，模型开始重复调用同一个接口。

那次事故之后我花了大概两个月，把整个架构推倒重来，最终沉淀出一套以多模态输入为入口、Harness 编排层为骨架、MCP 协议为工具接入标准的 Agent 方案。这套东西现在跑在几个内部场景里，稳定性比第一版好了不止一个量级。这篇笔记就是把这几个月的踩坑、选型、参数调优和排查经验完整摊开讲一遍，适合正在做 Agent 落地、被工具调用和多模态输入折磨过的开发者参考。不管你是刚接触 Agent 的新手，还是已经写过几版编排逻辑的老手，应该都能从里面找到点能直接抄的东西。

2. 三个核心概念到底在解决什么问题

在动手之前，得先把这三个词掰扯清楚。很多人把它们混在一起谈，结果架构设计的时候边界模糊，后面全是坑。

2.1 多模态：不是"能看图"这么简单

多模态在大模型语境里，指的是模型能同时处理文本、图像、音频、视频等多种输入模态。但落到工程上，它真正解决的问题是信息入口的多样性。传统文本模型只能吃文字，用户得自己把截图里的内容敲成文字，这个转换过程既慢又容易出错。

我现在的理解是：多模态的价值不在于"炫技"，而在于减少人工转录环节。一张发票、一个报错截图、一段会议白板的照片，这些信息如果靠人转述，损耗极大；直接丢给模型，让它自己抽取结构化信息，效率完全不一样。

但这里有个关键认知：多模态模型不是 OCR 的替代品。我早期就犯过这个错，指望模型把图片里的每个字都精准识别出来。实测下来，对于规整的印刷体文档，专用 OCR 的准确率依然更稳；多模态模型的优势在于理解语义和布局关系——比如它能判断"这个数字属于哪一列"、"这个箭头指向哪个模块"，这是纯 OCR 做不到的。

2.2 Harness：Agent 的"骨架"和"交通警察"

Harness 这个词直译是"马具、挽具"，在 Agent 开发里，它指的是包裹在模型外面的那层编排框架。模型本身只会"输入 token、输出 token"，它不知道什么时候该调工具、调完结果怎么处理、多轮对话怎么管理上下文。这些活儿全归 Harness 管。

你可以把 Harness 想象成一个项目经理：模型是干活的专家，但专家不知道项目进度、不知道哪些资料已经查过、不知道下一步该找谁。Harness 负责拆解任务、分发指令、收集结果、维护状态、决定循环还是终止。

我踩过的最大的坑，就是早期把太多逻辑塞进 prompt 里，指望模型"自觉"遵守流程。比如在 system prompt 里写"如果用户问的是数据类问题，请先调用查询工具"。结果模型十次里有三次直接凭记忆回答，根本不调工具。后来把这些判断逻辑挪到 Harness 层，用代码来强制路由，稳定性立刻上来了。

2.3 MCP：工具接入的"统一插座"

MCP 全称 Model Context Protocol，是一套让模型和外部工具、数据源通信的标准化协议。在它出现之前，每接一个工具，你都得为那个模型写一套适配代码——A 模型的 function call 格式和 B 模型不一样，换个模型就得重写。

MCP 的思路是把工具的定义和调用抽象成标准接口。工具提供方按 MCP 规范暴露自己的能力（有哪些方法、参数是什么、返回什么），Agent 侧按统一方式去发现和调用。这就像 USB 接口统一了外设连接，你不用再为每个设备准备不同的插口。

对我们这种要接一堆内部系统的场景，MCP 最大的价值是解耦。工具团队只管按协议暴露接口，Agent 团队只管按协议调用，两边可以并行开发，模型换代了工具侧也不用动。

这三个东西是分层协作的关系，不是三选一。多模态负责"看得见"，Harness 负责"想得清、走得对"，MCP 负责"够得着"。理解了这个分层，后面的架构设计就顺了。

3. 整体架构设计：为什么这么分层

3.1 分层原则与数据流

我最终的架构是四层：输入层 → 编排层 → 模型层 → 工具层。数据流是这样的：用户输入（可能含图片）先进输入层做预处理和模态归一化，然后交给编排层；编排层根据任务类型决定走哪条链路，组装上下文，调用模型；模型如果需要工具，通过 MCP 客户端发起调用，结果回灌到编排层，再决定是否继续循环。

这个分层最关键的设计决策是：编排层不碰具体业务逻辑，只做流程控制。业务逻辑（比如"报销单要校验哪些字段"）全部下沉到工具层，编排层只负责"什么时候调、调完怎么办"。

为什么这么设计？因为业务逻辑变化频繁，流程控制相对稳定。如果两者混在一起，每次业务调整都要动编排代码，回归测试成本极高。分开之后，工具层可以独立迭代，编排层基本不动。

3.2 为什么不用"一个大模型全包"

我第一版就是"一个大模型全包"，失败的原因很典型：模型的能力边界和工程的可控性要求是矛盾的。模型越"自主"，行为越难预测；而生产系统要求的是确定性。

具体来说，全包方案有三个致命问题。第一，上下文膨胀。多模态输入本身就占大量 token，再加上工具定义、历史对话、工具返回结果，很快就爆上下文窗口。第二，错误累积。模型一次判断失误，后面全跟着错，而且很难定位是哪一步出的问题。第三，成本失控。每次调用都带着全部上下文，token 消耗随轮次线性增长。

分层之后，每一层职责单一，可以独立优化。比如输入层可以做图片压缩和关键区域裁剪，把 token 降下来；编排层可以做上下文裁剪策略，只保留相关历史；工具层可以缓存高频查询结果。

3.3 模型选型：不是越大越好

选型上我走过弯路。一开始迷信"参数越大越强"，用了最大的模型，结果延迟高、成本高，很多简单任务（比如判断用户意图是查询还是闲聊）根本用不上这么大的模型。

后来改成分级路由：简单意图识别用小模型，复杂多模态理解用大模型，工具参数生成用中等模型。实测下来，整体成本降了大概六成，延迟降了一半，效果几乎没损失。

提示：分级路由的前提是你能准确判断任务复杂度。我的做法是先用规则做粗筛（比如输入是否含图片、是否命中特定关键词），再用小模型做意图分类，最后才决定用哪个模型。

这里有个经验：不要过早优化模型选型。先把流程跑通，用统一模型验证架构，等架构稳定了再根据实际瓶颈做分级。我见过太多人一上来就纠结用哪个模型，结果架构还没定型，选型全是白费。

4. 多模态输入处理：从图片到结构化信息的完整链路

4.1 图片预处理：省 token 的第一道关

多模态输入最直接的成本就是 token。一张手机拍的高清照片，直接丢给模型，可能吃掉几千 token。我的做法是在输入层做预处理，核心是降分辨率 + 关键区域裁剪。

降分辨率不是无脑压缩。我的经验是：文字类图片保留长边 1024 像素左右，再低文字就糊了；场景类图片（比如白板、实物）可以压到 768，因为模型主要看语义不看细节。压缩用双线性插值就够，别用太激进的算法，否则边缘文字会失真。

关键区域裁剪更省。比如用户传一张带表格的截图，如果整张图里表格只占中间一块，可以把四周裁掉。怎么定位表格？我早期用 OpenCV 做轮廓检测，后来发现更简单的办法：让模型先做一次粗定位，返回表格的边界框，再按框裁剪。虽然多了一次调用，但省下的 token 远超这次调用的成本。

# 图片预处理的核心逻辑（示意） def preprocess_image(img, mode="text"): # 按模式决定目标长边 target = 1024 if mode == "text" else 768 h, w = img.shape[:2] scale = target / max(h, w) if scale < 1: img = cv2.resize(img, (int(w*scale), int(h*scale)), interpolation=cv2.INTER_LINEAR) return img

4.2 多模态信息的结构化抽取

图片进来之后，不能直接把原始像素丢给下游。我的做法是先抽取结构化信息，再让下游基于结构化的文本工作。这样做的好处是：下游逻辑不依赖具体模型，换模型不用改代码。

抽取什么？取决于场景。报销单场景抽"金额、日期、类目、发票号"；报错截图场景抽"错误码、错误信息、堆栈关键行"；白板场景抽"模块名、连线关系、标注文字"。

抽取的实现方式有两种。一种是让多模态模型直接输出 JSON，在 prompt 里给 schema，要求严格按格式返回。另一种是模型输出自由文本，再用规则或小模型解析。我倾向第一种，因为格式可控，但要注意：模型输出的 JSON 经常带 markdown 代码块标记，解析前得先剥掉。

注意：要求模型输出 JSON 时，一定要在 prompt 里明确"只输出 JSON，不要任何解释文字"。我早期没强调这点，模型经常在 JSON 前后加一句"好的，以下是抽取结果"，导致解析失败。

4.3 模态对齐与上下文组装

多模态输入往往不是单一的。用户可能同时传了图片和文字说明，比如"这张图里的第三行数据帮我查一下"。这时候需要模态对齐——把文字里的指代（"第三行"）和图片里的内容对应起来。

我的做法是在组装上下文时，给图片内容加显式编号。比如把图片抽取出的表格转成带行号的文本，然后在 prompt 里说明"图片内容已转为下方表格，行号从 1 开始"。这样模型处理"第三行"这种指代时就有据可依。

上下文组装的顺序也有讲究。我的经验是：系统指令 → 工具定义 → 图片结构化内容 → 历史对话 → 当前用户输入。图片内容放在历史对话之前，是因为它通常是本轮任务的背景信息，放前面模型更容易建立全局认知。

5. Harness 编排层：Agent 的"大脑"怎么搭

5.1 状态机 vs 自由循环：我为什么选状态机

编排层的核心问题是：怎么控制 Agent 的执行流程。主流有两种思路，一种是让模型自由决定下一步（ReAct 那套），一种是预定义状态机，模型只在特定节点做决策。

我两种都试过。自由循环的问题是不可控——模型可能陷入死循环，可能跳过必要步骤，可能在不该调工具的时候调工具。状态机的问题是不够灵活——遇到预设之外的情况就卡住。

最后我选的是混合方案：主流程用状态机，每个状态内部的决策交给模型。比如"信息抽取"状态里，模型可以自由决定用哪种抽取策略；但状态之间的流转（抽取完必须进"校验"状态）由代码强制。

这样既保证了主流程的确定性，又保留了局部灵活性。实测下来，比纯自由循环稳定太多，比纯状态机灵活太多。

5.2 上下文管理：裁剪策略与优先级

上下文管理是 Harness 最容易被低估的部分。我见过太多项目，模型效果不好，排查半天发现是上下文塞了太多无关信息。

我的裁剪策略是分层保留。第一优先级是系统指令和工具定义，永远保留；第二优先级是当前任务相关的图片结构化内容；第三优先级是最近 N 轮对话；第四优先级是更早的历史，按相关性打分，低于阈值的直接丢弃。

相关性怎么算？简单做法是用关键词匹配，复杂做法是用 embedding 算相似度。我目前用的是关键词 + 时间衰减的混合策略：越近的对话权重越高，命中当前任务关键词的对话权重也高。这个策略实现简单，效果够用。

# 上下文裁剪的优先级逻辑（示意） def trim_context(messages, current_task, max_tokens): # 系统指令和工具定义永远保留 must_keep = [m for m in messages if m.role in ("system", "tools")] # 其余按优先级排序 others = [m for m in messages if m not in must_keep] others.sort(key=lambda m: score(m, current_task), reverse=True) # 按 token 预算填充 result = must_keep[:] budget = max_tokens - count_tokens(must_keep) for m in others: if count_tokens([m]) <= budget: result.append(m) budget -= count_tokens([m]) return result

5.3 工具调用的编排逻辑

工具调用不是"模型说要调就调"。Harness 在这里要做三件事：校验、执行、回灌。

校验包括参数格式校验和权限校验。参数格式校验是防止模型生成非法参数（比如日期格式不对、枚举值不在范围内）；权限校验是防止越权调用（比如普通用户不能调管理接口）。这两道校验必须在 Harness 层做，不能指望模型自觉。

执行环节要注意超时和重试。工具调用可能因为网络或下游系统问题失败，Harness 要设置合理的超时时间，失败后按策略重试。我的经验是：查询类工具重试 2 次，写入类工具不自动重试（避免重复写入），改为返回错误让模型决定。

回灌环节的关键是结果格式化。工具返回的原始数据往往很冗长，直接塞回上下文会爆 token。我的做法是先在 Harness 层做一次精简，只保留模型决策需要的字段，再回灌。

提示：工具返回结果里如果有大段文本（比如日志），一定要截断。我一般保留前 500 字符和后 200 字符，中间用省略号代替，并在 prompt 里说明"日志已截断"。

6. MCP 工具接入：标准化带来的效率提升

6.1 MCP 的核心机制

MCP 的核心是工具发现 + 标准化调用。工具提供方按协议暴露一个描述文件，里面声明了有哪些工具、每个工具的参数 schema、返回值格式。Agent 侧启动时拉取这个描述，动态生成工具定义，不需要硬编码。

这个机制最大的好处是工具可以热插拔。新接一个内部系统，只要它按 MCP 规范暴露接口，Agent 侧不用改代码，重启拉取描述就能用。我们内部现在有十几个工具，分布在不同的服务里，全靠 MCP 统一接入。

6.2 工具定义的最佳实践

工具定义写得好不好，直接决定模型调用得准不准。我总结了几个要点。

工具名要语义清晰。别用query_data这种模糊名字，用query_reimbursement_by_invoice这种一看就知道干什么的。模型选工具主要靠名字和描述，名字模糊它就容易选错。

参数描述要具体。别写"日期参数"，写"报销日期，格式 YYYY-MM-DD，例如 2024-01-15"。模型生成参数时严重依赖描述，描述越具体，生成越准。

返回值要说明结构。在工具描述里写清楚返回的字段和含义，模型回灌后才知道怎么用。我见过工具返回一个嵌套三层的 JSON，模型完全不知道怎么解析，最后只能瞎猜。

6.3 工具粒度：粗一点还是细一点

工具粒度是个反复权衡的问题。粒度太细，模型要调很多次才能完成一个任务，容易中途出错；粒度太粗，工具内部逻辑复杂，复用性差。

我的经验是：按业务动作划分，而不是按数据操作划分。比如"查询报销单"是一个业务动作，对应一个工具；而不是拆成"查报销单主表"、"查报销明细"、"查审批记录"三个工具。前者模型一次调用搞定，后者要调三次，中间任何一次出错都影响结果。

但也不能太粗。如果一个工具要处理十几种情况，参数多到模型记不住，那就该拆。我的判断标准是：参数超过 5 个，或者内部分支超过 3 条，就考虑拆。

7. 实操全流程：从零搭一个能跑的最小系统

7.1 环境准备与依赖

先说环境。我用的是 Python 3.11，主要依赖几个库：多模态处理用 Pillow 和 OpenCV，HTTP 通信用 httpx，MCP 客户端用官方 SDK，模型调用用各家 SDK。版本上没什么特别的坑，注意 OpenCV 装 headless 版本就行，服务器上不需要 GUI。

配置管理我用的是环境变量加配置文件。敏感信息（API key 之类）走环境变量，业务配置（工具地址、超时时间）走 YAML 文件。这样本地开发和线上部署用同一套代码，只换配置。

7.2 最小可运行示例

下面是一个最小可运行的骨架，包含输入处理、编排循环、工具调用三个核心环节。代码是示意性的，实际项目里要补全错误处理和日志。

import httpx from PIL import Image class MinimalAgent: def __init__(self, model_client, mcp_client): self.model = model_client self.mcp = mcp_client self.max_turns = 8 # 防止死循环 def run(self, user_input, image=None): # 1. 输入预处理 context = self._prepare_input(user_input, image) # 2. 编排循环 for turn in range(self.max_turns): response = self.model.chat(context) # 3. 判断是否需要调工具 if response.tool_calls: for call in response.tool_calls: result = self._execute_tool(call) context.append({"role": "tool", "content": result}) else: return response.content return "达到最大轮次，任务未完成" def _prepare_input(self, text, image): ctx = [{"role": "system", "content": SYSTEM_PROMPT}] if image: structured = self._extract_image(image) ctx.append({"role": "user", "content": structured}) ctx.append({"role": "user", "content": text}) return ctx def _execute_tool(self, call): # 校验参数 if not self._validate(call): return "参数校验失败" # 通过 MCP 调用 return self.mcp.invoke(call.name, call.arguments)

7.3 关键参数的选择过程

几个关键参数我调了很久，这里把过程说清楚。

最大轮次：一开始设 5，发现复杂任务不够用；设 15，又容易在异常情况下空转。最后定在 8，配合"连续两轮无工具调用则强制结束"的规则，基本覆盖了所有正常场景。

工具超时：查询类设 10 秒，写入类设 30 秒。查询慢一点可以忍，写入如果超时了状态不确定，得给足时间。

上下文 token 上限：我留了模型窗口的 70% 给上下文，剩下 30% 给模型输出。因为多模态输入占 token 多，留足输出空间很重要，否则模型回答到一半被截断。

重试次数：查询类 2 次，间隔 1 秒；写入类 0 次。这个前面说过，写入重试有风险。

7.4 一次完整的调用记录

拿一个真实场景走一遍。用户传了一张报销单截图，问"这张单子能报吗"。

第一步，输入层识别到图片，走多模态抽取，得到结构化结果：{amount: 1280, date: "2024-03-15", category: "差旅", invoice_no: "INV-2024-0315"}。

第二步，编排层组装上下文，系统指令说明"你是报销助手，需要校验报销规则"，然后附上结构化结果和用户问题。

第三步，模型判断需要调用"查询报销规则"工具，Harness 校验参数后通过 MCP 调用，返回规则：{max_amount: 2000, allowed_categories: ["差旅", "办公"], need_invoice: true}。

第四步，结果回灌，模型对比后输出"可以报销，金额 1280 在限额内，类目合规，发票号已提供"。

整个过程 3 轮模型调用，2 次工具调用，总耗时约 4 秒。这个延迟在交互场景里可以接受。

8. 常见问题与排查技巧实录

8.1 模型不调工具，直接瞎编

这是最高频的问题。模型明明有工具可用，却凭记忆回答。排查思路：先看工具描述是不是太模糊，模型没理解工具能干什么；再看 system prompt 里有没有明确要求"数据类问题必须调工具"；最后看是不是上下文里已经有类似答案，模型觉得不用调了。

我的解决组合拳：工具描述写具体 + system prompt 强制要求 + 在 Harness 层做后置校验（如果模型输出里包含具体数据但没调工具，打回重来）。

8.2 工具参数格式错误

模型生成的参数经常格式不对，比如日期写成"2024年3月15日"而不是"2024-03-15"。根因是参数描述不够具体。解决办法是在参数描述里给例子，并且用 JSON Schema 的 pattern 做约束。如果还不行，就在 Harness 层做参数归一化，把常见格式统一转换。

8.3 多模态识别不准

图片识别错误通常有几个原因：分辨率太低、图片倾斜、光照不均、关键区域太小。我的处理顺序是：先做图像增强（去噪、纠偏、提亮），再重新识别；如果还不行，就降低抽取粒度，只抽最关键的字段，别贪多。

8.4 上下文爆炸

多轮对话后上下文超限。排查：统计每轮 token 消耗，找出增长最快的部分。通常是工具返回结果太长。解决办法是 Harness 层做结果精简，只保留必要字段。

8.5 几个独家避坑技巧

第一个，给工具调用加 trace id。每次调用生成一个唯一 id，贯穿日志，排查问题时能快速串起整条链路。这个习惯帮我省了无数排查时间。

第二个，保留原始输入。图片预处理后，原始图片也要存一份。有时候预处理引入的问题比解决的还多，能回退到原始输入重新处理很关键。

第三个，模型输出做二次校验。尤其是涉及金额、日期这类关键字段，Harness 层要用规则再校验一遍，别全信模型。

第四个，灰度发布新工具。新接的工具先只对内部账号开放，观察一段时间再全量。我见过新工具参数设计有问题，全量后大量调用失败的情况。

9. 性能与成本优化：把账算清楚

9.1 Token 消耗的构成分析

要优化成本，先得知道钱花在哪。我统计过一个典型的多模态任务，token 消耗大致是：图片结构化内容占 40%，工具定义占 15%，历史对话占 25%，工具返回结果占 15%，系统指令占 5%。

图片是大头，所以优化重点在图片。前面说的降分辨率和裁剪，能把这部分砍掉一半以上。工具定义也不小，如果工具多，可以考虑按场景动态加载，只加载当前任务相关的工具。

9.2 缓存策略

缓存能省不少钱。我的做法是两级缓存：一级是工具结果缓存，相同参数的查询在短时间内直接返回缓存；二级是模型响应缓存，完全相同的输入直接返回上次结果。

工具结果缓存要注意失效策略。查询类数据可以缓存几分钟，写入类不能缓存。模型响应缓存只对确定性任务有效，涉及实时数据的不能缓存。

9.3 分级路由的落地

分级路由前面提过，这里说落地细节。我用一个小模型做意图分类，输出"简单查询"、"复杂分析"、"多模态处理"三类，分别路由到不同规格的模型。分类模型的准确率大概 90%，剩下 10% 误判的代价可以接受，因为即使路由错了，大模型也能兜底。

实测数据：分级路由后，整体成本降了约 60%，P95 延迟从 8 秒降到 4 秒。这个收益在规模化之后非常可观。

10. 我在这套架构上的一些个人体会

这套架构跑了大半年，最大的体会是：Agent 开发的难点不在模型，而在工程。模型能力每年都在涨，但编排逻辑、上下文管理、工具接入这些工程问题，换个模型还是得自己解决。

另一个体会是别追求一步到位。我第一版想做个"全能 Agent"，结果什么都没做好。后来拆成一个个小能力，逐个打磨，反而整体效果更好。现在这套系统也不是终点，工具还在加，编排逻辑还在调，但骨架已经稳了。

最后分享一个我最近在试的扩展方向：把 Harness 的状态机做成可配置的。现在流程流转是硬编码的，改一次要发版。如果做成配置驱动，业务方自己就能调整流程，开发只维护引擎。这个方向还在验证，等跑通了再单独写一篇。