Skip to content

README.md

Latest commit

 

History

History
203 lines (154 loc) · 5.47 KB

README.md

File metadata and controls

203 lines (154 loc) · 5.47 KB

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