@ agent-infra/ sandbox
节点.js/TypeScript SDK用于AIO沙盒集成,提供沙盒管理和云提供商集成的工具和接口.
安装
npm install @agent-infra/sandbox
或带线:
yarn add @agent-infra/sandbox
或带pnm:
pnpm add @agent-infra/sandbox
快速启动
基本用途
import { SandboxApiClient } from '@agent-infra/sandbox';
// Initialize the client
const client = new SandboxApiClient({
environment: 'https://your-sandbox-api.com',
// Add authentication if required
});
// Use the API
const result = await client.file.read({
path: '/path/to/file',
});
console.log(result);
使用云提供商
SDK包括不同云平台上管理沙盒的供应商执行.
Volcengine 供应商
import { providers } from '@agent-infra/sandbox';
// Initialize Volcengine provider
const volcengineProvider = new providers.VolcengineProvider({
accessKey: process.env.VOLCENGINE_ACCESS_KEY,
secretKey: process.env.VOLCENGINE_SECRET_KEY,
region: 'cn-beijing', // Optional, defaults to 'cn-beijing'
});
// Create a sandbox
const sandboxId = await volcengineProvider.createSandbox(
'your-function-id',
30 // timeout in minutes
);
console.log('Created sandbox:', sandboxId);
// Get sandbox details with APIG domains
const sandbox = await volcengineProvider.getSandbox(
'your-function-id',
sandboxId
);
console.log('Sandbox domains:', sandbox.domains);
// List all sandboxes for a function
const sandboxes = await volcengineProvider.listSandboxes('your-function-id');
console.log('Total sandboxes:', sandboxes.length);
// Delete a sandbox
await volcengineProvider.deleteSandbox('your-function-id', sandboxId);
console.log('Sandbox deleted');
应用程序管理
// Create an application
const appId = await volcengineProvider.createApplication(
'my-app',
'my-gateway'
);
// Check application readiness
const [isReady, functionId] = await volcengineProvider.getApplicationReadiness(appId);
if (isReady) {
console.log('Application is ready, function ID:', functionId);
}
// Get APIG domains for a function
const domains = await volcengineProvider.getApigDomains('your-function-id');
console.log('Available domains:', domains);
特征
Sandbox API 客户端
- 文件操作: 读取、写入、搜索和管理文件
- 执行壳牌: 执行 shell 命令并管理会话
- 浏览器自动化: 控制浏览器动作并检索信息
- 代码执行: 执行各种语言的代码(Python, Node.js, Jupyter)
- MCP 一体化: 执行MCP(模式上下文协议)工具
云提供商
Volcengine 供应商
- QQ 沙盒生命周期管理( 创建、 删除、 获取、 列表)
- * 应用程序部署和监测
- APIG( API Gateway) 域管理
- 与 HMAC-SHA256 自动签署请求
- 支持临时全权证书
可扩展提供者系统
通过扩展 BaseProvider 类 :
import { providers } from '@agent-infra/sandbox';
class MyCustomProvider extends providers.BaseProvider {
async createSandbox(functionId: string, ...kwargs: any[]): Promise<any> {
// Your implementation
}
async deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any> {
// Your implementation
}
async getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any> {
// Your implementation
}
async listSandboxes(functionId: string, ...kwargs: any[]): Promise<any> {
// Your implementation
}
}
API 参考
沙盒Api客户端
与 Sandbox API 互动的主要客户端.
const client = new SandboxApiClient({
environment: string, // API base URL
timeout?: number, // Request timeout in milliseconds
headers?: Record<string, string>, // Custom headers
});
可用模块
client.file- 文件操作client.shell- 壳牌命令执行client.browser- 浏览器自动化client.code- 代码执行client.jupyter- Jupyter笔记本操作client.nodejs- 节点作业client.mcp- MCP工具执行
供应商
碱基提供器( Abstract)
所有云提供方实施的基础类.
方法:
createSandbox(functionId: string, ...kwargs: any[]): Promise<any>deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any>getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any>listSandboxes(functionId: string, ...kwargs: any[]): Promise<any>
伏尔肯宁
Volcengine VEFAAS实施.
构造器选项 :
{
accessKey: string; // Volcengine access key ID
secretKey: string; // Volcengine secret access key
region?: string; // Region (default: 'cn-beijing')
clientSideValidation?: boolean; // Enable validation (default: true)
}
补充方法:
createApplication(name: string, gatewayName: string): Promise<string | null>getApplicationReadiness(id: string): Promise<[boolean, string | null]>getApigDomains(functionId: string): Promise<DomainInfo[]>
环境变量
使用环境变量配置 Volcengine 证书 :
# Volcengine credentials (option 1)
VOLCENGINE_ACCESS_KEY=your-access-key
VOLCENGINE_SECRET_KEY=your-secret-key
# Volcengine credentials (option 2)
VOLC_ACCESSKEY=your-access-key
VOLC_SECRETKEY=your-secret-key
类型脚本支持
此软件包以 TypeScript 写成,包含完整类型定义. 建议采用5.0+型.
import type {
SandboxApi,
BaseClientOptions,
BaseRequestOptions
} from '@agent-infra/sandbox';
实例
执行 Shell 命令
const result = await client.shell.exec({
command: 'ls -la',
timeout: 5000,
});
console.log(result.stdout);
读取文件
const fileContent = await client.file.read({
path: '/path/to/file.txt',
});
console.log(fileContent.content);
浏览器自动化
const browserInfo = await client.browser.info();
console.log('Browser:', browserInfo);
await client.browser.config({
action: {
type: 'click',
selector: '#button',
},
});
执行 Python 代码
const result = await client.code.execute({
code: 'print("Hello from sandbox!")',
language: 'python',
});
console.log(result.output);
处理错误
import { SandboxApiError, SandboxApiTimeoutError } from '@agent-infra/sandbox';
try {
const result = await client.file.read({ path: '/nonexistent' });
} catch (error) {
if (error instanceof SandboxApiTimeoutError) {
console.error('Request timed out');
} else if (error instanceof SandboxApiError) {
console.error('API error:', error.statusCode, error.message);
} else {
console.error('Unexpected error:', error);
}
}
发展
项目结构
sdk/js/
├── src/ # TypeScript source code
│ ├── api/ # Generated API modules
│ ├── core/ # Core utilities
│ ├── errors/ # Error classes
│ ├── providers/ # Cloud provider implementations (custom code)
│ │ ├── base.ts # Base provider interface
│ │ ├── volcengine.ts # Volcengine implementation
│ │ ├── sign.ts # Request signing utilities
│ │ └── README.md # Provider documentation
│ ├── BaseClient.ts # Base client implementation
│ ├── Client.ts # Main API client
│ └── index.ts # Package entry point
├── dist/ # Compiled JavaScript output (generated by build)
├── package.json # Package configuration
└── tsconfig.json # TypeScript configuration
大楼
SDK 使用 TypeScript 并编译源代码 src/ 改为 dist/数字 :
npm run build
这将:
- 编译类型脚本文件
src/到 Java 脚本在dist/ - 生成
.d.ts类型定义文件 - 生成用于调试的源地图
测试
npm test
# With coverage
npm run test:coverage
# With UI
npm run test:ui
发展模式
npm run dev # Watch mode with auto-rebuild
正在生成 SDK
基 SDK 代码使用 费恩数字 :
cd sdk/fern
fern generate --group nodejs-sdk --local
从 OpenAPI 规格生成类型脚本代码 src/。 。 。 .
自定义提供者在 src/providers/ 保存通过 .fernignore。 。 。 .
捐款
欢迎捐款! 请随意提交拉力请求.
添加自定义提供者
见 供应商/README.md 关于实施自定义云提供者的详细信息.
许可证
公务员制度委员会
链接
支助
询问和支持请在GitHub上打开一个问题.
版本: 1.0.0 (中文(简体) ) 节点.js页:1 类型脚本页:1