refactor(adk): introduce AgentHandler interface for runtime agent customization

[shentongmartin]

Summary

This PR introduces a new AgentHandler interface to replace the struct-based AgentMiddleware approach, enabling runtime customization of agent behavior.

Motivation

The existing AgentMiddleware has fundamental limitations:

1. Static at creation time: Configuration is locked when the agent is created, preventing per-request customization
2. Append-only: Can only add instructions/tools, cannot remove or conditionally filter them
3. No context flow: Cannot propagate context values between middleware stages

These limitations block important use cases like:

• Per-user tool filtering based on permissions
• Dynamic instruction injection based on request context
• Conditional tool availability based on conversation state

Solution

New AgentHandler Interface

type AgentHandler interface {
    Name() string
    BeforeAgent(ctx context.Context, config *AgentConfig) (context.Context, error)
    BeforeModelRewriteHistory(ctx context.Context, messages []Message) (context.Context, []Message, error)
    AfterModelRewriteHistory(ctx context.Context, messages []Message) (context.Context, []Message, error)
    WrapInvokableToolCall(ctx, input, next) (*ToolCallResult, error)
    WrapStreamableToolCall(ctx, input, next) (*StreamToolCallResult, error)
}

Key design decisions:

• BeforeAgent runs at Run time, not creation time, enabling per-request customization
• AgentConfig is mutable, allowing handlers to modify instruction and tools
• Context propagation throughout the handler chain
• BaseAgentHandler provides default no-op implementations for easy composition

Example: Runtime Tool Filtering

agent, _ := NewChatModelAgent(ctx, &ChatModelAgentConfig{
    Handlers: []AgentHandler{
        WithToolsFunc(func(ctx context.Context, tools []ToolMeta) (context.Context, []ToolMeta, error) {
            if GetUserRole(ctx) != "admin" {
                return ctx, filterOutAdminTools(tools), nil
            }
            return ctx, tools, nil
        }),
    },
})

Convenience Helpers

• WithInstruction(text) / WithInstructionFunc(fn) - Modify instructions
• WithTools(tools...) / WithToolsFunc(fn) - Add/remove/filter tools
• WithBeforeModelRewriteHistory(fn) / WithAfterModelRewriteHistory(fn) - Rewrite message history
• WithInvokableToolCallWrapper(fn) / WithStreamableToolCallWrapper(fn) - Wrap tool calls

Backward Compatibility

AgentMiddleware now implements AgentHandler, so existing code continues to work unchanged.

[codecov]

Codecov Report

❌ Patch coverage is 80.86124% with 80 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.28%. Comparing base (d11713a) to head (6b7acb1).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
adk/chatmodel.go	80.00%	46 Missing and 21 partials ⚠️
adk/handler_helpers.go	84.78%	3 Missing and 4 partials ⚠️
adk/handler.go	66.66%	4 Missing ⚠️
adk/react.go	92.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #660      +/-   ##
==========================================
- Coverage   80.31%   80.28%   -0.03%     
==========================================
  Files         124      126       +2     
  Lines       11904    12181     +277     
==========================================
+ Hits         9561     9780     +219     
- Misses       1613     1653      +40     
- Partials      730      748      +18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.