코드 실행

ADK-Rust은 두 개의 크레이트를 통해 코드 실행을 제공합니다.

• 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은 컴파일 없이 백엔드를 통해 직접 코드를 실행합니다.

백엔드 기능 매트릭스

ProcessBackend은 자신이 시행하지 않는 사항을 솔직하게 밝힙니다. 완전한 샌드박싱에는 WasmBackend을 사용하고, 컨테이너 수준의 격리에는 DockerExecutor을 사용하세요.

도구

CodeTool, SandboxTool, MontyPythonCodeTool는 오류를 정보로 취급하는 패턴을 따릅니다. 오류는 "status" 필드를 포함한 구조화된 JSON로 반환되며, 절대 ToolError로 반환되지 않습니다. 이를 통해 agent가 실패 원인을 추론할 수 있습니다. PythonCodeTool는 예외로, 누락된 code 인수 및 executor 수준의 실패에 대해 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(), stdin 파싱 및 stdout 직렬화를 추가합니다. 사용자 코드는 fn main()을 정의하거나 크레이트 수준 속성(#![...])을 사용해서는 안 됩니다.

이전 API에서 마이그레이션

이전 adk-code 타입(CodeExecutor, ExecutionRequest, RustSandboxExecutor)과 adk-tool의 RustCodeTool이 제거되었습니다. 대신 새 타입을 사용하세요.

전체 마이그레이션 가이드는 adk_code::compat를 참조하세요.

브라우저 JavaScript

adk-browser를 통한 브라우저 페이지 JavaScript 실행은 별도의 기능입니다. 원격 페이지 컨텍스트 내에서 실행되며 코드 실행 기반의 일부가 아닙니다. 웹 자동화 및 페이지 상호작용에는 adk-browser 도구를 사용하세요.

Studio 통합

ADK Studio는 동일한 코드 실행 파이프라인을 사용합니다.

• 라이브 실행기: RustExecutor + ProcessBackend을 통해 작성된 Rust를 실행합니다.
• 코드 생성: 동일한 Rust 본문을 생성된 프로젝트에 삽입합니다.
• 샌드박스 설정: 백엔드에서 적용 가능한 기능으로 매핑됩니다.