@agentrun/sdk

AgentRun SDK for Node.js

AgentRun SDK 是阿里云 AgentRun 服务的 Node.js 客户端库，为 AI Agent 应用提供托管的运行环境。

特性

• 🚀 Agent Runtime: 创建、管理和部署 AI Agent
• 📜 Credential: 安全的凭证管理
• 🔧 Model: 模型服务和代理管理
• 📦 Sandbox: 代码解释器和浏览器沙箱
• 🧰 ToolSet: OpenAPI / MCP 工具集管理
• 🌐 Server: OpenAI 兼容的 HTTP 服务器
• 🔌 Integration: Mastra 框架集成

安装

npm install @agentrun/sdk

快速开始

配置

SDK 支持从环境变量或代码中配置：

import { Config } from '@agentrun/sdk';

// 从环境变量读取配置
// AGENTRUN_ACCESS_KEY_ID     (回退到 ALIBABA_CLOUD_ACCESS_KEY_ID)
// AGENTRUN_ACCESS_KEY_SECRET (回退到 ALIBABA_CLOUD_ACCESS_KEY_SECRET)
// AGENTRUN_ACCOUNT_ID        (回退到 FC_ACCOUNT_ID)
// AGENTRUN_REGION            (回退到 FC_REGION，默认 cn-hangzhou)
const config = new Config();

// 或者直接传入配置
const config = new Config({
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  accountId: 'your-account-id',
  regionId: 'cn-hangzhou',
});

Agent Runtime

import {
  AgentRuntime,
  AgentRuntimeLanguage,
  codeFromFile,
} from '@agentrun/sdk';

// 创建 Agent Runtime
const runtime = await AgentRuntime.create({
  input: {
    agentRuntimeName: 'my-agent',
    codeConfiguration: await codeFromFile(
      AgentRuntimeLanguage.NODEJS18,
      ['node', 'index.js'],
      './my-agent-code'
    ),
    port: 9000,
    cpu: 2,
    memory: 4096,
  },
});

// 等待就绪 (READY 或 *_FAILED)
await runtime.waitUntilReadyOrFailed();

// 创建端点
const endpoint = await runtime.createEndpoint({
  input: { agentRuntimeEndpointName: 'default' },
});

await endpoint.waitUntilReadyOrFailed();
console.log('Endpoint URL:', endpoint.endpointPublicUrl);

// 删除
await runtime.delete();

Sandbox

import { SandboxClient, Template, TemplateType } from '@agentrun/sdk';

const client = new SandboxClient();

// 创建模板
const template = await Template.create({
  input: {
    templateName: 'my-template',
    templateType: TemplateType.CODE_INTERPRETER,
  },
});

await template.waitUntilReadyOrFailed();

// 创建沙箱
const sandbox = await client.createCodeInterpreterSandbox({
  templateName: template.templateName!,
});
await sandbox.waitUntilRunning();
await sandbox.waitUntilReadyOrFailed();

// 执行代码
const ctx = await sandbox.context.create();
const result = await ctx.execute({ code: "print('Hello!')" });
console.log(result);

// 删除
await sandbox.delete();
await template.delete();

模块

模块	描述
AgentRuntime	Agent 运行时管理
Credential	凭证管理
Model	模型服务和代理管理
Sandbox	沙箱环境管理 (代码解释器、浏览器)
ToolSet	OpenAPI / MCP 工具集管理
Server	OpenAI 兼容的 HTTP 服务器
Integration	Mastra 等第三方框架集成

示例

examples/ 目录下提供了各模块的端到端示例：

# Agent Runtime 示例
npm run example:agent-runtime

# Credential 示例
npm run example:credential

# Sandbox 示例
npm run example:sandbox

其他可直接运行的示例（用 npx tsx 启动）：

npx tsx examples/model.ts
npx tsx examples/toolset.ts
npx tsx examples/mastra.ts

开发

# 安装依赖
npm install

# 运行测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 构建
npm run build

# 类型检查
npm run typecheck

# 代码检查和格式化
npm run lint
npm run lint:fix
npm run format
npm run format:check
npm run format:fix  # 同时运行格式化和lint修复

环境变量

变量	描述	默认值
AGENTRUN_ACCESS_KEY_ID	阿里云 Access Key ID（回退到 ALIBABA_CLOUD_ACCESS_KEY_ID）	-
AGENTRUN_ACCESS_KEY_SECRET	阿里云 Access Key Secret（回退到 ALIBABA_CLOUD_ACCESS_KEY_SECRET）	-
AGENTRUN_SECURITY_TOKEN	STS 临时安全令牌（回退到 ALIBABA_CLOUD_SECURITY_TOKEN）	-
AGENTRUN_ACCOUNT_ID	阿里云账号 ID（回退到 FC_ACCOUNT_ID）	-
AGENTRUN_REGION	区域 ID（回退到 FC_REGION）	cn-hangzhou
AGENTRUN_CONTROL_ENDPOINT	自定义控制面 API 端点	区域默认值
AGENTRUN_DATA_ENDPOINT	自定义数据面 API 端点	区域默认值
DEVS_ENDPOINT	自定义 DevS API 端点	区域默认值

超时和读超时通过 new Config({ timeout, readTimeout }) 在代码中配置（单位：毫秒），不通过环境变量读取。

兼容性

• Node.js 18.x, 20.x, 22.x
• TypeScript 5.x
• 同时支持 CommonJS 和 ESM

License

Apache-2.0