HarnessAgent全适配器支持图像输入：AI编程助手迎来多模态

AI SDK 的 HarnessAgent 层近期完成了一次值得关注的升级：所有 harness 适配器现在都能接受图像输入。这意味着开发者只需在标准消息格式中混入 { type: 'file' } 内容块，就能让不同编码代理"看懂"图片。

一次接口统一，九种适配器同时受益

按照官方说明，图像输入走的是标准 AI SDK 消息格式——content 数组里可以同时放 { type: 'text' } 和 { type: 'file' } 两种部分。图片由各 harness 底层所依赖的视觉模型负责处理，而不需要开发者为每个代理单独适配。

覆盖的适配器清单相当长：Claude Code、Cline、Codex、Cursor、Deep Agents、fx、GitHub Copilot、Grok Build、OpenCode、Pi。对熟悉这一生态的人来说，这份名单本身就说明了问题——它几乎涵盖当前主流编码代理，从命令行工具到 IDE 插件都有涉及。

为什么统一在 HarnessAgent 层很关键

过去，多模态能力往往取决于某个具体工具是否实现了图片解析。开发者想切换代理，就得重新处理传输格式。HarnessAgent 把图像输入收拢到抽象层，调用方代码保持不变，只换 harness 实现即可，这降低了多代理方案之间的迁移成本。

HarnessAgent 是 AI SDK 中面向编码代理（coding agent）的抽象层。所谓 harness，指的是把一个具体代理工具（如 Codex、Claude Code）包装成统一调用接口的适配器，使调用方可以用同一套 generate、createSession API 驱动不同工具。这一设计沿用了 AI SDK 核心的分层思路：模型/工具差异被收拢在实现层，业务代码只依赖抽象。因此当图像输入被加入抽象层时，所有实现该接口的 harness 会自动继承该能力，而不需要逐个修改。这也是此次升级能用“一处改动、九种适配器受益”方式落地的原因。

{ type: 'file' } 内容块是 AI SDK 标准消息格式中的多模态载体，与 { type: 'text' } 并列放在 content 数组中。其中 mediaType 字段声明 MIME 类型（如 image/png、image/jpeg），data 字段接受 Buffer、Uint8Array 或 base64 字符串。这一格式最初用于直接调用视觉模型的 generateText/streamText 场景，HarnessAgent 复用它意味着上层消息构造方式与直接调用模型保持一致，开发者已有的多模态消息代码可以平移过来。

代码怎么写：文本与图片并行传入

官方给出的基础示例用 Codex harness 描述一张图片。核心结构是构造 messages 时，把用户消息的 content 写成数组，文本和文件交替排列：

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { codex } from '@ai-sdk/harness-codex';
import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';
import { readFileSync } from 'node:fs';

const agent = new HarnessAgent({ harness: codex });
const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});
const session = await agent.createSession({ sandboxSession });

const result = await agent.generate({
  session,
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe the image in one sentence.' },
        { type: 'file', mediaType: 'image/png', data: readFileSync('image.png') },
      ],
    },
  ],
});

这段代码值得注意的地方在于沙箱会话的创建方式：通过 createVercelNetworkSandboxSession 拉起运行时环境，再用 agent.getSandboxTemplate() 提供模板。图片数据直接以 readFileSync 读出的 Buffer 传入，mediaType 标注为 image/png。整个流程没有额外的图像预处理步骤。

实用场景推演

图像输入对编码代理的价值不止于"描述图片"这种演示。结合常见工作流，至少有几类用法值得尝试：

• 界面截图转代码：把设计稿或现有页面截图交给代理，要求生成对应组件结构。
• 报错截图诊断：将终端或浏览器报错截图作为上下文，减少手动复制粘贴。
• 图表与文档理解：让代理读取架构图、流程图，辅助理解既有系统。

这些场景能否落地，取决于各 harness 底层视觉模型的实际能力。官方只声明了"由底层视觉模型处理"，并未给出各适配器之间的效果对比。

示例中的 createVercelNetworkSandboxSession 用于在 Vercel 上拉起一个带网络访问的隔离运行环境，编码代理在其中执行命令、读写文件。agent.getSandboxTemplate() 返回该 harness 所需的沙箱镜像模板，确保运行时具备代理依赖的工具链。agent.createSession({ sandboxSession }) 则把代理会话绑定到该沙箱上。图像输入本身不经过沙箱，而是随消息传给底层视觉模型；沙箱只承载代理的文件系统与命令执行环境。理解这一分工有助于判断图像数据在链路中的位置。

多代理协作的新变量

HarnessAgent 把图像能力下沉到统一层，客观上让"同一张图喂给不同代理"成为低成本操作。对于需要交叉验证结果的场景——例如让 Codex 与 Claude Code 分别解读同一张架构图——调用方只需更换 harness 参数。

不过这种便利也带来一个待观察的问题：不同代理背后的视觉模型在图像理解上存在差异，统一接口并不等于统一输出质量。官方文档目前聚焦于接入方式，尚未涉及各适配器的能力边界说明，实际选型时仍需自行验证。

不同编码代理底层绑定的视觉模型并不相同：有的依赖 Claude 系列的多模态能力，有的走 GPT 系列或其他视觉模型。这些模型在细粒度文字识别（如小字号终端截图）、图表结构还原、UI 布局推断上的表现差异明显。统一接口只保证消息能送达，不保证解读一致。实际选型时建议针对目标场景（截图转代码、报错诊断、架构图理解）分别做小样本对比，并留意各 harness 是否对图片尺寸、格式或数量有隐式限制。

上手路径

官方建议从 HarnessAgent 图像输入文档入手。需要准备的是：支持图像输入的底层视觉模型、标准格式的消息构造，以及按需配置的沙箱会话。对于已经在使用 HarnessAgent 的项目，迁移成本主要在于把原有纯文本消息改写为 content 数组形式。