AI SDK 的 Deep Agents Harness 适配器演进从 ai-sdk/harness-deepagents 看桥接式编码代理的运行机制与能力全景【免费下载链接】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/aiai-sdk/harness-deepagents是 AI SDKThe AI Toolkit for TypeScript中把 LangChain 的 Deep Agents基于 LangGraph 的编码代理运行时接入 AI SDK Harness 体系的适配器。本文以该包的 CHANGELOG.md版本 1.0.0 至 1.0.107为骨架结合 源码实现 逐层剖析它如何在沙箱内通过 Node 桥接进程驱动deepagents包、如何通过 WebSocket 与宿主适配器交互、认证与凭据代理如何工作以及activeTools/inactiveTools工具过滤、output结构化输出、credentialForwarding、mintBridgeToken、per-harness MCP 服务器、会话恢复等关键能力是如何随版本演进而逐步落地的。读完本文你将掌握该适配器的完整配置面、生命周期模型与升级断点可直接用于评估和接入自己的 Agent 应用。一、包定位桥接式Bridge-BackedHarness 适配器从 README.md 与 package.json 可以看到该包是一个HarnessV1适配器harnessId为deepagents见 deepagents-harness.ts。它的核心设计是运行时在沙箱内Deep Agents 运行时并不运行在宿主进程而是通过一个 Node 桥接脚本bridge.mjs运行在 AI SDK 沙箱Sandbox中桥接运行时基于共享的ai-sdk/harness/bridge。宿主通过 WebSocket 驱动轮次宿主适配器doStart加会话的doPromptTurn/doStop/doDestroy通过 WebSocket 通道与沙箱内的桥接进程通信流式事件文本增量、推理增量、工具调用、文件变更等沿该通道回传。依赖按需安装桥接进程所依赖的deepagents包与 LangChain 系依赖会在启动时通过pnpm install --frozen-lockfile安装到引导bootstrap目录而不是打进宿主包。包版本与ai-sdk/harness、ai-sdk/provider-utils保持严格同步每次 Patch 都会联动升级对应依赖版本这是 CHANGELOG 中最频繁出现的条目类型。包要求 Node.js 22并以zod^3.25.76 或 ^4.1.8为 peer 依赖——这正是 1.0.3 中fix(harness): fix harness Zod usage to be v3/v4 compatible的由来适配器内部统一使用zod/v4解析桥接协议同时兼容宿主侧的 zod v3 与 v4。1.1 快速上手pnpm add ai-sdk/harness-deepagents ai-sdk/harnessimport { HarnessAgent } from ai-sdk/harness/agent; import { deepAgents } from ai-sdk/harness-deepagents; const agent new HarnessAgent({ harness: deepAgents, // 等价于 createDeepAgents() // ...sandbox provider configuration });deepAgents是默认实例等价于createDeepAgents()见 index.tscreateDeepAgents(settings)则用于传入自定义设置。二、认证体系Anthropic 直连与 AI Gateway 双模式Deep Agents 始终通过 Anthropic 客户端驱动模型但非 Anthropic 模型可以经由 AI Gateway 的 Anthropic 兼容端点转发含工具调用转换。deepagents-auth.ts 完整实现了这套逻辑认证模式DeepAgentsAuthenticationMode目前只有anthropic一种字面量继承HarnessV1Authenticationanthropic运行时解析出的实际模式DeepAgentsResolvedAuthenticationMode则可能是anthropic或ai-gateway。凭据环境变量固定为三个AI_GATEWAY_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN。解析优先级未显式配置时若环境存在 AI Gateway 凭据则优先走 gateway否则回退到 ambient Anthropic 凭据显式传auth: anthropic则强制直连 Anthropic读取ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_BASE_URLgateway 模式则把AI_GATEWAY_API_KEY同时映射为ANTHROPIC_API_KEY并设置ANTHROPIC_BASE_URLAnthropic SDK 会自行追加/v1/messages因此 base URL 保留在根路径。这也是 CHANGELOG 中auth选项演进的完整脉络版本变更含义1.0.71simplify the auth param to be a simple string to choose the auth methodauth简化为字符串选择认证方式1.0.92allow harness sessions to optionally authenticate from an isolated environment supplied through the auth option, and remove support for the formerly deprecated legacy auth options typesauth可传入隔离的凭据环境不必读process.env同时删除旧的遗留 auth 选项类型因此现在可以这样编程式传入认证环境const agent new HarnessAgent({ harness: createDeepAgents({ auth: { ANTHROPIC_API_KEY: token }, // 隔离环境不读 process.env }), model: anthropic/claude-sonnet-4.5, });三、凭据代理与请求转换沙箱内不落盘真实密钥沙箱内的桥接进程也需要调用模型 API但真实密钥不应直接注入沙箱进程环境。适配器在 1.0.72 引入了网络沙箱抽象层的请求转换能力并基于它实现凭据代理credential brokering沙箱内使用临时伪造的秘密宿主侧通过请求转换把请求头中的临时秘密替换回真实凭据。实现位于 deepagents-auth.tscreateDeepAgentsRequestTransformations根据认证模式匹配请求 URLgateway 模式用ANTHROPIC_BASE_URLanthropic 模式默认https://api.anthropic.com当宿主环境与沙箱环境同时存在ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN时分别注册x-api-key与Authorization: Bearer ...的请求头改写规则。围绕该机制的 CHANGELOG 条目1.0.87新增credentialForwarding设置为桥接式适配器提供细粒度控制——它自定义每个凭据值在被转发进沙箱进程前的改写方式但不限制宿主进程能发现、读取的凭据范围见 deepagents-harness.ts 的类型注释。1.0.90加固凭据代理只在携带正确的临时秘密时才应用替换harden credential brokering to only apply with correct ephemeral secret。1.0.100当credentialForwarding回调把全部凭据替换为临时假秘密时不再误报缺乏凭据代理支持的警告avoid warning about lack of credential brokering support ...。1.0.72支持网络沙箱抽象中的请求转换并用于凭据代理同时引入getPortEndpoint()作为getPortUrl()已弃用的更全面替代。此外从源码看若沙箱会话不支持addRequestTransformations适配器会退化为直接把改写后的凭据环境注入桥接进程并通过warnCredentialBrokeringUnavailable提示凭据代理不可用。这解释了 CHANGELOG 中多次出现的凭据代理相关修复的上下文。四、DeepAgentsHarnessSettings 完整配置面结合 deepagents-harness.ts 的DeepAgentsHarnessSettings类型与协议定义适配器的全部设置如下设置项类型说明authDeepAgentsAuthenticationMode认证方式或隔离认证环境未设置时按环境自动解析credentialForwardingHarnessV1CredentialForwarding自定义每个凭据转发进沙箱前的改写thinkingDeepAgentsThinkingConfig控制 Anthropic 扩展思考未设置保留 Deep Agents 运行时默认值effortlow \| medium \| high \| xhigh \| max自适应思考下的努力程度未设置使用 LangChain Anthropic 客户端默认值portnumber桥接端口覆盖默认取沙箱第一个声明的端口portEndpointHarnessV1PortEndpoint覆盖连接沙箱桥接的宿主端点使用 basic sandbox 会话时必须与port一起提供startupTimeoutMsnumber等待桥接广播端口的最长时间默认 120000mintBridgeTokenHarnessV1MintBridgeTokenCallback生成沙箱桥接认证令牌默认随机 32 字节十六进制令牌recursionLimitnumber每轮 LangGraph super-step 上限超限报错省略时用 Deep Agents 默认值mcpServersRecordstring, unknown按名称键控的 MCP 服务器定义使用底层运行时的原生 MCP 配置格式其中thinking支持三种形态bridge 协议 中有对应的 discriminated union schematype DeepAgentsThinkingConfig | { type: adaptive; display?: summarized | omitted } | { type: enabled; budget_tokens: number; display?: summarized | omitted } | { type: disabled };4.1 设置相关的重要版本演进1.0.93model参数上移到HarnessAgent各 harness 适配器构造函数不再各自支持model同时新增prepareCall()支持允许在两个轮次之间更改 harness 设置。1.0.94 进一步允许通过调用选项call options在轮次之间更换model。1.0.104正式移除先前已弃用的 harness 适配器设置上的model与modelId配置——从源码看模型现在统一由HarnessAgent持有并在doPromptTurn时经start消息传入桥接。1.0.102新增headers属性允许在推理请求inference requests上附带任意请求头源码中该值通过start消息的headers字段下发。1.0.64新增 per-harness MCP 服务器支持mcpServers同一版本还引入可选的mintBridgeToken(sandboxId)回调用于控制桥接令牌的具体取值。1.0.95新增可复用的createBridgeToken()与withBridgeToken()助手供桥接式 harness 适配器使用并修复了桥接解析会去寻找替代路径、进而引发 Turbopack 报错的问题。1.0.96新增可复用的createReadBridgeAsset()助手bootstrap 引导资产读取即由它实现见 deepagents-bootstrap.ts。1.0.52bootstrap 文件不再写入/tmp改放在沙箱工作目录内以便快照型沙箱提供方可以持久化其安装与配方标记。1.0.19适配器统一发送User-Agent与x-client-app请求头客户端标识为ai-sdk/harness-deepagents/version见 deepagents-harness.ts。五、内置工具通用名到 LangGraph 原生工具的映射适配器声明了 Deep Agents 全部可被模型调用的内置工具统一注册在DEEPAGENTS_BUILTIN_TOOLSdeepagents-harness.ts。AI SDK 侧若未全部列出会抛出AI_NoSuchToolError因此这张表必须与桥接层实际发射的工具名完全一致通用名原生LangGraph工具工具用途类别输入 Schema 要点readread_filereadonly{ file_path }writewrite_fileedit{ file_path, content }editedit_fileedit{ file_path, old_string, new_string }bashexecutebash{ command }grepgrepreadonly{ pattern }globglobreadonly{ pattern }lsls—{ path? }无通用名按原生名键控tasktask—{ description?, subagent_type? }派生子代理处理委派任务write_todoswrite_todos—{ todos? }管理结构化待办列表需要说明包 README.md 中的内置工具表bash → shell、grep → search与当前源码实现不一致应以源码中的read_file/write_file/edit_file/execute/grep/glob映射为准——这属于文档滞后于代码的情况。工具过滤能力activeTools/inactiveTools在1.0.11加入允许按名启用/禁用内置工具过滤逻辑经start消息的builtinToolFiltering字段下发。1.0.11同时为 harness 中若干重复层提供了工具函数。六、生命周期与会话恢复从停止/挂起到跨进程续跑适配器实现的会话方法deepagents-harness.ts包括doPromptTurn发起新轮次。校验结构化输出必须携带 JSON Schema把 skills 物化到沙箱$HOME/.agents/skillswriteSkills名称需匹配^a-z0-9?$1-64 位小写字母数字加连字符随后发送start消息并挂起订阅stream-start、text-delta、reasoning-delta、tool-call、tool-approval-request、tool-result、file-change、finish-step、raw等流部件。doContinueTurn续跑当前轮次。若continueFrom目标桥接进程仍存活doStart会以{ resume: true }打开通道回放游标之后的事件不再发送start发送会清空回放日志。doSuspendTurn/doDetach在游标处冻结当前轮次channel.suspend()取得lastSeenEventId保留桥接进程存活返回包含桥接坐标port、token、lastSeenEventId、sandboxId与凭据代理环境的状态载荷供后续进程重新附着attach。doStop/doDestroy向桥接发送stop/destroy命令并执行进程回收等待 5 秒超时后 kill。doCompact手动压缩不支持抛HarnessCapabilityUnsupportedError。CHANGELOG 中与之相关的关键条目1.0.94Preserve Deep Agents conversation context when a stopped session is resumed——停止的会话恢复时保留对话上下文。1.0.78实验性支持转向中干预steering agent conversations mid-turn同版本还支持向HarnessAgentSession传入文件系统与进程受限的沙箱会话网络沙箱会话方法不可用时自动回退fallback。1.0.54桥接方法重命名——detach改为stop、shutdown改为destroy语义更清晰。1.0.42移除损坏的桥接channel.interrupt()层及其调用。1.0.22改进 opaque sandbox bridge 的错误处理按底层模型步骤正确发射finish-step流部件。1.0.40重构桥接代码把流事件发射从 launcher 中拆分出来使其可测试修复 Deep Agents 遥测中缺失模型 ID 的问题修复对 Deep Agents 递归限制默认值过度覆盖的问题。从源码结构看doStart优先尝试附着已有桥接路径只要continueFrom/resumeFrom状态里带桥接坐标就先尝试以该坐标连接 WebSocket 并回放失败再回退到全新拉起桥接进程。七、引导Bootstrap机制ripgrep 校验安装与依赖锁定沙箱内首次启动时适配器会写入三份引导资产deepagents-bootstrap.tsbridge.mjs桥接入口从包内src/bridge/index.mjs读取后写入沙箱$WORKDIR/.harness-bootstrap/deepagents/package.json与pnpm-lock.yaml锁定deepagents及 LangChain 系版本随后执行两条引导命令ripgrep 校验安装command -v rg已存在则跳过否则按架构下载固定版本14.1.1的压缩包用硬编码 SHA-256 校验x64 与 aarch64 各一份后安装到/usr/local/bin/rg。之所以必须安装是因为 Deep Agents 的 grep 会外部调用rg缺失时回退逻辑会整个读取工作目录含 node_modules到内存容易 OOM。pnpm install --frozen-lockfile --store-dir .pnpm-store按锁定文件安装桥接运行时依赖。bootstrap 目录位于沙箱默认工作目录之下正是 1.0.52 变更的结果快照型沙箱提供方可以在不要求根文件系统访问的前提下持久化这份安装产物与配方标记。八、协议约束与当前能力边界从 deepagents-bridge-protocol.ts 与源码中的unsupported分支可以梳理出明确的边界提示prompt仅支持纯文本extractUserText会拒绝非 text 类型的内容部件如图片、文件部件否则抛HarnessCapabilityUnsupportedError。结构化输出必须有 JSON SchemaresponseFormat.type json但未提供 schema 时会直接拒绝。basic 沙箱会话无getPortEndpoint能力必须显式提供port与portEndpoint否则启动即报错。mintBridgeToken需要沙箱暴露 id无 id 的会话使用该选项会抛HarnessCapabilityUnsupportedErrordeepagents-harness.ts。手动压缩不支持README 同时提示续跑轮次、挂起/脱离、跨进程恢复与内置工具审批等能力仍属后续迭代部分能力如工具审批、续跑与恢复在后续版本中已逐步落地如 1.0.78、1.0.94 的进展。内置工具审批built-in tool approvals由桥接侧通过 Deep Agents 的interruptOnHITL中间件门控supportsBuiltinToolApprovals: true宿主侧通过tool-approval-request/tool-approval-response流部件完成人工确认交互。九、验证与测试资产包内提供了覆盖各层逻辑的测试可直接作为理解行为的参考入口deepagents-harness.test.ts宿主适配器端到端行为测试deepagents-auth.test.ts认证模式与环境解析测试deepagents-bridge-protocol.test.ts桥接协议 schema 测试deepagents-bootstrap.ts 旁的路由资产、bridge 目录下的approvals.test.ts、create-emit-stream-event.test.ts、json-schema-to-zod.test.ts、tool-filtering.test.ts、persistent-memory-saver.test.ts等则验证桥接内部各模块README 明确标注当前状态为happy-path validated文本生成、流式输出、多轮记忆与宿主执行工具均已在真实 Vercel Sandbox 中端到端验证。测试可通过pnpm test:node运行vitest 配置见 vitest.node.config.js。十、升级要点速览对使用方而言CHANGELOG 中最值得注意的破坏性/行为变化集中在model 迁移1.0.93 → 1.0.104模型统一由HarnessAgent({ model })持有适配器设置上的model/modelId已删除升级时需把模型参数上移。auth 选项简化1.0.71 → 1.0.92旧的 legacy auth 选项类型已移除现在只接受认证方式字符串或隔离凭据环境对象。桥接方法重命名1.0.54detach→stopshutdown→destroy。zod v3/v4 兼容1.0.3peer 依赖放宽到^3.25.76 || ^4.1.8宿主可按自身生态选择。其余版本主要是ai-sdk/harness与ai-sdk/provider-utils的依赖联动升级配合本文第五节列出的功能落地时间点即可完整回溯该适配器的能力成长路径。【免费下载链接】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 的 Deep Agents Harness 适配器演进：从 @ai-sdk/harness-deepagents 看桥接式编码代理的运行机制与能力全景
AI SDK 的 Deep Agents Harness 适配器演进从 ai-sdk/harness-deepagents 看桥接式编码代理的运行机制与能力全景【免费下载链接】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/aiai-sdk/harness-deepagents是 AI SDKThe AI Toolkit for TypeScript中把 LangChain 的 Deep Agents基于 LangGraph 的编码代理运行时接入 AI SDK Harness 体系的适配器。本文以该包的 CHANGELOG.md版本 1.0.0 至 1.0.107为骨架结合 源码实现 逐层剖析它如何在沙箱内通过 Node 桥接进程驱动deepagents包、如何通过 WebSocket 与宿主适配器交互、认证与凭据代理如何工作以及activeTools/inactiveTools工具过滤、output结构化输出、credentialForwarding、mintBridgeToken、per-harness MCP 服务器、会话恢复等关键能力是如何随版本演进而逐步落地的。读完本文你将掌握该适配器的完整配置面、生命周期模型与升级断点可直接用于评估和接入自己的 Agent 应用。一、包定位桥接式Bridge-BackedHarness 适配器从 README.md 与 package.json 可以看到该包是一个HarnessV1适配器harnessId为deepagents见 deepagents-harness.ts。它的核心设计是运行时在沙箱内Deep Agents 运行时并不运行在宿主进程而是通过一个 Node 桥接脚本bridge.mjs运行在 AI SDK 沙箱Sandbox中桥接运行时基于共享的ai-sdk/harness/bridge。宿主通过 WebSocket 驱动轮次宿主适配器doStart加会话的doPromptTurn/doStop/doDestroy通过 WebSocket 通道与沙箱内的桥接进程通信流式事件文本增量、推理增量、工具调用、文件变更等沿该通道回传。依赖按需安装桥接进程所依赖的deepagents包与 LangChain 系依赖会在启动时通过pnpm install --frozen-lockfile安装到引导bootstrap目录而不是打进宿主包。包版本与ai-sdk/harness、ai-sdk/provider-utils保持严格同步每次 Patch 都会联动升级对应依赖版本这是 CHANGELOG 中最频繁出现的条目类型。包要求 Node.js 22并以zod^3.25.76 或 ^4.1.8为 peer 依赖——这正是 1.0.3 中fix(harness): fix harness Zod usage to be v3/v4 compatible的由来适配器内部统一使用zod/v4解析桥接协议同时兼容宿主侧的 zod v3 与 v4。1.1 快速上手pnpm add ai-sdk/harness-deepagents ai-sdk/harnessimport { HarnessAgent } from ai-sdk/harness/agent; import { deepAgents } from ai-sdk/harness-deepagents; const agent new HarnessAgent({ harness: deepAgents, // 等价于 createDeepAgents() // ...sandbox provider configuration });deepAgents是默认实例等价于createDeepAgents()见 index.tscreateDeepAgents(settings)则用于传入自定义设置。二、认证体系Anthropic 直连与 AI Gateway 双模式Deep Agents 始终通过 Anthropic 客户端驱动模型但非 Anthropic 模型可以经由 AI Gateway 的 Anthropic 兼容端点转发含工具调用转换。deepagents-auth.ts 完整实现了这套逻辑认证模式DeepAgentsAuthenticationMode目前只有anthropic一种字面量继承HarnessV1Authenticationanthropic运行时解析出的实际模式DeepAgentsResolvedAuthenticationMode则可能是anthropic或ai-gateway。凭据环境变量固定为三个AI_GATEWAY_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN。解析优先级未显式配置时若环境存在 AI Gateway 凭据则优先走 gateway否则回退到 ambient Anthropic 凭据显式传auth: anthropic则强制直连 Anthropic读取ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_BASE_URLgateway 模式则把AI_GATEWAY_API_KEY同时映射为ANTHROPIC_API_KEY并设置ANTHROPIC_BASE_URLAnthropic SDK 会自行追加/v1/messages因此 base URL 保留在根路径。这也是 CHANGELOG 中auth选项演进的完整脉络版本变更含义1.0.71simplify the auth param to be a simple string to choose the auth methodauth简化为字符串选择认证方式1.0.92allow harness sessions to optionally authenticate from an isolated environment supplied through the auth option, and remove support for the formerly deprecated legacy auth options typesauth可传入隔离的凭据环境不必读process.env同时删除旧的遗留 auth 选项类型因此现在可以这样编程式传入认证环境const agent new HarnessAgent({ harness: createDeepAgents({ auth: { ANTHROPIC_API_KEY: token }, // 隔离环境不读 process.env }), model: anthropic/claude-sonnet-4.5, });三、凭据代理与请求转换沙箱内不落盘真实密钥沙箱内的桥接进程也需要调用模型 API但真实密钥不应直接注入沙箱进程环境。适配器在 1.0.72 引入了网络沙箱抽象层的请求转换能力并基于它实现凭据代理credential brokering沙箱内使用临时伪造的秘密宿主侧通过请求转换把请求头中的临时秘密替换回真实凭据。实现位于 deepagents-auth.tscreateDeepAgentsRequestTransformations根据认证模式匹配请求 URLgateway 模式用ANTHROPIC_BASE_URLanthropic 模式默认https://api.anthropic.com当宿主环境与沙箱环境同时存在ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN时分别注册x-api-key与Authorization: Bearer ...的请求头改写规则。围绕该机制的 CHANGELOG 条目1.0.87新增credentialForwarding设置为桥接式适配器提供细粒度控制——它自定义每个凭据值在被转发进沙箱进程前的改写方式但不限制宿主进程能发现、读取的凭据范围见 deepagents-harness.ts 的类型注释。1.0.90加固凭据代理只在携带正确的临时秘密时才应用替换harden credential brokering to only apply with correct ephemeral secret。1.0.100当credentialForwarding回调把全部凭据替换为临时假秘密时不再误报缺乏凭据代理支持的警告avoid warning about lack of credential brokering support ...。1.0.72支持网络沙箱抽象中的请求转换并用于凭据代理同时引入getPortEndpoint()作为getPortUrl()已弃用的更全面替代。此外从源码看若沙箱会话不支持addRequestTransformations适配器会退化为直接把改写后的凭据环境注入桥接进程并通过warnCredentialBrokeringUnavailable提示凭据代理不可用。这解释了 CHANGELOG 中多次出现的凭据代理相关修复的上下文。四、DeepAgentsHarnessSettings 完整配置面结合 deepagents-harness.ts 的DeepAgentsHarnessSettings类型与协议定义适配器的全部设置如下设置项类型说明authDeepAgentsAuthenticationMode认证方式或隔离认证环境未设置时按环境自动解析credentialForwardingHarnessV1CredentialForwarding自定义每个凭据转发进沙箱前的改写thinkingDeepAgentsThinkingConfig控制 Anthropic 扩展思考未设置保留 Deep Agents 运行时默认值effortlow \| medium \| high \| xhigh \| max自适应思考下的努力程度未设置使用 LangChain Anthropic 客户端默认值portnumber桥接端口覆盖默认取沙箱第一个声明的端口portEndpointHarnessV1PortEndpoint覆盖连接沙箱桥接的宿主端点使用 basic sandbox 会话时必须与port一起提供startupTimeoutMsnumber等待桥接广播端口的最长时间默认 120000mintBridgeTokenHarnessV1MintBridgeTokenCallback生成沙箱桥接认证令牌默认随机 32 字节十六进制令牌recursionLimitnumber每轮 LangGraph super-step 上限超限报错省略时用 Deep Agents 默认值mcpServersRecordstring, unknown按名称键控的 MCP 服务器定义使用底层运行时的原生 MCP 配置格式其中thinking支持三种形态bridge 协议 中有对应的 discriminated union schematype DeepAgentsThinkingConfig | { type: adaptive; display?: summarized | omitted } | { type: enabled; budget_tokens: number; display?: summarized | omitted } | { type: disabled };4.1 设置相关的重要版本演进1.0.93model参数上移到HarnessAgent各 harness 适配器构造函数不再各自支持model同时新增prepareCall()支持允许在两个轮次之间更改 harness 设置。1.0.94 进一步允许通过调用选项call options在轮次之间更换model。1.0.104正式移除先前已弃用的 harness 适配器设置上的model与modelId配置——从源码看模型现在统一由HarnessAgent持有并在doPromptTurn时经start消息传入桥接。1.0.102新增headers属性允许在推理请求inference requests上附带任意请求头源码中该值通过start消息的headers字段下发。1.0.64新增 per-harness MCP 服务器支持mcpServers同一版本还引入可选的mintBridgeToken(sandboxId)回调用于控制桥接令牌的具体取值。1.0.95新增可复用的createBridgeToken()与withBridgeToken()助手供桥接式 harness 适配器使用并修复了桥接解析会去寻找替代路径、进而引发 Turbopack 报错的问题。1.0.96新增可复用的createReadBridgeAsset()助手bootstrap 引导资产读取即由它实现见 deepagents-bootstrap.ts。1.0.52bootstrap 文件不再写入/tmp改放在沙箱工作目录内以便快照型沙箱提供方可以持久化其安装与配方标记。1.0.19适配器统一发送User-Agent与x-client-app请求头客户端标识为ai-sdk/harness-deepagents/version见 deepagents-harness.ts。五、内置工具通用名到 LangGraph 原生工具的映射适配器声明了 Deep Agents 全部可被模型调用的内置工具统一注册在DEEPAGENTS_BUILTIN_TOOLSdeepagents-harness.ts。AI SDK 侧若未全部列出会抛出AI_NoSuchToolError因此这张表必须与桥接层实际发射的工具名完全一致通用名原生LangGraph工具工具用途类别输入 Schema 要点readread_filereadonly{ file_path }writewrite_fileedit{ file_path, content }editedit_fileedit{ file_path, old_string, new_string }bashexecutebash{ command }grepgrepreadonly{ pattern }globglobreadonly{ pattern }lsls—{ path? }无通用名按原生名键控tasktask—{ description?, subagent_type? }派生子代理处理委派任务write_todoswrite_todos—{ todos? }管理结构化待办列表需要说明包 README.md 中的内置工具表bash → shell、grep → search与当前源码实现不一致应以源码中的read_file/write_file/edit_file/execute/grep/glob映射为准——这属于文档滞后于代码的情况。工具过滤能力activeTools/inactiveTools在1.0.11加入允许按名启用/禁用内置工具过滤逻辑经start消息的builtinToolFiltering字段下发。1.0.11同时为 harness 中若干重复层提供了工具函数。六、生命周期与会话恢复从停止/挂起到跨进程续跑适配器实现的会话方法deepagents-harness.ts包括doPromptTurn发起新轮次。校验结构化输出必须携带 JSON Schema把 skills 物化到沙箱$HOME/.agents/skillswriteSkills名称需匹配^a-z0-9?$1-64 位小写字母数字加连字符随后发送start消息并挂起订阅stream-start、text-delta、reasoning-delta、tool-call、tool-approval-request、tool-result、file-change、finish-step、raw等流部件。doContinueTurn续跑当前轮次。若continueFrom目标桥接进程仍存活doStart会以{ resume: true }打开通道回放游标之后的事件不再发送start发送会清空回放日志。doSuspendTurn/doDetach在游标处冻结当前轮次channel.suspend()取得lastSeenEventId保留桥接进程存活返回包含桥接坐标port、token、lastSeenEventId、sandboxId与凭据代理环境的状态载荷供后续进程重新附着attach。doStop/doDestroy向桥接发送stop/destroy命令并执行进程回收等待 5 秒超时后 kill。doCompact手动压缩不支持抛HarnessCapabilityUnsupportedError。CHANGELOG 中与之相关的关键条目1.0.94Preserve Deep Agents conversation context when a stopped session is resumed——停止的会话恢复时保留对话上下文。1.0.78实验性支持转向中干预steering agent conversations mid-turn同版本还支持向HarnessAgentSession传入文件系统与进程受限的沙箱会话网络沙箱会话方法不可用时自动回退fallback。1.0.54桥接方法重命名——detach改为stop、shutdown改为destroy语义更清晰。1.0.42移除损坏的桥接channel.interrupt()层及其调用。1.0.22改进 opaque sandbox bridge 的错误处理按底层模型步骤正确发射finish-step流部件。1.0.40重构桥接代码把流事件发射从 launcher 中拆分出来使其可测试修复 Deep Agents 遥测中缺失模型 ID 的问题修复对 Deep Agents 递归限制默认值过度覆盖的问题。从源码结构看doStart优先尝试附着已有桥接路径只要continueFrom/resumeFrom状态里带桥接坐标就先尝试以该坐标连接 WebSocket 并回放失败再回退到全新拉起桥接进程。七、引导Bootstrap机制ripgrep 校验安装与依赖锁定沙箱内首次启动时适配器会写入三份引导资产deepagents-bootstrap.tsbridge.mjs桥接入口从包内src/bridge/index.mjs读取后写入沙箱$WORKDIR/.harness-bootstrap/deepagents/package.json与pnpm-lock.yaml锁定deepagents及 LangChain 系版本随后执行两条引导命令ripgrep 校验安装command -v rg已存在则跳过否则按架构下载固定版本14.1.1的压缩包用硬编码 SHA-256 校验x64 与 aarch64 各一份后安装到/usr/local/bin/rg。之所以必须安装是因为 Deep Agents 的 grep 会外部调用rg缺失时回退逻辑会整个读取工作目录含 node_modules到内存容易 OOM。pnpm install --frozen-lockfile --store-dir .pnpm-store按锁定文件安装桥接运行时依赖。bootstrap 目录位于沙箱默认工作目录之下正是 1.0.52 变更的结果快照型沙箱提供方可以在不要求根文件系统访问的前提下持久化这份安装产物与配方标记。八、协议约束与当前能力边界从 deepagents-bridge-protocol.ts 与源码中的unsupported分支可以梳理出明确的边界提示prompt仅支持纯文本extractUserText会拒绝非 text 类型的内容部件如图片、文件部件否则抛HarnessCapabilityUnsupportedError。结构化输出必须有 JSON SchemaresponseFormat.type json但未提供 schema 时会直接拒绝。basic 沙箱会话无getPortEndpoint能力必须显式提供port与portEndpoint否则启动即报错。mintBridgeToken需要沙箱暴露 id无 id 的会话使用该选项会抛HarnessCapabilityUnsupportedErrordeepagents-harness.ts。手动压缩不支持README 同时提示续跑轮次、挂起/脱离、跨进程恢复与内置工具审批等能力仍属后续迭代部分能力如工具审批、续跑与恢复在后续版本中已逐步落地如 1.0.78、1.0.94 的进展。内置工具审批built-in tool approvals由桥接侧通过 Deep Agents 的interruptOnHITL中间件门控supportsBuiltinToolApprovals: true宿主侧通过tool-approval-request/tool-approval-response流部件完成人工确认交互。九、验证与测试资产包内提供了覆盖各层逻辑的测试可直接作为理解行为的参考入口deepagents-harness.test.ts宿主适配器端到端行为测试deepagents-auth.test.ts认证模式与环境解析测试deepagents-bridge-protocol.test.ts桥接协议 schema 测试deepagents-bootstrap.ts 旁的路由资产、bridge 目录下的approvals.test.ts、create-emit-stream-event.test.ts、json-schema-to-zod.test.ts、tool-filtering.test.ts、persistent-memory-saver.test.ts等则验证桥接内部各模块README 明确标注当前状态为happy-path validated文本生成、流式输出、多轮记忆与宿主执行工具均已在真实 Vercel Sandbox 中端到端验证。测试可通过pnpm test:node运行vitest 配置见 vitest.node.config.js。十、升级要点速览对使用方而言CHANGELOG 中最值得注意的破坏性/行为变化集中在model 迁移1.0.93 → 1.0.104模型统一由HarnessAgent({ model })持有适配器设置上的model/modelId已删除升级时需把模型参数上移。auth 选项简化1.0.71 → 1.0.92旧的 legacy auth 选项类型已移除现在只接受认证方式字符串或隔离凭据环境对象。桥接方法重命名1.0.54detach→stopshutdown→destroy。zod v3/v4 兼容1.0.3peer 依赖放宽到^3.25.76 || ^4.1.8宿主可按自身生态选择。其余版本主要是ai-sdk/harness与ai-sdk/provider-utils的依赖联动升级配合本文第五节列出的功能落地时间点即可完整回溯该适配器的能力成长路径。【免费下载链接】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），仅供参考