跳转到主要内容

​
代码执行器

使用安全的沙箱执行或高性能的本地执行来运行代码片段。

​
执行器类型

​
内置代码执行器（沙箱模式）

在隔离的E2B容器中安全执行，支持完整功能集。 
import { BuiltInCodeExecutor } from '@ag-kit/tools';

const executor = new BuiltInCodeExecutor(
  { sandbox }, // 可选：提供现有沙箱
  {
    timeoutMs: 60000,
    envs: { CUSTOM_VAR: 'value' },
    onStdout: (data) => console.log('输出:', data.line),
    onStderr: (data) => console.error('错误:', data.line),
  }
);

​
非安全本地代码执行器

在本地系统直接执行，功能集完全相同。 
import { UnsafeLocalCodeExecutor } from '@ag-kit/tools';

const executor = new UnsafeLocalCodeExecutor({
  timeoutMs: 30000,
  envs: { CUSTOM_VAR: 'value' },
  onStdout: (data) => console.log('输出:', data.line),
  onStderr: (data) => console.error('错误:', data.line),
});

​
通用功能

两种执行器支持相同功能：
功能内置（沙箱）非安全本地
安全性✅ 隔离环境⚠️ 完全系统访问
性能存在网络开销✅ 最高速度
上下文持久化✅ 支持✅ 支持
实时输出✅ onStdout/onStderr✅ onStdout/onStderr
环境变量✅ envs✅ envs
超时控制✅ timeoutMs✅ timeoutMs
多语言支持✅ Python/JS/TS/Java/R/Bash✅ Python/JS/TS/Bash

​
基础用法

const result = await executor.invoke({
  code: 'x = "Hello World!"\nx',
  language: 'python'
});

console.log(result.data.results[0].text); // "Hello World!"

​
高级功能

​
持久化上下文

两种执行器均支持跨执行保留变量： 
// 首次执行
await executor.invoke({
  code: 'x = 10',
  language: 'python'
});

// 二次执行 - x仍可用
const result = await executor.invoke({
  code: 'print(x)',  // 输出: 10
  language: 'python'
});

​
实时输出流

const executor = new UnsafeLocalCodeExecutor({
  onStdout: (data) => console.log('输出:', data.line),
  onStderr: (data) => console.error('错误:', data.line)
});

await executor.invoke({
  code: `
import time
for i in range(3):
    print(f"步骤 {i}")
    time.sleep(1)
  `,
  language: 'python'
});
// 实时输出: 输出: 步骤 0, 输出: 步骤 1, 输出: 步骤 2

​
环境变量配置

// 内置执行器
const sandboxExecutor = new BuiltInCodeExecutor({}, {
  envs: { 
    API_KEY: 'secret-key',
    DEBUG: 'true'
  }
});

// 本地执行器  
const localExecutor = new UnsafeLocalCodeExecutor({
  envs: { 
    API_KEY: 'secret-key',
    DEBUG: 'true'
  }
});

const result = await executor.invoke({
  code: 'import os; print(os.environ.get("API_KEY"))',
  language: 'python'
});

​
超时设置

const executor = new UnsafeLocalCodeExecutor({
  timeoutMs: 60000 // 60秒
});

// 内置执行器配置
const sandboxExecutor = new BuiltInCodeExecutor({}, {
  timeoutMs: 60000
});

​
安装指南

​
内置执行器配置

export AG_KIT_SANDBOX_API_KEY=your_sandbox_api_key
export AG_KIT_SANDBOX_DOMAIN=your_sandbox_domain  # 可选

// 自定义沙箱配置
const sandbox = await Sandbox.create('code-interpreter-v1', {
  apiKey: process.env.AG_KIT_SANDBOX_API_KEY,
  domain: process.env.AG_KIT_SANDBOX_DOMAIN,
  timeoutMs: 60000
});

const executor = new BuiltInCodeExecutor({ sandbox });

​
本地执行器准备

确保已安装解释器： 
python3 --version  # Python
node --version     # Node.js
bash --version     # Bash

​
API参考

​
通用接口

interface ICodeExecutorInput {
  code: string;
  language?: "python" | "js" | "ts" | "java" | "r" | "bash";
}

interface CodeExecutorOptions {
  timeoutMs?: number;                    // 执行超时（默认：30000）
  envs?: Record<string, string>;         // 环境变量
  onStdout?: (data: OutputMessage) => void;  // 标准输出实时回调
  onStderr?: (data: OutputMessage) => void;  // 标准错误实时回调
  onResult?: (result: Result) => void;   // 结果回调
  onError?: (error: ExecutionError) => void; // 错误回调
}

​
构造函数签名

// 内置执行器
new BuiltInCodeExecutor(
  fields?: { sandbox?: Sandbox },
  options?: CodeExecutorOptions
)

// 本地执行器
new UnsafeLocalCodeExecutor(options: CodeExecutorOptions)

​
执行结果

interface Execution {
  results: Result[];           // 执行输出
  logs: {                     // 捕获的日志
    stdout: string[];
    stderr: string[];
  };
  error?: ExecutionError;     // 执行失败时的错误
  executionCount?: number;    // 执行计数器
}

​
语言支持

语言内置支持本地支持备注
Python✅✅完整支持
JavaScript✅✅完整支持
TypeScript✅✅完整支持
Bash✅✅完整支持
Java✅❌仅限沙箱
R✅❌仅限沙箱

​
环境变量选择

function createExecutor() {
  const useLocal = process.env.USE_LOCAL_EXECUTOR === 'true';
  
  const options = {
    timeoutMs: 60000,
    onStdout: (data) => console.log(data.line),
    envs: { NODE_ENV: 'development' }
  };
  
  return useLocal 
    ? new UnsafeLocalCodeExecutor(options)
    : new BuiltInCodeExecutor({}, options);
}

​
错误处理

try {
  const result = await executor.invoke({
    code: userCode,
    language: 'python'
  });

  if (result.data.error) {
    console.error('执行失败:', result.data.error.value);
    console.error('追踪信息:', result.data.error.traceback);
  }
} catch (error) {
  console.error('系统错误:', error);
}

​
安全考量

​
内置执行器

  • ✅ 可安全执行不可信代码
  • ✅ 网络隔离
  • ✅ 文件系统限制
  • ✅ 资源限制

​
本地执行器

  • ⚠️ 完全系统访问权限
  • ⚠️ 可修改文件
  • ⚠️ 可发起网络请求
  • ⚠️ 可执行系统命令
安全准则：
  • 对不可信代码使用内置执行器
  • 本地执行前验证输入
  • 尽可能在受限环境中运行
  • 监控资源使用情况

​
性能优化

​
内置执行器

  • 复用沙箱实例
  • 批量执行操作
  • 使用连接池

​
本地执行器

  • 利用持久化上下文
  • 对长时操作使用实时回调
  • 优化解释器启动时间

​
清理操作

// 清理持久化会话
executor.cleanup?.();

​
故障排查

​
内置执行器

  • 沙箱创建失败：检查AG_KIT_SANDBOX_API_KEY
  • 网络超时：增加超时时间或检查网络连接

​
本地执行器

  • 解释器未找到：安装所需解释器
  • 权限拒绝：检查文件/目录权限
  • 上下文丢失：会话可能已终止，需重启执行器