Skip to content

Commit b53e50e

Browse files
OanakiajaOanakiaja
committed
refactor: rewrite aiosandbox example with filesystem.Backend middleware
- Adapt backend to eino v0.8.1 API (FileContent return type, Shell interface) - Fix GrepRaw: support regex, add all GrepRequest params (-i, -U, -A, -B, -t) - Fix LsInfo: populate IsDir/Size/ModifiedAt, convert unix timestamp to ISO 8601 - Add sandbox lifecycle management via veFaaS SDK (Create/Describe/Kill) - Support Direct mode (existing sandbox) and Managed mode (auto create/kill) - Use faasInstanceName query param instead of custom headers - Remove deep-aiosandbox example (depends on unpublished commandline/aiosandbox)
1 parent 8828a15 commit b53e50e

10 files changed

Lines changed: 400 additions & 716 deletions

File tree

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

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
1-
# AIO Sandbox configuration (without trailing slash)
2-
AIO_SANDBOX_BASE_URL=https://xxx.apigateway-cn-beijing.volceapi.com
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
36

4-
# Model configuration (choose one provider)
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) ===
515

616
# Option 1: OpenAI compatible
717
OPENAI_API_KEY=your-api-key

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

Lines changed: 69 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# AIO Sandbox Filesystem Middleware Example
22

