feat(adk): deepagents support default filesystem tools

meguminnnnnnnnn · meguminnnnnnnnn · commit a015ab421d62 · 2026-02-05T21:58:45.000+08:00
diff --git a/adk/middlewares/filesystem/filesystem.go b/adk/middlewares/filesystem/filesystem.go
@@ -37,16 +37,19 @@ import (
 // Config is the configuration for the filesystem middleware
 type Config struct {
 	// Backend provides filesystem operations used by tools and offloading.
-	// required
+	// If set, filesystem tools (read_file, write_file, edit_file, glob, grep) will be registered.
+	// At least one of Backend, Shell, or StreamingShell must be set.
 	Backend filesystem.Backend
 
 	// Shell provides shell command execution capability.
 	// If set, an execute tool will be registered to support shell command execution.
-	// optional, mutually exclusive with StreamingShell
+	// At least one of Backend, Shell, or StreamingShell must be set.
+	// Mutually exclusive with StreamingShell.
 	Shell filesystem.Shell
 	// StreamingShell provides streaming shell command execution capability.
-	// If set, a streaming execute tool will be registered for real-time output.
-	// optional, mutually exclusive with Shell
+	// If set, a streaming execute tool will be registered to support streaming shell command execution.
+	// At least one of Backend, Shell, or StreamingShell must be set.
+	// Mutually exclusive with Shell.
 	StreamingShell filesystem.StreamingShell
 
 	// WithoutLargeToolResultOffloading disables automatic offloading of large tool result to Backend
@@ -90,8 +93,8 @@ func (c *Config) Validate() error {
 	if c == nil {
 		return errors.New("config should not be nil")
 	}
-	if c.Backend == nil {
-		return errors.New("backend should not be nil")
+	if c.Backend == nil && c.Shell == nil && c.StreamingShell == nil {
+		return errors.New("at least one of Backend, Shell, or StreamingShell must be set")
 	}
 	if c.StreamingShell != nil && c.Shell != nil {
 		return errors.New("shell and streaming shell should not be both set")
@@ -101,7 +104,7 @@ func (c *Config) Validate() error {
 
 // NewMiddleware constructs and returns the filesystem middleware.
 //
-// Deprecated: Use NewChatModelAgentMiddleware instead. NewChatModelAgentMiddleware returns
+// Deprecated: Use New instead. New returns
 // a ChatModelAgentMiddleware which provides better context propagation through wrapper methods
 // and is the recommended approach for new code. See ChatModelAgentMiddleware documentation
 // for details on the benefits over AgentMiddleware.
@@ -294,6 +297,27 @@ func (m *filesystemMiddleware) WrapStreamableToolCall(ctx context.Context, endpo
 
 func getFilesystemTools(_ context.Context, validatedConfig *Config) ([]tool.BaseTool, error) {
 	var tools []tool.BaseTool
+	var err error
+
+	if validatedConfig.StreamingShell != nil {
+		var executeTool tool.BaseTool
+		executeTool, err = newStreamingExecuteTool(validatedConfig.StreamingShell, validatedConfig.CustomExecuteToolDesc)
+		if err != nil {
+			return nil, err
+		}
+		tools = append(tools, executeTool)
+	} else if validatedConfig.Shell != nil {
+		var executeTool tool.BaseTool
+		executeTool, err = newExecuteTool(validatedConfig.Shell, validatedConfig.CustomExecuteToolDesc)
+		if err != nil {
+			return nil, err
+		}
+		tools = append(tools, executeTool)
+	}
+
+	if validatedConfig.Backend == nil {
+		return tools, nil
+	}
 
 	lsTool, err := newLsTool(validatedConfig.Backend, validatedConfig.CustomLsToolDesc)
 	if err != nil {
@@ -331,22 +355,6 @@ func getFilesystemTools(_ context.Context, validatedConfig *Config) ([]tool.Base
 	}
 	tools = append(tools, grepTool)
 
-	if validatedConfig.StreamingShell != nil {
-		var executeTool tool.BaseTool
-		executeTool, err = newStreamingExecuteTool(validatedConfig.StreamingShell, validatedConfig.CustomExecuteToolDesc)
-		if err != nil {
-			return nil, err
-		}
-		tools = append(tools, executeTool)
-	} else if validatedConfig.Shell != nil {
-		var executeTool tool.BaseTool
-		executeTool, err = newExecuteTool(validatedConfig.Shell, validatedConfig.CustomExecuteToolDesc)
-		if err != nil {
-			return nil, err
-		}
-		tools = append(tools, executeTool)
-	}
-
 	return tools, nil
 }
 
diff --git a/adk/middlewares/filesystem/filesystem_test.go b/adk/middlewares/filesystem/filesystem_test.go
@@ -532,7 +532,7 @@ func TestNewMiddleware(t *testing.T) {
 	t.Run("nil backend returns error", func(t *testing.T) {
 		_, err := NewMiddleware(ctx, &Config{Backend: nil})
 		assert.Error(t, err)
-		assert.Contains(t, err.Error(), "backend should not be nil")
+		assert.Contains(t, err.Error(), "at least one of Backend, Shell, or StreamingShell must be set")
 	})
 
 	t.Run("valid config with default settings", func(t *testing.T) {
@@ -649,7 +649,7 @@ func TestNew(t *testing.T) {
 	t.Run("nil backend returns error", func(t *testing.T) {
 		_, err := New(ctx, &Config{Backend: nil})
 		assert.Error(t, err)
-		assert.Contains(t, err.Error(), "backend should not be nil")
+		assert.Contains(t, err.Error(), "at least one of Backend, Shell, or StreamingShell must be set")
 	})
 
 	t.Run("valid config with default settings", func(t *testing.T) {
diff --git a/adk/prebuilt/deep/deep.go b/adk/prebuilt/deep/deep.go
@@ -24,9 +24,10 @@ import (
 	"github.com/bytedance/sonic"
 
 	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/adk/filesystem"
 	"github.com/cloudwego/eino/adk/internal"
+	filesystem2 "github.com/cloudwego/eino/adk/middlewares/filesystem"
 	"github.com/cloudwego/eino/components/model"
-	"github.com/cloudwego/eino/components/tool"
 	"github.com/cloudwego/eino/components/tool/utils"
 	"github.com/cloudwego/eino/schema"
 )
@@ -58,6 +59,10 @@ type Config struct {
 	// MaxIteration limits the maximum number of reasoning iterations the agent can perform.
 	MaxIteration int
 
+	Backend        filesystem.Backend
+	Shell          filesystem.Shell
+	StreamingShell filesystem.StreamingShell
+
 	// WithoutWriteTodos disables the built-in write_todos tool when set to true.
 	WithoutWriteTodos bool
 	// WithoutGeneralSubAgent disables the general-purpose subagent when set to true.
@@ -89,7 +94,7 @@ type Config struct {
 // This function initializes built-in tools, creates a task tool for subagent orchestration,
 // and returns a fully configured ChatModelAgent ready for execution.
 func New(ctx context.Context, cfg *Config) (adk.ResumableAgent, error) {
-	middlewares, err := buildBuiltinAgentMiddlewares(cfg.WithoutWriteTodos)
+	handlers, err := buildBuiltinAgentMiddlewares(ctx, cfg)
 	if err != nil {
 		return nil, err
 	}
@@ -116,12 +121,13 @@ func New(ctx context.Context, cfg *Config) (adk.ResumableAgent, error) {
 			instruction,
 			cfg.ToolsConfig,
 			cfg.MaxIteration,
-			append(middlewares, cfg.Middlewares...),
+			cfg.Middlewares,
+			append(handlers, cfg.Handlers...),
 		)
 		if err != nil {
 			return nil, fmt.Errorf("failed to new task tool: %w", err)
 		}
-		middlewares = append(middlewares, tt)
+		handlers = append(handlers, tt)
 	}
 
 	return adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
@@ -131,8 +137,8 @@ func New(ctx context.Context, cfg *Config) (adk.ResumableAgent, error) {
 		Model:         cfg.ChatModel,
 		ToolsConfig:   cfg.ToolsConfig,
 		MaxIterations: cfg.MaxIteration,
-		Middlewares:   append(middlewares, cfg.Middlewares...),
-		Handlers:      cfg.Handlers,
+		Middlewares:   cfg.Middlewares,
+		Handlers:      append(handlers, cfg.Handlers...),
 
 		GenModelInput:    genModelInput,
 		ModelRetryConfig: cfg.ModelRetryConfig,
@@ -152,16 +158,29 @@ func genModelInput(ctx context.Context, instruction string, input *adk.AgentInpu
 	return msgs, nil
 }
 
-func buildBuiltinAgentMiddlewares(withoutWriteTodos bool) ([]adk.AgentMiddleware, error) {
-	var ms []adk.AgentMiddleware
-	if !withoutWriteTodos {
+func buildBuiltinAgentMiddlewares(ctx context.Context, cfg *Config) ([]adk.ChatModelAgentMiddleware, error) {
+	var ms []adk.ChatModelAgentMiddleware
+	if !cfg.WithoutWriteTodos {
 		t, err := newWriteTodos()
 		if err != nil {
 			return nil, err
 		}
 		ms = append(ms, t)
 	}
 
+	if cfg.Backend != nil || cfg.Shell != nil || cfg.StreamingShell != nil {
+		fm, err := filesystem2.New(ctx, &filesystem2.Config{
+			Backend:                          cfg.Backend,
+			Shell:                            cfg.Shell,
+			StreamingShell:                   cfg.StreamingShell,
+			WithoutLargeToolResultOffloading: true,
+		})
+		if err != nil {
+			return nil, err
+		}
+		ms = append(ms, fm)
+	}
+
 	return ms, nil
 }
 
@@ -175,27 +194,27 @@ type writeTodosArguments struct {
 	Todos []TODO `json:"todos"`
 }
 
-func newWriteTodos() (adk.AgentMiddleware, error) {
+func newWriteTodos() (adk.ChatModelAgentMiddleware, error) {
 	toolDesc, err := internal.SelectPrompt(internal.I18nPrompts{
 		English: writeTodosToolDescription,
 		Chinese: writeTodosToolDescriptionChinese,
 	})
 	if err != nil {
-		return adk.AgentMiddleware{}, err
+		return nil, err
 	}
 	prompt, err := internal.SelectPrompt(internal.I18nPrompts{
 		English: writeTodosPrompt,
 		Chinese: writeTodosPromptChinese,
 	})
 	if err != nil {
-		return adk.AgentMiddleware{}, err
+		return nil, err
 	}
 	resultMsg, err := internal.SelectPrompt(internal.I18nPrompts{
 		English: "Updated todo list to %s",
 		Chinese: "已更新待办列表为 %s",
 	})
 	if err != nil {
-		return adk.AgentMiddleware{}, err
+		return nil, err
 	}
 
 	t, err := utils.InferTool("write_todos", toolDesc, func(ctx context.Context, input writeTodosArguments) (output string, err error) {
@@ -207,11 +226,8 @@ func newWriteTodos() (adk.AgentMiddleware, error) {
 		return fmt.Sprintf(resultMsg, todos), nil
 	})
 	if err != nil {
-		return adk.AgentMiddleware{}, err
+		return nil, err
 	}
 
-	return adk.AgentMiddleware{
-		AdditionalInstruction: prompt,
-		AdditionalTools:       []tool.BaseTool{t},
-	}, nil
+	return buildAppendPromptTool(prompt, t), nil
 }
diff --git a/adk/prebuilt/deep/deep_test.go b/adk/prebuilt/deep/deep_test.go
@@ -67,10 +67,10 @@ func TestGenModelInput(t *testing.T) {
 }
 
 func TestWriteTodos(t *testing.T) {
-	m, err := buildBuiltinAgentMiddlewares(false)
+	m, err := buildBuiltinAgentMiddlewares(context.Background(), &Config{WithoutWriteTodos: false})
 	assert.NoError(t, err)
 
-	wt := m[0].AdditionalTools[0].(tool.InvokableTool)
+	wt := m[0].(*appendPromptTool).t.(tool.InvokableTool)
 
 	todos := `[{"content":"content1","activeForm":"","status":"pending"},{"content":"content2","activeForm":"","status":"pending"}]`
 	args := fmt.Sprintf(`{"todos": %s}`, todos)
diff --git a/adk/prebuilt/deep/task_tool.go b/adk/prebuilt/deep/task_tool.go
@@ -44,23 +44,21 @@ func newTaskToolMiddleware(
 	toolsConfig adk.ToolsConfig,
 	maxIteration int,
 	middlewares []adk.AgentMiddleware,
-) (adk.AgentMiddleware, error) {
-	t, err := newTaskTool(ctx, taskToolDescriptionGenerator, subAgents, withoutGeneralSubAgent, cm, instruction, toolsConfig, maxIteration, middlewares)
+	handlers []adk.ChatModelAgentMiddleware,
+) (adk.ChatModelAgentMiddleware, error) {
+	t, err := newTaskTool(ctx, taskToolDescriptionGenerator, subAgents, withoutGeneralSubAgent, cm, instruction, toolsConfig, maxIteration, middlewares, handlers)
 	if err != nil {
-		return adk.AgentMiddleware{}, err
+		return nil, err
 	}
 	prompt, err := internal.SelectPrompt(internal.I18nPrompts{
 		English: taskPrompt,
 		Chinese: taskPromptChinese,
 	})
 	if err != nil {
-		return adk.AgentMiddleware{}, err
+		return nil, err
 	}
 
-	return adk.AgentMiddleware{
-		AdditionalInstruction: prompt,
-		AdditionalTools:       []tool.BaseTool{t},
-	}, nil
+	return buildAppendPromptTool(prompt, t), nil
 }
 
 func newTaskTool(
@@ -75,6 +73,7 @@ func newTaskTool(
 	ToolsConfig adk.ToolsConfig,
 	MaxIteration int,
 	middlewares []adk.AgentMiddleware,
+	handlers []adk.ChatModelAgentMiddleware,
 ) (tool.InvokableTool, error) {
 	t := &taskTool{
 		subAgents:     map[string]tool.InvokableTool{},
@@ -102,6 +101,7 @@ func newTaskTool(
 			ToolsConfig:   ToolsConfig,
 			MaxIterations: MaxIteration,
 			Middlewares:   middlewares,
+			Handlers:      handlers,
 			GenModelInput: genModelInput,
 		})
 		if err != nil {
diff --git a/adk/prebuilt/deep/task_tool_test.go b/adk/prebuilt/deep/task_tool_test.go
@@ -40,6 +40,7 @@ func TestTaskTool(t *testing.T) {
 		adk.ToolsConfig{},
 		10,
 		nil,
+		nil,
 	)
 	assert.NoError(t, err)
 
diff --git a/adk/prebuilt/deep/types.go b/adk/prebuilt/deep/types.go
@@ -17,8 +17,10 @@
 package deep
 
 import (
+	"context"
 	"fmt"
 
+	"github.com/cloudwego/eino/adk"
 	"github.com/cloudwego/eino/components/tool"
 )
 
@@ -38,3 +40,26 @@ func assertAgentTool(t tool.BaseTool) (tool.InvokableTool, error) {
 	}
 	return it, nil
 }
+
+func buildAppendPromptTool(prompt string, t tool.BaseTool) adk.ChatModelAgentMiddleware {
+	return &appendPromptTool{
+		BaseChatModelAgentMiddleware: &adk.BaseChatModelAgentMiddleware{},
+		t:                            t,
+		prompt:                       prompt,
+	}
+}
+
+type appendPromptTool struct {
+	*adk.BaseChatModelAgentMiddleware
+	t      tool.BaseTool
+	prompt string
+}
+
+func (w *appendPromptTool) BeforeAgent(ctx context.Context, runCtx *adk.ChatModelAgentContext) (context.Context, *adk.ChatModelAgentContext, error) {
+	nRunCtx := *runCtx
+	nRunCtx.Instruction += w.prompt
+	if w.t != nil {
+		nRunCtx.Tools = append(nRunCtx.Tools, w.t)
+	}
+	return ctx, &nRunCtx, nil
+}

Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,7 @@ func TestTaskTool(t *testing.T) {`
`40`	`40`	`adk.ToolsConfig{},`
`41`	`41`	`10,`
`42`	`42`	`nil,`
	`43`	`+ nil,`
`43`	`44`	`)`
`44`	`45`	`assert.NoError(t, err)`
`45`	`46`