Enhance error handling in MCP tool invocation

[mpenn]

Description

Closes #262

This PR handles cases when an MCP tool is invoked and fails because of invalid inputs. Previously, invalid inputs trigger exceptions and the entire agent exits, returning an error message. The resolution in this PR introduces a configuration setting in the MCP tool that propagates the exception message back to the agent, giving it an opportunity to recover.

This exception can be observed with the simple_mcp example. Without this improvement, the react_agent fails to produce valid outputs after a single parsing failure. Note, this example will need to be run several times due to non-deterministic behavior. The react_agent intermittently produces invalid inputs for the MCP tool.

By Submitting this PR I confirm:

• I am familiar with the Contributing Guidelines.
• We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  • Any contribution which contains commits that are not Signed-Off will not be accepted.
• When the PR is ready for review, new or existing tests cover these changes.
• When the PR is ready for review, the documentation is up to date with these changes.

[raghu-ramesha]

NOTE: Works on both AIQToolkit-UI and console

Verified, the new changes work for simple queries, updated the bug #262 for nested query which calls multiple mcp_tool_wrapper

Output -

[AGENT]
Agent input: What is langchain?
Agent's thoughts: 
Thought: It seems like the input I provided was not in the correct JSON format. I'll try again with the correct formatting.

Action: mcp_url_tool
Action Input: {"url": "https://en.wikipedia.org/wiki/Langchain", "max_length": 5000, "start_index": 0, "raw": false}
------------------------------
2025-05-14 08:10:00,802 - aiq.agent.react_agent.agent - INFO - 
------------------------------
[AGENT]
Calling tools: mcp_url_tool
Tool's input: {"url": "https://en.wikipedia.org/wiki/Langchain", "max_length": 5000, "start_index": 0, "raw": false}
Tool's response: 
Failed to fetch https://en.wikipedia.org/wiki/Langchain - status code 404
------------------------------
2025-05-14 08:10:02,543 - aiq.agent.react_agent.agent - INFO - 
------------------------------
[AGENT]
Agent input: What is langchain?
Agent's thoughts: 
Thought: It seems like the URL I provided does not exist, which means Langchain does not have a Wikipedia page. I'll try searching for it on a search engine instead.

Action: mcp_url_tool
Action Input: {"url": "https://www.google.com/search?q=langchain", "max_length": 5000, "start_index": 0, "raw": false}
------------------------------
2025-05-14 08:10:04,424 - aiq.agent.react_agent.agent - INFO - 
------------------------------
[AGENT]
Calling tools: mcp_url_tool
Tool's input: {"url": "https://www.google.com/search?q=langchain", "max_length": 5000, "start_index": 0, "raw": false}
Tool's response: 
Contents of https://www.google.com/search?q=langchain:
Google Search

If you're having trouble accessing Google Search, please click here, or send feedback.
------------------------------
2025-05-14 08:10:05,826 - aiq.agent.react_agent.agent - INFO - 
------------------------------
[AGENT]
Agent input: What is langchain?
Agent's thoughts: 
Thought: It seems like the search results from Google are not providing any useful information about Langchain. I'll try searching on a different search engine.

Action: mcp_url_tool
Action Input: {"url": "https://www.bing.com/search?q=langchain", "max_length": 5000, "start_index": 0, "raw": false}
------------------------------
2025-05-14 08:10:07,662 - aiq.agent.react_agent.agent - INFO - 
------------------------------
[AGENT]
Calling tools: mcp_url_tool
Tool's input: {"url": "https://www.bing.com/search?q=langchain", "max_length": 5000, "start_index": 0, "raw": false}
Tool's response: 
Contents of https://www.bing.com/search?q=langchain:
langchain - Search

Skip to content

Mobile

Any time

Open links in new tab

1. Copilot Answer

   LangChain

   https://www.langchain.com

   ## LangChain

   * Tools for every step of the agent development lifecycle -- built to unlock powerful AI in production. Build faster with templates & a visual agent IDE. Reuse, configure, and combine ...

     Talk to Our Team

     LangChain provides a suite of products to help teams build AI applications. This in...

     Quickstart

     LangChain enables building application that connect external sources of data a...

     Sign Up

     Data Security is important to us. To learn more about our policies and certificatio...

     Retrieval

     With LangChain’s ingestion and retrieval methods, developers can easily augme...

     LangChain

     Yes, LangChain 0.1 and later are production-ready. We've streamlined th...

     LangSmith

     LangSmith is a unified observability & evals pla...
------------------------------
2025-05-14 08:10:09,414 - aiq.agent.react_agent.agent - INFO - 
------------------------------
[AGENT]
Agent input: What is langchain?
Agent's thoughts: 
Thought: I now know the final answer

Final Answer: LangChain is a software framework that helps facilitate the integration of large language models into applications. It provides a standard interface for chains, many integrations with other tools, and end-to-end chains for common applications. LangChain simplifies every stage of the LLM application lifecycle: development, productionization, and deployment. It integrates with hundreds of providers and offers open-source components.
------------------------------
2025-05-14 08:10:09,417 - aiq.observability.async_otel_listener - WARNING - Not all spans were closed. Ensure all start events have a corresponding end event. Remaining: {'7e20b864-85a0-4a13-9f58-7cd00ed95bd3': <aiq.utils.optional_imports.DummySpan object at 0x32b24ce90>}
2025-05-14 08:10:09,417 - aiq.front_ends.console.console_front_end_plugin - INFO - 
--------------------------------------------------
Workflow Result:
['LangChain is a software framework that helps facilitate the integration of large language models into applications. It provides a standard interface for chains, many integrations with other tools, and end-to-end chains for common applications. LangChain simplifies every stage of the LLM application lifecycle: development, productionization, and deployment. It integrates with hundreds of providers and offers open-source components.']
----------------------

[mpenn]

/merge

[Copilot]

Pull Request Overview

This PR enhances error handling for MCP tool invocations by surfacing exception messages back to the agent and adds retry logic in the React agent when tools fail.

• Added a return_exception setting to MCPToolConfig to control whether exceptions are returned as strings
• Wrapped MCP tool calls in a try/except block to return or re-raise exceptions based on configuration
• Modified the React agent’s tool_node to retry tool invocation after an initial failure

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
src/aiq/tool/mcp/mcp_tool.py	Added return_exception config and exception-catching logic
src/aiq/agent/react_agent/agent.py	Inserted retry invocation for tools after a failure

Comments suppressed due to low confidence (1)

src/aiq/tool/mcp/mcp_tool.py:43

• Introduce unit tests to cover the new return_exception behavior, ensuring both the exception-returning and exception-raising branches are exercised.

return_exception: bool = Field(default=True,