AI SDK 接入 Deep Agents用 ai-sdk/harness-deepagents 在沙箱中运行 LangGraph 编码 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/aiai-sdk/harness-deepagents是 AI SDK 生态中的一款Bridge 型 Harness 适配器它将 LangChain 基于 LangGraph 构建的 Deep Agentsdeepagentsnpm 包作为编码 Agent 运行时放进 AI SDK 沙箱内执行。读完本文你将掌握如何安装并配置该 Harness、通过HarnessAgent发起对话与流式输出、理解其“宿主导航 Node Bridge WebSocket 通信”的架构原理以及认证、内置工具、多轮记忆、MCP 与审批HITL等核心能力的正确用法与当前限制。一、什么是 Bridge 型 Harness架构总览ai-sdk/harness-deepagents本身不是一个独立运行的 Agent而是 AI SDK Harness 体系中的一名适配器成员。它把 Deep Agents 的运行时安装进沙箱并通过共享的ai-sdk/harness/bridge运行时驱动整体由三层构成宿主导配器host adapter实现HarnessV1接口负责doStart启动会话、doPromptTurn/doStop/doDestroy等会话生命周期操作通过 WebSocket 与沙箱内的 Bridge 进程通信沙箱内的 Node Bridge以node bridge.mjs形式在沙箱内运行内部通过createDeepAgentstreamEvents驱动deepagentsnpm 包把 LangGraph 的流式事件翻译成 AI SDK 的标准流式消息沙箱network sandboxBridge 需要暴露 TCP 端口供宿主导配器回连因此必须使用支持端口的网络沙箱会话。关键源码入口见 deepagents-harness.ts其中createDeepAgents()工厂返回的 Harness 声明了specificationVersion: harness-v1与harnessId: deepagentsBridge 的完整实现在 bridge/index.ts它基于runBridge事件循环将 Deep Agents 的 LangGraph 流式事件转换为text-delta、tool-call、finish等标准消息。默认导出deepAgents等价于createDeepAgents()的入口见 index.ts。当前状态说明据 README.md 的状态说明该适配器已完成happy-path 端到端验证针对真实的 Vercel Sandbox文本生成、流式输出、多轮记忆、宿主导工具执行均可用而回合续跑turn continuation、suspend/detach、跨进程恢复、内置工具审批在当时被标记为后续工作会抛出HarnessCapabilityUnsupportedError。需要说明的是从当前仓库源码看doContinueTurn、doSuspendTurn、doDetach以及基于 HITL 中间件的内置工具审批supportsBuiltinToolApprovals: true均已具备完整实现见 deepagents-harness.ts 与 approvals.ts可以推断 README 的状态描述早于这些实现落地。实际使用时请以你安装版本的发布说明为准。二、安装与快速开始安装在项目中使用pnpm安装两个包pnpm add ai-sdk/harness-deepagents ai-sdk/harness注意该 Harness 是bridge-backed适配器需要能暴露端口的网络沙箱。根据 packages/harness/README.md 的说明ai-sdk/sandbox-vercel是当前受支持的沙箱提供方ai-sdk/sandbox-just-bash只适合宿主运行时或非 Bridge 流程如 Pi不能用于 Deep Agents。依赖的版本要求包声明engines.node 22Bridge 侧锁定deepagents1.13.1及 LangChain 相关依赖见 bridge/package.json。最小使用示例import { HarnessAgent } from ai-sdk/harness/agent; import { deepAgents } from ai-sdk/harness-deepagents; const agent new HarnessAgent({ harness: deepAgents, // ...sandbox provider configuration });完整实战示例结合沙箱、引导脚本与流式输出一个可运行的完整示例大致如下模式参考 packages/harness/README.md 中HarnessAgent的用法import { HarnessAgent } from ai-sdk/harness/agent; import { deepAgents } from ai-sdk/harness-deepagents; import { createVercelSandbox } from ai-sdk/sandbox-vercel; const agent new HarnessAgent({ harness: deepAgents, model: anthropic/claude-sonnet-4.5, instructions: You are a careful refactoring assistant. Prefer minimal diffs., sandbox: createVercelSandbox({ runtime: node24, ports: [4000], // Bridge 依赖沙箱暴露 TCP 端口 }), sandboxConfig: { bootstrapHash: deepagents-v1, onBootstrap: async ({ session, abortSignal }) { // 昂贵的、可快照复用的初始化在这里完成 const result await session.run({ command: command -v rg /dev/null || (apt-get update apt-get install -y ripgrep), abortSignal, }); if (result.exitCode ! 0) { throw new Error(Failed to install ripgrep: ${result.stderr}); } }, }, }); 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 专属的model接受任意字符串。Deep Agents 始终驱动 Anthropic 客户端直连 Anthropic 时 Bridge 会剥掉anthropic/前缀见 bridge/index.ts 中buildModel的rawModel.replace(/^anthropic[/:]/, )通过 AI Gateway 时则保留creator/model形式的模型 slug 交给网关翻译。端口是硬性要求Bridge 端口默认取沙箱声明的第一个端口ports[0]也可用createDeepAgents({ port })覆盖使用 basic sandbox session 时则必须同时显式提供port与portEndpoint否则抛出HarnessCapabilityUnsupportedError见 deepagents-harness.ts。会话状态管理session.detach()用于驻留parkBridge 会话以待后续 attachsession.stop()保存状态并停止沙箱session.destroy()直接清理且不保留恢复状态。三、认证AuthAnthropic 直连与 AI GatewayDeep Agents 使用 Anthropic 客户端可直连也可经由 AI Gateway 转发。根据 deepagents-auth.ts 的解析逻辑认证优先级为未配置任何模式优先采用环境中的 AI Gateway 凭据存在AI_GATEWAY_API_KEY即走 Gateway否则回退到 Anthropic 凭据显式传入认证环境createDeepAgents({ auth: { ANTHROPIC_API_KEY: token } })这类“认证环境”只读取你传入的对象不再读process.env显式模式auth: anthropic强制直连auth: ai-gateway强制走网关。示例程序化提供凭据避免直接读取process.envconst agent new HarnessAgent({ harness: createDeepAgents({ auth: { ANTHROPIC_API_KEY: token }, }), model: anthropic/claude-sonnet-4.5, });凭据转发与请求改写适配器把以下环境变量识别为 Deep Agents 凭据AI_GATEWAY_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN。在宿主导配器启动时若沙箱会话支持addRequestTransformations适配器会执行credential brokering把宿主机的真实凭据注入沙箱进程同时安装请求变换x-api-key与Authorization: Bearer ...头让沙箱内发出的模型请求在网关上被改写为宿主凭据从而避免把真实 Key 暴露给沙箱内进程见 deepagents-auth.ts若沙箱不支持请求变换则退化为普通的环境变量透传并打印warnCredentialBrokeringUnavailable警告走 AI Gateway 时适配器会把ANTHROPIC_BASE_URL设为网关根地址注意 Anthropic SDK 会自动追加/v1/messages并将网关 Key 同时写入AI_GATEWAY_API_KEY与ANTHROPIC_API_KEY。DeepAgentsHarnessSettings.credentialForwarding可进一步定制每个凭据值在转发进沙箱前的改写方式但它不限制宿主进程对凭据的发现与读取。四、沙箱引导Bootstrap自动安装依赖与 ripgrep该 Harness 会在启动时把 Bridge 的 Node 依赖deepagents包及 LangChain 全家桶通过pnpm安装进自己的bootstrap 目录整个过程由getDeepAgentsBootstrap()定义见 deepagents-bootstrap.tsbootstrap 目录沙箱默认工作目录/.harness-bootstrap/deepagents存放在沙箱默认工作目录下便于支持快照的沙箱提供方把安装结果烘焙进可复用快照写入文件bridge.mjs、package.json、pnpm-lock.yaml锁文件保证pnpm install --frozen-lockfile --store-dir .pnpm-store可复现安装 ripgrepDeep Agents 的 grep 会 shell 出到rg缺失时其回退实现会把整个工作目录含node_modules读进内存容易 OOM。因此 bootstrap 会校验并安装锁定版本14.1.1的 ripgrepx64 与 arm64 各配 SHA-256 校验和已存在rg时跳过安装Bridge 启动命令node bridge.mjs --workdir workdir --bridge-state-dir dir --bootstrap-dir dir [--resume true]随后宿主等待 Bridge 通过 WebSocket 宣告就绪默认超时120s可用startupTimeoutMs调整。与沙箱配置的配合在HarnessAgent.sandboxConfig中onSession在适配器启动前准备沙箱新会话与恢复会话都会执行需保持幂等onBootstrapbootstrapHash用于昂贵且应烘焙进快照的初始化如安装工具、克隆大仓库改动bootstrapHash可使缓存快照失效workDir设置稳定的工作目录相对沙箱默认工作目录未设置时使用harnessId-sessionId目录。五、会话生命周期、流式输出与多轮记忆HarnessAgent的统一会话模型让 Deep Agents 与其它 Harness 使用相同 APIagent.createSession()→agent.generate()/agent.stream()→session.destroy()。Bridge 侧一次回合的执行流程见 bridge/index.ts 的runTurn为接收宿主的start消息含 prompt、instructions、tools、responseFormat、thinking、effort、skillsPaths 等协议定义见 deepagents-bridge-protocol.ts若配置签名变化instructions/tools/skillsPaths或 skills 变更则重建createDeepAgent实例LangGraph 的MemorySaver作为 checkpointer 提供多轮记忆调用activeAgent.streamEvents()消费 LangGraph 流式事件翻译为text-start/delta/end、reasoning-*、tool-call、finish等标准消息推给宿主回合结束或 Bridge 以suspended原因关闭连接时干净收尾。持久化的对话检查点多轮记忆不仅存在于内存Bridge 在--bridge-state-dir下维护conversation.checkpoint格式为带deepagents-memory-saver-v1头部的 base64 TSV将 LangGraphMemorySaver的 storage 与 writes 全量落盘。onStop时保存快照--resume true启动时加载onDestroy时删除见 persistent-memory-saver.ts。这正是“跨进程恢复/续跑”的数据基础。会话生命周期方法宿主会话对象见 deepagents-harness.ts实现了doPromptTurn发送start把宿主工具、permissionMode、builtinToolFiltering、recursionLimit、mcpServers、headers一并透传doContinueTurnattach/续跑时由doStart以{ resume: true }打开通道并回放游标之后的事件不发送新的start否则会清空回放日志doSuspendTurn/doDetach在游标处冻结当前回合suspend或在回合间驻留detach把{ port, token, lastSeenEventId, sandboxId? }写进生命周期状态供后续进程重新连接doStop停止 Bridge 并返回 resume 状态doDestroy直接拆除不保留恢复状态doCompact当前会抛HarnessCapabilityUnsupportedError不支持手动压缩。六、内置工具原生工具注册表与审批HITLREADME 提供的映射表通用名Common name原生工具Native LangGraph toolreadread_filewritewrite_filebashshellgrepsearch源码确认的完整注册表对照当前源码 deepagents-harness.tsDEEPAGENTS_BUILTIN_TOOLS实际注册的工具比 README 表格更全且部分原生名与 README 表格不一致README 的bash → shell、grep → search应为早期版本命名源码当前为execute与grep通用名原生名nativeName用途toolUseKindreadread_file读取文件内容readonlywritewrite_file创建文件editeditedit_file在文件中做精确字符串替换editbashexecute执行 shell 命令bashgrepgrep搜索文件内容readonlyglobglob按 glob 模式查找文件readonly—ls列出目录内容无通用名按原生名引用readonly—task生成子 Agent 处理委派任务edit—write_todos管理结构化待办列表edit注意所有模型可调用的内置工具都必须出现在该注册表中否则 AI SDK 会抛出AI_NoSuchToolError。README 表格之外的工具edit/glob/ls/task/write_todos正是这一机制的延伸。内置工具审批与权限模式适配器声明supportsBuiltinToolApprovals: true审批在 Bridge 内通过 Deep Agents 的interruptOnHITL中间件实现见 approvals.tspermissionMode allow-all全部放行无需审批permissionMode allow-edits仅bashexecute类工具需要审批默认模式edit与bash类工具都需要审批。builtinToolFiltering支持allow/deny两种模式配合toolNames列表决定哪些内置工具参与审批isBuiltinToolIncluded会在桥内先把原生名换算成通用名再比对。审批流程为Bridge 发出tool-approval-request→ 宿主调用submitToolApproval({ approvalId, approved, reason? })→ Bridge 以Command({ resume: { decisions } })恢复 LangGraph 执行被拒绝的工具不会执行直接把拒绝原因作为tool-result返回。七、模型、思考模式、effort 与结构化输出thinking 与 effortDeep Agents 适配器支持 Anthropic 扩展思考extended thinkingDeepAgentsThinkingConfig有三种形态type DeepAgentsThinkingConfig | { type: adaptive; display?: summarized | omitted } | { type: enabled; budget_tokens: number; display?: summarized | omitted } | { type: disabled };未设置thinking时保留 Deep Agents 运行时默认effortlow | medium | high | xhigh | max在启用 adaptive 思考时控制 Claude 投入的推理量未设置时使用 LangChain Anthropic 客户端默认值。两者都会通过 Bridge 的modelMiddleware应用到ChatAnthropic实例见 bridge/index.ts 的buildModeleffort映射到outputConfig.effort。结构化输出在HarnessAgent上设置output如Output.object({ schema })后每个回合都要求同样的 schema 化输出。Bridge 侧通过 LangChain 的toolStrategy把 JSON Schema 转成 tool 约束JSON Schema → Zod 的转换见 json-schema-to-zod.ts并把最终的structuredResponse以普通文本片段形式输出保证generate()的result.output与stream()的partialOutputStream都可用。注意responseFormat.type json但缺少 schema 时适配器会抛出HarnessCapabilityUnsupportedError。八、扩展能力MCP 服务器、Skills 与宿主工具MCP 服务器createDeepAgents({ mcpServers })接受以服务器名为键的配置对象值使用底层运行时原生 MCP 配置格式必须为对象。Bridge 通过MultiServerMCPClient加载工具工具名以mcp服务器名_工具名形式前缀化且会剔除与宿主工具同名的冲突项见 bridge/index.ts。Skills技能Deep Agents 会在工作目录下发现仓库自带 skillsHarness 提供的 skills 则写入$HOME/.agents/skills绝对路径避开与克隆进工作目录的代码冲突。由于 Harness skills 路径排在最后同名时以 Harness 提供的为准。skill 名称必须匹配^a-z0-9?$小写字母数字加连字符1–64 字符文件路径采用剥离前导斜杠模式见 deepagents-harness.ts。宿主工具传给HarnessAgent.tools的自定义工具会成为 LangChain 工具运行在沙箱内Bridge 发出tool-call事件宿主执行后在submitToolResult中回传结果见buildHostTools。宿主工具本身不走 HITL 审批审批发生在 Agent 层因此适用于需要宿主环境能力如调用外部 API、读取宿主机密的场景。九、当前限制与注意事项综合 README 与源码使用前请留意必须使用网络沙箱Bridge 需要端口与 WebSocket 回连当前支持ai-sdk/sandbox-vercel若用 basic sandbox session 则必须显式提供portportEndpoint能力边界README 将回合续跑、suspend/detach、跨进程恢复、内置工具审批列为后续项源码中已具备实现以发布版本为准doCompact明确不支持用户消息只接受纯文本内容extractUserText遇到非文本 part 会抛HarnessCapabilityUnsupportedError模型受限Deep Agents 只驱动 Anthropic 客户端其它厂商模型需要经由 AI Gateway 的 Anthropic 兼容端点翻译运行环境包要求 Node.js 22Bridge 依赖pnpm在沙箱内完成frozen-lockfile安装bootstrap 需要出网下载 ripgrep 与 npm 依赖。十、进一步阅读适配器 README 与实现packages/harness-deepagents/README.md、deepagents-harness.ts、index.tsHarness 通用规范与HarnessAgent用法packages/harness/README.md认证与凭据转发deepagents-auth.ts引导安装与 ripgrep 校验deepagents-bootstrap.tsBridge 运行时与消息协议bridge/index.ts、deepagents-bridge-protocol.ts审批、工具过滤与记忆持久化approvals.ts、tool-filtering.ts、persistent-memory-saver.ts配套测试验证协议与流程deepagents-harness.test.ts、deepagents-bridge-protocol.test.ts、deepagents-auth.test.ts【免费下载链接】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），仅供参考