Agent Sandbox Registry

nodejs-sdk

@agent-sandbox/sdk

English

README.zh-CN.md

@agent-sandbox/sdk

中文 | English

Agent Sandbox 的 Node.js 客户端。需要 Node.js 20 或更高版本，仅提供 ESM。

本包是 Node.js SDK 的第一片。它包含：

它不是 Sandbox.create、云 provider 或 server SDK 的移植。创建云沙箱仍属于 Python SDK 和 abx CLI。

安装

npm install @agent-sandbox/sdk

发布入口是 dist/。在检出的仓库里：

npm install
npm test
node examples/agent-loop.mjs

npm test 会先构建，再跑 node:test。

ServerClient

ServerClient 通过 HTTP 访问 python3 -m agent_sandbox.server serve 启动的进程（默认端口 9000）。本地 agent 循环用到的是下面四个调用，它们默认开启：

方法 请求
health() GET /health
process.shell(command) POST /shell，JSON { "command": "..." }
files.upload(path, data) POST /files/upload-stream，JSON { "path", "content_base64" }
files.download(path) / files.readText(path) GET /files/download-stream?path=

只有在你设置了 cwd、env、timeout 时，它们才会出现在 shell 请求体里。服务端对 command 做分词，不会交给 shell。构造时传入的 bearer token 会以 Authorization: Bearer 发送（与 ABX_SERVER_TOKEN 是同一个密钥）。

可选能力组（dev_tools、browser、agents）默认关闭，只有 ABX_SERVER_ENABLED_GROUPS 列出它们时才打开。这是唯一的分组开关。Agents 路由的响应带 X-Agent-Sandbox-* 头（例如 X-Agent-Sandbox-Local）。本客户端不调用那些路由。

import { ServerClient } from "@agent-sandbox/sdk";

const server = new ServerClient("http://127.0.0.1:9000");
if (await server.health()) {
  const ran = await server.process.shell("python3 -c 'print(2 + 2)'");
  console.log(ran.stdout); // "4\n"
}
await server.close();

examples/agent-loop.mjs 会启动这个本地服务，并执行与 Python 场景 examples/scenarios/agent_loop_local.py 相同的四步：健康检查、python3 -c 'print(2 + 2)'、写入并读回 result.txt、然后 SIGTERM。记录见 examples/README.md。

配置名

src/config-keys.json 是规范列表，来自 python -m agent_sandbox.utils.config_keys --json。每个 key 只有一个环境变量，没有别名。readEnv 只读这个名字。

产品 key 使用 ABX_ 前缀：ABX_SANDBOX_API_KEY、ABX_SANDBOX_BASE_URL、ABX_SANDBOX_DOMAIN、ABX_PROVIDER。

厂商已经公布名字时，环境变量就用那个名字：ALICLOUD_ACCESS_KEY_ID、ALICLOUD_ACCESS_KEY_SECRET、ALIBABA_CLOUD_REGION_ID，以及 GITHUB_TOKEN。

import { envName, readEnv } from "@agent-sandbox/sdk";

envName("sandbox_api_key"); // ABX_SANDBOX_API_KEY
envName("access_key_id", "alicloud-express"); // ALICLOUD_ACCESS_KEY_ID
readEnv("sandbox_api_key", process.env);
Key 范围 环境变量 说明
provider core ABX_PROVIDER 默认 provider 标识（见 'abx provider list'）
sandbox_api_key core ABX_SANDBOX_API_KEY 当前 provider 的 Agent Sandbox API Key
sandbox_base_url core ABX_SANDBOX_BASE_URL 当前 provider 的 Agent Sandbox API 端点
sandbox_domain core ABX_SANDBOX_DOMAIN envd 数据面域名
http_timeout core ABX_HTTP_TIMEOUT HTTP 请求超时（秒）
http2 core ABX_HTTP2 启用 HTTP/2
max_retries core ABX_MAX_RETRIES 最大自动重试次数
max_connections core ABX_MAX_CONNECTIONS
max_keepalive_connections core ABX_MAX_KEEPALIVE_CONNECTIONS
keepalive_expiry core ABX_KEEPALIVE_EXPIRY
ws_ping_interval core ABX_WS_PING_INTERVAL
retry_base_delay core ABX_RETRY_BASE_DELAY
log_level core ABX_LOG_LEVEL 日志级别
default_template core ABX_DEFAULT_TEMPLATE 未指定模板时使用的模板
github_token core GITHUB_TOKEN 用于模板索引的 GitHub Token
template_index_url core ABX_TEMPLATE_INDEX_URL
template_dir core ABX_TEMPLATE_DIR
mcp_auth_token core ABX_MCP_AUTH_TOKEN
mcp_allowed_origins core ABX_MCP_ALLOWED_ORIGINS
mcp_runtime_dir core ABX_MCP_RUNTIME_DIR
region alicloud-express ALIBABA_CLOUD_REGION_ID 地域（用于推导 API 地址和域名）
access_key_id alicloud-express ALICLOUD_ACCESS_KEY_ID 阿里云 AccessKey ID
access_key_secret alicloud-express ALICLOUD_ACCESS_KEY_SECRET 阿里云 AccessKey Secret

本包不做的事

许可

Apache-2.0。见 LICENSE 和 NOTICE。