Make tool choice a parameter of the agent

Signed-off-by: Djordje Lukic <djordje.lukic@docker.com>

Author: rumpl

agent-schema.json

@@ -365,6 +365,15 @@
           "type": "boolean",
           "description": "Whether to add a 'description' parameter to tool calls, allowing the LLM to provide context about why it is calling a tool"
         },
+        "tool_choice": {
+          "type": "string",
+          "description": "Controls how the model selects tools. 'auto' (default) lets the model decide, 'required' forces the model to always call a tool, 'none' prevents tool use.",
+          "enum": [
+            "auto",
+            "required",
+            "none"
+          ]
+        },
         "hooks": {
           "$ref": "#/definitions/HooksConfig",
           "description": "Lifecycle hooks for executing shell commands at various points in the agent's execution"

examples/tool_choice_required.yaml

@@ -0,0 +1,11 @@
+agents:
+  root:
+    model: anthropic/claude-opus-4-6
+    instruction: >
+      You are a coding agent. Use your tools to read, write, and modify files,
+      and to run shell commands. Always use tools to accomplish tasks rather than
+      just describing what to do.
+    tool_choice: required
+    toolsets:
+      - type: filesystem
+      - type: shell

pkg/agent/agent.go

@@ -32,6 +32,7 @@ type Agent struct {
 	addDate                 bool
 	addEnvironmentInfo      bool
 	addDescriptionParameter bool
+	toolChoice              string
 	maxIterations           int
 	maxConsecutiveToolCalls int
 	maxOldToolCallTokens    int
@@ -206,6 +207,11 @@ func (a *Agent) Hooks() *latest.HooksConfig {
 	return a.hooks
 }
 
+// ToolChoice returns the tool choice mode for this agent (e.g., "auto", "required", "none").
+func (a *Agent) ToolChoice() string {
+	return a.toolChoice
+}
+
 // Tools returns the tools available to this agent
 func (a *Agent) Tools(ctx context.Context) ([]tools.Tool, error) {
 	a.ensureToolSetsAreStarted(ctx)

pkg/agent/opts.go

@@ -115,6 +115,12 @@ func WithAddDescriptionParameter(addDescriptionParameter bool) Opt {
 	}
 }
 
+func WithToolChoice(toolChoice string) Opt {
+	return func(a *Agent) {
+		a.toolChoice = toolChoice
+	}
+}
+
 func WithAddPromptFiles(addPromptFiles []string) Opt {
 	return func(a *Agent) {
 		a.addPromptFiles = addPromptFiles

pkg/config/latest/types.go

@@ -366,6 +366,7 @@ type AgentConfig struct {
 	AddEnvironmentInfo      bool              `json:"add_environment_info,omitempty"`
 	CodeModeTools           bool              `json:"code_mode_tools,omitempty"`
 	AddDescriptionParameter bool              `json:"add_description_parameter,omitempty"`
+	ToolChoice              string            `json:"tool_choice,omitempty"`
 	MaxIterations           int               `json:"max_iterations,omitempty"`
 	MaxConsecutiveToolCalls int               `json:"max_consecutive_tool_calls,omitempty"`
 	MaxOldToolCallTokens    int               `json:"max_old_tool_call_tokens,omitempty"`

pkg/config/latest/validate.go

@@ -23,6 +23,11 @@ func (t *Config) validate() error {
 			return err
 		}
 
+		// Validate tool_choice
+		if err := agent.validateToolChoice(); err != nil {
+			return err
+		}
+
 		for j := range agent.Toolsets {
 			if err := agent.Toolsets[j].validate(); err != nil {
 				return err
@@ -38,6 +43,19 @@ func (t *Config) validate() error {
 	return nil
 }
 
+// validateToolChoice validates the tool_choice configuration for an agent
+func (a *AgentConfig) validateToolChoice() error {
+	if a.ToolChoice == "" {
+		return nil
+	}
+	switch a.ToolChoice {
+	case "auto", "required", "none":
+		return nil
+	default:
+		return errors.New("tool_choice must be one of: auto, required, none")
+	}
+}
+
 // validateFallback validates the fallback configuration for an agent
 func (a *AgentConfig) validateFallback() error {
 	if a.Fallback == nil {

pkg/config/latest/validate_test.go

@@ -115,3 +115,79 @@ agents:
 		})
 	}
 }
+
+func TestAgentConfig_Validate_ToolChoice(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		config  string
+		wantErr string
+	}{
+		{
+			name: "valid tool_choice auto",
+			config: `
+agents:
+  root:
+    model: "openai/gpt-4"
+    tool_choice: auto
+`,
+			wantErr: "",
+		},
+		{
+			name: "valid tool_choice required",
+			config: `
+agents:
+  root:
+    model: "openai/gpt-4"
+    tool_choice: required
+`,
+			wantErr: "",
+		},
+		{
+			name: "valid tool_choice none",
+			config: `
+agents:
+  root:
+    model: "openai/gpt-4"
+    tool_choice: none
+`,
+			wantErr: "",
+		},
+		{
+			name: "no tool_choice set",
+			config: `
+agents:
+  root:
+    model: "openai/gpt-4"
+`,
+			wantErr: "",
+		},
+		{
+			name: "invalid tool_choice value",
+			config: `
+agents:
+  root:
+    model: "openai/gpt-4"
+    tool_choice: force
+`,
+			wantErr: "tool_choice must be one of: auto, required, none",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var cfg Config
+			err := yaml.Unmarshal([]byte(tt.config), &cfg)
+
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}

pkg/model/provider/anthropic/beta_client.go

@@ -109,6 +109,19 @@ func (c *Client) createBetaStream(
 
 	if len(requestTools) > 0 {
 		slog.Debug("Anthropic Beta API: Adding tools to request", "tool_count", len(requestTools))
+
+		// Apply tool_choice from agent config
+		if toolChoice := c.ModelOptions.ToolChoice(); toolChoice != "" {
+			switch toolChoice {
+			case "required":
+				params.ToolChoice = anthropic.BetaToolChoiceUnionParam{OfAny: &anthropic.BetaToolChoiceAnyParam{}}
+			case "none":
+				params.ToolChoice = anthropic.BetaToolChoiceUnionParam{OfNone: &anthropic.BetaToolChoiceNoneParam{}}
+			default: // "auto" or any other value
+				params.ToolChoice = anthropic.BetaToolChoiceUnionParam{OfAuto: &anthropic.BetaToolChoiceAutoParam{}}
+			}
+			slog.Debug("Anthropic Beta API request using tool_choice", "tool_choice", toolChoice)
+		}
 	}
 
 	slog.Debug("Anthropic Beta API chat completion stream request",

pkg/model/provider/anthropic/client.go

@@ -330,6 +330,19 @@ func (c *Client) CreateChatCompletionStream(
 
 	if len(requestTools) > 0 {
 		slog.Debug("Adding tools to Anthropic request", "tool_count", len(requestTools))
+
+		// Apply tool_choice from agent config
+		if toolChoice := c.ModelOptions.ToolChoice(); toolChoice != "" {
+			switch toolChoice {
+			case "required":
+				params.ToolChoice = anthropic.ToolChoiceUnionParam{OfAny: &anthropic.ToolChoiceAnyParam{}}
+			case "none":
+				params.ToolChoice = anthropic.ToolChoiceUnionParam{OfNone: &anthropic.ToolChoiceNoneParam{}}
+			default: // "auto" or any other value
+				params.ToolChoice = anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}}
+			}
+			slog.Debug("Anthropic request using tool_choice", "tool_choice", toolChoice)
+		}
 	}
 
 	// Log the request details for debugging

pkg/model/provider/bedrock/client.go

@@ -249,7 +249,7 @@ func (c *Client) buildConverseStreamInput(messages []chat.Message, requestTools
 
 	// Convert and set tools
 	if len(requestTools) > 0 {
-		input.ToolConfig = convertToolConfig(requestTools, enableCaching)
+		input.ToolConfig = convertToolConfig(requestTools, enableCaching, c.ModelOptions.ToolChoice())
 	}
 
 	return input