Found docs updates needed from ADK python release v1.26.0 to v1.27.0

### 1. **Document new A2A capabilities: Reasoning, Long-Running Tools, and Artifacts**

**Doc file**: docs/a2a/intro.md

**Current state**:
> The introduction covers the "What", "When", and "How" of A2A but does not detail the specific capabilities supported by the protocol implementation, such as reasoning models or artifact streaming.

**Proposed Change**:
> Add a new section "Supported Capabilities" that outlines the advanced features supported by the ADK A2A implementation:
> 1. **Reasoning Models**: Support for transmitting "thought" traces from reasoning models (like Gemini 2.0 Flash Thinking).
> 2. **Long-Running Tools**: Built-in handling for tools that require significant time to execute.
> 3. **Artifact Streaming**: Support for streaming large data or files as artifacts between agents.

**Reasoning**:
The new converter files (`part_converter.py`, `long_running_functions.py`, `from_adk_event.py`) introduce support for these advanced capabilities. Users building complex agent systems need to know that the A2A protocol in ADK supports these features.

**Reference**: src/google/adk/a2a/converters/part_converter.py

### 2. **Document the new A2A agent configuration and interception capabilities**

**Doc file**: docs/a2a/quickstart-consuming.md

**Current state**:
> The consuming quickstart shows basic usage of `RemoteA2aAgent` with just a name, description, and agent card URL. It does not mention any advanced configuration or interception capabilities.

**Proposed Change**:
> Add an 'Advanced Configuration' section that explains how to use `A2aRemoteAgentConfig` to customize the agent's behavior. This should include:
> 1. Importing `A2aRemoteAgentConfig` and `RequestInterceptor`.
> 2. Creating an interceptor to modify requests or responses (e.g., adding headers).
> 3. Passing the configuration to `RemoteA2aAgent`.

**Reasoning**:
The new `A2aRemoteAgentConfig` and `RequestInterceptor` classes provide powerful capabilities for customizing A2A interactions, such as adding authentication headers or logging. Users need to know how to use these features.

**Reference**: src/google/adk/a2a/agent/config.py

### 3. **Create documentation for the new Skills framework and SkillToolset**

**Doc file**: docs/tools/built-in-tools/skills.md

**Current state**:
> (New file)

**Proposed Change**:
> # Skills
>
> Skills are specialized packages of instructions and resources that extend an agent's capabilities for specific tasks. A skill is essentially a folder containing a `SKILL.md` file (manifest) and optional resources like scripts, assets, and reference documents.
>
> ## Skill Structure
>
> A skill folder typically has the following structure:
>
> ```
> my-skill/
> ├── SKILL.md # Required: Metadata and main instructions
> ├── scripts/ # Optional: Python or Bash scripts
> │ ├── setup.py
> │ └── process.sh
> ├── references/ # Optional: Additional markdown documentation
> │ └── details.md
> └── assets/ # Optional: Binary or text assets
> └── logo.png
> ```
>
> ### SKILL.md
>
> The `SKILL.md` file contains YAML frontmatter for metadata and Markdown for instructions.
>
> ```markdown
> ---
> name: my-skill
> description: Performs complex data processing.
> metadata:
> adk_additional_tools: ["analyze_data"] # Tools to dynamically enable
> ---
>
> # My Skill Instructions
>
> Follow these steps to process data:
> 1. Run the setup script.
> 2. ...
> ```
>
> ## Using `SkillToolset`
>
> To use skills in your agent, add the `SkillToolset` to your agent's tools.
>
> ```python
> from google.adk.tools.skill_toolset import SkillToolset
> from google.adk.skills import load_skills_from_directory
>
> # Load skills
> skills = load_skills_from_directory("./my_skills")
>
> # Create toolset
> skill_toolset = SkillToolset(
> skills=skills,
> code_executor=agent_engine_executor, # Required for running scripts
> )
>
> # Add to agent
> agent = LlmAgent(
> # ...
> tools=[skill_toolset]
> )
> ```
>
> ## Features
>
> ### Script Execution
> Skills can contain scripts in the `scripts/` directory. The `RunSkillScriptTool` allows the agent to execute these scripts using the configured `code_executor`.
>
> ### Binary Content
> The `LoadSkillResourceTool` supports reading binary files (e.g., images, PDFs) from `assets/` or `references/`. The content is automatically injected into the conversation history for the model to analyze.
>
> ### Dynamic Tools
> Skills can request additional tools via the `adk_additional_tools` metadata key. When the skill is activated, these tools are dynamically resolved from the `SkillToolset`'s available tools.

