Repository navigation
fix(agentgateway): opt-in handle_tool_error for graceful MCP tool-error propagation - #386
Merged
NicoleMGomes merged 2 commits intoOct 14, 2026
Conversation
…or propagation Adds an opt-in handle_tool_error parameter to mcp_tool_to_langchain. When set, Agent Gateway tool-call failures are surfaced to the LLM as a LangChain ToolException (converted to an error ToolMessage) instead of propagating as a raw SDK exception that crashes the agent loop. Default behavior is unchanged when the parameter is omitted. Covers both MCP error kinds (tool-execution isError results and JSON-RPC protocol errors). Includes a version bump to 0.58.5. 4 new unit tests; 315 agentgateway tests pass; ruff + ty clean.
Address review feedback on error propagation: - call_mcp_tool now surfaces JSON-RPC protocol errors (not just isError results): catch McpError (bare or wrapped in an anyio BaseExceptionGroup) and raise AgentGatewayServerError carrying the server message + code. - Check isError before the empty-content early return so an error result with empty content raises instead of being swallowed as a success . - agw_client re-raises a clean AgentGatewaySDKError found inside an ExceptionGroup instead of burying it under a generic wrapper; log a handled error at INFO (breadcrumb) rather than ERROR+stack trace. - Drop the internal gateway URL from the isError exception message (kept in an operator WARNING log); keep the tool name for attribution. - Remove review-flagged comments in converters.py; document handle_tool_error in the user guide. Add unit tests for find_mcp_error, _find_sdk_error, grouped McpError, and isError-with-empty-content.
NicoleMGomes
approved these changes
Oct 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an opt-in
handle_tool_errorparameter tomcp_tool_to_langchain. When set, AgentGateway tool-call failures are surfaced to the LLM as a LangChain
ToolException(convertedto an error
ToolMessagethe model can see and self-correct on) instead of propagating as araw SDK exception that crashes the agent loop.
Default behavior is unchanged: when the parameter is omitted (
None), the converter behavesexactly as before.
Why
An agent that converts Agent Gateway tools with
mcp_tool_to_langchainand then invokes onewould crash on any tool failure. Two things combined to cause this:
ToolException, so LangChain'shandle_tool_error(which onlycatches
ToolException) could not intercept the failure.handle_tool_errorat LangChain's default (False), so even aToolExceptionwould be re-raised rather than handled.Both MCP error kinds were affected: tool-execution errors (
isError: trueresults) andJSON-RPC protocol errors (e.g.
-32602). Both crashed the agent loop instead of reaching theLLM.