Skip to content

Commit ff469d8

Browse files
zhuangjie1125zhuangjie1125
committed
feat(adk/backend): implement both Ark Sandbox and Local filesystem backends
This commit introduces two new backend implementations for `adk/backend` to support flexible filesystem operations: `arksandbox` for secure remote execution and `local` for direct local filesystem access. Key changes include: - **Ark Sandbox Backend (`arksandbox`)**: - Implements `filesystem.Backend` to integrate with Volcengine's Ark Sandbox. - Features include request signing, session management, and remote execution of filesystem commands (LsInfo, Read, Write, Edit, GrepRaw, GlobInfo). - Adds `code_template.go` for Python-based sandbox operations and `types.go` for API definitions. - **Local Backend (`local`)**: - Implements `filesystem.Backend` for operating directly on the local machine's filesystem. - Supports standard operations: `LsInfo` (directory listing), `Read` (with line limits/offsets), `Write` (file creation), `GrepRaw` (content search), and `GlobInfo` (pattern matching). - Includes input validation to ensure paths are absolute and handles permission errors gracefully. - **General**: - Adds unit tests for both backends (`arksandbox_test.go`, `local_sandbox_test.go`) to verify functionality. - Updates `go.mod` and `go.sum` with necessary dependencies. - Provides comprehensive `README.md` documentation for both implementations.
1 parent 9f93a13 commit ff469d8

File tree

14 files changed

+2623
-0
lines changed

14 files changed

+2623
-0
lines changed

