Skip to content

Commit b15bac0

Browse files
OanakiajaOanakiaja
committed
feat: add aiosandbox filesystem.Backend middleware example
- Implement filesystem.Backend + Shell using AIO Sandbox SDK (data plane) - Add sandbox lifecycle management via veFaaS SDK (control plane) - Support Direct mode (existing sandbox) and Managed mode (auto create/kill) - Tools: ls, read_file, write_file, edit_file (str_replace_editor), glob, grep (rg), execute - Use faasInstanceName query param for sandbox identification
1 parent 6a9fa80 commit b15bac0

8 files changed

Lines changed: 1068 additions & 12 deletions

File tree

‎adk/middleware/aiosandbox-backend/.example.env‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# === Mode 1: Direct (use existing sandbox) ===
2+
# Data plane URL with faasInstanceName query parameter
3+
AIO_SANDBOX_BASE_URL=https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name
4+
# Optional: Bearer token authentication
5+
# AIO_SANDBOX_TOKEN=your-token
6+
7+
# === Mode 2: Managed (auto create/kill sandbox) ===
8+
# Volcengine credentials for sandbox lifecycle management
9+
# VOLC_ACCESSKEY=your-access-key
10+
# VOLC_SECRETKEY=your-secret-key
11+
# VEFAAS_FUNCTION_ID=your-function-id
12+
# VEFAAS_GATEWAY_URL=https://xxx.apigateway-cn-beijing.volceapi.com
13+
14+
# === Model configuration (choose one provider) ===
15+
16+
# Option 1: OpenAI compatible
17+
OPENAI_API_KEY=your-api-key
18+
OPENAI_MODEL=gpt-4
19+
OPENAI_BASE_URL=https://api.openai.com/v1
20+
21+
# Option 2: Ark (set MODEL_TYPE=ark)
22+
# MODEL_TYPE=ark
23+
# ARK_API_KEY=your-ark-api-key
24+
# ARK_MODEL=your-model-name
25+
# ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3

