Found docs updates needed from ADK python release v2.4.0 to v2.5.0

[adk-bot]

Compare URL: google/adk-python@v2.4.0...v2.5.0

Feature Changes

1. Update error execution callbacks

Doc file: docs/plugins/index.md

Current state:

Agent execution callbacks

Agent execution callbacks (before_agent, after_agent) happen when a
Runner object invokes an agent. The before_agent_callback runs immediately
before the agent's main work begins. The main work encompasses the agent's
entire process for handling the request, which could involve calling models or
tools. After the agent has finished all its steps and prepared a result, the
after_agent_callback runs.

Runner end callbacks

The Runner end callback (after_run_callback) happens when the agent has
finished its entire process and all events have been handled, the Runner
completes its run. The after_run_callback is the final hook, perfect for
cleanup and final reporting.

Proposed Change:

Agent execution callbacks

Agent execution callbacks (before_agent, after_agent, on_agent_error) happen when a
Runner object invokes an agent. The before_agent_callback runs immediately
before the agent's main work begins. The main work encompasses the agent's
entire process for handling the request, which could involve calling models or
tools. After the agent has finished all its steps and prepared a result, the
after_agent_callback runs. If an error occurs during the agent's execution, the on_agent_error_callback is triggered.

Agent on error callback details

Unlike model and tool error callbacks which can suppress exceptions and return a fallback result, the agent on error callback (on_agent_error_callback) is notification-only and best-effort. The triggering exception is always re-raised by the caller. This callback is useful for logging or tracking agent-level failures.

Runner end callbacks

Runner end callbacks include (after_run_callback, on_run_error_callback). The after_run_callback happens when the agent has finished its entire process and all events have been handled, and the Runner completes its run successfully. The on_run_error_callback is triggered if an unhandled exception escapes the runner's execution.

Runner on error callback details

The runner on error callback (on_run_error_callback) is notification-only and best-effort. The triggering exception is always re-raised by the framework after plugins are notified. It cannot be suppressed by the plugin. It is useful for logging the failure or performing critical cleanup before the application crashes.

Reasoning:
The release introduces on_agent_error_callback for BaseAgent and on_run_error_callback for BasePlugin. These are notification-only and best-effort callbacks for handling exceptions.

Reference: src/google/adk/agents/base_agent.py, src/google/adk/plugins/base_plugin.py

2. Update ManagedAgent with composition mode and remote MCP server capabilities

Doc file: docs/agents/managed-agents.md

Current state:

Limitations

• Location pinned (Agent Platform only): For the Agent Platform backend, the
  Managed Agents API is currently served only from the global location.
  Regional endpoints raise an error.

• Server-side tools only: Client-executed tools (Python functions,
  callables) and MCP tools are not supported and raise a NotImplementedError.

• Streaming only: The agent uses streaming interactions (stream=True).

  A managed code execution agent using raw types.Tool

  managed_code_execution_agent = ManagedAgent(
  name='managed_code_execution_agent',
  description='Solves computational questions by running code server-side.',
  agent_id=_AGENT_ID,
  environment={'type': 'remote'},
  tools=[types.Tool(code_execution=types.ToolCodeExecution())],
  )

Proposed Change:

Composition Mode

ManagedAgent supports a mode parameter. When set to single_turn (mode='single_turn'), the agent runs as an inline single-turn tool of a parent LlmAgent (this is the recommended replacement for AgentTool), preserving its internal events in the shared session. Leaving it as None (the default) allows the agent to be used as a standard LLM-transfer target.

Limitations

• Location pinned (Agent Platform only): For the Agent Platform backend, the
  Managed Agents API is currently served only from the global location.
  Regional endpoints raise an error.

• Server-side tools only: Supported tools include ADK built-in tools, raw types.Tool configs, and server-side remote MCP servers declared as RemoteMcpServer specs. Client-executed tools (Python functions,
  callables) and raw types.Tool.mcp_servers configs are not supported and raise a NotImplementedError.

• Streaming only: The agent uses streaming interactions (stream=True).

  A managed code execution agent using raw types.Tool

  managed_code_execution_agent = ManagedAgent(
  name='managed_code_execution_agent',
  description='Solves computational questions by running code server-side.',
  agent_id=_AGENT_ID,
  environment={'type': 'remote'},
  tools=[types.Tool(code_execution=types.ToolCodeExecution())],
  )

  A managed agent using a remote MCP server

  from google.adk.tools import RemoteMcpServer

  managed_mcp_agent = ManagedAgent(
  name='managed_mcp_agent',
  agent_id=_AGENT_ID,
  tools=[
  RemoteMcpServer(
  url="https://api.example.com/mcp",
  name="my_remote_mcp_server",
  )
  ],
  )