3-
This example demonstrates how to use the Deep Agent with [AIO Sandbox](https://github.com/agent-infra/sandbox)
3+
This example demonstrates how to use the Deep Agent with [AIO Sandbox](https://github.com/agent-infra/sandbox)
44

55
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.
66

@@ -10,9 +10,10 @@ This example demonstrates how to implement a custom `filesystem.Backend` and use
1010

1111
The `filesystem.Backend` interface allows you to plug in any file system implementation. This example shows how to:
1212

13-
1. Implement the `filesystem.Backend` interface using AIO Sandbox SDK
14-
2. Create a filesystem middleware with the custom backend
15-
3. Use the middleware with a deep agent
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
1617

1718
## Architecture
1819

@@ -25,11 +26,13 @@ The `filesystem.Backend` interface allows you to plug in any file system impleme
2526
│ glob, grep, execute tools) │
2627
├─────────────────────────────────────────────────────────────────┤
2728
│ AIOSandboxBackend │
28-
│ (implements filesystem.Backend + ShellBackend) │
29-
├─────────────────────────────────────────────────────────────────┤
30-
│ AIO Sandbox SDK │
31-
│ (Remote sandbox environment) │
32-
└─────────────────────────────────────────────────────────────────┘
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+
└──────────────────────┴──────────────────────────────────────────┘
3336
```
3437

3538
## Backend Interface Mapping
@@ -42,18 +45,35 @@ The `filesystem.Backend` interface allows you to plug in any file system impleme
4245
| Edit | File.ReplaceInFile |
4346
| GrepRaw | Ripgrep |
4447
| GlobInfo | File.FindFiles |
45-
| Execute (ShellBackend) | Shell.ExecCommand |
48+
| Execute (Shell) | Shell.ExecCommand |
4649

4750
## Prerequisites
4851

49-
Set the following environment variables:
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)
5065

5166
```bash
52-
# AIO Sandbox configuration (without trailing slash)
53-
AIO_SANDBOX_BASE_URL=https://xxx.apigateway-cn-beijing.volceapi.com
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+
```
5473

55-
# Model configuration (choose one provider)
74+
### Model configuration
5675

76+
```bash
5777
# Option 1: OpenAI compatible
5878
OPENAI_API_KEY=your-api-key
5979
OPENAI_MODEL=gpt-4
@@ -68,28 +88,51 @@ OPENAI_BASE_URL=https://api.openai.com/v1
6888

6989
## Usage
7090

71-
### Basic Usage
91+
### Direct mode
7292

7393
```go
74-
// Create custom filesystem backend
94+
// Use an existing sandbox via data plane URL
7595
backend, err := NewAIOSandboxBackend(ctx, &AIOSandboxBackendConfig{
76-
BaseURL: "https://xxx.apigateway-cn-beijing.volceapi.com",
96+
BaseURL: "https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name",
7797
WorkDir: "/tmp",
7898
})
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+
})
79110

80-
// Create filesystem middleware with custom backend
81-
fsMW, err := filesystem.NewMiddleware(ctx, &filesystem.Config{
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{
82126
Backend: backend,
127+
Shell: backend,
83128
})
84129

85-
// Use with agent
86-
agent, err := deep.New(ctx, &deep.Config{
130+
agent, _ := deep.New(ctx, &deep.Config{
87131
ChatModel: chatModel,
88132
Middlewares: []adk.AgentMiddleware{fsMW},
89133
})
90134
```
91135

92-
93136
## Run the Example
94137

95138
```bash
@@ -104,29 +147,18 @@ To implement a custom filesystem backend, implement the `filesystem.Backend` int
104147
```go
105148
type Backend interface {
106149
LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
107-
Read(ctx context.Context, req *ReadRequest) (string, error)
150+
Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
108151
GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
109152
GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
110153
Write(ctx context.Context, req *WriteRequest) error
111154
Edit(ctx context.Context, req *EditRequest) error
112155
}
113156
```
114157

158+
Optionally implement the `filesystem.Shell` interface to provide the `execute` tool:
159+
115160
```go
116-
type ShellBackend interface {
117-
Backend
161+
type Shell interface {
118162
Execute(ctx context.Context, input *ExecuteRequest) (*ExecuteResponse, error)
119163
}
120164
```
121-
122-
## Comparison with CommandLine Approach
123-
124-
This example uses the **Middleware approach** with `filesystem.Backend`:
125-
- Automatically registers 7 tools: `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`
126-
- Includes built-in large result offloading
127-
- Clean interface-based design
128-
129-
The [deep-aiosandbox](../../multiagent/deep-aiosandbox) example uses the **Tool approach** with `commandline.Operator`:
130-
- Manually registers tools: `bash`, `read_file`, `edit_file`, `tree`
131-
- More flexible for custom tool combinations
132-
- Requires more setup code

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

Lines changed: 69 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,18 @@
22

33
本示例演示如何将 Deep Agent 与 [AIO Sandbox](https://github.com/agent-infra/sandbox) 集成
44

5-
您可以访问 AIO Sandbox 通过 [Volcano Engine veFaaS Sandbox](https://www.volcengine.com/docs/6662/1802770) 快速获得一个安全隔离的代码执行环境。
5+
您可以通过 [火山引擎 veFaaS Sandbox](https://www.volcengine.com/docs/6662/1802770) 快速获得一个安全隔离的代码执行环境。
66

77
本示例演示如何实现自定义 `filesystem.Backend`，并将其与 `filesystem.NewMiddleware` 配合使用，为运行在远程 AIO Sandbox 环境中的 Agent 提供文件系统工具。
88

99
## 概述
1010

1111
`filesystem.Backend` 接口允许你接入任意文件系统实现。本示例展示了如何：
1212

13-
1. 使用 AIO Sandbox SDK 实现 `filesystem.Backend` 接口
14-
2. 使用自定义后端创建文件系统中间件
15-
3. 将中间件与 Deep Agent 配合使用
13+
1. 使用 AIO Sandbox SDK 实现 `filesystem.Backend` 接口（数据面）
14+
2. 通过 veFaaS API 管理沙箱生命周期（控制面）
15+
3. 使用自定义后端创建文件系统中间件
16+
4. 将中间件与 Deep Agent 配合使用
1617

1718
## 架构
1819

@@ -25,11 +26,13 @@
2526
│ glob, grep, execute 工具) │
2627
├─────────────────────────────────────────────────────────────────┤
2728
│ AIOSandboxBackend │
28-
│ (实现 filesystem.Backend + ShellBackend) │
29-
├─────────────────────────────────────────────────────────────────┤
30-
│ AIO Sandbox SDK │
31-
│ (远程沙箱环境) │
32-
└─────────────────────────────────────────────────────────────────┘
29+
│ (实现 filesystem.Backend + Shell) │
30+
├──────────────────────┬──────────────────────────────────────────┤
31+
│ 控制面 │ 数据面 │
32+
│ veFaaS SDK │ AIO Sandbox SDK │
33+
│ (创建/销毁/ │ (文件/Shell 操作，通过 │
34+
│ 查询沙箱) │ faasInstanceName 查询参数) │
35+
└──────────────────────┴──────────────────────────────────────────┘
3336
```
3437

3538
## 后端接口映射
@@ -42,18 +45,35 @@
4245
| Edit | File.ReplaceInFile |
4346
| GrepRaw | Ripgrep |
4447
| GlobInfo | File.FindFiles |
45-
| Execute (ShellBackend) | Shell.ExecCommand |
48+
| Execute (Shell) | Shell.ExecCommand |
4649

4750
## 前置条件
4851

49-
设置以下环境变量：
52+
示例支持两种模式：
53+
54+
### 模式一：直连（使用已有沙箱）
5055

5156
```bash
52-
# AIO Sandbox 配置（不含尾部斜杠）
53-
AIO_SANDBOX_BASE_URL=https://xxx.apigateway-cn-beijing.volceapi.com
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+
```
5463

55-
# 模型配置（选择其中一种方式）
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+
```
5673

74+
### 模型配置
75+
76+
```bash
5777
# 方式一：OpenAI 兼容接口
5878
OPENAI_API_KEY=your-api-key
5979
OPENAI_MODEL=gpt-4
@@ -68,28 +88,51 @@ OPENAI_BASE_URL=https://api.openai.com/v1
6888

6989
## 使用方法
7090

71-
### 基本用法
91+
### 直连模式
7292

7393
```go
74-
// 创建自定义文件系统后端
94+
// 通过数据面 URL 使用已有沙箱
7595
backend, err := NewAIOSandboxBackend(ctx, &AIOSandboxBackendConfig{
76-
BaseURL: "https://xxx.apigateway-cn-beijing.volceapi.com",
77-
WorkDir: "/tmp",
96+
BaseURL: "https://xxx.apigateway-cn-beijing.volceapi.com?faasInstanceName=your-instance-name",
97+
WorkDir: "/tmp",
7898
})
99+
```
79100

80-
// 使用自定义后端创建文件系统中间件
81-
fsMW, err := filesystem.NewMiddleware(ctx, &filesystem.Config{
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{
82126
Backend: backend,
127+
Shell: backend,
83128
})
84129

85-
// 与 Agent 配合使用
86-
agent, err := deep.New(ctx, &deep.Config{
130+
agent, _ := deep.New(ctx, &deep.Config{
87131
ChatModel: chatModel,
88132
Middlewares: []adk.AgentMiddleware{fsMW},
89133
})
90134
```
91135

92-
93136
## 运行示例
94137

95138
```bash
@@ -104,31 +147,18 @@ go run .
104147
```go
105148
type Backend interface {
106149
LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
107-
Read(ctx context.Context, req *ReadRequest) (string, error)
150+
Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
108151
GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
109152
GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
110153
Write(ctx context.Context, req *WriteRequest) error
111154
Edit(ctx context.Context, req *EditRequest) error
112155
}
113156
```
114157

115-
实现 `ShellBackend` 以提供 `execute` 工具：
158+
可选实现 `filesystem.Shell` 接口以提供 `execute` 工具：
116159

117160
```go
118-
type ShellBackend interface {
119-
Backend
161+
type Shell interface {
120162
Execute(ctx context.Context, input *ExecuteRequest) (*ExecuteResponse, error)
121163
}
122164
```
123-
124-
## 与 CommandLine 方式的对比
125-
126-
本示例使用 **中间件方式** 配合 `filesystem.Backend`：
127-
- 自动注册 7 个工具：`ls`、`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`execute`
128-
- 内置大结果分流处理
129-
- 简洁的基于接口的设计
130-
131-
[deep-aiosandbox](../../multiagent/deep-aiosandbox) 示例使用 **工具方式** 配合 `commandline.Operator`：
132-
- 手动注册工具：`bash`、`read_file`、`edit_file`、`tree`
133-
- 对自定义工具组合更灵活
134-
- 需要更多配置代码

0 commit comments

Comments
 (0)