‎adk/middleware/aiosandbox-backend/README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# AIO Sandbox Filesystem Middleware Example
2+
3+
This example demonstrates how to use the Deep Agent with [AIO Sandbox](https://github.com/agent-infra/sandbox)
4+
5+
You can access AIO Sandbox through [Volcano Engine veFaaS Sandbox](https://www.volcengine.com/docs/6662/1802770) to quickly get a secure isolated code execution environment.
6+
7+
This example demonstrates how to implement a custom `filesystem.Backend` and use it with `filesystem.NewMiddleware` to provide file system tools to an agent running in a remote AIO Sandbox environment.
8+
9+
## Overview
10+
11+
The `filesystem.Backend` interface allows you to plug in any file system implementation. This example shows how to:
12+
13+
1. Implement the `filesystem.Backend` interface using AIO Sandbox SDK (data plane)
14+
2. Manage sandbox lifecycle via veFaaS API (control plane)
15+
3. Create a filesystem middleware with the custom backend
16+
4. Use the middleware with a deep agent
17+
18+
## Architecture
19+
20+
```
21+
┌─────────────────────────────────────────────────────────────────┐
22+
│ Deep Agent │
23+
├─────────────────────────────────────────────────────────────────┤
24+
│ Filesystem Middleware │
25+
│ (Auto-registers: ls, read_file, write_file, edit_file, │
26+
│ glob, grep, execute tools) │
27+
├─────────────────────────────────────────────────────────────────┤
28+
│ AIOSandboxBackend │
29+
│ (implements filesystem.Backend + Shell) │
30+
├──────────────────────┬──────────────────────────────────────────┤
31+
│ Control Plane │ Data Plane │
32+
│ veFaaS SDK │ AIO Sandbox SDK │
33+
│ (Create/Kill/ │ (File/Shell operations via │
34+
│ Describe sandbox) │ faasInstanceName query param) │
35+
└──────────────────────┴──────────────────────────────────────────┘
36+
```
37+
38+
## Backend Interface Mapping
39+
40+
| filesystem.Backend Method | AIO Sandbox SDK API |
41+
|---------------------------|-------------------------------|
42+
| LsInfo | File.ListPath |
43+
| Read | File.ReadFile |
44+
| Write | File.WriteFile |
45+
| Edit | File.ReplaceInFile |
46+
| GrepRaw | Ripgrep |
47+
| GlobInfo | File.FindFiles |
48+
| Execute (Shell) | Shell.ExecCommand |
49+
50+
## Prerequisites
51+
52+
The example supports two modes:
53+
54+
### Mode 1: Direct (use existing sandbox)
55+
56+
```bash
57+
# Data plane URL with faasInstanceName query parameter
58+
AIO_SANDBOX_BASE_URL=https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name
59+
60+
# Optional: Bearer token authentication
61+
# AIO_SANDBOX_TOKEN=your-token
62+
```
63+
64+
### Mode 2: Managed (auto create/kill sandbox)
65+
66+
```bash
67+
# Volcengine credentials for sandbox lifecycle management
68+
VOLC_ACCESSKEY=your-access-key
69+
VOLC_SECRETKEY=your-secret-key
70+
VEFAAS_FUNCTION_ID=your-function-id
71+
VEFAAS_GATEWAY_URL=https://xxx.apigateway-cn-beijing.volceapi.com
72+
```
73+
74+
### Model configuration
75+
76+
```bash
77+
# Option 1: OpenAI compatible
78+
OPENAI_API_KEY=your-api-key
79+
OPENAI_MODEL=gpt-4
80+
OPENAI_BASE_URL=https://api.openai.com/v1
81+
82+
# Option 2: Ark (set MODEL_TYPE=ark)
83+
# MODEL_TYPE=ark
84+
# ARK_API_KEY=your-ark-api-key
85+
# ARK_MODEL=your-model-name
86+
# ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
87+
```
88+
89+
## Usage
90+
91+
### Direct mode
92+
93+
```go
94+
// Use an existing sandbox via data plane URL
95+
backend, err := NewAIOSandboxBackend(ctx, &AIOSandboxBackendConfig{
96+
BaseURL: "https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name",
97+
WorkDir: "/tmp",
98+
})
99+
```
100+
101+
### Managed mode
102+
103+
```go
104+
// Create sandbox via control plane
105+
mgr, _ := NewSandboxManager(&SandboxManagerConfig{
106+
AccessKey: "your-ak",
107+
SecretKey: "your-sk",
108+
FunctionID: "your-function-id",
109+
})
110+
111+
sandboxID, _ := mgr.CreateSandbox()
112+
defer mgr.KillSandbox(sandboxID)
113+
114+
// Connect data plane
115+
baseURL := mgr.DataPlaneBaseURL("https://xxx.apigateway-cn-beijing.volceapi.com", sandboxID)
116+
backend, err := NewAIOSandboxBackend(ctx, &AIOSandboxBackendConfig{
117+
BaseURL: baseURL,
118+
WorkDir: "/tmp",
119+
})
120+
```
121+
122+
### Use with agent
123+
124+
```go
125+
fsMW, _ := filesystem.NewMiddleware(ctx, &filesystem.Config{
126+
Backend: backend,
127+
Shell: backend,
128+
})
129+
130+
agent, _ := deep.New(ctx, &deep.Config{
131+
ChatModel: chatModel,
132+
Middlewares: []adk.AgentMiddleware{fsMW},
133+
})
134+
```
135+
136+
## Run the Example
137+
138+
```bash
139+
cd adk/middleware/aiosandbox-backend
140+
go run .
141+
```
142+
143+
## Implementing Your Own Backend
144+
145+
To implement a custom filesystem backend, implement the `filesystem.Backend` interface:
146+
147+
```go
148+
type Backend interface {
149+
LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
150+
Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
151+
GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
152+
GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
153+
Write(ctx context.Context, req *WriteRequest) error
154+
Edit(ctx context.Context, req *EditRequest) error
155+
}
156+
```
157+
158+
Optionally implement the `filesystem.Shell` interface to provide the `execute` tool:
159+
160+
```go
161+
type Shell interface {
162+
Execute(ctx context.Context, input *ExecuteRequest) (*ExecuteResponse, error)
163+
}
164+
```

‎adk/middleware/aiosandbox-backend/README_zh.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# AIO Sandbox 文件系统中间件示例
2+
3+
本示例演示如何将 Deep Agent 与 [AIO Sandbox](https://github.com/agent-infra/sandbox) 集成
4+
5+
您可以通过 [火山引擎 veFaaS Sandbox](https://www.volcengine.com/docs/6662/1802770) 快速获得一个安全隔离的代码执行环境。
6+
7+
本示例演示如何实现自定义 `filesystem.Backend`，并将其与 `filesystem.NewMiddleware` 配合使用，为运行在远程 AIO Sandbox 环境中的 Agent 提供文件系统工具。
8+
9+
## 概述
10+
11+
`filesystem.Backend` 接口允许你接入任意文件系统实现。本示例展示了如何：
12+
13+
1. 使用 AIO Sandbox SDK 实现 `filesystem.Backend` 接口（数据面）
14+
2. 通过 veFaaS API 管理沙箱生命周期（控制面）
15+
3. 使用自定义后端创建文件系统中间件
16+
4. 将中间件与 Deep Agent 配合使用
17+
18+
## 架构
19+
20+
```
21+
┌─────────────────────────────────────────────────────────────────┐
22+
│ Deep Agent │
23+
├─────────────────────────────────────────────────────────────────┤
24+
│ Filesystem Middleware │
25+
│ (自动注册: ls, read_file, write_file, edit_file, │
26+
│ glob, grep, execute 工具) │
27+
├─────────────────────────────────────────────────────────────────┤
28+
│ AIOSandboxBackend │
29+
│ (实现 filesystem.Backend + Shell) │
30+
├──────────────────────┬──────────────────────────────────────────┤
31+
│ 控制面 │ 数据面 │
32+
│ veFaaS SDK │ AIO Sandbox SDK │
33+
│ (创建/销毁/ │ (文件/Shell 操作，通过 │
34+
│ 查询沙箱) │ faasInstanceName 查询参数) │
35+
└──────────────────────┴──────────────────────────────────────────┘
36+
```
37+
38+
## 后端接口映射
39+
40+
| filesystem.Backend 方法 | AIO Sandbox SDK API |
41+
|---------------------------|-------------------------------|
42+
| LsInfo | File.ListPath |
43+
| Read | File.ReadFile |
44+
| Write | File.WriteFile |
45+
| Edit | File.ReplaceInFile |
46+
| GrepRaw | Ripgrep |
47+
| GlobInfo | File.FindFiles |
48+
| Execute (Shell) | Shell.ExecCommand |
49+
50+
## 前置条件
51+
52+
示例支持两种模式：
53+
54+
### 模式一：直连（使用已有沙箱）
55+
56+
```bash
57+
# 数据面 URL，通过 faasInstanceName 查询参数指定沙箱实例
58+
AIO_SANDBOX_BASE_URL=https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name
59+
60+
# 可选：Bearer Token 认证
61+
# AIO_SANDBOX_TOKEN=your-token
62+
```
63+
64+
### 模式二：托管（自动创建/销毁沙箱）
65+
66+
```bash
67+
# 火山引擎凭证，用于沙箱生命周期管理
68+
VOLC_ACCESSKEY=your-access-key
69+
VOLC_SECRETKEY=your-secret-key
70+
VEFAAS_FUNCTION_ID=your-function-id
71+
VEFAAS_GATEWAY_URL=https://xxx.apigateway-cn-beijing.volceapi.com
72+
```
73+
74+
### 模型配置
75+
76+
```bash
77+
# 方式一：OpenAI 兼容接口
78+
OPENAI_API_KEY=your-api-key
79+
OPENAI_MODEL=gpt-4
80+
OPENAI_BASE_URL=https://api.openai.com/v1
81+
82+
# 方式二：Ark（设置 MODEL_TYPE=ark）
83+
# MODEL_TYPE=ark
84+
# ARK_API_KEY=your-ark-api-key
85+
# ARK_MODEL=your-model-name
86+
# ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
87+
```
88+
89+
## 使用方法
90+
91+
### 直连模式
92+
93+
```go
94+
// 通过数据面 URL 使用已有沙箱
95+
backend, err := NewAIOSandboxBackend(ctx, &AIOSandboxBackendConfig{
96+
BaseURL: "https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name",
97+
WorkDir: "/tmp",
98+
})
99+
```
100+
101+
### 托管模式
102+
103+
```go
104+
// 通过控制面创建沙箱
105+
mgr, _ := NewSandboxManager(&SandboxManagerConfig{
106+
AccessKey: "your-ak",
107+
SecretKey: "your-sk",
108+
FunctionID: "your-function-id",
109+
})
110+
111+
sandboxID, _ := mgr.CreateSandbox()
112+
defer mgr.KillSandbox(sandboxID)
113+
114+
// 连接数据面
115+
baseURL := mgr.DataPlaneBaseURL("https://xxx.apigateway-cn-beijing.volceapi.com", sandboxID)
116+
backend, err := NewAIOSandboxBackend(ctx, &AIOSandboxBackendConfig{
117+
BaseURL: baseURL,
118+
WorkDir: "/tmp",
119+
})
120+
```
121+
122+
### 与 Agent 配合使用
123+
124+
```go
125+
fsMW, _ := filesystem.NewMiddleware(ctx, &filesystem.Config{
126+
Backend: backend,
127+
Shell: backend,
128+
})
129+
130+
agent, _ := deep.New(ctx, &deep.Config{
131+
ChatModel: chatModel,
132+
Middlewares: []adk.AgentMiddleware{fsMW},
133+
})
134+
```
135+
136+
## 运行示例
137+
138+
```bash
139+
cd adk/middleware/aiosandbox-backend
140+
go run .
141+
```
142+
143+
## 实现自定义后端
144+
145+
要实现自定义文件系统后端，需要实现 `filesystem.Backend` 接口：
146+
147+
```go
148+
type Backend interface {
149+
LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
150+
Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
151+
GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
152+
GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
153+
Write(ctx context.Context, req *WriteRequest) error
154+
Edit(ctx context.Context, req *EditRequest) error
155+
}
156+
```
157+
158+
可选实现 `filesystem.Shell` 接口以提供 `execute` 工具：
159+
160+
```go
161+
type Shell interface {
162+
Execute(ctx context.Context, input *ExecuteRequest) (*ExecuteResponse, error)
163+
}
164+
```

0 commit comments

Comments
 (0)