10中间件与 Handler 的设计

// Deprecated: Use ChatModelAgentMiddleware (interface-based Handlers) instead.
// AgentMiddleware will be removed in a future release.
//
// AgentMiddleware provides hooks to customize agent behavior at various stages of execution.
type AgentMiddleware struct {
  // AdditionalInstruction adds supplementary text to the agent's system instruction.
  // This instruction is concatenated with the base instruction before each chat model call.
  AdditionalInstruction string

  // AdditionalTools adds supplementary tools to the agent's available toolset.
  // These tools are combined with the tools configured for the agent.
  AdditionalTools []tool.BaseTool

  // BeforeChatModel is called before each ChatModel invocation, allowing modification of the agent state.
  BeforeChatModel func(context.Context, *ChatModelAgentState) error

  // AfterChatModel is called after each ChatModel invocation, allowing modification of the agent state.
  AfterChatModel func(context.Context, *ChatModelAgentState) error

  // WrapToolCall wraps tool calls with custom middleware logic.
  // Each middleware contains Invokable and/or Streamable functions for tool calls.
  WrapToolCall compose.ToolMiddleware
}

// TypedChatModelAgentMiddleware defines the interface for customizing TypedChatModelAgent behavior.
//
// IMPORTANT: This interface is specifically designed for TypedChatModelAgent and agents built
// on top of it (e.g., DeepAgent).
//
// Why TypedChatModelAgentMiddleware instead of AgentMiddleware?
//
// AgentMiddleware is a struct type, which has inherent limitations:
//   - Struct types are closed: users cannot add new methods to extend functionality
//   - The framework only recognizes AgentMiddleware's fixed fields, so even if users
//     embed AgentMiddleware in a custom struct and add methods, the framework cannot
//     call those methods (config.Middlewares is []AgentMiddleware, not a user type)
//   - Callbacks in AgentMiddleware only return error, cannot return modified context
//
// TypedChatModelAgentMiddleware is an interface type, which is open for extension:
//   - Users can implement custom handlers with arbitrary internal state and methods
//   - Hook methods return (context.Context, ..., error) for direct context propagation
//   - Wrapper methods (WrapToolCall, WrapModel) enable context propagation through the
//     wrapped endpoint chain: wrappers can pass modified context to the next wrapper
//   - Configuration is centralized in struct fields rather than scattered in closures
//
// TypedChatModelAgentMiddleware vs AgentMiddleware:
//   - Use AgentMiddleware for simple, static additions (extra instruction/tools)
//   - Use TypedChatModelAgentMiddleware for dynamic behavior, context modification, or call wrapping
//   - AgentMiddleware is kept for backward compatibility with existing users
//   - Both can be used together; see AgentMiddleware documentation for execution order
//
// Use *TypedBaseChatModelAgentMiddleware as an embedded struct to provide default no-op
// implementations for all methods.
type TypedChatModelAgentMiddleware[M MessageType] interface {
  // BeforeAgent is called before each agent run, allowing modification of
  // the agent's instruction and tools configuration.
  BeforeAgent(ctx context.Context, runCtx *ChatModelAgentContext) (context.Context, *ChatModelAgentContext, error)

  // AfterAgent is called after the agent run reaches a successful terminal state.
  // Successful terminal states are: final answer (model response with no tool calls),
  // and return-directly tool result.
  //
  // AfterAgent is NOT called when the agent terminates with an error (e.g.,
  // ErrExceedMaxIterations, context cancellation, model errors).
  //
  // The state parameter contains the final conversation state, including all messages
  // from the completed run.
  //
  // AfterAgent handlers are called in the same order as BeforeAgent handlers
  // (first registered = first called). Consistent with all other middleware hooks,
  // if any handler returns an error, subsequent handlers are NOT called (fail-fast)
  // and the error is sent to the event stream.
// … 省略 98 行；完整声明 L110–255，点击上方「浏览完整文件」

// TypedChatModelAgentMiddleware defines the interface for customizing TypedChatModelAgent behavior.
//
// IMPORTANT: This interface is specifically designed for TypedChatModelAgent and agents built
// on top of it (e.g., DeepAgent).
//
// Why TypedChatModelAgentMiddleware instead of AgentMiddleware?
//
// AgentMiddleware is a struct type, which has inherent limitations:
//   - Struct types are closed: users cannot add new methods to extend functionality
//   - The framework only recognizes AgentMiddleware's fixed fields, so even if users
//     embed AgentMiddleware in a custom struct and add methods, the framework cannot
//     call those methods (config.Middlewares is []AgentMiddleware, not a user type)
//   - Callbacks in AgentMiddleware only return error, cannot return modified context
//
// TypedChatModelAgentMiddleware is an interface type, which is open for extension:
//   - Users can implement custom handlers with arbitrary internal state and methods
//   - Hook methods return (context.Context, ..., error) for direct context propagation
//   - Wrapper methods (WrapToolCall, WrapModel) enable context propagation through the
//     wrapped endpoint chain: wrappers can pass modified context to the next wrapper
//   - Configuration is centralized in struct fields rather than scattered in closures
//
// TypedChatModelAgentMiddleware vs AgentMiddleware:
//   - Use AgentMiddleware for simple, static additions (extra instruction/tools)
//   - Use TypedChatModelAgentMiddleware for dynamic behavior, context modification, or call wrapping
//   - AgentMiddleware is kept for backward compatibility with existing users
//   - Both can be used together; see AgentMiddleware documentation for execution order
//
// Use *TypedBaseChatModelAgentMiddleware as an embedded struct to provide default no-op
// … 这是 L110–137 的片段（该行不在任何顶层声明内）；点击上方「浏览完整文件」

// TypedChatModelAgentMiddleware defines the interface for customizing TypedChatModelAgent behavior.
//
// IMPORTANT: This interface is specifically designed for TypedChatModelAgent and agents built
// on top of it (e.g., DeepAgent).
//
// Why TypedChatModelAgentMiddleware instead of AgentMiddleware?
//
// AgentMiddleware is a struct type, which has inherent limitations:
//   - Struct types are closed: users cannot add new methods to extend functionality
//   - The framework only recognizes AgentMiddleware's fixed fields, so even if users
//     embed AgentMiddleware in a custom struct and add methods, the framework cannot
//     call those methods (config.Middlewares is []AgentMiddleware, not a user type)
//   - Callbacks in AgentMiddleware only return error, cannot return modified context
//
// TypedChatModelAgentMiddleware is an interface type, which is open for extension:
//   - Users can implement custom handlers with arbitrary internal state and methods
//   - Hook methods return (context.Context, ..., error) for direct context propagation
//   - Wrapper methods (WrapToolCall, WrapModel) enable context propagation through the
//     wrapped endpoint chain: wrappers can pass modified context to the next wrapper
//   - Configuration is centralized in struct fields rather than scattered in closures
//
// TypedChatModelAgentMiddleware vs AgentMiddleware:
//   - Use AgentMiddleware for simple, static additions (extra instruction/tools)
//   - Use TypedChatModelAgentMiddleware for dynamic behavior, context modification, or call wrapping
//   - AgentMiddleware is kept for backward compatibility with existing users
//   - Both can be used together; see AgentMiddleware documentation for execution order
//
// Use *TypedBaseChatModelAgentMiddleware as an embedded struct to provide default no-op
// implementations for all methods.
type TypedChatModelAgentMiddleware[M MessageType] interface {
  // BeforeAgent is called before each agent run, allowing modification of
  // the agent's instruction and tools configuration.
  BeforeAgent(ctx context.Context, runCtx *ChatModelAgentContext) (context.Context, *ChatModelAgentContext, error)

  // AfterAgent is called after the agent run reaches a successful terminal state.
// … 这是 L110–144 的片段（该行不在任何顶层声明内）；点击上方「浏览完整文件」

// TypedChatModelAgentConfig is the generic configuration for ChatModelAgent.
type TypedChatModelAgentConfig[M MessageType] struct {
  // Name of the agent. Better be unique across all agents.
  // Optional. If empty, the agent can still run standalone but cannot be used as
  // a sub-agent tool via NewAgentTool (which requires a non-empty Name).
  Name string
  // Description of the agent's capabilities.
  // Helps other agents determine whether to transfer tasks to this agent.
  // Optional. If empty, the agent can still run standalone but cannot be used as
  // a sub-agent tool via NewAgentTool (which requires a non-empty Description).
  Description string
  // Instruction used as the system prompt for this agent.
  // Optional. If empty, no system prompt will be used.
  // Supports f-string placeholders for session values in default GenModelInput, for example:
  // "You are a helpful assistant. The current time is {Time}. The current user is {User}."
  // These placeholders will be replaced with session values for "Time" and "User".
  Instruction string

  // Model is the chat model used by the agent.
  // If your ChatModelAgent uses any tools, this model must support the model.WithTools
  // call option, as that's how ChatModelAgent configures the model with tool information.
  Model model.BaseModel[M]

  ToolsConfig ToolsConfig

  // GenModelInput transforms instructions and input messages into the model's input format.
  // Optional. Defaults to defaultGenModelInput which combines instruction and messages.
  GenModelInput TypedGenModelInput[M]

  // Exit defines the tool used to terminate the agent process.
  // Optional. If nil, no Exit Action will be generated.
  // You can use the provided 'ExitTool' implementation directly.
  //
  // NOT RECOMMENDED: Agent transfer with full context sharing between agents has not proven
  // to be more effective empirically. Consider using ChatModelAgent with AgentTool
  // or DeepAgent instead for most multi-agent scenarios.
  Exit tool.BaseTool

  // OutputKey stores the agent's response in the session.
  // Optional. When set, stores output via AddSessionValue(ctx, outputKey, msg.Content).
  //
  // NOT RECOMMENDED: Agent transfer with full context sharing between agents has not proven
  // to be more effective empirically. Consider using ChatModelAgent with AgentTool
  // or DeepAgent instead for most multi-agent scenarios.
  OutputKey string

  // MaxIterations defines the upper limit of ChatModel generation cycles.
  // The agent will terminate with an error if this limit is exceeded.
// … 省略 109 行；完整声明 L259–415，点击上方「浏览完整文件」

// New constructs and returns the filesystem middleware as a ChatModelAgentMiddleware.
//
// This is the recommended constructor for new code. It returns a ChatModelAgentMiddleware which provides:
//   - Better context propagation through WrapInvokableToolCall and WrapStreamableToolCall methods
//   - BeforeAgent hook for modifying agent instruction and tools at runtime
//   - More flexible extension points compared to the struct-based AgentMiddleware
//
// The middleware provides filesystem tools (ls, read_file, write_file, edit_file, glob, grep)
// and optionally an execute tool if the Backend implements ShellBackend or StreamingShellBackend.
//
// Example usage:
//
//  middleware, err := filesystem.New(ctx, &filesystem.Config{
//      Backend: myBackend,
//  })
//  agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
//      // ...
//      Handlers: []adk.ChatModelAgentMiddleware{middleware},
//  })
func New(ctx context.Context, config *MiddlewareConfig) (adk.ChatModelAgentMiddleware, error) {
  return NewTyped[*schema.Message](ctx, config)
}