Xuan Yang

This commit introduces a **new capability** to **propagate grounding metadata** from `AgentTool` instances to their parent session. It adds a `propagate_grounding_metadata` flag to the `AgentTool` class and updates the `_handle_after_model_callback` in `base_llm_flow.py` to process this flag, ensuring metadata is passed up. This change **simplifies tool implementations**, notably **refactoring** `GoogleSearchAgentTool` to leverage the base `AgentTool`'s propagation logic instead of custom handling. A new sample in `contributing/samples/agent_tool_with_grounding_metadata` demonstrates how to effectively use this feature, enhancing the consistency and utility of grounding information across the system.

This commit **fixes** an issue where `FunctionCall` objects might lack identifiers when received from an LLM, particularly during **streaming responses**. It enhances the **`google.adk.utils.streaming_utils`** module by implementing client-side ID generation for `FunctionCall` objects within the `StreamingResponseAggregator._process_function_call_part` method. This ensures that all `FunctionCall` instances, whether from streaming or non-streaming contexts, consistently have a unique ID. This change improves the **robustness and reliability of LLM integrations** by preventing downstream issues that rely on these identifiers, and new unit tests verify this ID generation and preservation logic.

This commit significantly **enhances the ADK release analyzer** by introducing **resume functionality** and **improving session management**. The `adk_release_analyzer` now supports resuming analysis from a previous state, enabled by new input parameters in the `.github/workflows/analyze-releases-for-adk-docs-updates.yml` workflow, command-line arguments in `main.py`, and a refined resume pipeline within `agent.py`. Session management has been upgraded from in-memory to a more robust database-backed system, with caching implemented for the session database. Additionally, error handling in `tools.py` for `read_local_git_repo_file_content` has been made more robust, ensuring the analyzer can handle interruptions and large analysis tasks more reliably.

This commit performs a **code formatting refactoring** within the **unit tests** for the `bash_tool` module. Specifically, it modifies the `test_timeout` function in `tests/unittests/tools/test_bash_tool.py` to improve **readability** by adjusting the `with` statement syntax for multi-line context managers to use parentheses. This **maintenance chore** ensures **code style consistency** and has no functional impact on the system's behavior.

This commit performs a **maintenance chore** by adding missing copyright notices to the `__init__.py` files within the **`adk.integrations.agent_registry`** and **`adk.integrations.api_registry`** modules. This ensures proper legal compliance for these core integration components. The change is purely administrative and has no functional impact on the system's behavior, features, or any downstream consumers.

This commit provides a **fix** to the **`google.adk.utils.context_utils`** module, specifically enhancing the `find_context_parameter` function. It now correctly **resolves string annotations for context types**, leveraging `typing.get_type_hints` to interpret type hints provided as forward references or deferred strings. This **improves the robustness and flexibility of context parameter identification**, ensuring that type hints like `'MyType'` are properly understood within the ADK's context management system. Accompanying **unit tests** have been added to `tests/unittests/utils/test_context_utils.py` to verify this new capability.

This commit **updates the GitHub Actions workflow** responsible for analyzing releases and updating ADK documentation. It **refactors the security configuration** by switching from a general API key to a **dedicated API key secret** specifically for the documentation agents. This **maintenance chore** enhances security practices by isolating credentials, ensuring that the automated documentation update process uses more granularly scoped access. The change primarily affects the **CI/CD infrastructure** for documentation generation, specifically the workflow defined in `.github/workflows/analyze-releases-for-adk-docs-updates.yml`.

This commit **enhances the `LlmAgent` to support all `types.SchemaUnion` as its `output_schema`**, significantly **improving the flexibility and structure of LLM agent outputs**. It introduces a new **`_schema_utils` module** for robust schema validation and processing, which is integrated across the **`LlmAgent`**, **`SetModelResponseTool`**, and other **agent tools**. The change also includes a **fix** in `_output_schema_processor` to correctly unwrap nested tool responses and **refactoring** to dynamically generate function signatures based on the specified schema. This comprehensive **feature enhancement** allows agents to produce more complex and reliably structured data, making them more seamlessly integrable into downstream systems.

This commit **refactors** the system to **allow custom parameter names for `ToolContext` injection** across various tool implementations. It introduces dynamic detection of context parameters based on type annotations, moving away from a hardcoded `tool_context` name. This change impacts **`FunctionTool`**, **`CrewaiTool`**, and **`MCPTool`** by updating their argument processing and invocation logic, as well as the **LLM flow functions** that call these tools. A new **`context_utils` module** provides the core `find_context_parameter` utility, significantly enhancing the **flexibility** of tool definitions and improving maintainability.

This commit introduces a **bug fix** to ensure the **`thought_signature` field** is correctly preserved during **`FunctionCall` conversions** between GenAI and A2A formats. The `src/google/adk/a2a/converters/part_converter.py` module is updated, specifically the `convert_a2a_part_to_genai_part` and `convert_genai_part_to_a2a_part` functions, to handle base64 encoding and decoding of this field. This prevents data loss for `FunctionCall` parts that include a `thought_signature` when transforming between the two API representations. New unit tests in `tests/unittests/a2a/converters/test_part_converter.py` validate that the `thought_signature` is now accurately maintained across these critical data transformations.

