joeyutong opened a new issue, #956: URL: https://github.com/apache/flink-agents/issues/956
### Search before asking - [x] I searched the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description ## Background Java and Python currently expose different Tool result contracts: - Java `Tool.call` returns `ToolResponse`, which can explicitly represent success or failure without throwing an exception. - Python `Tool.call` returns `Any`. An exception represents failure, while any normal return is treated as success because Python has no equivalent explicit error-result type. [Issue #925](https://github.com/apache/flink-agents/issues/925) and [PR #926](https://github.com/apache/flink-agents/pull/926) introduce parallel Tool calls and a cross-language `Outcome` abstraction for durable batch execution. `Outcome` aligns invocation results as `value` or `error`, but it does not align the Tool-specific result contract: a successful Java `Outcome<ToolResponse>` may still contain an unsuccessful `ToolResponse`, while a successful Python `Outcome` contains an arbitrary value that is treated as a successful Tool result. [Discussion #901](https://github.com/apache/flink-agents/discussions/901) and the corresponding [Metrics PR #955](https://github.com/apache/flink-agents/pull/955) expose this difference through Tool success/failure metrics. The Metrics implementation follows each runtime's existing Tool contract and does not inspect arbitrary return payloads, so strict Java/Python outcome parity is not currently guaranteed. ## Proposed direction After PR #926, define one Tool outcome contract across Java and Python while preserving compatibility for existing Python Tools that return raw values: - A normal raw Python return remains a successful Tool result. - Both languages can explicitly return a successful or failed Tool result. - An invocation exception remains a failed Tool result. - Sequential and parallel Tool-call paths use the same mapping. - Java/Python bridges preserve explicit Tool success, failure, and error details. - `ToolResponseEvent`, Execution Events, and Tool/MCP metrics consume the same normalized outcome. - MCP protocol-level error results should map to the same failed Tool outcome instead of being treated as successful content. The runtime must not infer failure by inspecting arbitrary Tool payloads. ## Expected validation Cover native Java, native Python, and both cross-language directions for: - normal success; - explicit returned failure; - thrown exception; - sequential and parallel execution; - MCP protocol-level failure. ### Are you willing to submit a PR? - [x] I'm willing to submit a PR! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