**Reasoning**:
The `SkillToolset` and related skill features have been significantly updated to support script execution, binary file handling, and dynamic tool resolution. These features provide powerful capabilities for building modular agent behaviors and should be documented.

**Reference**: src/google/adk/tools/skill_toolset.py

### 4. **Create documentation for the new Agent Optimization feature and CLI command**

**Doc file**: docs/optimization/index.md

**Current state**:
> (New file)

**Proposed Change**:
> # Agent Optimization
>
> The ADK includes tools to optimize your agent's instructions automatically using the Generative Prompt Optimization (GEPA) technique.
>
> ## CLI Command
>
> You can run the optimizer using the `adk optimize` command:
>
> ```bash
> adk optimize AGENT_MODULE_FILE_PATH --sampler_config_file_path=SAMPLER_CONFIG [options]
> ```
>
> ### Arguments
>
> * `AGENT_MODULE_FILE_PATH`: Path to the agent's module file (e.g., `my_agent/__init__.py`). The module must expose a `root_agent`.
> * `--sampler_config_file_path`: Path to the configuration file for `LocalEvalSampler`. This config defines the evaluation sets used for training and validation.
> * `--optimizer_config_file_path`: (Optional) Path to the configuration file for `GEPARootAgentPromptOptimizer`.
> * `--print_detailed_results`: (Optional) Flag to print detailed optimization metrics.
>
> ## Configuration
>
> ### Sampler Config (`LocalEvalSamplerConfig`)
>
> Defined in a JSON file, typically containing:
> * `app_name`: Name of the application.
> * `eval_set_ids`: List of evaluation set IDs to use.
>
> ### Optimizer Config (`GEPARootAgentPromptOptimizerConfig`)
>
> Defined in a JSON file, controls parameters like:
> * Number of optimization rounds.
> * Batch size.
> * LLM to use for optimization.

**Reasoning**:
The `adk optimize` command and related optimization classes (`GEPARootAgentPromptOptimizer`, `LocalEvalSampler`) are new features in this release. Users need documentation to understand how to use them to improve their agents.

**Reference**: src/google/adk/cli/cli_tools_click.py

### 5. **Create documentation for the new ExecuteBashTool**

**Doc file**: docs/tools/built-in-tools/bash.md

**Current state**:
> (New file)

**Proposed Change**:
> # Bash Tool
>
> The `ExecuteBashTool` allows an agent to execute bash commands within a local workspace directory. This tool is useful for file system operations, running scripts, or interacting with the local environment.
>
> ## Usage
>
> To use the Bash tool, instantiate `ExecuteBashTool` and add it to your agent's tools.
>
> ```python
> from google.adk.tools.bash_tool import ExecuteBashTool, BashToolPolicy
> from google.adk.agents import LlmAgent
>
> # Create the tool with a policy
> bash_tool = ExecuteBashTool(
> workspace="/path/to/workspace", # Defaults to current working directory
> policy=BashToolPolicy(allowed_command_prefixes=("ls", "cat", "grep")) # Whitelist commands
> )
>
> agent = LlmAgent(
> name="system_helper",
> model="gemini-2.0-flash",
> tools=[bash_tool],
> instruction="You can execute bash commands to help the user."
> )
> ```
>
> ## Security
>
> The `ExecuteBashTool` includes several security features:
>
> 1. **Prefix Policy:** You can restrict which commands are allowed using `BashToolPolicy(allowed_command_prefixes=...)`. By default, all commands are allowed (`("*",)`).
> 2. **User Confirmation:** The tool **always** requests user confirmation before executing a command. The framework will pause execution and wait for the user (or client application) to approve the command via the `adk_request_confirmation` flow.
>
> ## Configuration
>
> * **`workspace`** (`pathlib.Path | None`): The directory where commands will be executed. Defaults to the current working directory.
> * **`policy`** (`BashToolPolicy | None`): Configuration for allowed command prefixes.
>

