feat: Add progressive streaming for run_async via ProgressiveTool (partial progress + final result)

[ac-machache]

Linked Issue

Closes: #2014

Summary

This PR introduces progressive streaming support for non-live runs (run_async).

• Tools can now emit intermediate progress updates as partial function_response events.
• Only the final function_response is injected back into the model.
• Intermediate results are surfaced to the user/runner only, not used by the model for reasoning.
• Live runner behavior remains unchanged (live mode continues to inject intermediates into the model loop).
• Existing non-progressive tools remain unaffected.

Rationale

Users need progress visibility for long-running tools during run_async, without switching to the live APIs.
This feature mirrors live runner ergonomics while remaining opt-in and ensuring model reasoning is unchanged (only final outputs affect the model).

New API

• google.adk.tools.progressive_function_tool.ProgressiveFunctionTool (abstract base)
• google.adk.tools.progressive_tool.ProgressiveTool (convenience wrapper)

Supported patterns:

• Async generator: each yield → partial; last yield → final
• Async coroutine with optional progress or progress_callback: injected reporter emits partials; return value → final

Changes

• src/google/adk/flows/llm_flows/base_llm_flow.py
  • _postprocess_handle_function_calls_async updated to handle progressive tools (stream partials + final).
• src/google/adk/flows/llm_flows/functions.py
  • Added iter_progressive_function_calls_async(...) to stream partials and yield a final function_response.
• src/google/adk/tools/progressive_function_tool.py
  • New abstract base class for progressive tools.
• src/google/adk/tools/progressive_tool.py
  • Wrapper to support async generators or injected progress callbacks.
  • Excludes progress params from function schema (_ignore_params).
• src/google/adk/tools/__init__.py
  • Export ProgressiveTool.

Backward Compatibility

• No behavior changes for existing tools or live runs.
• Non-progressive tools continue to return only a single final result.
• Progressive streaming is opt-in.

Testing Plan

Unit Tests (added)

• Tools: tests/unittests/tools/test_progressive_tool.py

  • Streams partial + final results
  • Final equals last yield
  • Error → converted to final
  • Multiple progressive tools in one turn
  • Non-progressive tool unaffected
  • Callback style (progress, progress_callback)
  • Direct run_async returns last yield

• Flows: tests/unittests/flows/llm_flows/test_progressive_flow.py

  • Flow emits partial then final with ProgressiveTool
  • Subclass of ProgressiveFunctionTool supported
  • Fallback path works for non-progressive tools

• Functions: tests/unittests/flows/llm_flows/test_functions_progressive_unit.py

  • Progressive iteration streams + final
  • Error handling converts to final
  • Parallel merge of function response events

Commands:

# Run only progressive tool/flow tests
pytest -q tests/unittests/tools/test_progressive_tool.py \
         tests/unittests/flows/llm_flows/test_progressive_flow.py \
         tests/unittests/flows/llm_flows/test_functions_progressive_unit.py
  

Manual End-to-End (E2E)

Minimal script with InMemoryRunner + ProgressiveTool(export_report) (async generator).

Observed output (truncated):

Partial events:

{"status": "started", "country": "Germany"}
{"status": "progress", "percent": 20}
...
{"status": "progress", "percent": 100}
{"status": "completed", "url": "https://example.com/germany.pdf"}

Model Reply

The report for Germany has been exported and can be accessed at https://example.com/germany.pdf

Documentation

No user-facing docs changed in this PR.
A follow-up PR to adk-docs will add a short usage guide for ProgressiveTool.

[hangfei]

Could you fix the merge conflicts?

[sandangel]

hi @hangfei
I resolved the merge conflict in this PR, could you help me take a look and merge this soon to release in 1.19?
I'm kind of really need this feature.

Warm regards

https://github.com/google/adk-python/pull/3564/files