refactor: export backend struct types for external access

.github/workflows/tests.yml

@@ -32,16 +32,16 @@ jobs:
       #     for module in $modules; do
       #       echo "--------------------------------------------------"
       #       echo "run unit test for ${module}"
-            
+
       #       cd ${module}
       #       go test -race -coverprofile=./${COVERAGE_FILE} -gcflags="all=-l -N" -coverpkg=./... ./...
       #       cd -
       #       coverprofiles="${module}/${COVERAGE_FILE},$coverprofiles"
       #     done
-          
+
       #     # Remove trailing comma from coverprofiles
       #     coverprofiles=${coverprofiles%,}
-          
+
       #     echo "COVERAGE_PROFILES=$coverprofiles" >> $GITHUB_ENV
 
       - name: Go test in go workspace
@@ -70,7 +70,7 @@ jobs:
           go test -race -coverprofile=coverage.out -gcflags="all=-l -N" -coverpkg=$coverpkg $list
 
           echo "COVERAGE_PROFILES=$coverprofiles" >> $GITHUB_ENV
-          
+
       - name: Download base.coverage for diff coverage rate
         id: download-base-coverage
         uses: actions/download-artifact@v4
@@ -86,7 +86,7 @@ jobs:
           config: ./.testcoverage.yml
           breakdown-file-name: ${{ github.ref_name == 'main' && env.BREAKDOWN_FILE || '' }}
           diff-base-breakdown-file-name: ${{ steps.download-base-coverage.outcome == 'success' && env.BREAKDOWN_FILE || '' }}
-          
+
       - name: Upload base.coverage of main branch
         uses: actions/upload-artifact@v4
         if: github.ref_name == 'main'
@@ -124,7 +124,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: stable
+          go-version: "1.25.6"
 
       - name: Go BenchMark
         run: |
@@ -147,7 +147,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      
+
       - name: Check modified files in submodules
         id: check-mods
         run: |

adk/backend/agentkit/sandbox.go

@@ -104,7 +104,7 @@ type Config struct {
 	ExecutionTimeout int
 }
 
