feat: add HostTools API to Go ADK for SDK-registered custom tools

Add HostToolDef and ToolHandlerFunc types to the ADK so users can
declaratively register custom tools with auto-dispatch handlers.
The agent intercepts host tool calls from the harness, invokes the
registered handler, and sends results back automatically.

Key changes:
- HostToolDef type with Name, Description, Parameters, Handler fields
- ToolHandlerFunc signature: func(ctx, args) (any, error)
- Validation: reject duplicate names, built-in name collisions, nil handlers
- Auto-dispatch in Agent.processStep via handleHostToolCall
- buildHarnessConfig translates HostTools to proto host_tools
- IsHostToolCall flag on connection.Step for detection
- 8 new tests (3 dispatch + 5 validation)
- adk-host-tools example with get_weather and convert_units tools
- Updated docs/adding-tools.md with Go ADK section

Author: ngoyal16

adk/agent.go

@@ -38,7 +38,8 @@ type Agent struct {
 	logger         *slog.Logger
 	started        bool
 	totalTokens    int
-	seenUsageSteps map[int32]bool // tracks step indices whose Usage has been counted
+	seenUsageSteps map[int32]bool           // tracks step indices whose Usage has been counted
+	toolHandlers   map[string]ToolHandlerFunc // host tool name → handler
 }
 
 // NewAgent creates a new Agent with the given configuration.
@@ -89,12 +90,19 @@ func NewAgent(config *LocalAgentConfig) (*Agent, error) {
 	// Build middleware chain
 	mwChain := middleware.NewChain(logger, config.Middlewares...)
 
+	// Build host tool handler map
+	toolHandlers := make(map[string]ToolHandlerFunc, len(config.HostTools))
+	for _, ht := range config.HostTools {
+		toolHandlers[ht.Name] = ht.Handler
+	}
+
 	return &Agent{
 		config:         config,
 		hookRunner:     runner,
 		mwChain:        mwChain,
 		logger:         logger,
 		seenUsageSteps: make(map[int32]bool),
+		toolHandlers:   toolHandlers,
 	}, nil
 }
 
@@ -545,6 +553,11 @@ func (a *Agent) processStep(ctx context.Context, step connection.Step) Step {
 		a.handleQuestionRequest(ctx, step)
 	}
 
+	// Handle host tool calls — auto-dispatch to registered handlers
+	if step.IsHostToolCall && step.State == connection.StateWaiting {
+		a.handleHostToolCall(ctx, step)
+	}
+
 	return result
 }
 
@@ -628,7 +641,57 @@ func (a *Agent) handleQuestionRequest(ctx context.Context, step connection.Step)
 	}
 }
 
