fix(spring-ai): make tool execution configurable

[mumu-1029521]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Addresses: [spring-ai] NullPointerException in ToolConverter when ADK tool uses ToolContext #699
• Related: Tool call fix for Spring AI - Let ADK call tools #733

Problem:

ToolConverter executed converted ADK tools from a Spring AI callback with tool.runAsync(processedArguments, null). Any tool that uses ADK's ToolContext could therefore fail with a NullPointerException. Making all tool calls definition-only avoids that null but makes execution ownership one-size-fits-all.

Solution:

Make tool execution ownership explicit and configurable:

• ADK_MANAGED is the default. Spring AI receives definition-only callbacks and returns tool calls to ADK. ADK executes them with its normal invocation-derived ToolContext, callbacks, confirmation, and state lifecycle.
• SPRING_AI_MANAGED is opt-in. The wrapper drives Spring AI's ToolCallingManager loop for blocking and streaming requests.
• Spring-AI-managed execution requires an AdkToolContextResolver. Construction or Spring Boot startup fails fast when the resolver is missing, and execution fails if it returns null; no hard-coded null context remains.
• Provider-specific argument wrappers are still normalized before both context resolution and tool execution.
• Existing constructors remain source-compatible and default to ADK_MANAGED.

Spring Boot users can select the owner with:

adk.spring-ai.tool-execution.mode=SPRING_AI_MANAGED

and provide an AdkToolContextResolver bean. The default is ADK_MANAGED, so existing applications keep ADK lifecycle semantics without configuration. Spring-AI-managed streaming buffers each model turn before executing requested tools and emitting the final turn.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Coverage includes:

• ADK-managed callbacks expose schemas without executing tools.
• Spring-AI-managed callbacks receive the exact non-null resolved ToolContext.
• Missing and null-returning resolvers fail fast.
• Blocking and streaming Spring AI flows execute a requested tool exactly once and send a ToolResponseMessage to the next model turn.
• Provider-specific nested argument wrappers remain normalized.
• Spring Boot default, missing-resolver, and configured-resolver behavior.
• A real ADK Runner integration flow verifies that ADK executes the requested tool exactly once with a non-null invocation-derived ToolContext, then returns the final model response.

./mvnw -pl contrib/spring-ai -am test

Google Agent Development Kit Maven Parent POM ... SUCCESS
Agent Development Kit .......................... SUCCESS
Agent Development Kit - Dev Tools .............. SUCCESS
Agent Development Kit - Spring AI .............. SUCCESS

Spring AI: Tests run: 219, Failures: 0, Errors: 0, Skipped: 20
BUILD SUCCESS

Manual End-to-End (E2E) Tests:

The in-memory ADK Runner integration test exercises the complete model tool-call → ADK tool execution → tool-response → final model-response flow. A live external-provider E2E test was not run because it requires provider credentials.

Checklist

• I have read the CONTRIBUTING.md document.
• My pull request contains a single commit.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

No downstream dependency changes are required. This supersedes the one-size-fits-all execution approach in the previous revision while preserving the later ToolResponseMessage and mixed text/function-response fixes already present on main.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[hemasekhar-p]

Hi @mumu-1029521, thank you for your contribution! We appreciate you taking the time to submit this pull request. Currently this PR is under review by our team we will keep you posted if any additional information is required. thank you.