Mastra mastra/agentcore 沙箱提供方深度解析从 AWS Bedrock AgentCore Runtime 到工作区命令执行【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南围绕 Mastra 仓库中workspaces/agentcore包的官方变更记录CHANGELOG.md展开系统讲解mastra/agentcore作为 Mastra Workspace 沙箱提供方如何把命令执行映射到 AWS Bedrock AgentCore Runtime并逐一拆解 0.2.0 至 0.5.0 各版本引入的workingDirectory、运行时环境变量合并、ProcessHandle.closeStdin()等关键能力。读完本文你将掌握AgentCoreRuntimeSandbox的完整配置项、命令构建与超时语义、会话生命周期管理以及如何通过源码与测试验证这些行为。一、mastra/agentcore 是什么mastra/agentcore是 Mastra 的 Workspace 沙箱提供方之一其核心能力是在 AWS Bedrock AgentCore Runtime 会话中执行命令并支持会话管理、环境变量与文件操作见 README.md。它把 Mastra 一次性命令执行契约映射到 AWS SDK 的InvokeAgentRuntimeCommand并且刻意不暴露进程管理与文件系统挂载——因为 AgentCore Runtime 的命令执行本身不提供这两类 WorkspaceSandbox 语义见 sandbox/index.ts 顶部注释。从包元数据看package.json该包当前版本为 0.5.0依赖aws-sdk/client-bedrock-agentcore^3.1095.0要求 Node.js 22.13.0并以mastra/core1.12.0-0 2.0.0-0为 peerDependency。包的主入口src/index.ts只导出两类内容AgentCoreRuntimeSandbox类与AgentCoreRuntimeSandboxOptions类型来自./sandboxagentCoreRuntimeSandboxProvider提供方描述符与AgentCoreRuntimeProviderConfig类型来自./provider。二、安装与最小可用示例安装npm install mastra/agentcore与 Mastra Workspace 组合使用源自 README.md 的官方示例import { Workspace } from mastra/core/workspace; import { AgentCoreRuntimeSandbox } from mastra/agentcore; const workspace new Workspace({ sandbox: new AgentCoreRuntimeSandbox({ region: us-west-2, agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!, runtimeSessionId: 12345678-1234-1234-1234-123456789012, }), }); const result await workspace.sandbox?.executeCommand?.(npm, [test], { cwd: /workspace, timeout: 300_000, });这是 CHANGELOG 0.2.0 版本引入的核心能力PR #16642通过沙箱提供方在 AWS Bedrock AgentCore Runtime 中运行 Workspace 命令。CHANGELOG 给出的原始最小示例同样成立import { AgentCoreRuntimeSandbox } from mastra/agentcore; const sandbox new AgentCoreRuntimeSandbox({ region: us-west-2, agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!, }); const result await sandbox.executeCommand(node, [--version]);三、配置参数全表AgentCoreRuntimeSandboxOptionsAgentCoreRuntimeSandboxOptions的定义位于 sandbox/index.ts它继承自mastra/core的MastraSandboxOptions剔除processes字段并增加了 AgentCore 专属参数参数类型默认值说明regionstringAWS SDK 默认 region 链Bedrock AgentCore 客户端使用的 AWS 区域agentRuntimeArnstring必填无命令将要执行的 AgentCore Runtime ARN构造时缺失会直接抛错runtimeSessionIdstring自动生成 UUIDRuntime 会话 ID。生成值满足 AgentCore 33 字符最小长度要求同时它也被用作沙箱的idqualifierstringAgentCore 的DEFAULTqualifierAgent runtime 限定符/端点contentTypestringapplication/json命令请求的 MIME 类型acceptstringapplication/vnd.amazon.eventstream命令事件流的 Accept 头commandTimeoutnumber300_000毫秒默认命令超时时间stopSessionOnLifecyclebooleanfalse在stop()/destroy()时是否停止 AgentCore Runtime 会话stopClientTokenstring需要时生成 UUID用于StopRuntimeSession的客户端令牌clientAgentCoreRuntimeClient内部新建 SDK 客户端预配置的 AWS SDK 客户端主要供高级凭证配置与测试使用instructionsstring \| 函数默认指令文本自定义getInstructions()输出函数形式接收defaultInstructions与requestContext同时从MastraSandboxOptions继承的通用选项包括生命周期钩子onStart/onStop/onDestroy、运行时环境env、默认工作目录workingDirectory详见下文。MastraSandboxOptions的完整定义见 packages/core/src/workspace/sandbox/mastra-sandbox.ts。值得一提的是AgentCoreRuntimeSandbox的构造器sandbox/index.ts会校验agentRuntimeArn必填、用runtimeSessionId ?? randomUUID()决定沙箱 ID并记录_ownsClient只有内部创建的客户端才由沙箱在销毁时负责释放。用于 UI 配置的 Provider 描述符provider.ts 导出的agentCoreRuntimeSandboxProvider把上述配置序列化为 JSON Schema使 Mastra Editor 可以通过 UI 驱动沙箱配置。从源码可以看到其约束provider.tsrequired: [agentRuntimeArn]commandTimeout的minimum: 1、maximum: 3_600_000、default: 300_000qualifier默认DEFAULTstopSessionOnLifecycle默认falsecreateSandbox: config new AgentCoreRuntimeSandbox(config)。四、workingDirectory统一的默认工作目录0.5.0CHANGELOG 0.5.0PR #22697是本文档的Minor Change 核心向MastraSandboxOptions新增workingDirectory选项并被每一个沙箱提供方采纳。行为规则每个沙箱接受一个实例级的workingDirectory选项作为命令执行与进程启动的默认目录单条命令的cwd始终优先于它两者都未提供时各提供方保留原有默认值E2B 为 homedocker 为/workspaceVercel serverless 为/tmp以此类推生效值可通过新的sandbox.workingDirectorygetter 读取。CHANGELOG 给出的官方示例const sandbox new E2BSandbox({ workingDirectory: /home/user/my-repo }); await sandbox.executeCommand(pwd); // /home/user/my-repo await sandbox.executeCommand(pwd, [], { cwd: /tmp }); // /tmp与既有命名别名共存那些已经用其他名字承载该概念的提供方旧名字作为废弃别名继续可用并喂给同一字段workingDirmastra/docker、mastra/apple-containerworkdirmastra/modal。当别名与workingDirectory同时设置时workingDirectory胜出。必须使用绝对路径该值会原样传递给提供方因此~与$HOME这类环境变量不会被展开除非提供方明确文档化其展开行为例如LocalSandbox会展开~。AgentCore 上的实现细节在AgentCoreRuntimeSandbox中workingDirectory生效于buildCommand()sandbox/index.ts当options?.cwd ?? workingDirectory有值时命令会被前缀为cd 目录并用shellQuote做 shell 引号转义。源码注释特别指出cd 目标被 shell 引号包裹会抵消~展开——因此该提供方的 workingDirectory 必须是绝对路径。单元测试也验证了这一点配置workingDirectory: /srv/app后执行pwd实际发送的命令为cd /srv/app pwd见 index.test.ts单条命令传cwd: /tmp时命令变为cd /tmp pwd即 per-commandcwd胜出index.test.ts两者均未设置时无cd前缀sandbox.workingDirectory返回undefinedindex.test.ts。基类语义在MastraSandbox基类中workingDirectory通过_workingDirectory存储、workingDirectorygetter 暴露并提供受保护的setWorkingDirectory()供需要在运行时探测/回写生效值的提供方使用mastra-sandbox.ts。基类文档同时强调沙箱不会创建该目录且不支持该概念的提供方回退到各自旧默认值。五、环境变量构造时注入与运行时合并0.4.1CHANGELOG 0.4.1PR #22250解决了一个跨提供方的一致性问题让mastra/core的setEnv()/getEnv()运行时环境在每一个 Workspace 沙箱提供方上生效。此前构造后设置的环境变量无法到达后续命令。两条执行路径的归一进程管理器路由的提供方E2B、Blaxel、Cloudflare、Daytona、Docker、Modal、Vercel microVM spawn继承自 core spawn wrapper 的合并逻辑删除了这些提供方各自重复的 per-manager env 管道自带 exec 传输的提供方AgentCore、Apple Container、Railway、Vercel microVM 与 serverless 的executeCommand、Platform 的 private-network、WebSocket lease、E2B lease 路径现在在 per-call env 之下合并getEnv()。AgentCore 属于第二类。在 sandbox/index.ts 中可以看到具体实现——executeCommand里const fullCommand buildCommand( command, args, { ...options, env: { ...this.getEnv(), ...options?.env } }, this.workingDirectory, );即运行时环境 overlay 与单条命令env合并单条命令的env优先。环境变量优先级总表构造器env继续扮演“种子”角色注入沙箱运行时环境Docker、Modal、Railway、Apple Container、Vercel、Platform 等会把 env 在创建时烤进 VM/容器setEnv()运行时更新的 overlay构造后修改立即作用于后续命令单条命令的 per-callenv仅对该命令生效优先级最高。测试用例验证了该行为index.test.tssandbox.setEnv(env ({ ...env, GH_TOKEN: tok_1 }))后执行命令发送的命令体包含GH_TOKENtok_1。移除的导出类型作为 minor bump 的连带变更以下两个仅为手工构造进程管理器而存在的类型被删除BlaxelProcessManagerOptionsmastra/blaxelRailwayProcessManagerOptionsmastra/railway。因为 core spawn wrapper 现在自己拥有 env 合并逻辑这两个只用来向手工构造的进程管理器传env的选项及其类型随之消失。环境变量名校验AgentCore 提供方对 env 名做了严格校验sandbox/index.ts名称必须匹配/^[A-Za-z_][A-Za-z0-9_]*$/否则抛出Invalid environment variable name for AgentCore Runtime command测试见 index.test.ts。命令中的 env 赋值同样经过shellQuote转义。六、ProcessHandle.closeStdin()向后台进程发送 EOF0.4.0CHANGELOG 0.4.0PR #21606为ProcessHandle增加了closeStdin()方法用于向后台进程发出标准输入 EOF。支持度矩阵Local 与 Docker 沙箱原生支持关闭 stdin无 stdin-close API 的提供方返回提供方专属的“不支持的操作”错误并通过新的UnsupportedStdinCloseError类型标识基类默认行为基类默认提供该行为因此现有ProcessHandle子类无需改动即可继续编译等价写法调用handle.writer.end()也会关闭 stdin且在提供方无法关闭 stdin 时无错误地正常完成。在 AgentCore 提供方中CommandOutputAccumulator extends ProcessHandlesandbox/index.ts的closeStdin()直接抛出UnsupportedStdinCloseError与sendStdin()抛错一致——因为 AgentCore Runtime 命令执行本身不支持 stdin。这也解释了为何CommandOutputAccumulator的pid固定为agentcore-command、kill()返回falseAgentCore 命令是一次性、非交互的。七、命令构建、超时与输出语义源码级命令字符串如何组装buildCommand()sandbox/index.ts的组装顺序为cd cwd若配置了 cwd 或 workingDirectory合法的 env 赋值KEYvalue均经shellQuote原始命令与参数command arg1 arg2参数逐个shellQuote。各部分用连接。shellQuotesandbox/index.ts对安全字符集/^[a-zA-Z0-9._\-\/:]$/原样保留其余用单引号包裹并把内嵌单引号转义为\。测试中的断言cd /workspace/app NODE_ENVtest npm test完整印证了这一过程index.test.ts。超时语义toAgentCoreTimeoutSeconds()sandbox/index.ts把毫秒超时向上取整为秒并施加硬限制超时必须为正数否则抛RangeError上限MAX_AGENTCORE_TIMEOUT_SECONDS 3600秒即 3,600,000 ms超过即抛错默认commandTimeout 300_000ms。超时后的行为很有意思AgentCore 事件流中的contentStop.status若为TIMED_OUT提供方会把最终退出码规范化为124Linux timeout 惯例timedOut: true且即使 AgentCore 省略了超时退出码也会补上 124实现见 sandbox/index.ts测试见 index.test.ts。超时上限与默认值的双重校验测试见 index.test.ts。事件流处理与错误上报executeCommand通过InvokeAgentRuntimeCommandCommand发送请求并逐条消费响应的事件流sandbox/index.tscontentDelta.stdout/contentDelta.stderr实时通过output.emitStdout/emitStderr回调对应ExecuteCommandOptions.onStdout/onStderrcontentStop记录退出码与状态七类流异常accessDeniedException、internalServerException、resourceNotFoundException、serviceQuotaExceededException、throttlingException、validationException、runtimeClientError以及$unknown字段都会被识别并格式化为[AgentCoreRuntimeSandbox] Name: message抛给调用方sandbox/index.ts测试见 index.test.ts请求同时支持abortSignal透传给 AWS SDKindex.test.ts。返回的CommandResult包含success、exitCode、stdout、stderr、executionTimeMs、timedOut、stdoutTruncated、stderrTruncated、stdoutDroppedBytes、stderrDroppedBytes等完整字段并支持maxRetainedBytes截断输出上限。使用限制getInstructions()的默认指令文本sandbox/index.ts明示了该提供方的边界这对 Agent 编排尤其重要命令一次性、非交互命令之间没有持久的 shell 会话不暴露后台进程管理不暴露文件系统挂载git、npm、Python、Node 等工具必须存在于 AgentCore 容器镜像中AgentCore Code Interpreter 是独立服务不属于本 Runtime 沙箱。instructions选项支持字符串替换或函数接收defaultInstructionsrequestContext后返回新文本测试见 index.test.ts。八、会话生命周期何时停止 Runtime SessionAgentCore Runtime 会话常常与沙箱实例之外的 Agent 调用共享因此提供方把“停止会话”与“销毁沙箱”分离sandbox/index.tsstop()/destroy()仅当stopSessionOnLifecycle: true时才调用StopRuntimeSessionCommandstopRuntimeSession()显式停止会话的独立方法供会话共享场景下由调用方自行决定destroy()同时负责释放自建的AWS SDK 客户端_ownsClient为 true 时调用client.destroy()stopClientToken未提供时用生成 UUID保证StopRuntimeSessionCommand的幂等令牌getInfo()返回的元数据包含agentRuntimeArn、runtimeSessionId、qualifier ?? DEFAULT、stopSessionOnLifecyclesandbox/index.ts。对应测试覆盖了“仅在启用 lifecycle 清理时停止会话”“默认不停止”“可显式停止”“销毁自建客户端”四条路径index.test.ts。九、发布维护与安全Patch Changes 解读CHANGELOG 中的 Patch 记录同样值得关注供应链安全修复0.2.4PR #18056针对 2026-06-17 的 easy-day-js 供应链事件做了安全修复发布干净版本并把latestdist-tag 前移取代那些声明了恶意easy-day-js依赖的受影响版本。这提醒使用者升级到 0.2.4 及以上版本即可避开被污染的版本。依赖更新0.2.1、0.3.1aws-sdk/client-bedrock-agentcore从^3.1045.0一路升级到^3.1095.0PR #17521、#17600、#20406。CHANGELOG 移出 npm 包0.5.0PR #22737CHANGELOG.md不再随包分发减小了包体积——这也解释了为何本仓库保留独立的 changelog 文件供查阅。README 持续更新0.5.0PR #22858。版本演进中mastra/core的依赖始终跟随0.5.0 对应mastra/core1.64.0且每个功能版本都有对应的-alpha预发布记录说明该包遵循 changesets 的常规发布流程。十、测试与验证该包测试分层明确见 package.json 的 scriptstest:unit跑vitest run --exclude **/*.integration.test.tstest/test:cloud跑vitest run ./src/**/*.integration.test.ts即需要真实 AWS 凭证的云端集成测试test:watch开发时持续监听。单元测试sandbox/index.test.ts通过 mockaws-sdk/client-bedrock-agentcore验证会话元数据、ARN 必填校验、命令组装与结果收集、workingDirectory与 per-commandcwd优先级、非零退出码、超时归一为 124、abortSignal 透传、流异常上报、setEnv运行时生效、非法 env 名拒绝、超时上限校验、会话停止策略与客户端销毁等十余条行为提供方描述符测试provider.test.ts验证 JSON Schema 的必填项与commandTimeout边界1 ~ 3,600,000。云端集成测试位于 index.integration.test.ts需要环境变量提供真实的agentRuntimeArn等凭据。十一、总结mastra/agentcore的演进清晰地体现了 Mastra 沙箱抽象的三大设计取向统一契约workingDirectory被提为所有沙箱提供方共享的MastraSandboxOptions成员setEnv()/getEnv()运行时环境覆盖所有执行路径closeStdin()由基类兜底——上层 API 稳定下层各提供方自行适配会话边界显式化AgentCore Runtime 会话常与外部 Agent 调用共享因此“停止会话”是独立方法默认不随沙箱生命周期自动触发诚实的能力边界一次性命令、无持久 shell、无后台进程与文件系统挂载等限制被明确写进默认指令供编排层与模型感知。对于需要在 AWS Bedrock AgentCore Runtime 上运行一次性命令的 Mastra Workspace 用户建议按以下顺序落地先按本文第三节配置region/agentRuntimeArn必要时指定runtimeSessionId以复用会话再用workingDirectory固定默认目录、用 per-commandcwd/env做单次覆盖最后根据会话是否共享决定stopSessionOnLifecycle与stopRuntimeSession()的使用时机。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra @mastra/agentcore 沙箱提供方深度解析：从 AWS Bedrock AgentCore Runtime 到工作区命令执行
Mastra mastra/agentcore 沙箱提供方深度解析从 AWS Bedrock AgentCore Runtime 到工作区命令执行【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南围绕 Mastra 仓库中workspaces/agentcore包的官方变更记录CHANGELOG.md展开系统讲解mastra/agentcore作为 Mastra Workspace 沙箱提供方如何把命令执行映射到 AWS Bedrock AgentCore Runtime并逐一拆解 0.2.0 至 0.5.0 各版本引入的workingDirectory、运行时环境变量合并、ProcessHandle.closeStdin()等关键能力。读完本文你将掌握AgentCoreRuntimeSandbox的完整配置项、命令构建与超时语义、会话生命周期管理以及如何通过源码与测试验证这些行为。一、mastra/agentcore 是什么mastra/agentcore是 Mastra 的 Workspace 沙箱提供方之一其核心能力是在 AWS Bedrock AgentCore Runtime 会话中执行命令并支持会话管理、环境变量与文件操作见 README.md。它把 Mastra 一次性命令执行契约映射到 AWS SDK 的InvokeAgentRuntimeCommand并且刻意不暴露进程管理与文件系统挂载——因为 AgentCore Runtime 的命令执行本身不提供这两类 WorkspaceSandbox 语义见 sandbox/index.ts 顶部注释。从包元数据看package.json该包当前版本为 0.5.0依赖aws-sdk/client-bedrock-agentcore^3.1095.0要求 Node.js 22.13.0并以mastra/core1.12.0-0 2.0.0-0为 peerDependency。包的主入口src/index.ts只导出两类内容AgentCoreRuntimeSandbox类与AgentCoreRuntimeSandboxOptions类型来自./sandboxagentCoreRuntimeSandboxProvider提供方描述符与AgentCoreRuntimeProviderConfig类型来自./provider。二、安装与最小可用示例安装npm install mastra/agentcore与 Mastra Workspace 组合使用源自 README.md 的官方示例import { Workspace } from mastra/core/workspace; import { AgentCoreRuntimeSandbox } from mastra/agentcore; const workspace new Workspace({ sandbox: new AgentCoreRuntimeSandbox({ region: us-west-2, agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!, runtimeSessionId: 12345678-1234-1234-1234-123456789012, }), }); const result await workspace.sandbox?.executeCommand?.(npm, [test], { cwd: /workspace, timeout: 300_000, });这是 CHANGELOG 0.2.0 版本引入的核心能力PR #16642通过沙箱提供方在 AWS Bedrock AgentCore Runtime 中运行 Workspace 命令。CHANGELOG 给出的原始最小示例同样成立import { AgentCoreRuntimeSandbox } from mastra/agentcore; const sandbox new AgentCoreRuntimeSandbox({ region: us-west-2, agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!, }); const result await sandbox.executeCommand(node, [--version]);三、配置参数全表AgentCoreRuntimeSandboxOptionsAgentCoreRuntimeSandboxOptions的定义位于 sandbox/index.ts它继承自mastra/core的MastraSandboxOptions剔除processes字段并增加了 AgentCore 专属参数参数类型默认值说明regionstringAWS SDK 默认 region 链Bedrock AgentCore 客户端使用的 AWS 区域agentRuntimeArnstring必填无命令将要执行的 AgentCore Runtime ARN构造时缺失会直接抛错runtimeSessionIdstring自动生成 UUIDRuntime 会话 ID。生成值满足 AgentCore 33 字符最小长度要求同时它也被用作沙箱的idqualifierstringAgentCore 的DEFAULTqualifierAgent runtime 限定符/端点contentTypestringapplication/json命令请求的 MIME 类型acceptstringapplication/vnd.amazon.eventstream命令事件流的 Accept 头commandTimeoutnumber300_000毫秒默认命令超时时间stopSessionOnLifecyclebooleanfalse在stop()/destroy()时是否停止 AgentCore Runtime 会话stopClientTokenstring需要时生成 UUID用于StopRuntimeSession的客户端令牌clientAgentCoreRuntimeClient内部新建 SDK 客户端预配置的 AWS SDK 客户端主要供高级凭证配置与测试使用instructionsstring \| 函数默认指令文本自定义getInstructions()输出函数形式接收defaultInstructions与requestContext同时从MastraSandboxOptions继承的通用选项包括生命周期钩子onStart/onStop/onDestroy、运行时环境env、默认工作目录workingDirectory详见下文。MastraSandboxOptions的完整定义见 packages/core/src/workspace/sandbox/mastra-sandbox.ts。值得一提的是AgentCoreRuntimeSandbox的构造器sandbox/index.ts会校验agentRuntimeArn必填、用runtimeSessionId ?? randomUUID()决定沙箱 ID并记录_ownsClient只有内部创建的客户端才由沙箱在销毁时负责释放。用于 UI 配置的 Provider 描述符provider.ts 导出的agentCoreRuntimeSandboxProvider把上述配置序列化为 JSON Schema使 Mastra Editor 可以通过 UI 驱动沙箱配置。从源码可以看到其约束provider.tsrequired: [agentRuntimeArn]commandTimeout的minimum: 1、maximum: 3_600_000、default: 300_000qualifier默认DEFAULTstopSessionOnLifecycle默认falsecreateSandbox: config new AgentCoreRuntimeSandbox(config)。四、workingDirectory统一的默认工作目录0.5.0CHANGELOG 0.5.0PR #22697是本文档的Minor Change 核心向MastraSandboxOptions新增workingDirectory选项并被每一个沙箱提供方采纳。行为规则每个沙箱接受一个实例级的workingDirectory选项作为命令执行与进程启动的默认目录单条命令的cwd始终优先于它两者都未提供时各提供方保留原有默认值E2B 为 homedocker 为/workspaceVercel serverless 为/tmp以此类推生效值可通过新的sandbox.workingDirectorygetter 读取。CHANGELOG 给出的官方示例const sandbox new E2BSandbox({ workingDirectory: /home/user/my-repo }); await sandbox.executeCommand(pwd); // /home/user/my-repo await sandbox.executeCommand(pwd, [], { cwd: /tmp }); // /tmp与既有命名别名共存那些已经用其他名字承载该概念的提供方旧名字作为废弃别名继续可用并喂给同一字段workingDirmastra/docker、mastra/apple-containerworkdirmastra/modal。当别名与workingDirectory同时设置时workingDirectory胜出。必须使用绝对路径该值会原样传递给提供方因此~与$HOME这类环境变量不会被展开除非提供方明确文档化其展开行为例如LocalSandbox会展开~。AgentCore 上的实现细节在AgentCoreRuntimeSandbox中workingDirectory生效于buildCommand()sandbox/index.ts当options?.cwd ?? workingDirectory有值时命令会被前缀为cd 目录并用shellQuote做 shell 引号转义。源码注释特别指出cd 目标被 shell 引号包裹会抵消~展开——因此该提供方的 workingDirectory 必须是绝对路径。单元测试也验证了这一点配置workingDirectory: /srv/app后执行pwd实际发送的命令为cd /srv/app pwd见 index.test.ts单条命令传cwd: /tmp时命令变为cd /tmp pwd即 per-commandcwd胜出index.test.ts两者均未设置时无cd前缀sandbox.workingDirectory返回undefinedindex.test.ts。基类语义在MastraSandbox基类中workingDirectory通过_workingDirectory存储、workingDirectorygetter 暴露并提供受保护的setWorkingDirectory()供需要在运行时探测/回写生效值的提供方使用mastra-sandbox.ts。基类文档同时强调沙箱不会创建该目录且不支持该概念的提供方回退到各自旧默认值。五、环境变量构造时注入与运行时合并0.4.1CHANGELOG 0.4.1PR #22250解决了一个跨提供方的一致性问题让mastra/core的setEnv()/getEnv()运行时环境在每一个 Workspace 沙箱提供方上生效。此前构造后设置的环境变量无法到达后续命令。两条执行路径的归一进程管理器路由的提供方E2B、Blaxel、Cloudflare、Daytona、Docker、Modal、Vercel microVM spawn继承自 core spawn wrapper 的合并逻辑删除了这些提供方各自重复的 per-manager env 管道自带 exec 传输的提供方AgentCore、Apple Container、Railway、Vercel microVM 与 serverless 的executeCommand、Platform 的 private-network、WebSocket lease、E2B lease 路径现在在 per-call env 之下合并getEnv()。AgentCore 属于第二类。在 sandbox/index.ts 中可以看到具体实现——executeCommand里const fullCommand buildCommand( command, args, { ...options, env: { ...this.getEnv(), ...options?.env } }, this.workingDirectory, );即运行时环境 overlay 与单条命令env合并单条命令的env优先。环境变量优先级总表构造器env继续扮演“种子”角色注入沙箱运行时环境Docker、Modal、Railway、Apple Container、Vercel、Platform 等会把 env 在创建时烤进 VM/容器setEnv()运行时更新的 overlay构造后修改立即作用于后续命令单条命令的 per-callenv仅对该命令生效优先级最高。测试用例验证了该行为index.test.tssandbox.setEnv(env ({ ...env, GH_TOKEN: tok_1 }))后执行命令发送的命令体包含GH_TOKENtok_1。移除的导出类型作为 minor bump 的连带变更以下两个仅为手工构造进程管理器而存在的类型被删除BlaxelProcessManagerOptionsmastra/blaxelRailwayProcessManagerOptionsmastra/railway。因为 core spawn wrapper 现在自己拥有 env 合并逻辑这两个只用来向手工构造的进程管理器传env的选项及其类型随之消失。环境变量名校验AgentCore 提供方对 env 名做了严格校验sandbox/index.ts名称必须匹配/^[A-Za-z_][A-Za-z0-9_]*$/否则抛出Invalid environment variable name for AgentCore Runtime command测试见 index.test.ts。命令中的 env 赋值同样经过shellQuote转义。六、ProcessHandle.closeStdin()向后台进程发送 EOF0.4.0CHANGELOG 0.4.0PR #21606为ProcessHandle增加了closeStdin()方法用于向后台进程发出标准输入 EOF。支持度矩阵Local 与 Docker 沙箱原生支持关闭 stdin无 stdin-close API 的提供方返回提供方专属的“不支持的操作”错误并通过新的UnsupportedStdinCloseError类型标识基类默认行为基类默认提供该行为因此现有ProcessHandle子类无需改动即可继续编译等价写法调用handle.writer.end()也会关闭 stdin且在提供方无法关闭 stdin 时无错误地正常完成。在 AgentCore 提供方中CommandOutputAccumulator extends ProcessHandlesandbox/index.ts的closeStdin()直接抛出UnsupportedStdinCloseError与sendStdin()抛错一致——因为 AgentCore Runtime 命令执行本身不支持 stdin。这也解释了为何CommandOutputAccumulator的pid固定为agentcore-command、kill()返回falseAgentCore 命令是一次性、非交互的。七、命令构建、超时与输出语义源码级命令字符串如何组装buildCommand()sandbox/index.ts的组装顺序为cd cwd若配置了 cwd 或 workingDirectory合法的 env 赋值KEYvalue均经shellQuote原始命令与参数command arg1 arg2参数逐个shellQuote。各部分用连接。shellQuotesandbox/index.ts对安全字符集/^[a-zA-Z0-9._\-\/:]$/原样保留其余用单引号包裹并把内嵌单引号转义为\。测试中的断言cd /workspace/app NODE_ENVtest npm test完整印证了这一过程index.test.ts。超时语义toAgentCoreTimeoutSeconds()sandbox/index.ts把毫秒超时向上取整为秒并施加硬限制超时必须为正数否则抛RangeError上限MAX_AGENTCORE_TIMEOUT_SECONDS 3600秒即 3,600,000 ms超过即抛错默认commandTimeout 300_000ms。超时后的行为很有意思AgentCore 事件流中的contentStop.status若为TIMED_OUT提供方会把最终退出码规范化为124Linux timeout 惯例timedOut: true且即使 AgentCore 省略了超时退出码也会补上 124实现见 sandbox/index.ts测试见 index.test.ts。超时上限与默认值的双重校验测试见 index.test.ts。事件流处理与错误上报executeCommand通过InvokeAgentRuntimeCommandCommand发送请求并逐条消费响应的事件流sandbox/index.tscontentDelta.stdout/contentDelta.stderr实时通过output.emitStdout/emitStderr回调对应ExecuteCommandOptions.onStdout/onStderrcontentStop记录退出码与状态七类流异常accessDeniedException、internalServerException、resourceNotFoundException、serviceQuotaExceededException、throttlingException、validationException、runtimeClientError以及$unknown字段都会被识别并格式化为[AgentCoreRuntimeSandbox] Name: message抛给调用方sandbox/index.ts测试见 index.test.ts请求同时支持abortSignal透传给 AWS SDKindex.test.ts。返回的CommandResult包含success、exitCode、stdout、stderr、executionTimeMs、timedOut、stdoutTruncated、stderrTruncated、stdoutDroppedBytes、stderrDroppedBytes等完整字段并支持maxRetainedBytes截断输出上限。使用限制getInstructions()的默认指令文本sandbox/index.ts明示了该提供方的边界这对 Agent 编排尤其重要命令一次性、非交互命令之间没有持久的 shell 会话不暴露后台进程管理不暴露文件系统挂载git、npm、Python、Node 等工具必须存在于 AgentCore 容器镜像中AgentCore Code Interpreter 是独立服务不属于本 Runtime 沙箱。instructions选项支持字符串替换或函数接收defaultInstructionsrequestContext后返回新文本测试见 index.test.ts。八、会话生命周期何时停止 Runtime SessionAgentCore Runtime 会话常常与沙箱实例之外的 Agent 调用共享因此提供方把“停止会话”与“销毁沙箱”分离sandbox/index.tsstop()/destroy()仅当stopSessionOnLifecycle: true时才调用StopRuntimeSessionCommandstopRuntimeSession()显式停止会话的独立方法供会话共享场景下由调用方自行决定destroy()同时负责释放自建的AWS SDK 客户端_ownsClient为 true 时调用client.destroy()stopClientToken未提供时用生成 UUID保证StopRuntimeSessionCommand的幂等令牌getInfo()返回的元数据包含agentRuntimeArn、runtimeSessionId、qualifier ?? DEFAULT、stopSessionOnLifecyclesandbox/index.ts。对应测试覆盖了“仅在启用 lifecycle 清理时停止会话”“默认不停止”“可显式停止”“销毁自建客户端”四条路径index.test.ts。九、发布维护与安全Patch Changes 解读CHANGELOG 中的 Patch 记录同样值得关注供应链安全修复0.2.4PR #18056针对 2026-06-17 的 easy-day-js 供应链事件做了安全修复发布干净版本并把latestdist-tag 前移取代那些声明了恶意easy-day-js依赖的受影响版本。这提醒使用者升级到 0.2.4 及以上版本即可避开被污染的版本。依赖更新0.2.1、0.3.1aws-sdk/client-bedrock-agentcore从^3.1045.0一路升级到^3.1095.0PR #17521、#17600、#20406。CHANGELOG 移出 npm 包0.5.0PR #22737CHANGELOG.md不再随包分发减小了包体积——这也解释了为何本仓库保留独立的 changelog 文件供查阅。README 持续更新0.5.0PR #22858。版本演进中mastra/core的依赖始终跟随0.5.0 对应mastra/core1.64.0且每个功能版本都有对应的-alpha预发布记录说明该包遵循 changesets 的常规发布流程。十、测试与验证该包测试分层明确见 package.json 的 scriptstest:unit跑vitest run --exclude **/*.integration.test.tstest/test:cloud跑vitest run ./src/**/*.integration.test.ts即需要真实 AWS 凭证的云端集成测试test:watch开发时持续监听。单元测试sandbox/index.test.ts通过 mockaws-sdk/client-bedrock-agentcore验证会话元数据、ARN 必填校验、命令组装与结果收集、workingDirectory与 per-commandcwd优先级、非零退出码、超时归一为 124、abortSignal 透传、流异常上报、setEnv运行时生效、非法 env 名拒绝、超时上限校验、会话停止策略与客户端销毁等十余条行为提供方描述符测试provider.test.ts验证 JSON Schema 的必填项与commandTimeout边界1 ~ 3,600,000。云端集成测试位于 index.integration.test.ts需要环境变量提供真实的agentRuntimeArn等凭据。十一、总结mastra/agentcore的演进清晰地体现了 Mastra 沙箱抽象的三大设计取向统一契约workingDirectory被提为所有沙箱提供方共享的MastraSandboxOptions成员setEnv()/getEnv()运行时环境覆盖所有执行路径closeStdin()由基类兜底——上层 API 稳定下层各提供方自行适配会话边界显式化AgentCore Runtime 会话常与外部 Agent 调用共享因此“停止会话”是独立方法默认不随沙箱生命周期自动触发诚实的能力边界一次性命令、无持久 shell、无后台进程与文件系统挂载等限制被明确写进默认指令供编排层与模型感知。对于需要在 AWS Bedrock AgentCore Runtime 上运行一次性命令的 Mastra Workspace 用户建议按以下顺序落地先按本文第三节配置region/agentRuntimeArn必要时指定runtimeSessionId以复用会话再用workingDirectory固定默认目录、用 per-commandcwd/env做单次覆盖最后根据会话是否共享决定stopSessionOnLifecycle与stopRuntimeSession()的使用时机。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考