**Reasoning**:
The `ExecuteBashTool` is a new built-in tool that provides capability to run bash commands. It has specific security policies and confirmation requirements that should be documented.

**Reference**: src/google/adk/tools/bash_tool.py

### 6. **Document the new search_catalog tool in BigQuery documentation**

**Doc file**: docs/tools/google-cloud/bigquery.md

**Current state**:
> * **`execute_sql`**: Runs a SQL query in BigQuery and fetch the result.
> * **`forecast`**: Runs a BigQuery AI time series forecast using the `AI.FORECAST` function.
> * **`ask_data_insights`**: Answers questions about data in BigQuery tables using natural language.
>
> They are packaged in the toolset `BigQueryToolset`.

**Proposed Change**:
> * **`execute_sql`**: Runs a SQL query in BigQuery and fetch the result.
> * **`forecast`**: Runs a BigQuery AI time series forecast using the `AI.FORECAST` function.
> * **`ask_data_insights`**: Answers questions about data in BigQuery tables using natural language.
> * **`search_catalog`**: Finds BigQuery datasets and tables using natural language semantic search via Dataplex.
>
> They are packaged in the toolset `BigQueryToolset`.

**Reasoning**:
The `BigQueryToolset` now includes a `search_catalog` tool that uses Dataplex semantic search to find BigQuery assets. This new capability should be documented in the BigQuery tool documentation.

**Reference**: src/google/adk/tools/bigquery/search_tool.py

### 7. **Document new Bigtable tools: list_clusters and get_cluster_info**

**Doc file**: docs/tools/google-cloud/bigtable.md

**Current state**:
> * **`list_tables`**: Fetches tables in a GCP Bigtable instance.
> * **`get_table_info`**: Fetches metadata table information in a GCP Bigtable.
> * **`execute_sql`**: Runs a SQL query in Bigtable table and fetch the result.

**Proposed Change**:
> * **`list_tables`**: Fetches tables in a GCP Bigtable instance.
> * **`get_table_info`**: Fetches metadata table information in a GCP Bigtable.
> * **`list_clusters`**: Fetches clusters in a GCP Bigtable instance.
> * **`get_cluster_info`**: Fetches metadata cluster information in a GCP Bigtable.
> * **`execute_sql`**: Runs a SQL query in Bigtable table and fetch the result.

**Reasoning**:
The `BigtableToolset` now includes `list_clusters` and `get_cluster_info` tools for managing Bigtable clusters. These new tools should be documented.

**Reference**: src/google/adk/tools/bigtable/metadata_tool.py

### 8. **Document UI Widget support for MCP Tools**

**Doc file**: docs/tools-custom/mcp-tools.md

**Current state**:
> * **Filtering (Optional):** You can use the `tool_filter` parameter when creating an `McpToolset` to select a specific subset of tools from the MCP server, rather than exposing all of them to your agent.

**Proposed Change**:
> * **Filtering (Optional):** You can use the `tool_filter` parameter when creating an `McpToolset` to select a specific subset of tools from the MCP server, rather than exposing all of them to your agent.
> 6. **UI Rendering (Experimental):** If an MCP tool defines a UI resource (via `meta.ui.resourceUri`), the ADK automatically detects it and signals the client to render the tool's UI widget. This allows for rich, interactive tool experiences.

