Merge pull request #927 from rumpl/feat-deferred

Add deferred tools

Author: dgageot

cagent-schema.json

@@ -432,6 +432,31 @@
           "type": "boolean",
           "description": "Whether to ignore VCS files (.git directories and .gitignore patterns) in filesystem operations. Default: true",
           "default": true
+        },
+        "defer": {
+          "description": "Enable deferred loading for tools in this toolset. Set to true to defer all tools, or an array of tool names to defer only those tools. Deferred tools are not loaded into the agent's context immediately, but can be discovered and loaded on-demand using search_tool and add_tool.",
+          "oneOf": [
+            {
+              "type": "boolean",
+              "description": "Set to true to defer all tools"
+            },
+            {
+              "type": "array",
+              "description": "Array of tool names to defer",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "examples": [
+            true,
+            ["read_file", "write_file"]
+          ]
+        },
+        "timeout": {
+          "type": "integer",
+          "description": "Timeout in seconds for the fetch tool",
+          "minimum": 1
         }
       },
       "additionalProperties": false,

examples/deferred.yaml

@@ -0,0 +1,12 @@
+#!/usr/bin/env cagent run
+
+agents:
+  root:
+    model: openai/gpt-4o
+    description: Simple agent with filesystem access
+    instruction: Use the tools to help the user with filesystem operations.
+    toolsets:
+      - type: filesystem
+        defer: true
+      - type: shell
+        defer: true

pkg/config/latest/types.go

@@ -121,6 +121,8 @@ type Toolset struct {
 	Instruction string   `json:"instruction,omitempty"`
 	Toon        string   `json:"toon,omitempty"`
 
+	Defer DeferConfig `json:"defer,omitempty" yaml:"defer,omitempty"`
+
 	// For the `mcp` tool
 	Command string   `json:"command,omitempty"`
 	Args    []string `json:"args,omitempty"`
@@ -168,6 +170,49 @@ type Remote struct {
 	Headers       map[string]string `json:"headers,omitempty"`
 }
 
+// DeferConfig represents the deferred loading configuration for a toolset.
+// It can be either a boolean (true to defer all tools) or a slice of strings
+// (list of tool names to defer).
+type DeferConfig struct {
+	// DeferAll is true when all tools should be deferred
+	DeferAll bool `json:"-"`
+	// Tools is the list of specific tool names to defer (empty if DeferAll is true)
+	Tools []string `json:"-"`
+}
+
+func (d DeferConfig) IsEmpty() bool {
+	return !d.DeferAll && len(d.Tools) == 0
+}
+
+func (d *DeferConfig) UnmarshalYAML(unmarshal func(any) error) error {
+	var b bool
+	if err := unmarshal(&b); err == nil {
+		d.DeferAll = b
+		d.Tools = nil
+		return nil
+	}
+
+	var tools []string
+	if err := unmarshal(&tools); err == nil {
+		d.DeferAll = false
+		d.Tools = tools
+		return nil
+	}
+
+	return nil
+}
+
+func (d DeferConfig) MarshalYAML() ([]byte, error) {
+	if d.DeferAll {
+		return yaml.Marshal(true)
+	}
+	if len(d.Tools) == 0 {
+		// Return false for empty config - this will be omitted by yaml encoder
+		return yaml.Marshal(false)
+	}
+	return yaml.Marshal(d.Tools)
+}
+
 // ThinkingBudget represents reasoning budget configuration.
 // It accepts either a string effort level or an integer token budget:
 // - String: "minimal", "low", "medium", "high" (for OpenAI)

pkg/teamloader/filter.go

@@ -8,6 +8,8 @@ import (
 	"github.com/docker/cagent/pkg/tools"
 )
 
+// WithToolsFilter creates a toolset that only includes the specified tools.
+// If no tool names are provided, all tools are included.
 func WithToolsFilter(inner tools.ToolSet, toolNames ...string) tools.ToolSet {
 	if len(toolNames) == 0 {
 		return inner
@@ -16,12 +18,28 @@ func WithToolsFilter(inner tools.ToolSet, toolNames ...string) tools.ToolSet {
 	return &filterTools{
 		ToolSet:   inner,
 		toolNames: toolNames,
+		exclude:   false,
+	}
+}
+
+// WithToolsExcludeFilter creates a toolset that excludes the specified tools.
+// If no tool names are provided, all tools are included.
+func WithToolsExcludeFilter(inner tools.ToolSet, toolNames ...string) tools.ToolSet {
+	if len(toolNames) == 0 {
+		return inner
+	}
+
+	return &filterTools{
+		ToolSet:   inner,
+		toolNames: toolNames,
+		exclude:   true,
 	}
 }
 
 type filterTools struct {
 	tools.ToolSet
 	toolNames []string
+	exclude   bool
 }
 
 func (f *filterTools) Tools(ctx context.Context) ([]tools.Tool, error) {
@@ -32,7 +50,11 @@ func (f *filterTools) Tools(ctx context.Context) ([]tools.Tool, error) {
 
 	var filtered []tools.Tool
 	for _, tool := range allTools {
-		if !slices.Contains(f.toolNames, tool.Name) {
+		contains := slices.Contains(f.toolNames, tool.Name)
+
+		// Exclude mode: keep only tools NOT in the list
+		// Include mode: keep only tools in the list
+		if (f.exclude && contains) || (!f.exclude && !contains) {
 			slog.Debug("Filtering out tool", "tool", tool.Name)
 			continue
 		}

pkg/teamloader/teamloader.go

@@ -284,6 +284,8 @@ func getToolsForAgent(ctx context.Context, a *latest.AgentConfig, parentDir stri
 		warnings []string
 	)
 
+	deferredToolset := builtin.NewDeferredToolset()
+
 	for i := range a.Toolsets {
 		toolset := a.Toolsets[i]
 
@@ -299,9 +301,25 @@ func getToolsForAgent(ctx context.Context, a *latest.AgentConfig, parentDir stri
 		wrapped = WithInstructions(wrapped, toolset.Instruction)
 		wrapped = WithToon(wrapped, toolset.Toon)
 
+		// Handle deferred tools
+		if !toolset.Defer.IsEmpty() {
+			deferredToolset.AddSource(wrapped, toolset.Defer.DeferAll, toolset.Defer.Tools)
+			if toolset.Defer.DeferAll {
+				// Don't add the wrapped toolset to toolSets - all its tools are deferred
+				// TODO: maybe we _do_ want to add this toolset since it has instructions?
+				continue
+			} else {
+				wrapped = WithToolsExcludeFilter(wrapped, toolset.Defer.Tools...)
+			}
+		}
+
 		toolSets = append(toolSets, wrapped)
 	}
 
+	if deferredToolset.HasSources() {
+		toolSets = append(toolSets, deferredToolset)
+	}
+
 	if len(a.SubAgents) > 0 {
 		toolSets = append(toolSets, builtin.NewTransferTaskTool())
 	}