ADK-Rust

代码执行

ADK-Rust 通过两个 crate 提供代码执行功能：

  • adk-sandbox — 隔离的执行运行时，包含 ProcessBackend（子进程）和 WasmBackend（wasmtime）
  • adk-code — 语言感知的工具链，包含 RustExecutor（检查、构建、执行流水线）和 CodeTool

这种分离是有意为之的：adk-sandbox 负责隔离，adk-code 负责编译和语言特定的逻辑。

快速开始

use adk_code::{CodeTool, RustExecutor, RustExecutorConfig};
use adk_sandbox::ProcessBackend;
use std::sync::Arc;

let backend = Arc::new(ProcessBackend::default());
let executor = RustExecutor::new(backend, RustExecutorConfig::default());
let tool = Arc::new(CodeTool::new(executor));

let agent = LlmAgentBuilder::new("code_agent")
    .instruction("Execute Rust code when asked to compute something.")
    .model(model)
    .tool(tool)
    .build()?;

如需在不使用 Rust 编译流水线的情况下直接执行沙箱代码：

use adk_sandbox::{SandboxTool, ProcessBackend};
use std::sync::Arc;

let backend = Arc::new(ProcessBackend::default());
let tool = Arc::new(SandboxTool::new(backend));

架构

CodeTool 添加了 Rust 编译流水线（检查错误、构建二进制文件，然后执行）。SandboxTool 通过后端直接执行代码，无需编译。

后端能力矩阵

能力ProcessBackendWasmBackendEmbeddedJsExecutorMonty 执行器DockerExecutor
超时强制执行强制执行强制执行强制执行（在虚拟机内）强制执行
内存限制未强制执行强制执行未强制执行强制执行容器限制
网络隔离未强制执行无 WASI 网络无 API 可用无 API 可用可配置
文件系统隔离未强制执行无 WASI 预打开无 API 可用仅限已授予的挂载可配置
环境隔离env_clear()完整无 API 可用仅限已授予的映射可配置
语言Rust、Python、JS、TS、命令WasmJavaScriptPythonPython、Node.js

ProcessBackend 诚实说明了它不会强制执行的内容。使用 WasmBackend 实现完整的沙箱隔离，或使用 DockerExecutor 实现容器级隔离。

工具

工具Crate名称语言作用域
CodeTooladk-codecode_execRustcode:execute, code:execute:rust
SandboxTooladk-sandboxsandbox_exec多语言code:execute
PythonCodeTooladk-toolpython_codePython（基于容器的 CPython）code:execute、code:execute:container
MontyPythonCodeTooladk-toolmonty_python_codePython（进程内 Monty）code:execute

CodeTool、SandboxTool 和 MontyPythonCodeTool 遵循“错误即信息”模式：错误以带有 "status" 字段的结构化 JSON 返回，而绝不会作为 ToolError 返回。这样，代理就能对失败进行推理。PythonCodeTool 是例外——对于缺少 code 参数以及执行器级别的失败，它会返回一个 ToolError；只有脚本级别的失败才会作为数据呈现。

有关进程内 Python 执行——一次性执行和 REPL 模式、OS 访问授权以及主机函数——请参阅 Python 代码执行。

结构化诊断

CodeTool 会返回 Rust 编译错误的解析后编译器诊断信息：

{
  "status": "compile_error",
  "diagnostics": [
    {
      "level": "error",
      "message": "expected `;`",
      "code": "E0308",
      "spans": [{ "file_name": "main.rs", "line_start": 3, "column_start": 15 }]
    }
  ],
  "stderr": "error: expected `;`"
}

成功响应包含从执行框架中提取的结构化输出：

{
  "status": "success",
  "stdout": "",
  "output": { "greeting": "hello" },
  "exit_code": 0,
  "duration_ms": 42
}

Rust 代码契约

用户代码必须提供 fn run(input: serde_json::Value) -> serde_json::Value。执行框架会为其添加 fn main()、标准输入解析和标准输出序列化。用户代码不得定义 fn main()，也不得使用 crate 级属性（#![...]）。

从之前的 API 迁移

之前的 adk-code 类型（CodeExecutor、ExecutionRequest、RustSandboxExecutor）以及 adk-tool 的 RustCodeTool 已被移除。请改用新的类型：

已移除替代项软件包
RustCodeTool（在 0.8.0 中移除）CodeTooladk-code
RustSandboxExecutorRustExecutoradk-code
ExecutionRequestExecRequestadk-sandbox
ExecutionResultExecResultadk-sandbox
CodeExecutorSandboxBackendadk-sandbox

请参阅 adk_code::compat 了解完整的迁移指南。

浏览器 JavaScript

通过 adk-browser 执行浏览器页面 JavaScript 是一项独立的功能。它在远程页面上下文中运行，不属于代码执行基础设施。使用 adk-browser 工具进行 Web 自动化和页面交互。

Studio 集成

ADK Studio 使用相同的代码执行流水线：

  • 实时运行器：通过 RustExecutor + ProcessBackend 执行编写的 Rust 代码
  • 代码生成：将相同的 Rust 代码主体嵌入生成的项目中
  • 沙箱设置：映射到后端可强制执行的功能权限
代码执行 - ADK-Rust 文档 | ADK-Rust