Xiang (Sean) Zhou

This commit implements a **bug fix** to significantly improve the **robustness of the agent's tool retrieval mechanism**. Previously, an unavailable or error-prone toolset would cause the entire agent to crash silently during the `_convert_tool_union_to_tools()` and `canonical_tools()` calls. Now, the `toolset.get_tools_with_prefix()` call within `src/google/adk/agents/llm_agent.py` is wrapped in a `try-except` block, which gracefully catches exceptions, logs a warning, and returns an empty tool list for the failing toolset. This ensures the **agent remains operational**, allowing it to continue using tools from other functional toolsets and preventing silent failures, thereby enhancing overall system stability.

This commit introduces a **new capability** to the **`a2a` (Agent-to-Agent) module** by adding a `lifespan` parameter to the `to_a2a()` function. This enables support for **Starlette's async startup/shutdown protocol**, allowing users to define custom asynchronous logic for application initialization and cleanup, such as database connections or prompt registries. It **refactors** the internal implementation to replace the deprecated `add_event_handler` pattern with the modern `Starlette(lifespan=...)` constructor. This enhancement improves the developer experience by providing a standard, non-global way to manage application lifecycle events within `a2a` applications, ensuring better resource management and future compatibility.

This commit **fixes** a critical issue in the **`DiscoveryEngineSearchTool`** that prevented it from querying **structured datastores** by hardcoding the `search_result_mode` to `CHUNKS`. It introduces **auto-detection** for the search result mode, allowing the tool to gracefully fall back to `DOCUMENTS` mode when `CHUNKS` fails for structured data, and also provides a new `SearchResultMode` enum for explicit configuration. This **enhancement** ensures broader compatibility for the tool, particularly unblocking `VertexAiSearchTool` usage with structured data sources like Jira Cloud.

This commit provides a **bug fix** to eliminate Pydantic serialization warnings encountered during **live streaming sessions**. It resolves a type mismatch by explicitly converting `response_modalities` from a list of strings to a `list[Modality]` enum before assigning it to the **LiveConnectConfig**. Specifically, the `_build_basic_request` function within `src/google/adk/flows/llm_flows/basic.py` now performs this conversion, ensuring the **LiveConnectConfig** receives the expected enum type. This change prevents runtime warnings without impacting the backward compatibility of the public `RunConfig` interface.

This commit provides a **bug fix** for the **OpenAPI tool** by **disabling the default 5-second timeout** for `httpx.AsyncClient` within the `_request` function in `rest_api_tool.py`. Previously, a migration to `httpx` introduced a regression where long-running API calls would fail with `ReadTimeout` errors due to `httpx`'s default timeout, unlike the prior `requests` library which had no default. By explicitly setting `timeout=None`, this change **restores the original behavior of no default timeout**, preventing `ReadTimeout` errors and unblocking users from upgrading past version 1.23.0. A new test case has also been added to ensure this critical timeout setting is correctly applied.

This commit performs a **maintenance chore** by **updating owner assignments** within the `LABEL_TO_OWNER` dictionary in the `contributing/samples/adk_triaging_agent/agent.py` file. Specifically, it modifies which individuals or teams are designated as owners for several labels. This change impacts the **ADK triaging agent's** logic for assigning responsibility, potentially altering issue routing and ownership for relevant labels.

This commit **introduces a new sample agent** for the `files_retrieval` tool, located under `contributing/samples/files_retrieval_agent`. This **new capability** provides a complete, runnable example, including the core agent definition in `agent.py`, supporting data files like `adk_overview.txt` for its knowledge base, and comprehensive `README.md` documentation. The sample is designed to demonstrate the `files_retrieval` tool's usage and specifically facilitates **testing with the latest Gemini embedding model**. This expands the available examples for developers and aids in validating new model integrations.

fix(deps): bump google-genai minimum to >=1.64.0 for gemini-embedding-2-preview

This commit **introduces a new capability** to the **files retrieval subsystem** by updating the default embedding model to `gemini-embedding-2-preview`. It modifies the `_get_default_embedding_model` function in `src/google/adk/tools/retrieval/files_retrieval.py` to reflect this change and also adds an `embed_batch_size` parameter for finer control. This **feature enhancement** ensures that the retrieval process leverages the latest model, potentially improving the quality and efficiency of file content embeddings. Corresponding unit tests have been updated to validate the new default model and batch size, ensuring the correctness of this change.

This commit **fixes** an issue by adding proper support for `before_tool_callback` and `after_tool_callback` in **Live mode** for **LLM flows**. It **refactors** the `_execute_single_function_call_live` function in `src/google/adk/flows/llm_flows/functions.py` to prioritize these plugin callbacks and integrate robust tool error handling. This **enhancement** ensures that custom logic can reliably execute before and after tool calls in real-time scenarios, improving the extensibility and stability of the **LLM function calling mechanism**. New unit tests in `tests/unittests/flows/llm_flows/test_plugin_tool_callbacks.py` validate the correct behavior and priority of these callbacks, including error handling.