This commit introduces a **maintenance chore** to optimize the project's **CI/CD pipeline**. It **stops the automatic triggering of the Release Please workflow** after cherry-pick operations, which previously led to unnecessary runs. Additionally, this change enhances security by **removing superfluous write permissions** for actions within the `.github/workflows/release-cherry-pick.yml` configuration. This adjustment streamlines the release process by preventing redundant automation and improves the overall security posture of the repository.

This commit **modifies the GitHub Actions configuration** for the `Release: Please` workflow, defined in `.github/workflows/release-please.yml`. It **changes the trigger mechanism** so that this specific workflow will now **only execute manually** via `workflow_dispatch`. The previous automatic trigger on pushes to the `release/candidate` branch has been removed. This **maintenance chore** provides more deliberate control over the release process by requiring explicit manual initiation for this workflow.

This commit **refactors** the **ADK agents module** by migrating its core components to utilize a new **feature decorator system**. It introduces `AGENT_CONFIG` and `AGENT_STATE` into the `FeatureName` enum and registers them within `_feature_registry.py`, then applies this decorator across various agent configuration classes like `AgentConfig`, `BaseAgentConfig`, and `LoopAgentConfig`, as well as state classes and utility methods such as `BaseAgentState` and `_parse_config`. This **standardizes the registration and management of agent configurations and states**, enhancing modularity and preparing the **agents subsystem** for more dynamic feature control. The change primarily affects the internal structure of how **ADK agents** are defined and configured, ensuring consistent integration with the broader feature management framework.

This commit **exports the `Context` class**, making it directly accessible from the **`google.adk`** top-level package and the **`google.adk.agents`** subpackage. This **API exposure** change simplifies imports for consumers of the library, allowing them to access `Context` without needing to navigate deeper module structures. By adding `Context` to the `__all__` lists in `src/google/adk/__init__.py` and `src/google/adk/agents/__init__.py`, this **maintenance chore** improves the usability and discoverability of this core class within the `adk` ecosystem.

This commit **unifies context management** within the `ADK` by **refactoring** `CallbackContext` and `ToolContext` into a single, central `Context` class. Specifically, the `src/google/adk/agents/callback_context.py` and `src/google/adk/tools/tool_context.py` modules are updated to alias the `Context` class, eliminating redundant definitions. Concurrently, the `src/google/adk/agents/context.py` module is **enhanced** with **new setter methods** for `function_call_id` and `tool_confirmation`, providing more direct control over these properties. This **simplifies the API** and consolidates related functionalities across the `agents` and `tools` subsystems, with corresponding test updates to reflect the new structure.

This commit introduces a **new `Context` class** within the **`google.adk.agents`** module, providing a **unified mechanism for managing agent interaction state**. This **architectural enhancement** centralizes the handling of session state, artifacts, credentials, and memory services, streamlining how agents access and persist critical operational data. By consolidating these functionalities, the `Context` class aims to simplify agent development, promote consistency, and improve the overall robustness of agent interactions. Comprehensive unit tests have been added in `tests/unittests/agents/test_context.py` to ensure the reliability of this core component.

This commit introduces a **bug fix** to the **interactions API integration** within the `adk.models` module. It modifies the conversion utilities, specifically `convert_part_to_interaction_content`, `convert_interaction_output_to_part`, and `convert_interaction_event_to_llm_response`, to correctly **preserve and decode the `thought_signature`** during function call conversions. This ensures that critical metadata is consistently maintained when converting between `Part` objects and the interaction API formats. New **unit tests** have been added to `test_interactions_utils.py` to verify the accurate handling of `thought_signature` across various conversion scenarios, significantly improving the robustness of the API integration.

This commit introduces **progress callback support** to the **`McpTool`** and **`McpToolset`** components, enabling users to monitor the execution status of long-running operations. It adds a new `ProgressCallbackFactory` protocol to `McpTool` for resolving and passing callbacks, and extends `McpToolset` to propagate these callbacks to individual tool instances. This **new feature** significantly enhances the ability to track and report the progress of tool executions. A new **sample agent** and mock server are included to demonstrate both simple and factory-based callback implementations, providing clear guidance for developers to integrate this functionality.

This commit delivers a **bug fix** for the **`google.adk.utils.streaming_utils`** module, enhancing the reliability of **streaming function call processing**. It refines the logic within `process_function_call_part` and `_process_part` to correctly aggregate function call arguments when `will_continue` is true in the initial streaming chunk, even if `partial_args` are absent. This ensures that **streaming function calls** are accurately reconstructed across all parts, preventing data inconsistencies in such edge cases. A new test case has been added to validate this specific streaming behavior, and the `hello_world_stream_fc_args` sample is updated with a new `write_document` tool.

This commit introduces **dynamic configuration support** for the **`VertexAiSearchTool`** within the `google.adk.tools` module. It implements a new method, `_build_vertex_ai_search_config`, to enable **customization of Vertex AI Search configurations** at runtime, with `process_llm_request` updated to leverage this. This **new feature** significantly enhances the flexibility of the tool, allowing for advanced use cases such as subclassing and context-based filtering. Comprehensive unit tests have been added to verify these dynamic capabilities.