-type sandboxToolBackend struct {
+type SandboxTool struct {
 	secretAccessKey  string
 	accessKeyID      string
 	baseURL          string
@@ -117,14 +117,14 @@ type sandboxToolBackend struct {
 	executionTimeout int
 }
 
-// NewSandboxToolBackend creates a new sandboxToolBackend instance.
-// sandboxToolBackend refers to the sandbox running instance created by the sandbox tool in Volcengine.
+// NewSandboxToolBackend creates a new SandboxTool instance.
+// SandboxTool refers to the sandbox running instance created by the sandbox tool in Volcengine.
 // For creating a sandbox tool environment, please refer to: https://www.volcengine.com/docs/86681/1847934?lang=zh;
 // For creating a sandbox tool running instance, please refer to: https://www.volcengine.com/docs/86681/1860266?lang=zh.
 // Note: The execution paths within the sandbox environment may be subject to permission restrictions (read, write, execute, etc.).
 // Improper path selection can result in operation failures or permission errors.
 // It is recommended to perform operations within paths where the sandbox environment has explicit permissions to mitigate permission-related risks.
-func NewSandboxToolBackend(config *Config) (filesystem.Backend, error) {
+func NewSandboxToolBackend(config *Config) (*SandboxTool, error) {
 	if config.AccessKeyID == "" {
 		return nil, fmt.Errorf("AccessKeyID is required")
 	}
@@ -159,7 +159,7 @@ func NewSandboxToolBackend(config *Config) (filesystem.Backend, error) {
 		return nil, fmt.Errorf("invalid region: %s", region)
 	}
 
-	return &sandboxToolBackend{
+	return &SandboxTool{
 		accessKeyID:      config.AccessKeyID,
 		secretAccessKey:  config.SecretAccessKey,
 		httpClient:       httpClient,
@@ -174,7 +174,7 @@ func NewSandboxToolBackend(config *Config) (filesystem.Backend, error) {
 }
 
 // LsInfo lists file information under the given path.
-func (s *sandboxToolBackend) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]filesystem.FileInfo, error) {
+func (s *SandboxTool) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]filesystem.FileInfo, error) {
 	path, err := formatPath(req.Path, "/", true)
 	if err != nil {
 		return nil, err
@@ -216,7 +216,7 @@ func (s *sandboxToolBackend) LsInfo(ctx context.Context, req *filesystem.LsInfoR
 }
 
 // Read reads file content with support for line-based offset and limit.
-func (s *sandboxToolBackend) Read(ctx context.Context, req *filesystem.ReadRequest) (string, error) {
+func (s *SandboxTool) Read(ctx context.Context, req *filesystem.ReadRequest) (string, error) {
 	path, err := formatPath(req.FilePath, "", true)
 	if err != nil {
 		return "", err
@@ -251,7 +251,7 @@ func (s *sandboxToolBackend) Read(ctx context.Context, req *filesystem.ReadReque
 }
 
 // GrepRaw searches for content matching the specified pattern in files.
-func (s *sandboxToolBackend) GrepRaw(ctx context.Context, req *filesystem.GrepRequest) ([]filesystem.GrepMatch, error) {
+func (s *SandboxTool) GrepRaw(ctx context.Context, req *filesystem.GrepRequest) ([]filesystem.GrepMatch, error) {
 	path, _ := formatPath(req.Path, "", false)
 	params := map[string]any{
 		"pattern":      req.Pattern,
@@ -292,7 +292,7 @@ func (s *sandboxToolBackend) GrepRaw(ctx context.Context, req *filesystem.GrepRe
 }
 
 // GlobInfo returns file information matching the glob pattern.
-func (s *sandboxToolBackend) GlobInfo(ctx context.Context, req *filesystem.GlobInfoRequest) ([]filesystem.FileInfo, error) {
+func (s *SandboxTool) GlobInfo(ctx context.Context, req *filesystem.GlobInfoRequest) ([]filesystem.FileInfo, error) {
 	path, _ := formatPath(req.Path, "/", false)
 	params := map[string]any{
 		"path_b64":    base64.StdEncoding.EncodeToString([]byte(path)),
@@ -330,7 +330,7 @@ func (s *sandboxToolBackend) GlobInfo(ctx context.Context, req *filesystem.GlobI
 }
 
 // Write creates file content.
-func (s *sandboxToolBackend) Write(ctx context.Context, req *filesystem.WriteRequest) error {
+func (s *SandboxTool) Write(ctx context.Context, req *filesystem.WriteRequest) error {
 	path, err := formatPath(req.FilePath, "", true)
 	if err != nil {
 		return err
@@ -358,7 +358,7 @@ func (s *sandboxToolBackend) Write(ctx context.Context, req *filesystem.WriteReq
 }
 
 // Edit replaces string occurrences in a file.
-func (s *sandboxToolBackend) Edit(ctx context.Context, req *filesystem.EditRequest) error {
+func (s *SandboxTool) Edit(ctx context.Context, req *filesystem.EditRequest) error {
 	path, err := formatPath(req.FilePath, "", true)
 	if err != nil {
 		return err
@@ -401,7 +401,7 @@ func (s *sandboxToolBackend) Edit(ctx context.Context, req *filesystem.EditReque
 }
 
 // execute executes a command in the sandbox.
-func (s *sandboxToolBackend) execute(ctx context.Context, command string) (text string, exitCode *int, err error) {
+func (s *SandboxTool) execute(ctx context.Context, command string) (text string, exitCode *int, err error) {
 	var operationPayload string
 	if s.executionTimeout <= 0 {
 		operationPayload, err = sonic.MarshalString(map[string]any{
@@ -473,7 +473,7 @@ func (s *sandboxToolBackend) execute(ctx context.Context, command string) (text
 	return text, exitCode, nil
 }
 
-func (s *sandboxToolBackend) invokeTool(ctx context.Context, method string, body []byte) ([]byte, error) {
+func (s *SandboxTool) invokeTool(ctx context.Context, method string, body []byte) ([]byte, error) {
 	queries := make(url.Values)
 	queries.Set("Action", "InvokeTool")
 	queries.Set("Version", "2025-10-30")
@@ -506,7 +506,7 @@ func (s *sandboxToolBackend) invokeTool(ctx context.Context, method string, body
 	return responseBody, nil
 }
 
-func (s *sandboxToolBackend) signRequest(request *http.Request, queries url.Values, body []byte) {
+func (s *SandboxTool) signRequest(request *http.Request, queries url.Values, body []byte) {
 	now := time.Now()
 	date := now.UTC().Format("20060102T150405Z")
 	authDate := date[:8]
@@ -558,7 +558,7 @@ func (s *sandboxToolBackend) signRequest(request *http.Request, queries url.Valu
 	request.Header.Set("Authorization", authorization)
 }
 
-func (s *sandboxToolBackend) Execute(ctx context.Context, input *filesystem.ExecuteRequest) (result *filesystem.ExecuteResponse, err error) {
+func (s *SandboxTool) Execute(ctx context.Context, input *filesystem.ExecuteRequest) (result *filesystem.ExecuteResponse, err error) {
 	if input.Command == "" {
 		return nil, fmt.Errorf("command is required")
 	}

adk/backend/agentkit/sandbox_test.go

@@ -40,8 +40,8 @@ func TestNewArkSandbox(t *testing.T) {
 			SessionTTL:       3600,
 			ExecutionTimeout: 60,
 		}
-		ss, err := NewSandboxToolBackend(config)
-		s := ss.(*sandboxToolBackend)
+		s, err := NewSandboxToolBackend(config)
+
 		require.NoError(t, err)
 		require.NotNil(t, s)
 		assert.Equal(t, "test-ak", s.accessKeyID)
@@ -61,8 +61,8 @@ func TestNewArkSandbox(t *testing.T) {
 			ToolID:          "test-tool",
 			UserSessionID:   "test-session",
 		}
-		ss, err := NewSandboxToolBackend(config)
-		s := ss.(*sandboxToolBackend)
+		s, err := NewSandboxToolBackend(config)
+
 		require.NoError(t, err)
 		require.NotNil(t, s)
 		assert.Equal(t, RegionOfBeijing, s.region)
@@ -115,7 +115,7 @@ func TestNewArkSandbox(t *testing.T) {
 var mockAPIHandler http.HandlerFunc
 
 // setupTest creates a mock server and an ArkSandbox client configured to use it.
-func setupTest(t *testing.T) (*sandboxToolBackend, *httptest.Server) {
+func setupTest(t *testing.T) (*SandboxTool, *httptest.Server) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if mockAPIHandler != nil {
 			mockAPIHandler(w, r)
@@ -131,8 +131,7 @@ func setupTest(t *testing.T) (*sandboxToolBackend, *httptest.Server) {
 		UserSessionID:   "test-session",
 		HTTPClient:      server.Client(),
 	}
-	ss, err := NewSandboxToolBackend(config)
-	sandbox := ss.(*sandboxToolBackend)
+	sandbox, err := NewSandboxToolBackend(config)
 	require.NoError(t, err)
 	sandbox.baseURL = server.URL // Override to point to the mock server
 

adk/backend/local/examples/middlewares/main.go

@@ -35,14 +35,14 @@ func main() {
 	ctx := context.Background()
 
 	fmt.Println("========================================")
-	fmt.Println("Local Backend Middleware Example")
+	fmt.Println("Local Local Middleware Example")
 	fmt.Println("========================================")
 	fmt.Println()
 
 	// ========================================
-	// Step 1: Initialize Local Backend
+	// Step 1: Initialize Local Local
 	// ========================================
-	fmt.Println("Step 1: Initializing Local Backend...")
+	fmt.Println("Step 1: Initializing Local Local...")
 
 	// The local backend operates directly on the local filesystem
 	// Optionally provide ValidateCommand for Execute() method security
@@ -53,7 +53,7 @@ func main() {
 		log.Fatalf("✗ Failed to create LocalBackend: %v", err)
 	}
 
-	fmt.Println("✓ Local Backend initialized")
+	fmt.Println("✓ Local Local initialized")
 	fmt.Println()
 
 	// ========================================
@@ -69,7 +69,7 @@ func main() {
 	defer os.RemoveAll(tempDir)
 
 	testFilePath := filepath.Join(tempDir, "example_file.txt")
-	testContent := "Hello from Local Backend!\nThis is a test for file operations.\n"
+	testContent := "Hello from Local Local!\nThis is a test for file operations.\n"
 
 	err = backend.Write(ctx, &filesystem.WriteRequest{
 		FilePath: testFilePath,

adk/backend/local/go.sum

@@ -16,10 +16,6 @@ github.com/bytedance/sonic/loader v0.3.0/go.mod h1:N8A3vUdtUebEY2/VQC0MyhYeKUFos
 github.com/certifi/gocertifi v0.0.0-20190105021004-abcd57078448/go.mod h1:GJKEexRPVJrBSOjoqN5VNOIKJ5Q3RViH6eu3puDRwx4=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
-github.com/cloudwego/eino v0.7.19 h1:KoA3KHoZ3adQI0nvC0EBR7tpeu/Ks69n+baRMOQGLqA=
-github.com/cloudwego/eino v0.7.19/go.mod h1:nA8Vacmuqv3pqKBQbTWENBLQ8MmGmPt/WqiyLeB8ohQ=
-github.com/cloudwego/eino v0.7.26 h1:FD8xnhd8WyV495eJs0Rka8aHnknqj/ljq3ZbwGH/SiQ=
-github.com/cloudwego/eino v0.7.26/go.mod h1:nA8Vacmuqv3pqKBQbTWENBLQ8MmGmPt/WqiyLeB8ohQ=
 github.com/cloudwego/eino v0.7.27 h1:pHxpvpQjAqez+yPgxxX0V298YmJd5cDQqCBAn8XnJYo=
 github.com/cloudwego/eino v0.7.27/go.mod h1:nA8Vacmuqv3pqKBQbTWENBLQ8MmGmPt/WqiyLeB8ohQ=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

adk/backend/local/local.go

@@ -40,22 +40,22 @@ type Config struct {
 	ValidateCommand func(string) error
 }
 
-type backend struct {
+type Local struct {
 	validateCommand func(string) error
 }
 
 var defaultValidateCommand = func(string) error {
 	return nil
 }
 
-// NewBackend creates a new local filesystem backend instance.
+// NewBackend creates a new local filesystem Local instance.
 //
 // IMPORTANT - System Compatibility:
 //   - Supported: Unix/MacOS only
-//   - NOT Supported: Windows (requires custom implementation of Backend)
+//   - NOT Supported: Windows (requires custom implementation of filesystem.Backend)
 //   - Command Execution: Uses /bin/sh by default for Execute method
-//   - If /bin/sh does not meet your requirements, please implement your own Backend
-func NewBackend(_ context.Context, cfg *Config) (filesystem.Backend, error) {
+//   - If /bin/sh does not meet your requirements, please implement your own filesystem.Backend
+func NewBackend(_ context.Context, cfg *Config) (*Local, error) {
 	if cfg == nil {
 		return nil, errors.New("config is required")
 	}
@@ -65,12 +65,12 @@ func NewBackend(_ context.Context, cfg *Config) (filesystem.Backend, error) {
 		validateCommand = cfg.ValidateCommand
 	}
 
-	return &backend{
+	return &Local{
 		validateCommand: validateCommand,
 	}, nil
 }
 
-func (s *backend) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]filesystem.FileInfo, error) {
+func (s *Local) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]filesystem.FileInfo, error) {
 	if req.Path == "" {
 		req.Path = defaultRootPath
 	}
@@ -105,7 +105,7 @@ func (s *backend) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]
 	return files, nil
 }
 
-func (s *backend) Read(ctx context.Context, req *filesystem.ReadRequest) (string, error) {
+func (s *Local) Read(ctx context.Context, req *filesystem.ReadRequest) (string, error) {
 	path := filepath.Clean(req.FilePath)
 	if !filepath.IsAbs(path) {
 		return "", fmt.Errorf("path must be an absolute path: %s", path)
@@ -160,7 +160,7 @@ func (s *backend) Read(ctx context.Context, req *filesystem.ReadRequest) (string
 	return result.String(), nil
 }
 
-func (s *backend) GrepRaw(ctx context.Context, req *filesystem.GrepRequest) ([]filesystem.GrepMatch, error) {
+func (s *Local) GrepRaw(ctx context.Context, req *filesystem.GrepRequest) ([]filesystem.GrepMatch, error) {
 	path := filepath.Clean(req.Path)
 
 	var matches []filesystem.GrepMatch
@@ -232,7 +232,7 @@ func (s *backend) GrepRaw(ctx context.Context, req *filesystem.GrepRequest) ([]f
 	return matches, nil
 }
 
-func (s *backend) GlobInfo(ctx context.Context, req *filesystem.GlobInfoRequest) ([]filesystem.FileInfo, error) {
+func (s *Local) GlobInfo(ctx context.Context, req *filesystem.GlobInfoRequest) ([]filesystem.FileInfo, error) {
 	if req.Path == "" {
 		req.Path = defaultRootPath
 	}
@@ -337,7 +337,7 @@ func globToRegex(pattern string) (*regexp.Regexp, error) {
 	return regexp.Compile(pattern)
 }
 
-func (s *backend) Write(ctx context.Context, req *filesystem.WriteRequest) error {
+func (s *Local) Write(ctx context.Context, req *filesystem.WriteRequest) error {
 	if !filepath.IsAbs(req.FilePath) {
 		return fmt.Errorf("path must be an absolute path: %s", req.FilePath)
 	}
@@ -364,7 +364,7 @@ func (s *backend) Write(ctx context.Context, req *filesystem.WriteRequest) error
 	return nil
 }
 
-func (s *backend) Edit(ctx context.Context, req *filesystem.EditRequest) error {
+func (s *Local) Edit(ctx context.Context, req *filesystem.EditRequest) error {
 	path := filepath.Clean(req.FilePath)
 	if !filepath.IsAbs(path) {
 		return fmt.Errorf("path must be an absolute path: %s", path)
@@ -403,7 +403,7 @@ func (s *backend) Edit(ctx context.Context, req *filesystem.EditRequest) error {
 	return os.WriteFile(path, []byte(newText), 0644)
 }
 
-func (s *backend) ExecuteStreaming(ctx context.Context, input *filesystem.ExecuteRequest) (result *schema.StreamReader[*filesystem.ExecuteResponse], err error) {
+func (s *Local) ExecuteStreaming(ctx context.Context, input *filesystem.ExecuteRequest) (result *schema.StreamReader[*filesystem.ExecuteResponse], err error) {
 	if input.Command == "" {
 		return nil, fmt.Errorf("command is required")
 	}