**Reasoning**:
The `McpTool` now supports detecting `mcp_app_resource_uri` and sending a `UiWidget` event. This is a significant new feature for MCP Apps that should be documented.

**Reference**: src/google/adk/tools/mcp_tool/mcp_tool.py

### 9. **Update ApiRegistry import path in documentation**

**Doc file**: docs/tools/google-cloud/api-registry.md

**Current state**:
> ```python
> import os
> from google.adk.agents.llm_agent import LlmAgent
> from google.adk.tools.api_registry import ApiRegistry
>
> # Configure with your Google Cloud Project ID and registered MCP server name
> PROJECT_ID = "your-google-cloud-project-id"

**Proposed Change**:
> ```python
> import os
> from google.adk.agents.llm_agent import LlmAgent
> from google.adk.integrations.api_registry import ApiRegistry
>
> # Configure with your Google Cloud Project ID and registered MCP server name
> PROJECT_ID = "your-google-cloud-project-id"

**Reasoning**:
The `ApiRegistry` class has been moved to `google.adk.integrations.api_registry`. The old import path `google.adk.tools.api_registry` is now deprecated and issues a warning. The documentation should be updated to use the new import path.

**Reference**: src/google/adk/tools/api_registry.py

### 10. **Update LlmAgent output_schema documentation to include all supported types**

**Doc file**: docs/agents/llm-agents.md

**Current state**:
> * **`output_schema` (Optional):** Define a schema representing the desired output structure. If set, the agent's final response *must* be a JSON string conforming to this schema.

**Proposed Change**:
> * **`output_schema` (Optional):** Define a schema representing the desired output structure. If set, the agent's final response *must* be a JSON string conforming to this schema.
> * Supports: `type[BaseModel]`, `list[type[BaseModel]]`, `list[primitive]`, `dict`, and `google.genai.types.Schema`.

**Reasoning**:
The `LlmAgent` now supports a wider range of output schemas beyond just `BaseModel`, including primitives, lists, and raw dicts. This flexibility should be documented.

**Reference**: src/google/adk/agents/llm_agent.py

### 12. **Document new BigQuery plugin configuration options: create_views and auto_schema_upgrade**

**Doc file**: docs/observability/bigquery-agent-analytics.md

**Current state**:
> - **`enabled`** (`bool`, default: `True`): To disable the plugin from logging agent data to the BigQuery table, set this parameter to False.
> - **`clustering_fields`** (`List[str]`, default: `["event_type", "agent", "user_id"]`): The fields used to cluster the BigQuery table when it is automatically created.

**Proposed Change**:
> - **`enabled`** (`bool`, default: `True`): To disable the plugin from logging agent data to the BigQuery table, set this parameter to False.
> - **`create_views`** (`bool`, default: `True`): Automatically creates or updates per-event-type BigQuery views (e.g., `v_llm_request`, `v_tool_completed`) for easier querying of JSON fields.
> - **`auto_schema_upgrade`** (`bool`, default: `True`): Automatically adds missing columns to the BigQuery table schema if they are present in the plugin's schema definition.
> - **`clustering_fields`** (`List[str]`, default: `["event_type", "agent", "user_id"]`): The fields used to cluster the BigQuery table when it is automatically created.

**Reasoning**:
The `BigQueryAgentAnalyticsPlugin` has new configuration options `create_views` and `auto_schema_upgrade` which significantly improve usability by providing typed views and handling schema evolution. These should be documented.

**Reference**: src/google/adk/plugins/bigquery_agent_analytics_plugin.py

### 13. **Document the --api_key option for adk deploy agent_engine**

**Doc file**: docs/deploy/agent-engine/deploy.md

