fix(ToolMethodInvoker): Re-throw ToolSuspendException

[wuji1428]

AgentScope-Java Version

[The version of AgentScope-Java you are working on, e.g. 1.0.8, check your pom.xml dependency version or run mvn dependency:tree | grep agentscope-parent:pom(only mac/linux)]

Related Issues
Ref #717

Description

Modify handleInvocationError to re-throw ToolSuspendException

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[gemini-code-assist]

Summary of Changes

Hello @wuji1428, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the exception handling mechanism within the ToolMethodInvoker to ensure that ToolSuspendException instances are properly re-thrown. This change is crucial for maintaining the intended flow of tool suspension logic, allowing the ToolExecutor to correctly manage and respond to these specific exceptions rather than treating them as general invocation errors. The update includes both the core logic modification and corresponding unit tests to cover various invocation scenarios.

Highlights

• Exception Handling: The handleInvocationError method in ToolMethodInvoker has been updated to explicitly re-throw ToolSuspendException if it is the primary exception or its underlying cause. This ensures that tool suspension events are not inadvertently swallowed and are propagated correctly.
• Javadoc Updates: The Javadoc for handleInvocationError has been enhanced to clearly document the special handling of ToolSuspendException and its re-throwing behavior, including the addition of an @throws tag.
• New Test Cases: Comprehensive test cases have been added to ToolMethodInvokerTest to validate the correct re-throwing of ToolSuspendException across synchronous methods, CompletableFuture asynchronous methods, and Reactor Mono reactive methods.

Changelog

• agentscope-core/src/main/java/io/agentscope/core/tool/ToolMethodInvoker.java
  • Modified handleInvocationError to check for and re-throw ToolSuspendException if it is the direct exception or its cause.
  • Updated Javadoc for handleInvocationError to describe the new ToolSuspendException handling and added @throws ToolSuspendException.
• agentscope-core/src/test/java/io/agentscope/core/tool/ToolMethodInvokerTest.java
  • Added import static org.junit.Assert.assertThrows; for new test assertions.
  • Introduced new test methods (suspendTool, suspendToolAsync, suspendToolMono) within the TestTools class to simulate ToolSuspendException for different return types.
  • Added three new test cases (testToolSuspendException_SyncMethod, testToolSuspendException_CompletableFuture, testToolSuspendException_Mono) to verify that ToolSuspendException is correctly propagated when thrown from tool methods.

Activity

• The code has been formatted using mvn spotless:apply.
• All existing tests are passing (mvn test).
• Javadoc comments have been completed and adhere to project conventions.
• The code is marked as ready for review.
• This pull request addresses issue [BUG]: Tools implemented using @Tool cannot be suspended correctly. #717.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request successfully addresses the issue of re-throwing ToolSuspendException within the ToolMethodInvoker's error handling. The updated Javadoc clearly explains this new behavior, and the added test cases provide good coverage for synchronous, CompletableFuture, and Mono methods. There is a minor improvement opportunity to ensure the exception chain is fully traversed when checking for ToolSuspendException.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!