Reasoning:
ManagedAgent now supports server-side remote MCP servers (RemoteMcpServer specs) and a new mode='single_turn' composition mode.

Reference: src/google/adk/agents/_managed_agent.py, src/google/adk/tools/_remote_mcp_server.py

3. Update captured events, views, and tool structures

Doc file: docs/integrations/bigquery-agent-analytics.md

Current state:

| INVOCATION_COMPLETED | An invocation ends | (common columns only) | v_invocation_completed |
| AGENT_STARTING | Agent execution begins | instruction summary | v_agent_starting |
| AGENT_COMPLETED | Agent execution ends | latency | v_agent_completed |
| LLM_REQUEST | A model request is sent | model, prompt, config, tools | v_llm_request |

| v_agent_completed | total_ms (INT64) |
| v_invocation_starting | (common columns only) |
| v_invocation_completed | (common columns only) |
| v_state_delta | state_delta (JSON) |

"model": "gemini-flash-latest",
"tools": ["list_dataset_ids", "execute_sql"],
"llm_config": {

Proposed Change:

| INVOCATION_COMPLETED | An invocation ends | (common columns only) | v_invocation_completed |
| INVOCATION_ERROR | Invocation fails | error message, traceback | v_invocation_error |
| AGENT_STARTING | Agent execution begins | instruction summary | v_agent_starting |
| AGENT_COMPLETED | Agent execution ends | latency | v_agent_completed |
| AGENT_ERROR | Agent execution fails | error message, traceback, latency | v_agent_error |
| LLM_REQUEST | A model request is sent | model, prompt, config, tools | v_llm_request |

| v_agent_completed | total_ms (INT64) |
| v_agent_error | total_ms (INT64), error_traceback (STRING) |
| v_invocation_starting | (common columns only) |
| v_invocation_completed | (common columns only) |
| v_invocation_error | error_traceback (STRING) |
| v_state_delta | state_delta (JSON) |

"model": "gemini-flash-latest",
"tools": [
  {
    "name": "list_dataset_ids",
    "description": "Lists available datasets."
  }
],
"llm_config": {

Reasoning:
The plugin now handles AGENT_ERROR and INVOCATION_ERROR events via new error callbacks, auto-creates views for these new events, and extracts structured tool declarations (name, description) instead of just string names.

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

4. Add parameters to RunConfig

Doc file: docs/runtime/runconfig.md

Current state:

• get_session_config: Limits which events are fetched when loading a session.
  Use num_recent_events or after_timestamp to avoid loading the full event
  history on every invocation.

• context_window_compression: Enables context window compression for LLM
  input, useful when sessions approach model context limits.

• save_live_blob: When True, saves live audio and video data to the session
  and artifact service.

• tool_thread_pool_config: Runs tool executions in a background thread pool
  to keep the event loop responsive to user interruptions.

Proposed Change:

• get_session_config: Limits which events are fetched when loading a session.
  Use num_recent_events or after_timestamp to avoid loading the full event
  history on every invocation.

• context_window_compression: Enables context window compression for LLM
  input, useful when sessions approach model context limits.

• include_thoughts_from_other_agents: Whether to include other agents' thought parts in the LLM context. By default, thoughts from other agents are excluded. Enable this only when agents are expected to share internal reasoning with one another.

• save_live_blob: When True, saves live audio and video data to the session
  and artifact service.

• tool_thread_pool_config: Runs tool executions in a background thread pool
  to keep the event loop responsive to user interruptions.

• explicit_vad_signal: Whether to enable explicit voice activity detection (VAD) signals from the model.

Reasoning:
The RunConfig class introduces new parameters for managing multi-agent internal reasoning and enabling explicit voice activity detection (VAD) signals.

Reference: src/google/adk/agents/run_config.py

5. Document A2A SDK backward compatibility

Doc file: docs/a2a/index.md

Current state:

With Agent Development Kit (ADK), you can build complex multi-agent systems where different agents need to collaborate and interact using Agent2Agent (A2A) Protocol! This section provides a comprehensive guide to building powerful multi-agent systems where agents can communicate and collaborate securely and efficiently.

Proposed Change:

With Agent Development Kit (ADK), you can build complex multi-agent systems where different agents need to collaborate and interact using Agent2Agent (A2A) Protocol! This section provides a comprehensive guide to building powerful multi-agent systems where agents can communicate and collaborate securely and efficiently.

!!! note "A2A SDK Compatibility"
ADK dynamically supports both a2a-sdk version 0.3.x and 1.x. The framework seamlessly bridges version differences behind the scenes, ensuring your existing A2A agents and servers continue working without requiring any code changes when you upgrade your Python SDK dependencies.

Reasoning:
The release introduces dynamic support for a2a-sdk versions 0.3.x and 1.x, which should be documented so users know it is safe to upgrade.

Reference: src/google/adk/a2a/_compat.py

6. Update EvalConfig to support polymorphic deserialization

Doc file: docs/evaluate/user-sim.md

Current state:

{
  "criteria": {
    # same as before
  },
  "user_simulator_config": {
    "model": "gemini-flash-latest",
    "model_configuration": {
      "thinking_config": {
        "include_thoughts": true,
        "thinking_budget": 10240
      }
    },
    "max_allowed_invocations": 20
  }
}

• model: The model backing the user simulator.

Proposed Change:

{
  "criteria": {
    # same as before
  },
  "user_simulator_config": {
    "type": "llm_backed",
    "model": "gemini-flash-latest",
    "model_configuration": {
      "thinking_config": {
        "include_thoughts": true,
        "thinking_budget": 10240
      }
    },
    "max_allowed_invocations": 20
  }
}

• type: The type of user simulator to use (e.g. "llm_backed").
• model: The model backing the user simulator.

Reasoning:
EvalConfig now supports polymorphic deserialization of user_simulator_config via a type discriminator. The documentation should show how to explicitly set this field.

Reference: src/google/adk/evaluation/eval_config.py

7. Add search methods for MCP servers and agents

Doc file: docs/integrations/agent-registry.md

Current state:

API Reference

The AgentRegistry class provides the following core methods:

• list_mcp_servers(self, filter_str, page_size, page_token): Fetches a list of
  registered MCP Servers.
• get_mcp_server(self, name): Retrieves detailed metadata of a specific MCP
  Server.
• get_mcp_toolset(self, mcp_server_name): Constructs an ADK McpToolset
  instance from a registered MCP Server.
• list_agents(self, filter_str, page_size, page_token): Fetches a list of
  registered A2A Agents.
• get_agent_info(self, name): Retrieves detailed metadata of a specific A2A
  Agent.
• get_remote_a2a_agent(self, agent_name): Creates an ADK RemoteA2aAgent
  instance for a registered A2A Agent.

Proposed Change:

API Reference

The AgentRegistry class provides the following core methods:

• list_mcp_servers(self, filter_str, page_size, page_token): Fetches a list of
  registered MCP Servers.
• search_mcp_servers(self, search_string, search_type, filter_str, order_by, page_size, page_token): Searches registered MCP Servers via keyword or semantic search.
• get_mcp_server(self, name): Retrieves detailed metadata of a specific MCP
  Server.
• get_mcp_toolset(self, mcp_server_name): Constructs an ADK McpToolset
  instance from a registered MCP Server.
• list_agents(self, filter_str, page_size, page_token): Fetches a list of
  registered A2A Agents.
• search_agents(self, search_string, search_type, filter_str, order_by, page_size, page_token): Searches registered A2A Agents via keyword or semantic search.
• get_agent_info(self, name): Retrieves detailed metadata of a specific A2A
  Agent.
• get_remote_a2a_agent(self, agent_name): Creates an ADK RemoteA2aAgent
  instance for a registered A2A Agent.

Reasoning:
AgentRegistry added search_mcp_servers and search_agents methods for discovering agents and MCP servers via keyword or semantic search.

Reference: src/google/adk/integrations/agent_registry/agent_registry.py

8. Document CloudRunSandboxCodeExecutor

Doc file: docs/integrations/cloud-run-sandbox.md

Current state:

Proposed Change:

Create a new page documenting CloudRunSandboxCodeExecutor.

Cloud Run Sandbox Code Executor

The CloudRunSandboxCodeExecutor executes Python code inside a Cloud Run sandbox using the sandbox CLI tool. This executor is designed to run from within a Cloud Run container where sandboxes are enabled.

Configuration

from google.adk.integrations.cloud_run import CloudRunSandboxCodeExecutor

executor = CloudRunSandboxCodeExecutor(
    sandbox_bin='/usr/local/gcp/bin/sandbox',
    allow_egress=False
)

Limitations

• Cannot be stateful (stateful=False).
• Relies on the local guest sandbox binary provided by the Cloud Run container runtime.
• Cannot be used remotely from a local machine.

Reasoning:
Release v2.5.0 introduced Cloud Run Sandbox support for code execution. This requires new documentation to guide users on how to configure and use CloudRunSandboxCodeExecutor.

Reference: src/google/adk/integrations/cloud_run/_cloud_run_sandbox_code_executor.py

9. Update GCPSkillRegistry backend connection and parameters

Doc file: docs/integrations/skills-registry.md

Current state:

!!! warning "Internet Access Requirements"
Since the GCP Skill Registry interacts with Vertex AI services using the Vertex AI Client SDK, agents running in sandboxed environments without outbound network access to Vertex AI endpoints will fail to reach the registry. Ensure proper network access is configured, or else the system falls back to local, filesystem-loaded skills.

...

On-Demand Loading (load_skill)

Once the agent identifies a matching remote skill (e.g., "bigquery"), it invokes the load_skill tool.

• SDK Fetch: ADK calls the Vertex AI Client SDK to retrieve the remote skill.

...

Parameter	Type	Default	Description
project_id	str	None	The Google Cloud project ID. If omitted, falls back to GOOGLE_CLOUD_PROJECT env variable.
location	str	None	The Google Cloud region/location. If omitted, falls back to GOOGLE_CLOUD_LOCATION env variable.

Methods

• search_skills(query: str) -> List[Frontmatter]:
  Performs a semantic or keyword query against the registry catalog, returning a list of skill frontmatter metadata (names and descriptions).
• get_skill(name: str, version: Optional[str] = None) -> Skill:
  Fetches the remote skill payload using the Vertex AI Client SDK for a specific skill name (and optional revision/version), unpacks it, and returns a loaded Skill object.

Proposed Change:

!!! warning "Internet Access Requirements"
Since the GCP Skill Registry interacts with Agent Registry services via HTTPS (with automatic mTLS support), agents running in sandboxed environments without outbound network access to these endpoints will fail to reach the registry. Ensure proper network access is configured, or else the system falls back to local, filesystem-loaded skills.

...

On-Demand Loading (load_skill)

Once the agent identifies a matching remote skill (e.g., "bigquery"), it invokes the load_skill tool.

• API Fetch: ADK calls the Agent Registry REST API to retrieve the remote skill.

...

Parameter	Type	Default	Description
project_id	str	None	The Google Cloud project ID. If omitted, falls back to GOOGLE_CLOUD_PROJECT env variable.
location	str	None	The Google Cloud region/location. If omitted, falls back to GOOGLE_CLOUD_LOCATION env variable.
credentials	Credentials	None	Optional Google Cloud credentials to use for the client. If omitted, uses Application Default Credentials.

Methods

• search_skills(query: str) -> List[Frontmatter]:
  Performs a semantic or keyword query against the registry catalog, returning a list of skill frontmatter metadata (names and descriptions).
• get_skill(name: str) -> Skill:
  Fetches the remote skill payload using the Agent Registry API for a specific skill name, unpacks it, and returns a loaded Skill object.

Reasoning:
GCPSkillRegistry was updated to use httpx.AsyncClient with automatic mTLS configuration instead of the Vertex AI Client SDK. It also added a credentials parameter to the constructor. The documentation must reflect these backend changes and the new parameter.

Reference: src/google/adk/integrations/skill_registry/gcp_skill_registry.py

10. Update VertexAiRagMemoryService initialization parameters

Doc file: docs/sessions/memory.md

Current state:

RAG memory

The VertexAiRagMemoryService stores conversations in Knowledge
Engine
and retrieves them by vector similarity. Use it when you already have RAG
infrastructure or want raw transcript retrieval rather than the LLM-extracted
memories produced by Memory Bank. Requires the Agent Platform SDK.

=== "Python"

```py
from google.adk.memory import VertexAiRagMemoryService

memory_service = VertexAiRagMemoryService(
    rag_corpus="projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID",
    similarity_top_k=5,
    vector_distance_threshold=0.6,
)
```

Proposed Change:

RAG memory

The VertexAiRagMemoryService stores conversations in Knowledge
Engine
and retrieves them by vector similarity. Use it when you already have RAG
infrastructure or want raw transcript retrieval rather than the LLM-extracted
memories produced by Memory Bank. Requires the agentplatform SDK.

=== "Python"

```py
from google.adk.memory import VertexAiRagMemoryService

memory_service = VertexAiRagMemoryService(
    project="PROJECT_ID",
    location="LOCATION",
    rag_corpus="CORPUS_ID",  # Or full resource name: projects/.../ragCorpora/...
    similarity_top_k=5,
    vector_distance_threshold=0.6,
)
```

Reasoning:
VertexAiRagMemoryService was updated to use the agentplatform SDK directly and introduced explicit project and location parameters to its constructor, allowing for short corpus IDs. The documentation should show these new explicit parameters instead of solely relying on parsing the fully-qualified rag_corpus string.

Reference: src/google/adk/memory/vertex_ai_rag_memory_service.py

11. Add explicit VAD signals to voice/audio events

Doc file: docs/streaming/dev-guide/part3.md

Current state:

For voice/audio applications:

• input_transcription: User's spoken words (when enabled in RunConfig)
• output_transcription: Model's spoken words (when enabled in RunConfig)
• content.parts[].inline_data: Audio data for playback

Proposed Change:

For voice/audio applications:

• input_transcription: User's spoken words (when enabled in RunConfig)
• output_transcription: Model's spoken words (when enabled in RunConfig)
• content.parts[].inline_data: Audio data for playback
• voice_activity: Explicit voice activity detection signals from the model (when explicit_vad_signal is enabled in RunConfig)

Reasoning:
The flow was updated to yield Voice Activity events directly from the model response when explicit_vad_signal is enabled in RunConfig. The event key fields documentation should include this new event attribute.

Reference: src/google/adk/flows/llm_flows/base_llm_flow.py

12. Introduce to_mcp_server built-in utility

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

Current state:

2. Build an MCP server with ADK tools (MCP server exposing ADK)

This pattern allows you to wrap existing ADK tools and make them available to any standard MCP client application. The example in this section exposes the ADK load_web_page tool through a custom-built MCP server.

Summary of steps

You will create a standard Python MCP server application using the mcp library. Within this server, you will:

Proposed Change:

2. Build an MCP server with ADK tools (MCP server exposing ADK)

ADK provides a built-in utility, to_mcp_server, that wraps an entire ADK agent (and its tools) into an MCP server automatically. This allows MCP hosts (like Claude Code, Cursor, or any MCP client) to drive an ADK agent by sending requests and receiving the agent's final response (including any images or audio the agent produced).

Expose an Agent via to_mcp_server

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import to_mcp_server

agent = LlmAgent(name="assistant", model="gemini-2.5-flash")

# Exposes the agent as a FastMCP server
server = to_mcp_server(agent)

if __name__ == "__main__":
    # Run the server on stdio (useful for local MCP clients)
    server.run(transport="stdio")

One ADK session is kept per MCP connection, so successive tool calls on the same connection form a single multi-turn conversation.

Advanced: Custom-built MCP server

If you prefer to manually expose individual tools rather than an entire agent, you can create a standard Python MCP server application using the mcp library. Within this server, you will:

Reasoning:
Release v2.5.0 introduces to_mcp_server, an easy way to expose an ADK agent as a FastMCP server, removing the need for developers to manually wire MCP handlers to ADK tools.

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

Other

13. Clarify min_tokens gating and model-specific minimums

Doc file: docs/context/caching.md

Current state:

• min_tokens (int): The minimum number of tokens required in a request
  to enable caching. This setting allows you to avoid the overhead of caching
  for very small requests where the performance benefit would be negligible.
  Defaults to 0.

Proposed Change:

• min_tokens (int): The minimum prior-request tokens required to enable caching. This gates on the previous request's actual prompt token count, not an estimate of the current request. Gemini's model-specific minimum always applies: 2048 tokens for Gemini 2.5 and 4096 tokens for Gemini 3. No cache is created on the first request of a session; caching begins on the second turn once a previous token count is known. Set this higher to avoid caching small requests where storage overhead may exceed benefits. Defaults to 0.

Reasoning:
The ContextCacheConfig class was updated to clarify that min_tokens gates on the previous request's actual token count, caching only begins on the second turn, and Gemini enforces model-specific minimums. The documentation should reflect this detailed behavior.

Reference: src/google/adk/agents/context_cache_config.py