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

[xuanyang15]

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.

---
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.

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:

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.

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:

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:

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:

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)

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:

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.

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