‎adk/backend/arksandbox/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# EINO ADK - Ark Sandbox Backend
2+
3+
`arksandbox` is an ADK (Agent Development Kit) backend that integrates with Volcengine's Ark Sandbox service. This backend provides a secure, sandboxed environment for executing code and performing filesystem operations, leveraging Volcengine's infrastructure to ensure isolation and security.
4+
5+
It implements the `filesystem.Backend` interface, allowing you to interact with the sandbox's filesystem through a standardized set of methods.
6+
7+
## Features
8+
9+
- **Secure Execution**: All operations are performed within a secure, isolated sandbox environment.
10+
- **Full `filesystem.Backend` Implementation**: Supports all standard filesystem operations:
11+
- `LsInfo`: Lists files and directories.
12+
- `Read`: Reads file content.
13+
- `Write`: Creates and writes to files.
14+
- `Edit`: Searches and replaces content within files.
15+
- `GrepRaw`: Searches for patterns in files.
16+
- `GlobInfo`: Finds files matching a glob pattern.
17+
- **Session Management**: Supports session isolation via `UserSessionID` and configurable session TTL.
18+
19+
## Configuration
20+
21+
To initialize the backend, you need to provide a `Config` struct with your Volcengine credentials and tool details.
22+
23+
```go
24+
// Config holds the configuration for the Ark Sandbox.
25+
type Config struct {
26+
// AccessKeyID for Volcengine. Required.
27+
AccessKeyID string
28+
29+
// SecretAccessKey for Volcengine. Required.
30+
SecretAccessKey string
31+
32+
// ToolID is the ID of the sandbox tool created in the Volcengine console. Required.
33+
ToolID string
34+
35+
// UserSessionID specifies the user session to achieve context isolation. Required.
36+
UserSessionID string
37+
38+
// Region is the request's region (e.g., "cn-beijing").
39+
// Optional. Defaults to "cn-beijing".
40+
Region Region
41+
42+
// SessionTTL is the session expiration time in seconds (range: 60-86400).
43+
// Optional. Defaults to 1800.
44+
SessionTTL int
45+
46+
// InvokeTimeout is the timeout for executing a single command in the sandbox, in seconds.
47+
// Optional. Defaults to 30.
48+
InvokeTimeout int
49+
50+
// HTTPClient specifies the client to send HTTP requests.
51+
// Optional. If not set, a default client with a timeout is used.
52+
HTTPClient *http.Client
53+
54+
// Timeout specifies the maximum duration for the HTTP client.
55+
// This is ignored if HTTPClient is set.
56+
// Optional.
57+
Timeout time.Duration
58+
}
59+
```
60+
61+
## Usage
62+
63+
Here is a complete example of how to initialize and use the `arksandbox` backend.
64+
65+
### Prerequisites
66+
67+
Set the following environment variables with your Volcengine credentials:
68+
69+
- `VOLC_ACCESS_KEY_ID`: Your Access Key ID.
70+
- `VOLC_SECRET_ACCESS_KEY`: Your Secret Access Key.
71+
- `VOLC_TOOL_ID`: The ID of your Ark Sandbox tool.
72+
73+
### Example Code
74+
75+
```go
76+
package main
77+
78+
import (
79+
"context"
80+
"fmt"
81+
"log"
82+
"os"
83+
"time"
84+
85+
"github.com/cloudwego/eino-ext/adk/backend/arksandbox"
86+
"github.com/cloudwego/eino/adk/middlewares/filesystem"
87+
)
88+
89+
func main() {
90+
// 1. Configure the backend
91+
accessKeyID := os.Getenv("VOLC_ACCESS_KEY_ID")
92+
secretAccessKey := os.Getenv("VOLC_SECRET_ACCESS_KEY")
93+
toolID := os.Getenv("VOLC_TOOL_ID")
94+
95+
if accessKeyID == "" || secretAccessKey == "" || toolID == "" {
96+
log.Fatal("Environment variables VOLC_ACCESS_KEY_ID, VOLC_SECRET_ACCESS_KEY, and VOLC_TOOL_ID must be set.")
97+
}
98+
99+
config := &arksandbox.Config{
100+
AccessKeyID: accessKeyID,
101+
SecretAccessKey: secretAccessKey,
102+
ToolID: toolID,
103+
UserSessionID: "example-session-" + time.Now().Format("20060102-150405"),
104+
Region: arksandbox.RegionOfBeijing,
105+
Timeout: 60 * time.Second,
106+
}
107+
108+
// 2. Create a new backend instance
109+
client, err := arksandbox.NewArkSandboxBackend(config)
110+
if err != nil {
111+
log.Fatalf("Failed to create backend: %v", err)
112+
}
113+
114+
// 3. Use the client for filesystem operations
115+
ctx := context.Background()
116+
117+
// Example: List files in the root directory
118+
// Note: The default user 'gem' may not have permission. Use a writable directory like '/home/gem'.
119+
files, err := client.LsInfo(ctx, &filesystem.LsInfoRequest{Path: "/home/gem"})
120+
if err != nil {
121+
log.Fatalf("Failed to list files: %v", err)
122+
}
123+
fmt.Println("Files in /home/gem:")
124+
for _, f := range files {
125+
fmt.Printf("- %s\n", f.Path)
126+
}
127+
128+
// Example: Write a new file
129+
filePath := "/home/gem/example.txt"
130+
err = client.Write(ctx, &filesystem.WriteRequest{
131+
FilePath: filePath,
132+
Content: "Hello, Ark Sandbox!",
133+
})
134+
if err != nil {
135+
log.Fatalf("Failed to write file: %v", err)
136+
}
137+
fmt.Printf("Successfully wrote to %s\n", filePath)
138+
139+
// Example: Read the file content
140+
content, err := client.Read(ctx, &filesystem.ReadRequest{
141+
FilePath: filePath,
142+
})
143+
if err != nil {
144+
log.Fatalf("Failed to read file: %v", err)
145+
}
146+
fmt.Printf("Content of %s: %s\n", filePath, content)
147+
}
148+
```
149+
150+
## API Reference
151+
152+
The `arksandbox` backend implements the `filesystem.Backend` interface.
153+
154+
### `NewArkSandboxBackend(config *Config) (filesystem.Backend, error)`
155+
156+
Initializes a new backend instance with the given configuration. It returns a `filesystem.Backend` interface, hiding the specific implementation.
157+
158+
## FAQ
159+
160+
**Q: Why am I getting "permission denied" errors?**
161+
162+
A: Instances created by the default AIO Sandbox and Skills Sandbox tools in Volcengine have a default execution user named `gem`. This user may not have permissions to operate on system paths like `/` or `/tmp`. Always perform file operations in a designated user-writable directory, such as `/home/gem`, to avoid permission issues.
163+
164+
**Q: How should I manage API credentials?**
165+
166+
A: Never hardcode your `AccessKeyID` and `SecretAccessKey` in your source code. Use environment variables (as shown in the example) or a secure secret management service to handle your credentials.

0 commit comments

Comments
 (0)