跳转到主要内容
AG-Kit通过两种主要执行器提供强大的代码执行能力：沙盒化执行保障安全，本地执行追求性能。本指南将帮助您选择合适的工具，并有效应用于Agent的工作流程中。

​
何时使用代码执行工具

当您的Agent需要运行动态代码片段或脚本时使用这些工具。

​
快速入门

from agkit.tools import BuiltInCodeExecutor, UnsafeLocalCodeExecutor
import os

# 根据场景选择执行器
executor = (
    BuiltInCodeExecutor(api_key=os.getenv("E2B_API_KEY"))
    if os.getenv("USE_SANDBOX")
    else UnsafeLocalCodeExecutor()
)

# 运行Python代码片段
result = await executor.execute({
    "language": "python",
    "code": "print(3 * 7)"
})

if result.success:
    print(f"Output: {result.data.stdout}")  # '21'

​
典型工作流

  • 数据处理：读取文件，执行Python脚本进行分析并输出结果
  • 代码生成与测试：让LLM生成代码，在沙盒中验证正确性并反馈
  • DevOps自动化：运行Shell脚本搭建项目、检查代码或运行测试

​
选择适合的执行器

执行器使用场景核心优势
BuiltInCodeExecutor不可信代码（来自LLM或用户）安全隔离
UnsafeLocalCodeExecutor可信代码（自有脚本）性能速度
  • 优先选择BuiltInCodeExecutor（沙盒化）：当安全性至关重要时使用，提供执行隔离、允许安装包并控制环境
  • 使用UnsafeLocalCodeExecutor（本地化）：在开发环境或受控CI环境中运行可信脚本，需要最高性能和直接访问本地文件时

​
核心功能与配置

两种执行器共享通用应用程序接口但采用不同后端实现。

​
配置选项

  • 超时设置：通过timeoutMs防止脚本失控运行
  • 环境变量：通过envs注入密钥或配置
  • 流式输出：使用onStdout和onStderr获取长时间任务的实时反馈
from agkit.tools import BuiltInCodeExecutor
import os

# 示例：带配置的沙盒执行器
executor = BuiltInCodeExecutor(
    api_key=os.getenv('E2B_API_KEY'),
    timeout_ms=60000,  # 1分钟超时
    envs={'CUSTOM_VAR': 'value'},
    on_stdout=lambda data: print('LOG:', data.line),
)

​
支持语言

可执行多种语言代码并获取结构化结果：

​
工作流示例：Agent集成

将代码执行与FilesystemToolkit等工具结合，构建强大的Agent。 
from agkit.tools import BuiltInCodeExecutor, FilesystemToolkit, LocalFileOperator
import os

# 1. 创建工具实例
fs_toolkit = FilesystemToolkit(
    name="fs",
    context={
        "working_directory": os.getcwd(),
        "fs_operator": LocalFileOperator()
    }
)

# 2. 为Agent提供工具集
tools=[executor, *fs_toolkit.get_tools()]
# 示例代码，具体取决于您的Agent框架
agent = Agent(
    # ... 其他Agent配置
    tools=[executor, *fs_toolkit.get_tools()],
    instructions="您是一个可以读写文件并执行代码的智能助手"
)

# 3. 运行Agent
response = await agent.run({
    "input": '编写一个打印"Hello from file!"的Python脚本到"hello.py"，然后运行它'
})