This commit performs a significant **refactoring** within the **ADK library** to enhance code reusability and maintainability. It extracts complex logic from the `process` methods in both the **authentication preprocessor** (`auth_preprocessor.py`) and the **LLM request confirmation flow** (`request_confirmation.py`) into new, dedicated helper functions. Specifically, authentication response processing is now handled by `_store_auth_and_collect_resume_targets`, while tool confirmation parsing and resolution are managed by `_parse_tool_confirmation` and `_resolve_confirmation_targets`. This modularization improves the clarity and testability of these critical components, with corresponding **test updates** ensuring continued correctness.

chore: Update pydantic versions

This commit performs a **maintenance chore** to officially **release version 1.25.1** of the **ADK Python library**. It updates the internal version tracking in `src/google/adk/version.py` to reflect the new `1.25.1` string and synchronizes the release manifest in `.github/.release-please-manifest.json`. This change primarily impacts the **version reporting** for the library, signifying the availability of the latest patch release to users and ensuring consistency across release tooling.

This commit **refactors** the **LLM agent transfer instruction building logic** within `src/google/adk/flows/llm_flows/agent_transfer.py`. It extracts the core, agent-tree-agnostic instruction generation into a new, reusable private function named `_build_transfer_instruction_body`. This **refactoring** significantly improves the **modularity and maintainability** of the agent transfer system. By centralizing this common logic, the component becomes more flexible and easier to extend for future agent configurations or different transfer scenarios.

This commit **refactors** the **`google.adk.flows.llm_flows`** subsystem by extracting several internal logic blocks into reusable private helper methods. Complex callback and tool processing logic within `BaseLlmFlow` is moved to new module-level functions like `_resolve_toolset_auth` and `_process_agent_tools`, while `SingleFlow`'s request/response processor definitions are extracted into `_create_request_processors`. This **improves code organization and maintainability** by breaking down large methods into smaller, more focused units. The change is purely an **internal restructuring** and has no functional impact on the public API, with corresponding unit tests updated to reflect the new modular structure.

This commit performs a significant **refactoring** of the **LLM flow processing logic** within the `google.adk.flows.llm_flows` module. It extracts numerous internal helper methods from the `BaseLlmFlow` class, such as `_resolve_toolset_auth` and `_generate_content_async`, into standalone private functions to improve modularity and reusability. Similarly, the `SingleFlow` class was refactored to use dedicated helper functions like `_create_request_processors` for its initializer. This **internal code restructuring** enhances maintainability and readability of the core **LLM flow components** without altering their external behavior, with unit tests updated to reflect these structural changes.

This commit **refactors** the management of **input-streaming tools** by **centralizing the creation and lifecycle of `LiveRequestQueue` instances** within the tool registration process. It moves the `LiveRequestQueue` creation from `_call_live` in `function_tool.py` to the lazy registration block in `_process_function_live_helper` within `functions.py`. This change ensures that the `input_stream` is correctly recreated upon re-invocation after `stop_streaming` resets it, **fixing** previous issues with stream handling. The `_call_live` method is simplified, now merely passing the existing stream without needing to know about `LiveRequestQueue` specifics, and new tests validate the improved streaming behavior.

This commit performs a **maintenance refactoring** within the **LLM flows content processing** of the `google.adk` library. Specifically, it updates the `run_async` method in `src/google/adk/flows/llm_flows/contents.py` to replace an `isinstance` check with a `hasattr` call for the `agent` object. This change semantically shifts from verifying the *type* of the `agent` to simply checking for the *presence* of a specific attribute, potentially enhancing the **flexibility and adaptability** of agent implementations within the `run_async` execution flow.

This commit introduces **lazy registration** for **streaming tools** within the **LLM flows** processing logic. Specifically, the `_process_function_live_helper` function in `src/google/adk/flows/llm_flows/functions.py` is updated to register these tools only when they are actively called by the model, rather than upfront. This **optimization** enhances efficiency by reducing initial overhead for unutilized tools in **LLM interactions**. Corresponding **unit tests** in `tests/unittests/streaming/test_streaming.py` have been updated to validate this new lazy behavior and ensure accurate context capturing.

This commit **expands the registration of streaming tools** within the **`runners` module**, ensuring a more uniform approach to their management. Previously, only streaming tools that accepted a specific stream input (like `LiveRequestQueue`) were registered; now, **all async-generator tools are uniformly registered as streaming tools** at startup. This **enhancement** includes a refactor in `src/google/adk/flows/llm_flows/functions.py` to simplify background task assignment for these tools, specifically within `_process_function_live_helper`. A new test case in `tests/unittests/streaming/test_streaming.py` validates this broader registration, improving the **consistency and capability of streaming tool integration** across the system.