**Current state**:
> The following example deploy command uses the `multi_tool_agent` sample code as
> the project to be deployed:
>
> ```shell
> PROJECT_ID=my-project-id
> LOCATION_ID=us-central1
> GCS_BUCKET=gs://MY-CLOUD-STORAGE-BUCKET
>
> adk deploy agent_engine \
> --project=$PROJECT_ID \
> --region=$LOCATION_ID \
> --staging_bucket=$GCS_BUCKET \
> --display_name="My First Agent" \
> multi_tool_agent
> ```

**Proposed Change**:
> The following example deploy command uses the `multi_tool_agent` sample code as
> the project to be deployed:
>
> **Option 1: Deploy with Google Cloud Project (Standard)**
>
> ```shell
> PROJECT_ID=my-project-id
> LOCATION_ID=us-central1
> GCS_BUCKET=gs://MY-CLOUD-STORAGE-BUCKET
>
> adk deploy agent_engine \
> --project=$PROJECT_ID \
> --region=$LOCATION_ID \
> --staging_bucket=$GCS_BUCKET \
> --display_name="My First Agent" \
> multi_tool_agent
> ```
>
> **Option 2: Deploy with API Key (Express Mode)**
>
> If you are using Express Mode, you can deploy using your API Key:
>
> ```shell
> adk deploy agent_engine --api_key=YOUR_API_KEY my_agent
> ```

**Reasoning**:
The `adk deploy agent_engine` command now supports an `--api_key` argument for Express Mode deployment. This option should be documented alongside the standard Google Cloud Project deployment method.

**Reference**: src/google/adk/cli/cli_tools_click.py

### 14. **Document the new 'sandbox' mode and configuration parameters for GkeCodeExecutor**

**Doc file**: docs/tools/google-cloud/gke-code-executor.md

**Current state**:
> | Parameter | Type | Description |
> | -------------------- | ------ | --------------------------------------------------------------------------------------- |
> | `namespace` | `str` | Kubernetes namespace where the execution Jobs will be created. Defaults to `"default"`. |
> | `image` | `str` | Container image to use for the execution Pod. Defaults to `"python:3.11-slim"`. |
> | `timeout_seconds` | `int` | Timeout in seconds for the code execution. Defaults to `300`. |

**Proposed Change**:
> | Parameter | Type | Description |
> | -------------------- | ------ | --------------------------------------------------------------------------------------- |
> | `executor_type` | `str` | Mode of execution: `"job"` (default) or `"sandbox"`. |
> | `sandbox_template` | `str` | (Sandbox mode only) The template name to use. Defaults to `"python-sandbox-template"`. |
> | `sandbox_gateway_name`| `str` | (Sandbox mode only) The name of the sandbox gateway. |
> | `namespace` | `str` | Kubernetes namespace where the execution Jobs/Sandboxes will be created. Defaults to `"default"`. |
> | `image` | `str` | Container image to use for the execution Pod. Defaults to `"python:3.11-slim"`. |
> | `timeout_seconds` | `int` | Timeout in seconds for the code execution. Defaults to `300`. |

**Reasoning**:
The `GkeCodeExecutor` has been updated to support a new `sandbox` mode using `agentic_sandbox.SandboxClient`. This mode requires new configuration parameters which should be documented.

**Reference**: src/google/adk/code_executors/gke_code_executor.py

### 15. **Document `render_ui_widgets` in EventActions**

**Doc file**: docs/events/index.md

**Current state**:
> * **Control Flow Signals:** Check boolean flags or string values:
> * `event.actions.transfer_to_agent` (string): Control should pass to the named agent.
> * `event.actions.escalate` (bool): A loop should terminate.
> * `event.actions.skip_summarization` (bool): A tool result should not be summarized by the LLM.

**Proposed Change**:
> * **Control Flow Signals & UI:**
> * `event.actions.transfer_to_agent` (string): Control should pass to the named agent.
> * `event.actions.escalate` (bool): A loop should terminate.
> * `event.actions.skip_summarization` (bool): A tool result should not be summarized by the LLM.
> * `event.actions.render_ui_widgets` (list[UiWidget]): A list of UI widgets to be rendered by the client.

