Design proposal: ToolboxClient middleware / hooks for interceptors

[Deeven-Seru]

Prerequisites

• Search the current open issues

What are you trying to do that currently feels hard or impossible?

Design proposal #2147

Suggested Solution(s)

Proposal: ToolboxClient Middleware / Hooks

AIM
Making things easier to add cross‑cutting behavior around tool calls (logging, input cleanup, retries, recoverable errors) without wrapping every tool manually.

Possible API (Python SDK example)

  from typing import Dict, Any                                                 
                                                                               
  ToolCall = Dict[str, Any]                                                    
  ToolResult = Any                                                             
                                                                               
  class ToolboxMiddleware:                                                     
      def before_call(self, call: ToolCall) -> ToolCall:                       
          return call                                                          
                                                                               
      def after_call(self, call: ToolCall, result: ToolResult) -> ToolResult:  
          return result                                                        
                                                                               
      def on_error(self, call: ToolCall, err: Exception) -> ToolResult |       
Exception:                                                                     
          return err  # default: re-raise                                      

  client = ToolboxClient(                                                      
      ...,                                                                     
      middlewares=[LoggingMW(), RecoverableErrorMW(), InputNormalizeMW()]      
  )                                                                            

Semantics (my guess)

• before_call: validate or normalize inputs, maybe add metadata
• after_call: post‑process tool outputs
• on_error: if the error is “recoverable,” return a tool message instead of raising so the LLM can retry

Example: recoverable error

If params are invalid and we can guess the intended value:

  "Error: input invalid. Did you mean 'X'? Please retry."                      

This seems close to the LangChain “recoverable” pattern the issue mentioned.

Ordering

I think middleware could run in order for before_call, and reverse order for after_call / on_error (stack‑style).

Async

Maybe async versions: before_call_async, after_call_async, on_error_async.

Scope

Maybe support:

• global middlewares on the client
• optional per‑tool ooverride if needed

Backwards compatibility

If no middleware is configured, behavior should not be changd.

Alternatives Considered

No response

Additional Details

#2147

[twishabansal]

Hi @Deeven-Seru . Thanks for opening this feature request.

I was wondering if you could use orchestration framework level middleware instead. This would ensure that we're using existing standard features instead of adding a new learning curve for the devs. These features are widely supported and relatively easy to use.

You can use our pre and post processing samples for guidance on how to use these for your use case. Please let me know in case this does not work for you!

[Deeven-Seru]

Hi @twishabansal — I reviewed the pre/post‑processing sample (ADK ToolboxToolset hooks). It does cover pre‑call validation that can block a tool and return an error message, plus post‑call response enrichment. What I didn’t see is intercepting tool exceptions (i.e., catching failures from the tool execution itself and converting them into recoverable messages for retries). Is there a recommended pattern for that within the same framework?

[twishabansal]

I think tool exceptions should be a part of tool Outputs in the ADK framework: https://google.github.io/adk-docs/callbacks/types-of-callbacks/#after-tool-callback.

Did you face any specific challenges while intercepting them?

[Deeven-Seru]

Thanks for the pointer. I looked at the after‑tool callback doc — it shows getting a ToolOutput. My question is about exceptions thrown during toolmexecution (e.g., network errors, invalid params) before a ToolOutput is produced.
In that case:

• Does ADK surface the exception as a ToolOutput with is_error=true in the aafter‑tool callback?
• Or is there a separate error callback / recommended wrapper pattern to convert exceptions into a recoverable ToolOutput? If there’s a canonical pattern, I’ll adopt it. My goal is just to catch tool failures and return a “recoverable” message so the LLM can retry, without wrapping every tool manually

[twishabansal]

Currently, I see errors being directly raised which means they should go directly to the tool output. Can you highlight the current behaviour that you are observing?

Assigning @anubhav756 who has better context on how ADK python works.