-// Close shuts down the agent, releasing all resources.
+// handleHostToolCall dispatches a host tool call to the registered handler
+// and sends the result back to the harness.
+func (a *Agent) handleHostToolCall(ctx context.Context, step connection.Step) {
+	stepID := fmt.Sprintf("%d", step.Index)
+	toolName := step.ToolName
+
+	handler, ok := a.toolHandlers[toolName]
+	if !ok {
+		a.logger.Error("no handler registered for host tool", "tool", toolName)
+		a.conn.SendToolResult(ctx, stepID, toolName,
+			fmt.Sprintf(`{"error": "no handler registered for tool %q"}`, toolName), true)
+		return
+	}
+
+	// Parse tool arguments
+	var args map[string]any
+	if step.ToolArgsJSON != "" {
+		if err := json.Unmarshal([]byte(step.ToolArgsJSON), &args); err != nil {
+			a.logger.Error("failed to parse host tool args", "tool", toolName, "error", err)
+			a.conn.SendToolResult(ctx, stepID, toolName,
+				fmt.Sprintf(`{"error": "failed to parse arguments: %s"}`, err), true)
+			return
+		}
+	}
+
+	// Call the handler
+	result, err := handler(ctx, args)
+	if err != nil {
+		a.logger.Warn("host tool handler returned error", "tool", toolName, "error", err)
+		a.conn.SendToolResult(ctx, stepID, toolName,
+			fmt.Sprintf(`{"error": %q}`, err.Error()), true)
+		return
+	}
+
+	// Marshal the result
+	resultJSON, err := json.Marshal(result)
+	if err != nil {
+		a.logger.Error("failed to marshal host tool result", "tool", toolName, "error", err)
+		a.conn.SendToolResult(ctx, stepID, toolName,
+			fmt.Sprintf(`{"error": "failed to marshal result: %s"}`, err), true)
+		return
+	}
+
+	if err := a.conn.SendToolResult(ctx, stepID, toolName, string(resultJSON), false); err != nil {
+		a.logger.Error("failed to send host tool result",
+			"tool", toolName,
+			"error", err,
+		)
+	}
+}
+
 func (a *Agent) Close() error {
 	a.logger.Debug("closing agent session")
 	if a.started {
@@ -741,6 +804,16 @@ func buildHarnessConfig(cfg *LocalAgentConfig) *pb.HarnessConfig {
 		}
 	}
 
+	// Host tools — SDK-registered custom tools forwarded to SDK handlers
+	for _, ht := range cfg.HostTools {
+		schemaJSON, _ := json.Marshal(ht.Parameters)
+		harnessCfg.HostTools = append(harnessCfg.HostTools, &pb.ToolDef{
+			Name:                 ht.Name,
+			Description:          ht.Description,
+			ParametersJsonSchema: string(schemaJSON),
+		})
+	}
+
 	// Slash command definitions (sent alongside PromptModules)
 	for _, cmd := range cfg.SlashCommands {
 		harnessCfg.SlashCommands = append(harnessCfg.SlashCommands, &pb.SlashCommandDef{

adk/config.go

@@ -28,6 +28,12 @@ type LocalAgentConfig struct {
 	// Capabilities controls which built-in tools are available.
 	Capabilities CapabilitiesConfig
 
+	// HostTools defines custom tools that execute on the SDK side.
+	// When the LLM calls a host tool, the harness forwards it to the
+	// registered handler and feeds the result back to the LLM.
+	// Tool names must be unique and must not collide with built-in harness tools.
+	HostTools []HostToolDef
+
 	// Policies is the list of tool call policies. Evaluated in priority order.
 	// Default: policy.ConfirmRunCommand()
 	Policies []policy.Policy
@@ -379,5 +385,66 @@ func (c *LocalAgentConfig) Validate() error {
 		}
 	}
 
+	// Validate host tools: no nil handlers, no duplicates, no built-in name collisions.
+	if err := validateHostTools(c.HostTools); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// reservedToolNames is the set of built-in harness tool names.
+// Host tools cannot use these names — harness tools always have priority.
+var reservedToolNames = map[string]bool{
+	"view_file":                  true,
+	"write_to_file":              true,
+	"replace_file_content":       true,
+	"multi_replace_file_content": true,
+	"list_dir":                   true,
+	"grep_search":                true,
+	"find_file":                  true,
+	"run_command":                true,
+	"manage_task":                true,
+	"finish":                     true,
+	"ask_question":               true,
+	"ask_permission":             true,
+	"list_permissions":           true,
+	"search_web":                 true,
+	"read_url_content":           true,
+	"schedule":                   true,
+	"invoke_subagent":            true,
+	"define_subagent":            true,
+	"manage_subagents":           true,
+	"send_message":               true,
+	"knowledge_read":             true,
+	"knowledge_write":            true,
+	"publish":                    true,
+}
+
+// validateHostTools checks host tool definitions for errors:
+//   - Each tool must have a non-empty name and a non-nil handler.
+//   - Tool names must not collide with built-in harness tools.
+//   - Tool names must be unique (no duplicates).
+func validateHostTools(tools []HostToolDef) error {
+	if len(tools) == 0 {
+		return nil
+	}
+
+	seen := make(map[string]bool, len(tools))
+	for _, ht := range tools {
+		if ht.Name == "" {
+			return fmt.Errorf("host tool has empty name")
+		}
+		if ht.Handler == nil {
+			return fmt.Errorf("host tool %q has nil handler", ht.Name)
+		}
+		if reservedToolNames[ht.Name] {
+			return fmt.Errorf("host tool %q conflicts with a built-in harness tool", ht.Name)
+		}
+		if seen[ht.Name] {
+			return fmt.Errorf("duplicate host tool name: %q", ht.Name)
+		}
+		seen[ht.Name] = true
+	}
 	return nil
 }

adk/config_test.go

@@ -1,6 +1,7 @@
 package adk
 
 import (
+	"context"
 	"strings"
 	"testing"
 
@@ -153,6 +154,96 @@ func TestValidate_EmptyPolicies_NoWriteTools_Accepted(t *testing.T) {
 	}
 }
 
+// --- Host Tool Validation Tests ---
+
+func dummyHandler(ctx context.Context, args map[string]any) (any, error) {
+	return nil, nil
+}
+
+func TestValidate_HostTools_Valid(t *testing.T) {
+	cfg := &LocalAgentConfig{
+		GeminiAPIKey: "key",
+		HostTools: []HostToolDef{
+			{Name: "get_weather", Description: "Weather", Handler: dummyHandler},
+			{Name: "query_db", Description: "Database", Handler: dummyHandler},
+		},
+	}
+	err := cfg.Validate()
+	if err != nil {
+		t.Fatalf("expected valid host tools to pass, got: %v", err)
+	}
+}
+
+func TestValidate_HostTools_DuplicateName(t *testing.T) {
+	cfg := &LocalAgentConfig{
+		GeminiAPIKey: "key",
+		HostTools: []HostToolDef{
+			{Name: "get_weather", Description: "Weather", Handler: dummyHandler},
+			{Name: "get_weather", Description: "Weather dupe", Handler: dummyHandler},
+		},
+	}
+	err := cfg.Validate()
+	if err == nil {
+		t.Fatal("expected error for duplicate host tool name")
+	}
+	if !strings.Contains(err.Error(), "duplicate host tool name") {
+		t.Errorf("expected 'duplicate host tool name' error, got: %v", err)
+	}
+}
+
+func TestValidate_HostTools_BuiltinCollision(t *testing.T) {
+	builtins := []string{"view_file", "run_command", "grep_search", "finish", "ask_question", "schedule"}
+	for _, name := range builtins {
+		t.Run(name, func(t *testing.T) {
+			cfg := &LocalAgentConfig{
+				GeminiAPIKey: "key",
+				HostTools: []HostToolDef{
+					{Name: name, Description: "Collision", Handler: dummyHandler},
+				},
+			}
+			err := cfg.Validate()
+			if err == nil {
+				t.Fatalf("expected error for built-in name collision: %s", name)
+			}
+			if !strings.Contains(err.Error(), "conflicts with a built-in harness tool") {
+				t.Errorf("expected 'conflicts with a built-in harness tool' error, got: %v", err)
+			}
+		})
+	}
+}
+
+func TestValidate_HostTools_NilHandler(t *testing.T) {
+	cfg := &LocalAgentConfig{
+		GeminiAPIKey: "key",
+		HostTools: []HostToolDef{
+			{Name: "broken_tool", Description: "No handler"},
+		},
+	}
+	err := cfg.Validate()
+	if err == nil {
+		t.Fatal("expected error for nil handler")
+	}
+	if !strings.Contains(err.Error(), "nil handler") {
+		t.Errorf("expected 'nil handler' error, got: %v", err)
+	}
+}
+
+func TestValidate_HostTools_EmptyName(t *testing.T) {
+	cfg := &LocalAgentConfig{
+		GeminiAPIKey: "key",
+		HostTools: []HostToolDef{
+			{Name: "", Description: "No name", Handler: dummyHandler},
+		},
+	}
+	err := cfg.Validate()
+	if err == nil {
+		t.Fatal("expected error for empty name")
+	}
+	if !strings.Contains(err.Error(), "empty name") {
+		t.Errorf("expected 'empty name' error, got: %v", err)
+	}
+}
+
 // testDecideHook implements PreToolCallDecideHook for testing.
 type testDecideHook struct{}
 
@@ -162,3 +253,4 @@ func (h *testDecideHook) Run(ctx *hooks.HookContext, tc hooks.ToolCall) hooks.Ho
 
 // Verify it implements the interface
 var _ hooks.PreToolCallDecideHook = (*testDecideHook)(nil)
+

adk/connection/connection.go

@@ -148,6 +148,10 @@ type Step struct {
 
 	// ToolResultIsError indicates the tool returned an error result.
 	ToolResultIsError bool
+
+	// IsHostToolCall is true when this step is a host-side (SDK-registered)
+	// tool call that requires the SDK to execute and return a result.
+	IsHostToolCall bool
 }
 
 // UsageMetadata tracks token consumption for a model call.

adk/connection/local_connection.go

@@ -411,6 +411,7 @@ func (c *LocalConnection) handleStepUpdate(su *pb.StepUpdate) {
 		case *pb.StepUpdate_HostToolCall:
 			step.ToolName = a.HostToolCall.ToolName
 			step.ToolArgsJSON = a.HostToolCall.ArgsJson
+			step.IsHostToolCall = true
 		case *pb.StepUpdate_PermissionRequest:
 			step.PermissionRequestID = a.PermissionRequest.RequestId
 			step.PermissionToolName = a.PermissionRequest.ToolName