AI SDK ai-sdk/harness 深度解析基于 harness-v1 规范与 HarnessAgent 接入外部 Agent 运行时【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读本文围绕 AI SDK 仓库中实验性包ai-sdk/harness当前版本 1.0.107展开以其变更日志 packages/harness/CHANGELOG.md 为时间线骨架结合包内 README、类型定义与源码实现系统梳理该包从0.0.0-canary.1一路演进到1.0.107的完整能力地图。读完本文你将理解 harness 抽象层在 AI SDK 生态中的定位、HarnessAgent的配置与会话生命周期、网络沙箱与桥接协议的设计并具备基于harness-v1规范自研适配器的能力。一、背景harness 抽象在 AI SDK 中的定位ai-sdk/harness是 AI SDK 仓库中标注为experimental实验性的包。从 packages/harness/CHANGELOG.md 中1.0.0版本的三条 Major Changes 可以看出它的架构定位21d3d60实现 harness 规范implement harness specification3d9a50c为 Claude Code、Codex、Pi 实现 harness 适配器9d6dbe0为 harness 抽象增加沙箱专属扩展并新增sandbox-just-bash与sandbox-vercel两个沙箱包。换言之harness 层的职责是把 Claude Code、Codex、OpenCode、DeepAgents、Pi 等第三方编码 Agent 运行时统一接入 AI SDK 的 Agent 编程模型。上层用户只面对统一的HarnessAgentAPI而底层运行时的差异启动方式、工具协议、流式输出、会话状态全部由适配器封装。包自身的依赖关系也能印证这一点packages/harness/package.json 声明了ai、ai-sdk/provider、ai-sdk/provider-utils三个运行时依赖并将wsWebSocket桥接通信与zod模式校验作为可选 peerDependencies要求node 22。导出入口分为四路主入口规范与类型、./agentHarnessAgent、./utils工具函数、./bridge桥接协议对应源码目录 packages/harness/src 下的v1/、agent/、utils/、bridge/四个子目录。二、快速上手最小 HarnessAgent 示例按照 packages/harness/README.md 的 Setup 与 Usage一个完整的桥接式 harness 应用由四部分组装HarnessAgent 具体适配器 网络沙箱 用户自定义工具。npm i ai zod ai-sdk/harness ai-sdk/harness-claude-code ai-sdk/sandbox-vercelimport { HarnessAgent } from ai-sdk/harness/agent; import { claudeCode } from ai-sdk/harness-claude-code; import { createVercelSandbox } from ai-sdk/sandbox-vercel; import { tool } from ai; import { z } from zod/v4; const agent new HarnessAgent({ harness: claudeCode, // 适配器驱动底层 Claude Code 运行时 id: auth-agent, model: claude-sonnet-4-5, instructions: You are a careful refactoring assistant. Prefer minimal diffs., sandbox: createVercelSandbox({ runtime: node24, ports: [4000], }), sandboxConfig: { bootstrapHash: ripgrep-v1, onBootstrap: async ({ session, abortSignal }) { const streamResult await session.run({ command: command -v rg /dev/null || (apt-get update apt-get install -y ripgrep), abortSignal, }); if (streamResult.exitCode ! 0) { throw new Error(Failed to install ripgrep: ${streamResult.stderr}); } }, onSession: async ({ session, sessionWorkDir, abortSignal }) { await session.writeTextFile({ path: ${sessionWorkDir}/README.md, content: Workspace notes for this session., abortSignal, }); }, }, tools: { deploy: tool({ description: Deploy to a target environment, inputSchema: z.object({ env: z.enum([staging, production]) }), execute: async ({ env }) ({ url: https://${env}.example.com }), }), }, }); const session await agent.createSession(); try { const generateResult await agent.generate({ session, prompt: Fix the failing test in src/auth.ts, }); console.log(generateResult.text); // 流式输出 const streamResult await agent.stream({ session, prompt: Now write a regression test, }); for await (const part of streamResult.stream) { if (part.type text-delta) { process.stdout.write(part.text); } } } finally { await session.destroy(); }这个示例覆盖了三个关键机制适配器驱动运行时harness: claudeCode、沙箱预置onBootstrap安装工具并固化进快照、onSession写入会话工作目录文件、宿主侧工具执行tools.deploy在 host 进程内运行结果回传给沙箱内运行时。三、HarnessAgent 配置项深度解析HarnessAgent的完整构造参数定义在 packages/harness/src/agent/harness-agent-settings.ts下面按功能分组说明。3.1 适配器、模型与指令harness必填实现HarnessV1规范的适配器实例其builtinTools会与用户tools合并并在类型化的tool-call流中暴露。用户工具与内置工具同名时用户工具优先可覆盖内置工具。idAgent 实例的稳定标识通过agent.id暴露省略时为undefined。model字符串形式的模型标识取值由所选 harness 定义模型标识是 harness 特有的因此接受任意字符串。prepareCall可在完成轮次之间替换它。instructionsstring | SystemModelMessage。适配器优先把指令追加到原生 system/developer prompt对应变更日志1.0.66中9ee30bf的修复不再用首条用户消息作为 workaround不支持时退化为前置到用户消息。传入SystemModelMessage时只转发其content。skills暴露给底层运行时的技能数组由各适配器决定如何呈现可在prepareCall中替换。headers随每次模型请求发送的额外 HTTP 头。authorization、x-api-key、user-agent、x-client-app由 harness 管理不允许在此设置对应1.0.102的eeed977。3.2 结构化输出 output1.0.73的62a9c2a为HarnessAgent引入了结构化输出能力。在构造时设置output则每一轮 turn 都要求同一份类型化、schema 校验的输出import { Output } from ai; const agent new HarnessAgent({ harness: claudeCode, sandbox, output: Output.object({ schema: z.object({ answer: z.string() }), }), });generate()通过result.output暴露校验后的值stream()额外暴露partialOutputStreamJSON 本身也保留在普通 text 与 stream 表面上便于同时兼容文本展示与结构化消费。3.3 轮次控制stopWhen 与 prepareCallstopWhen1.0.40的5f65e61在完成一个可继续进入下一模型步的 harness 工具步骤后停止当前结果例如isStepCount(1)。底层 turn 保持未完成状态可被挂起与继续。终端纯文本步骤自然结束不会被提前截断省略时 harness 一直运行到 turn 自然结束或暂停。prepareCall1.0.93的14d4fc0在已完成轮次之间调整model、skills、instructions、tools等可变设置并可将自定义 call options 解析为具体设置。准备值在 turn 生命周期内冻结包括挂起 turn 的继续过程。结合callOptionsSchema自定义调用选项的校验 schema与1.0.94的8961fde支持在轮次间更换model可实现真正的多轮动态配置。3.4 工具过滤与审批activeTools/inactiveTools1.0.12的7859cea在不改变结果类型的前提下限制或排除 harness 可调用的工具集合两者互斥。permissionMode内置工具权限模式默认allow-all保持原有跳过权限的行为除非用户主动选择更严格模式。toolApproval面向宿主执行自定义工具的按工具审批配置镜像 AI SDKtoolApproval对象配置但不支持回调。取值语义not-applicable与approved直接执行工具user-approval暂停 turn 等待用户决策denied立即提交execution-denied结果。与内置工具审批相关的修复见1.0.2544e988a工具审批回归修复、1.0.85fa6af57审批续期后先发出内置工具结果与1.0.8832349ccPi 单步发射多个工具调用时暴露每一次审批请求。3.5 生命周期回调与遥测构造期可配置onStart、onStepStart、onLanguageModelCallStart/End、onToolExecutionStart/End、onStepEnd、onEnd等回调AgentCallParameters支持的同类回调也可按调用传入二者由mergeCallbacks合并。1.0.62的25c9120在语言模型调用结束回调与遥测 span 上暴露 provider 元数据1.0.95的87b4858为逐 turn 遥测补充了 per-turn 配置数据1.0.20的b7aa06a在 step-end 遥测事件上加入步号。telemetryharness 从 turn 生命周期驱动 AI SDK 可插拔的Telemetry集成契约如ai-sdk/otel使 harness turn 以与streamText相同的 span 形状出现在消费方 trace 中但 harness 本身保持与 OpenTelemetry 无关。debug与onLog开启桥接日志转发沙箱 console 结构化debug-event与HARNESS_DEBUGstderr 默认输出onLog提供代码内程序化诊断接收器与 stderr 输出相互独立。四、会话生命周期显式会话调用方持有与Agent接口一致HarnessAgent是无状态定义在模块作用域构造一次持有适配器、合并后的工具面、沙箱 provider 与配置绝不持有活跃会话。每次调用的数据prompt、abortSignal、会话全部放在generate()/stream()上。HarnessAgentCallExtensions强制要求每个调用都传入session实现见 packages/harness/src/agent/harness-agent.ts。会话对象HarnessAgentSessionpackages/harness/src/agent/harness-agent-session.ts由agent.createSession()创建内部状态机分为active / detached / stopped / destroyed四种会话态与idle / running / awaiting-approval / awaiting-tool-result / suspended五种 turn 态。结束本地句柄有三种方式session.detach()把桥接支持的会话停放在一边供后续attach重新接续session.stop()保存状态并停止沙箱session.destroy()清理且不保留恢复状态。任何生命周期方法 resolve 之后会话即不可用再对之调用generate/stream会抛出异常。1.0.81起HarnessV1NetworkSandboxSession.destroy成为必选实现1.0.76允许调用方把自有sandboxSession传给createSession()此时可省略构造器里的sandbox参数。五、沙箱抽象网络沙箱会话与快照预置harness 会话建立在HarnessV1NetworkSandboxSession之上packages/harness/src/v1/harness-v1-network-sandbox-session.ts。它本身是SandboxSession文件 I/O、exec、spawn的超集额外提供id底层沙箱资源的稳定标识是跨进程恢复的持久化查找键Vercel 用沙箱名just-bash 用创建时铸造的 UUIDdefaultWorkingDirectory从存活沙箱读取Vercel 默认/vercel/sandboxjust-bash 默认/home/user框架在它之下组合defaultWorkingDirectory/harnessId-sessionId作为会话工作目录ports与getPortEndpoint({ port, protocol })解析沙箱暴露端口的连接细节URL 与作用域 headergetPortUrl已废弃由getPortEndpoint取代1.0.72的52bc889stop()/destroy()与网络策略、请求转换接口。restricted()返回的受限视图只暴露文件系统与进程接口代码无法停止沙箱、修改网络访问或转换请求用于工具安全的执行面。5.1 sandboxConfigonBootstrap 与 onSessionsandboxConfig与具体沙箱 provider 解耦包含三个选项源码见 packages/harness/src/agent/harness-agent-settings.ts 的HarnessAgentSandboxConfigworkDir固定会话工作目录相对沙箱默认工作目录省略时沿用harnessId-sessionId目录此时onBootstrap收到的是沙箱默认工作目录。bootstrapHashonBootstrap的调用方控制标识改变它即让可复用快照失效。onBootstrap在沙箱模板创建期间、适配器自身 bootstrap 之后、快照发布之前执行用于昂贵且应固化进快照的初始化安装工具、克隆大仓库。必须与bootstrapHash同时提供。onSession每个沙箱会话获取且工作目录就绪后、适配器启动前执行新会话与恢复会话都会运行因此必须保持幂等如写入会话配置文件、激活许可证、在sessionWorkDir准备文件。5.2 模板与快照管理prepareHarnessSandboxTemplate()为单个 harness 创建或刷新沙箱 provider 自己的可复用模板是已废弃prewarmHarness()的替代1.0.3还引入了prepareSandboxForHarness工具函数。prepareSandboxForHarness()当调用方已拥有一个沙箱时在创建自己的快照前先按其准备。它应用所选 harness 的 bootstrap 配方与sandboxConfig.onBootstrap返回计算出的准备标识与每个 harness 的配方标识而快照化或停止沙箱交由调用方代码完成。多个桥接 harness 共享调用方提供的沙箱时每个 harness 需要一个暴露端口并把各自端口传给对应 harness 的create*函数。1.0.93的6f8a2d7修复了恢复会话时的 bootstrap 配方问题标记以配方身份为键恢复时若配方已是最新仅花费一次文件读取若快照比生成它的 harness 版本更老旧构建产出的快照活过了 harness 版本则重新 bootstrap而不是用陈旧 bridge 对接更新的宿主。1.0.53的bdde5d9修复bootstrap 文件不再放到/tmp而是放入沙箱工作目录确保随快照持久化。六、桥接协议与工具函数桥接式适配器Claude Code、Codex、OpenCode、DeepAgents依赖 WebSocket 桥harness 在宿主侧通过SandboxChannel与沙箱内运行的 Agent 运行时通信。协议 schema 集中在 packages/harness/src/v1/harness-v1-bridge-protocol.ts涵盖hello、start、resume、stop、destroy、user-message、tool-result、tool-approval-response、abort等入站命令与流式出站消息。packages/harness/src/utils/index.ts 导出了桥接开发所需的成套工具函数令牌与资产createBridgeToken()/withBridgeToken()1.0.95的371e954、createReadBridgeAsset()1.0.96的c0c7fac就绪等待waitForBridgeReady()/markBridgeStarting()含BridgeReadySource1.0.0还修复了 Bun 下的就绪监听兼容aae0138与 WebSocket 端口无法绑定时拒绝桥启动be83911诊断createBridgeErrorHandler()、drainBridgeProcessStream()、forwardBridgeProcessStream()、logBridgeError()、classifyDiskLog()指令与技能writeInstructions()1.0.102的255cccf支持 ACP 适配器基于文件系统的instructionsMapping与writeSkills()把技能实体化到 HOME 目录1.0.102的a39c8bf澄清了该意图凭证createSandboxCredentialEnvironment()、applyCredentialForwarding()1.0.87的8a15038引入细粒度credentialForwarding设置、generateSandboxCredentialPlaceholder()、maskSandboxCredentials()、warnCredentialBrokeringUnavailable()认证与订阅getAiGatewayAuthFromEnv()OIDC token 支持1.0.0的534dac6修复了不完整实现、refreshOAuthAccessToken()、readMacOSKeychainPassword()、readLinuxSecretServicePassword()、readWindowsCredentialManagerPassword()等原生订阅凭证读取其它shellQuote()、getRestrictedSandboxSession()、resolveSandboxDefaultWorkingDirectory()、getHarnessErrorMessage()1.0.55的861d423。七、按变更日志梳理能力演进地图packages/harness/CHANGELOG.md 完整记录了从0.0.0-canary.1到1.0.107的迭代除上文已述外还有几条值得关注的能力里程碑版本变更说明1.0.06c7a3e5因脚手架 premajor 版本为0.0.0-canary.0无法在 major bump 上前进启动1.0.0canary 发布线1.0.4c493634Zod 用法兼容 v3/v4peerDeps 为^3.25.76 \|\| ^4.1.81.0.127859ceaactiveTools/inactiveTools工具过滤1.0.175c5c0f5实验性流式转写支持OpenAIgpt-realtime-whisper、xAI WebSocket STT1.0.37b460541/079591e客户端/宿主端工具支持与未完成 turn 语义发出消息级start流部分使toUIMessageStream持久化模式可注入响应消息 id1.0.3986a84c9调用方 abortSignal 中止以abort流部分结算对齐streamText的 abort 契约1.0.4059a2306宿主工具在遥测上下文包装器内执行1.0.43a9a22e1/9e4e816多步 turn 的final-step文本与推理遥测turn 中途挂起时不触发onTurnFinished/onTurnFailed1.0.558f10600桥接detach重命名为stop、shutdown重命名为destroy1.0.65a03ff6c每 harness 独立的 MCP servers1.0.718d717b3harness 单步内并发执行相互独立的宿主工具调用1.0.7269bb613网络沙箱请求转换 可用时应用凭证代理credential brokering1.0.73d25cae2桥事件流在 start/resume 时认领而非 connect 时1.0.78eace6fb/c0595b4轮次中途转向steering实验支持文件系统进程受限沙箱会话回退1.0.8832349ccPi 单步多工具调用时逐一暴露审批1.0.90 / 1.0.1000e590d2/0c37bf0凭证代理仅在正确的临时密钥下生效credentialForwarding全部替换为临时假密钥时不再误报缺乏凭证代理支持1.0.92e0d7cfb通过auth选项在隔离环境中认证会话移除废弃的旧 auth 选项类型1.0.93cc9f6ce停止把调用方发起的中止诊断成桥错误序列化桥 turn防止 start 与中止 turn 的 teardown 重叠有 teardown 宽限期1.0.101951c54daskUserQuestions工具及跨适配器归一化1.0.102fe86f8f/eeed977ToolLoopAgent生命周期回调同步到HarnessAgentheaders配置1.0.104c04ded8移除已废弃的 harness 适配器设置model/modelId依赖层面harness 包与ai7.0.x、ai-sdk/provider4.x、ai-sdk/provider-utils5.x严格同步演进如最新版 1.0.107 依赖ai7.0.97、ai-sdk/provider4.0.13、ai-sdk/provider-utils5.0.39这说明它属于 AI SDK v7 体系内与主包同频发布的组件。八、实现一个自定义 harnessharness-v1 规范按照 packages/harness/README.md 的 Implementing a harness 章节实现一个适配器只需完成两件事一个HarnessV1工厂实现doStart以及一个doPromptTurn会发射事件的HarnessV1Session。Agent 表面、流式、工具执行与多轮状态全部由框架代劳。HarnessV1类型定义在 packages/harness/src/v1/harness-v1.ts带specificationVersion: harness-v1标签、harnessIdkebab-case如claude-code、builtinTools按桥tool-call事件的commonName ?? nativeName为键的 ToolSet可选声明supportsBuiltinToolApprovals、supportsBuiltinToolFiltering、lifecycleStateSchema与getBootstrap。设计上刻意没有静态 capabilities 对象——可选特性通过 prompt-control 句柄上可选方法的有无来信号化无法满足请求不支持手动压缩、无法暴露所需端口等时从需要该能力的方法中抛出HarnessCapabilityUnsupportedError。以下是一个最小可用适配器README 原文示例已做必要修正import type { HarnessV1, HarnessV1Session } from ai-sdk/harness; export function myHarness(): HarnessV1 { return { specificationVersion: harness-v1, harnessId: my-harness, builtinTools: {}, doStart: async startOpts { const usage { inputTokens: { total: 0, noCache: 0 }, outputTokens: { total: 0, text: 0 }, }; const resumeState { type: resume-session as const, harnessId: my-harness, specificationVersion: harness-v1 as const, data: {}, }; const continueState { type: continue-turn as const, harnessId: my-harness, specificationVersion: harness-v1 as const, data: {}, }; const session: HarnessV1Session { sessionId: startOpts.sessionId, isResume: startOpts.resumeFrom ! null || startOpts.continueFrom ! null, doPromptTurn: async promptOpts { const done Promise.resolve().then(() { promptOpts.emit({ type: text-start, id: t }); promptOpts.emit({ type: text-delta, id: t, delta: Hello. }); promptOpts.emit({ type: text-end, id: t }); promptOpts.emit({ type: finish, finishReason: { unified: stop, raw: stop }, totalUsage: usage, }); }); return { submitToolResult: async () {}, done }; }, doContinueTurn: async continueOpts { const done Promise.resolve().then(() { continueOpts.emit({ type: finish, finishReason: { unified: stop, raw: stop }, totalUsage: usage, }); }); return { submitToolResult: async () {}, done }; }, doCompact: async () {}, doDetach: async () resumeState, doStop: async () resumeState, doDestroy: async () {}, doSuspendTurn: async () continueState, }; return session; }, }; }实现时需注意几点同样来自 README 与源码约定从startOpts.model读取消费方选择的模型从startOpts.sandboxSession读取网络沙箱会话harness 层会停止或销毁它从 provider 获取的会话而通过agent.createSession({ sandboxSession })传入的会话由调用方保有所有权。给工具安全的代码传sandboxSession.restricted()而不是整个网络沙箱会话。每次 prompt 与继续可携带可选responseFormatJSON 格式携带调用方提供的 JSON Schema 及可选 name/description适配器必须强制 schema 并通过普通文本部分发射结果 JSON运行时无法满足时须在 turn 开始前抛出HarnessCapabilityUnsupportedError。bootstrap 配方路径可为绝对或相对。相对bootstrapDir与文件路径相对sandboxSession.defaultWorkingDirectory解析框架会先创建bootstrapDir再写文件bootstrap 命令始终在该目录运行。建议使用.harness-bootstrap/my-harness这类相对目录让 bootstrap 资产随沙箱的快照持久化工作树保留。九、错误处理与调试包内错误体系由四个错误类构成见 packages/harness/src/index.ts 与 packages/harness/src/errorsHarnessErrorharness 层通用错误基类HarnessCapabilityUnsupportedError适配器缺少某能力时抛出HarnessSandboxAuthenticationError沙箱认证失败1.0.55的861d423改善了认证错误处理并提供getHarnessErrorMessage()帮助函数HarnessBridgeCapabilityUnsupportedError1.0.59的81bcf2e桥代码需要标记缺失能力时使用。调试方面HARNESS_DEBUG环境变量控制 stderr 默认输出代码内可用debug: { enabled: true }开启桥日志转发沙箱 console 与结构化debug-eventonLog作为独立于 stderr 的程序化接收器。桥诊断工具drainBridgeProcessStream、forwardBridgeProcessStream、formatBridgeError、logBridgeError等在 packages/harness/src/bridge/bridge-diagnostics.ts。十、延伸阅读包说明与完整示例packages/harness/README.md规范类型与流部分 schemapackages/harness/src/v1HarnessAgent 实现packages/harness/src/agent/harness-agent.ts、packages/harness/src/agent/harness-agent-session.ts适配器实现参考packages/harness-claude-code/src/claude-code-harness.ts官方用户文档仓库内概述HarnessAgent 指南工具技能适配器工作流工具UI 集成 与 终端 UI综上ai-sdk/harness通过一份版本化规范harness-v1、一个无状态 Agent 门面HarnessAgent、一组网络沙箱接口与一条 WebSocket 桥协议把异构的外部 Agent 运行时收敛为 AI SDK 统一的生成/流式编程体验。其变更日志不仅是版本记录更是一份完整的功能演进地图从 v1 规范确立、三大适配器落地到结构化输出、工具过滤、凭证代理、动态轮次配置与逐轮遥测的逐步成熟值得所有在 AI SDK 之上集成自定义编码 Agent 的开发者细读。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AI SDK ai-sdk/harness 深度解析基于 harness-v1 规范与 HarnessAgent 接入外部 Agent 运行时【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读本文围绕 AI SDK 仓库中实验性包ai-sdk/harness当前版本 1.0.107展开以其变更日志 packages/harness/CHANGELOG.md 为时间线骨架结合包内 README、类型定义与源码实现系统梳理该包从0.0.0-canary.1一路演进到1.0.107的完整能力地图。读完本文你将理解 harness 抽象层在 AI SDK 生态中的定位、HarnessAgent的配置与会话生命周期、网络沙箱与桥接协议的设计并具备基于harness-v1规范自研适配器的能力。一、背景harness 抽象在 AI SDK 中的定位ai-sdk/harness是 AI SDK 仓库中标注为experimental实验性的包。从 packages/harness/CHANGELOG.md 中1.0.0版本的三条 Major Changes 可以看出它的架构定位21d3d60实现 harness 规范implement harness specification3d9a50c为 Claude Code、Codex、Pi 实现 harness 适配器9d6dbe0为 harness 抽象增加沙箱专属扩展并新增sandbox-just-bash与sandbox-vercel两个沙箱包。换言之harness 层的职责是把 Claude Code、Codex、OpenCode、DeepAgents、Pi 等第三方编码 Agent 运行时统一接入 AI SDK 的 Agent 编程模型。上层用户只面对统一的HarnessAgentAPI而底层运行时的差异启动方式、工具协议、流式输出、会话状态全部由适配器封装。包自身的依赖关系也能印证这一点packages/harness/package.json 声明了ai、ai-sdk/provider、ai-sdk/provider-utils三个运行时依赖并将wsWebSocket桥接通信与zod模式校验作为可选 peerDependencies要求node 22。导出入口分为四路主入口规范与类型、./agentHarnessAgent、./utils工具函数、./bridge桥接协议对应源码目录 packages/harness/src 下的v1/、agent/、utils/、bridge/四个子目录。二、快速上手最小 HarnessAgent 示例按照 packages/harness/README.md 的 Setup 与 Usage一个完整的桥接式 harness 应用由四部分组装HarnessAgent 具体适配器 网络沙箱 用户自定义工具。npm i ai zod ai-sdk/harness ai-sdk/harness-claude-code ai-sdk/sandbox-vercelimport { HarnessAgent } from ai-sdk/harness/agent; import { claudeCode } from ai-sdk/harness-claude-code; import { createVercelSandbox } from ai-sdk/sandbox-vercel; import { tool } from ai; import { z } from zod/v4; const agent new HarnessAgent({ harness: claudeCode, // 适配器驱动底层 Claude Code 运行时 id: auth-agent, model: claude-sonnet-4-5, instructions: You are a careful refactoring assistant. Prefer minimal diffs., sandbox: createVercelSandbox({ runtime: node24, ports: [4000], }), sandboxConfig: { bootstrapHash: ripgrep-v1, onBootstrap: async ({ session, abortSignal }) { const streamResult await session.run({ command: command -v rg /dev/null || (apt-get update apt-get install -y ripgrep), abortSignal, }); if (streamResult.exitCode ! 0) { throw new Error(Failed to install ripgrep: ${streamResult.stderr}); } }, onSession: async ({ session, sessionWorkDir, abortSignal }) { await session.writeTextFile({ path: ${sessionWorkDir}/README.md, content: Workspace notes for this session., abortSignal, }); }, }, tools: { deploy: tool({ description: Deploy to a target environment, inputSchema: z.object({ env: z.enum([staging, production]) }), execute: async ({ env }) ({ url: https://${env}.example.com }), }), }, }); const session await agent.createSession(); try { const generateResult await agent.generate({ session, prompt: Fix the failing test in src/auth.ts, }); console.log(generateResult.text); // 流式输出 const streamResult await agent.stream({ session, prompt: Now write a regression test, }); for await (const part of streamResult.stream) { if (part.type text-delta) { process.stdout.write(part.text); } } } finally { await session.destroy(); }这个示例覆盖了三个关键机制适配器驱动运行时harness: claudeCode、沙箱预置onBootstrap安装工具并固化进快照、onSession写入会话工作目录文件、宿主侧工具执行tools.deploy在 host 进程内运行结果回传给沙箱内运行时。三、HarnessAgent 配置项深度解析HarnessAgent的完整构造参数定义在 packages/harness/src/agent/harness-agent-settings.ts下面按功能分组说明。3.1 适配器、模型与指令harness必填实现HarnessV1规范的适配器实例其builtinTools会与用户tools合并并在类型化的tool-call流中暴露。用户工具与内置工具同名时用户工具优先可覆盖内置工具。idAgent 实例的稳定标识通过agent.id暴露省略时为undefined。model字符串形式的模型标识取值由所选 harness 定义模型标识是 harness 特有的因此接受任意字符串。prepareCall可在完成轮次之间替换它。instructionsstring | SystemModelMessage。适配器优先把指令追加到原生 system/developer prompt对应变更日志1.0.66中9ee30bf的修复不再用首条用户消息作为 workaround不支持时退化为前置到用户消息。传入SystemModelMessage时只转发其content。skills暴露给底层运行时的技能数组由各适配器决定如何呈现可在prepareCall中替换。headers随每次模型请求发送的额外 HTTP 头。authorization、x-api-key、user-agent、x-client-app由 harness 管理不允许在此设置对应1.0.102的eeed977。3.2 结构化输出 output1.0.73的62a9c2a为HarnessAgent引入了结构化输出能力。在构造时设置output则每一轮 turn 都要求同一份类型化、schema 校验的输出import { Output } from ai; const agent new HarnessAgent({ harness: claudeCode, sandbox, output: Output.object({ schema: z.object({ answer: z.string() }), }), });generate()通过result.output暴露校验后的值stream()额外暴露partialOutputStreamJSON 本身也保留在普通 text 与 stream 表面上便于同时兼容文本展示与结构化消费。3.3 轮次控制stopWhen 与 prepareCallstopWhen1.0.40的5f65e61在完成一个可继续进入下一模型步的 harness 工具步骤后停止当前结果例如isStepCount(1)。底层 turn 保持未完成状态可被挂起与继续。终端纯文本步骤自然结束不会被提前截断省略时 harness 一直运行到 turn 自然结束或暂停。prepareCall1.0.93的14d4fc0在已完成轮次之间调整model、skills、instructions、tools等可变设置并可将自定义 call options 解析为具体设置。准备值在 turn 生命周期内冻结包括挂起 turn 的继续过程。结合callOptionsSchema自定义调用选项的校验 schema与1.0.94的8961fde支持在轮次间更换model可实现真正的多轮动态配置。3.4 工具过滤与审批activeTools/inactiveTools1.0.12的7859cea在不改变结果类型的前提下限制或排除 harness 可调用的工具集合两者互斥。permissionMode内置工具权限模式默认allow-all保持原有跳过权限的行为除非用户主动选择更严格模式。toolApproval面向宿主执行自定义工具的按工具审批配置镜像 AI SDKtoolApproval对象配置但不支持回调。取值语义not-applicable与approved直接执行工具user-approval暂停 turn 等待用户决策denied立即提交execution-denied结果。与内置工具审批相关的修复见1.0.2544e988a工具审批回归修复、1.0.85fa6af57审批续期后先发出内置工具结果与1.0.8832349ccPi 单步发射多个工具调用时暴露每一次审批请求。3.5 生命周期回调与遥测构造期可配置onStart、onStepStart、onLanguageModelCallStart/End、onToolExecutionStart/End、onStepEnd、onEnd等回调AgentCallParameters支持的同类回调也可按调用传入二者由mergeCallbacks合并。1.0.62的25c9120在语言模型调用结束回调与遥测 span 上暴露 provider 元数据1.0.95的87b4858为逐 turn 遥测补充了 per-turn 配置数据1.0.20的b7aa06a在 step-end 遥测事件上加入步号。telemetryharness 从 turn 生命周期驱动 AI SDK 可插拔的Telemetry集成契约如ai-sdk/otel使 harness turn 以与streamText相同的 span 形状出现在消费方 trace 中但 harness 本身保持与 OpenTelemetry 无关。debug与onLog开启桥接日志转发沙箱 console 结构化debug-event与HARNESS_DEBUGstderr 默认输出onLog提供代码内程序化诊断接收器与 stderr 输出相互独立。四、会话生命周期显式会话调用方持有与Agent接口一致HarnessAgent是无状态定义在模块作用域构造一次持有适配器、合并后的工具面、沙箱 provider 与配置绝不持有活跃会话。每次调用的数据prompt、abortSignal、会话全部放在generate()/stream()上。HarnessAgentCallExtensions强制要求每个调用都传入session实现见 packages/harness/src/agent/harness-agent.ts。会话对象HarnessAgentSessionpackages/harness/src/agent/harness-agent-session.ts由agent.createSession()创建内部状态机分为active / detached / stopped / destroyed四种会话态与idle / running / awaiting-approval / awaiting-tool-result / suspended五种 turn 态。结束本地句柄有三种方式session.detach()把桥接支持的会话停放在一边供后续attach重新接续session.stop()保存状态并停止沙箱session.destroy()清理且不保留恢复状态。任何生命周期方法 resolve 之后会话即不可用再对之调用generate/stream会抛出异常。1.0.81起HarnessV1NetworkSandboxSession.destroy成为必选实现1.0.76允许调用方把自有sandboxSession传给createSession()此时可省略构造器里的sandbox参数。五、沙箱抽象网络沙箱会话与快照预置harness 会话建立在HarnessV1NetworkSandboxSession之上packages/harness/src/v1/harness-v1-network-sandbox-session.ts。它本身是SandboxSession文件 I/O、exec、spawn的超集额外提供id底层沙箱资源的稳定标识是跨进程恢复的持久化查找键Vercel 用沙箱名just-bash 用创建时铸造的 UUIDdefaultWorkingDirectory从存活沙箱读取Vercel 默认/vercel/sandboxjust-bash 默认/home/user框架在它之下组合defaultWorkingDirectory/harnessId-sessionId作为会话工作目录ports与getPortEndpoint({ port, protocol })解析沙箱暴露端口的连接细节URL 与作用域 headergetPortUrl已废弃由getPortEndpoint取代1.0.72的52bc889stop()/destroy()与网络策略、请求转换接口。restricted()返回的受限视图只暴露文件系统与进程接口代码无法停止沙箱、修改网络访问或转换请求用于工具安全的执行面。5.1 sandboxConfigonBootstrap 与 onSessionsandboxConfig与具体沙箱 provider 解耦包含三个选项源码见 packages/harness/src/agent/harness-agent-settings.ts 的HarnessAgentSandboxConfigworkDir固定会话工作目录相对沙箱默认工作目录省略时沿用harnessId-sessionId目录此时onBootstrap收到的是沙箱默认工作目录。bootstrapHashonBootstrap的调用方控制标识改变它即让可复用快照失效。onBootstrap在沙箱模板创建期间、适配器自身 bootstrap 之后、快照发布之前执行用于昂贵且应固化进快照的初始化安装工具、克隆大仓库。必须与bootstrapHash同时提供。onSession每个沙箱会话获取且工作目录就绪后、适配器启动前执行新会话与恢复会话都会运行因此必须保持幂等如写入会话配置文件、激活许可证、在sessionWorkDir准备文件。5.2 模板与快照管理prepareHarnessSandboxTemplate()为单个 harness 创建或刷新沙箱 provider 自己的可复用模板是已废弃prewarmHarness()的替代1.0.3还引入了prepareSandboxForHarness工具函数。prepareSandboxForHarness()当调用方已拥有一个沙箱时在创建自己的快照前先按其准备。它应用所选 harness 的 bootstrap 配方与sandboxConfig.onBootstrap返回计算出的准备标识与每个 harness 的配方标识而快照化或停止沙箱交由调用方代码完成。多个桥接 harness 共享调用方提供的沙箱时每个 harness 需要一个暴露端口并把各自端口传给对应 harness 的create*函数。1.0.93的6f8a2d7修复了恢复会话时的 bootstrap 配方问题标记以配方身份为键恢复时若配方已是最新仅花费一次文件读取若快照比生成它的 harness 版本更老旧构建产出的快照活过了 harness 版本则重新 bootstrap而不是用陈旧 bridge 对接更新的宿主。1.0.53的bdde5d9修复bootstrap 文件不再放到/tmp而是放入沙箱工作目录确保随快照持久化。六、桥接协议与工具函数桥接式适配器Claude Code、Codex、OpenCode、DeepAgents依赖 WebSocket 桥harness 在宿主侧通过SandboxChannel与沙箱内运行的 Agent 运行时通信。协议 schema 集中在 packages/harness/src/v1/harness-v1-bridge-protocol.ts涵盖hello、start、resume、stop、destroy、user-message、tool-result、tool-approval-response、abort等入站命令与流式出站消息。packages/harness/src/utils/index.ts 导出了桥接开发所需的成套工具函数令牌与资产createBridgeToken()/withBridgeToken()1.0.95的371e954、createReadBridgeAsset()1.0.96的c0c7fac就绪等待waitForBridgeReady()/markBridgeStarting()含BridgeReadySource1.0.0还修复了 Bun 下的就绪监听兼容aae0138与 WebSocket 端口无法绑定时拒绝桥启动be83911诊断createBridgeErrorHandler()、drainBridgeProcessStream()、forwardBridgeProcessStream()、logBridgeError()、classifyDiskLog()指令与技能writeInstructions()1.0.102的255cccf支持 ACP 适配器基于文件系统的instructionsMapping与writeSkills()把技能实体化到 HOME 目录1.0.102的a39c8bf澄清了该意图凭证createSandboxCredentialEnvironment()、applyCredentialForwarding()1.0.87的8a15038引入细粒度credentialForwarding设置、generateSandboxCredentialPlaceholder()、maskSandboxCredentials()、warnCredentialBrokeringUnavailable()认证与订阅getAiGatewayAuthFromEnv()OIDC token 支持1.0.0的534dac6修复了不完整实现、refreshOAuthAccessToken()、readMacOSKeychainPassword()、readLinuxSecretServicePassword()、readWindowsCredentialManagerPassword()等原生订阅凭证读取其它shellQuote()、getRestrictedSandboxSession()、resolveSandboxDefaultWorkingDirectory()、getHarnessErrorMessage()1.0.55的861d423。七、按变更日志梳理能力演进地图packages/harness/CHANGELOG.md 完整记录了从0.0.0-canary.1到1.0.107的迭代除上文已述外还有几条值得关注的能力里程碑版本变更说明1.0.06c7a3e5因脚手架 premajor 版本为0.0.0-canary.0无法在 major bump 上前进启动1.0.0canary 发布线1.0.4c493634Zod 用法兼容 v3/v4peerDeps 为^3.25.76 \|\| ^4.1.81.0.127859ceaactiveTools/inactiveTools工具过滤1.0.175c5c0f5实验性流式转写支持OpenAIgpt-realtime-whisper、xAI WebSocket STT1.0.37b460541/079591e客户端/宿主端工具支持与未完成 turn 语义发出消息级start流部分使toUIMessageStream持久化模式可注入响应消息 id1.0.3986a84c9调用方 abortSignal 中止以abort流部分结算对齐streamText的 abort 契约1.0.4059a2306宿主工具在遥测上下文包装器内执行1.0.43a9a22e1/9e4e816多步 turn 的final-step文本与推理遥测turn 中途挂起时不触发onTurnFinished/onTurnFailed1.0.558f10600桥接detach重命名为stop、shutdown重命名为destroy1.0.65a03ff6c每 harness 独立的 MCP servers1.0.718d717b3harness 单步内并发执行相互独立的宿主工具调用1.0.7269bb613网络沙箱请求转换 可用时应用凭证代理credential brokering1.0.73d25cae2桥事件流在 start/resume 时认领而非 connect 时1.0.78eace6fb/c0595b4轮次中途转向steering实验支持文件系统进程受限沙箱会话回退1.0.8832349ccPi 单步多工具调用时逐一暴露审批1.0.90 / 1.0.1000e590d2/0c37bf0凭证代理仅在正确的临时密钥下生效credentialForwarding全部替换为临时假密钥时不再误报缺乏凭证代理支持1.0.92e0d7cfb通过auth选项在隔离环境中认证会话移除废弃的旧 auth 选项类型1.0.93cc9f6ce停止把调用方发起的中止诊断成桥错误序列化桥 turn防止 start 与中止 turn 的 teardown 重叠有 teardown 宽限期1.0.101951c54daskUserQuestions工具及跨适配器归一化1.0.102fe86f8f/eeed977ToolLoopAgent生命周期回调同步到HarnessAgentheaders配置1.0.104c04ded8移除已废弃的 harness 适配器设置model/modelId依赖层面harness 包与ai7.0.x、ai-sdk/provider4.x、ai-sdk/provider-utils5.x严格同步演进如最新版 1.0.107 依赖ai7.0.97、ai-sdk/provider4.0.13、ai-sdk/provider-utils5.0.39这说明它属于 AI SDK v7 体系内与主包同频发布的组件。八、实现一个自定义 harnessharness-v1 规范按照 packages/harness/README.md 的 Implementing a harness 章节实现一个适配器只需完成两件事一个HarnessV1工厂实现doStart以及一个doPromptTurn会发射事件的HarnessV1Session。Agent 表面、流式、工具执行与多轮状态全部由框架代劳。HarnessV1类型定义在 packages/harness/src/v1/harness-v1.ts带specificationVersion: harness-v1标签、harnessIdkebab-case如claude-code、builtinTools按桥tool-call事件的commonName ?? nativeName为键的 ToolSet可选声明supportsBuiltinToolApprovals、supportsBuiltinToolFiltering、lifecycleStateSchema与getBootstrap。设计上刻意没有静态 capabilities 对象——可选特性通过 prompt-control 句柄上可选方法的有无来信号化无法满足请求不支持手动压缩、无法暴露所需端口等时从需要该能力的方法中抛出HarnessCapabilityUnsupportedError。以下是一个最小可用适配器README 原文示例已做必要修正import type { HarnessV1, HarnessV1Session } from ai-sdk/harness; export function myHarness(): HarnessV1 { return { specificationVersion: harness-v1, harnessId: my-harness, builtinTools: {}, doStart: async startOpts { const usage { inputTokens: { total: 0, noCache: 0 }, outputTokens: { total: 0, text: 0 }, }; const resumeState { type: resume-session as const, harnessId: my-harness, specificationVersion: harness-v1 as const, data: {}, }; const continueState { type: continue-turn as const, harnessId: my-harness, specificationVersion: harness-v1 as const, data: {}, }; const session: HarnessV1Session { sessionId: startOpts.sessionId, isResume: startOpts.resumeFrom ! null || startOpts.continueFrom ! null, doPromptTurn: async promptOpts { const done Promise.resolve().then(() { promptOpts.emit({ type: text-start, id: t }); promptOpts.emit({ type: text-delta, id: t, delta: Hello. }); promptOpts.emit({ type: text-end, id: t }); promptOpts.emit({ type: finish, finishReason: { unified: stop, raw: stop }, totalUsage: usage, }); }); return { submitToolResult: async () {}, done }; }, doContinueTurn: async continueOpts { const done Promise.resolve().then(() { continueOpts.emit({ type: finish, finishReason: { unified: stop, raw: stop }, totalUsage: usage, }); }); return { submitToolResult: async () {}, done }; }, doCompact: async () {}, doDetach: async () resumeState, doStop: async () resumeState, doDestroy: async () {}, doSuspendTurn: async () continueState, }; return session; }, }; }实现时需注意几点同样来自 README 与源码约定从startOpts.model读取消费方选择的模型从startOpts.sandboxSession读取网络沙箱会话harness 层会停止或销毁它从 provider 获取的会话而通过agent.createSession({ sandboxSession })传入的会话由调用方保有所有权。给工具安全的代码传sandboxSession.restricted()而不是整个网络沙箱会话。每次 prompt 与继续可携带可选responseFormatJSON 格式携带调用方提供的 JSON Schema 及可选 name/description适配器必须强制 schema 并通过普通文本部分发射结果 JSON运行时无法满足时须在 turn 开始前抛出HarnessCapabilityUnsupportedError。bootstrap 配方路径可为绝对或相对。相对bootstrapDir与文件路径相对sandboxSession.defaultWorkingDirectory解析框架会先创建bootstrapDir再写文件bootstrap 命令始终在该目录运行。建议使用.harness-bootstrap/my-harness这类相对目录让 bootstrap 资产随沙箱的快照持久化工作树保留。九、错误处理与调试包内错误体系由四个错误类构成见 packages/harness/src/index.ts 与 packages/harness/src/errorsHarnessErrorharness 层通用错误基类HarnessCapabilityUnsupportedError适配器缺少某能力时抛出HarnessSandboxAuthenticationError沙箱认证失败1.0.55的861d423改善了认证错误处理并提供getHarnessErrorMessage()帮助函数HarnessBridgeCapabilityUnsupportedError1.0.59的81bcf2e桥代码需要标记缺失能力时使用。调试方面HARNESS_DEBUG环境变量控制 stderr 默认输出代码内可用debug: { enabled: true }开启桥日志转发沙箱 console 与结构化debug-eventonLog作为独立于 stderr 的程序化接收器。桥诊断工具drainBridgeProcessStream、forwardBridgeProcessStream、formatBridgeError、logBridgeError等在 packages/harness/src/bridge/bridge-diagnostics.ts。十、延伸阅读包说明与完整示例packages/harness/README.md规范类型与流部分 schemapackages/harness/src/v1HarnessAgent 实现packages/harness/src/agent/harness-agent.ts、packages/harness/src/agent/harness-agent-session.ts适配器实现参考packages/harness-claude-code/src/claude-code-harness.ts官方用户文档仓库内概述HarnessAgent 指南工具技能适配器工作流工具UI 集成 与 终端 UI综上ai-sdk/harness通过一份版本化规范harness-v1、一个无状态 Agent 门面HarnessAgent、一组网络沙箱接口与一条 WebSocket 桥协议把异构的外部 Agent 运行时收敛为 AI SDK 统一的生成/流式编程体验。其变更日志不仅是版本记录更是一份完整的功能演进地图从 v1 规范确立、三大适配器落地到结构化输出、工具过滤、凭证代理、动态轮次配置与逐轮遥测的逐步成熟值得所有在 AI SDK 之上集成自定义编码 Agent 的开发者细读。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