**Reasoning**:
The `render_ui_widget` method and `UiWidget` support were added to allow agents to send UI components. This is a new capability that should be documented in the Events section.

**Reference**: src/google/adk/agents/context.py

### 16. **Document `render_ui_widget` method in Context documentation**

**Doc file**: docs/context/index.md

**Current state**:
> * **State for Data Flow:** `context.state` is the primary way to share data...
> * **Artifacts for Files:** Use `context.save_artifact` and `context.load_artifact`...
> * **Tracked Changes:** Modifications to state or artifacts...

**Proposed Change**:
> * **State for Data Flow:** `context.state` is the primary way to share data...
> * **Artifacts for Files:** Use `context.save_artifact` and `context.load_artifact`...
> * **UI Rendering:** Use `context.render_ui_widget(widget)` to send rich UI components (like MCP App iframes) to the client.
> * **Tracked Changes:** Modifications to state or artifacts...

**Reasoning**:
The `render_ui_widget` method was added to the `Context` class. Documenting it in the "Common Tasks" or "Key Takeaways" section of the Context docs ensures developers know how to use this new feature.

**Reference**: src/google/adk/agents/context.py

### 17. **Document context injection and context_param_name for FunctionTool**

**Doc file**: docs/tools-custom/function-tools.md

**Current state**:
> #### Return Type
>
> The preferred return type for a Function Tool is a **dictionary** in Python, a **Map** in Java, or an **object** in TypeScript. This allows you to structure the response with key-value pairs, providing context and clarity to the LLM. If your function returns a type other than a dictionary, the framework automatically wraps it into a dictionary with a single key named **"result"**.

**Proposed Change**:
> #### Return Type
>
> The preferred return type for a Function Tool is a **dictionary** in Python, a **Map** in Java, or an **object** in TypeScript. This allows you to structure the response with key-value pairs, providing context and clarity to the LLM. If your function returns a type other than a dictionary, the framework automatically wraps it into a dictionary with a single key named **"result"**.
>
> #### Context Injection
>
> If your function needs access to the agent's context (e.g., to read/write state, access authentication, or use artifacts), add a parameter named `tool_context` with type `ToolContext` to your function signature. The ADK will automatically inject the context when calling your function.
>
> ```python
> def my_tool(arg1: str, tool_context: ToolContext):
> # ... use tool_context ...
> ```
>
> You can customize the parameter name used for injection by passing `context_param_name` to the `FunctionTool` constructor.

**Reasoning**:
The `FunctionTool` now supports customizing the context parameter name via `context_param_name`. Also, explicitly documenting context injection clarifies how to access `ToolContext` in custom functions.

**Reference**: src/google/adk/tools/function_tool.py

### 18. **Update artifact documentation to mention dictionary support in save_artifact**

**Doc file**: docs/artifacts/index.md

**Current state**:
> report_artifact = types.Part.from_bytes(
> data=report_bytes,
> mime_type="application/pdf"
> )
> filename = "generated_report.pdf"
>
> try:
> version = await context.save_artifact(filename=filename, artifact=report_artifact)

**Proposed Change**:
> report_artifact = types.Part.from_bytes(
> data=report_bytes,
> mime_type="application/pdf"
> )
> # You can also pass a dictionary representation of the part:
> # report_artifact_dict = {"inline_data": {"mime_type": "application/pdf", "data": report_bytes}}
>
> filename = "generated_report.pdf"
>
> try:
> # artifact argument accepts types.Part or dict
> version = await context.save_artifact(filename=filename, artifact=report_artifact)

**Reasoning**:
The `save_artifact` method in `BaseArtifactService` and its implementations now accepts `Union[types.Part, dict[str, Any]]` for the `artifact` parameter. This flexibility allows passing dictionary representations directly, which is useful when dealing with serialized data. The documentation should mention this alternative.

**Reference**: src/google/adk/artifacts/base_artifact_service.py