Ark Agentkit Sandbox
Agentkit Sandbox Backend
Package: github.com/cloudwego/eino-ext/adk/backend/agentkit
注意：如果 eino 版本是 v0.8.0 及以上，需要使用 ark agentkit backend 的 adk/backend/agentkit/v0.2.1 版本。
概述
Agentkit Sandbox Backend 是 EINO ADK FileSystem 的远程沙箱实现，通过火山引擎 Agentkit 服务在隔离的云端环境中执行文件系统操作。
核心特性
- 安全隔离 - 所有操作在远程沙箱环境中执行
- 会话管理 - 支持会话隔离与可配置的 TTL
- 请求签名 - 自动使用 AK/SK 进行火山引擎 API 认证
安装
go get github.com/cloudwego/eino-ext/adk/backend/agentkit
配置
环境变量
export VOLC_ACCESS_KEY_ID="your_access_key"
export VOLC_SECRET_ACCESS_KEY="your_secret_key"
export VOLC_TOOL_ID="your_tool_id"
Config 结构
type Config struct {
// 必填
AccessKeyID string // 访问密钥 ID
SecretAccessKey string // 访问密钥 Secret
ToolID string // 沙箱工具 ID
// 可选
UserSessionID string // 用户会话 ID，用于隔离
Region Region // 区域，默认 cn-beijing
SessionTTL int // 会话 TTL（60-86400 秒）
ExecutionTimeout int // 命令执行超时
HTTPClient *http.Client // 自定义 HTTP 客户端
}
快速开始
基本用法
import (
"context"
"os"
"time"
"github.com/cloudwego/eino-ext/adk/backend/agentkit"
"github.com/cloudwego/eino/adk/filesystem"
)
func main() {
ctx := context.Background()
backend, err := agentkit.NewSandboxToolBackend(&agentkit.Config{
AccessKeyID: os.Getenv("VOLC_ACCESS_KEY_ID"),
SecretAccessKey: os.Getenv("VOLC_SECRET_ACCESS_KEY"),
ToolID: os.Getenv("VOLC_TOOL_ID"),
UserSessionID: "session-" + time.Now().Format("20060102-150405"),
Region: agentkit.RegionOfBeijing,
})
if err != nil {
panic(err)
}
// 写入文件
err = backend.Write(ctx, &filesystem.WriteRequest{
FilePath: "/home/gem/hello.txt",
Content: "Hello, Sandbox!",
})
// 读取文件
fContent, err := backend.Read(ctx, &filesystem.ReadRequest{
FilePath: "/home/gem/hello.txt",
})
fmt.Println(fContent.Content)
}
与 Agent 集成
import (
"github.com/cloudwego/eino/adk"
fsMiddleware "github.com/cloudwego/eino/adk/middlewares/filesystem"
)
// 创建 Backend
backend, _ := agentkit.NewSandboxToolBackend(config)
// 创建 Middleware
middleware, _ := fsMiddleware.New(ctx, &fsMiddleware.Config{
Backend: backend,
Shell: backend,
})
// 创建 Agent
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
Name: "SandboxAgent",
Description: "具有安全文件系统访问能力的 AI Agent",
Model: chatModel,
Handlers: []adk.ChatModelAgentMiddleware{middleware},
})
API 参考
| 方法 | 描述 |
| LsInfo | 列出目录内容 |
| Read | 读取文件内容（支持分页） |
| Write | 创建新文件（已存在则报错） |
| Edit | 替换文件内容 |
| GrepRaw | 搜索文件内容 |
| GlobInfo | 按模式查找文件 |
| Execute | 执行 shell 命令 |
示例
// 列出目录
files, _ := backend.LsInfo(ctx, &filesystem.LsInfoRequest{
Path: "/home/gem",
})
// 读取文件（分页）
fcontent, _ := backend.Read(ctx, &filesystem.ReadRequest{
FilePath: "/home/gem/file.txt",
Offset: 0,
Limit: 100,
})
// 搜索内容
matches, _ := backend.GrepRaw(ctx, &filesystem.GrepRequest{
Path: "/home/gem",
Pattern: "keyword",
Glob: "*.txt",
})
// 查找文件
files, _ := backend.GlobInfo(ctx, &filesystem.GlobInfoRequest{
Path: "/home/gem",
Pattern: "**/*.txt",
})
// 编辑文件
backend.Edit(ctx, &filesystem.EditRequest{
FilePath: "/home/gem/file.txt",
OldString: "old",
NewString: "new",
ReplaceAll: true,
})
// 执行命令
result, _ := backend.Execute(ctx, &filesystem.ExecuteRequest{
Command: "ls -la /home/gem",
})
与 Local Backend 对比
| 特性 | Agentkit | Local |
| 执行模型 | 远程沙箱 | 本地直接 |
| 网络依赖 | 需要 | 不需要 |
| 配置复杂度 | 需要凭证 | 零配置 |
| 安全模型 | 隔离沙箱 | OS 权限 |
| 适用场景 | 多租户/生产环境 | 开发/本地环境 |
常见问题
Q: 认证失败
检查环境变量、AK/SK 是否匹配、账户是否有 Ark Sandbox 权限。
Q: 请求超时
增加 ExecutionTimeout 或 HTTPClient.Timeout 配置。