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

[xuanyang15]

1. Update CrewaiTool import path in example snippet

Doc file: examples/python/snippets/tools/third-party/crewai_serper_search.py

Current state:

examples/python/snippets/tools/third-party/crewai_serper_search.py imports CrewaiTool from google.adk.tools.crewai_tool.

Proposed Change:

Update the import path to from google.adk.integrations.crewai import CrewaiTool.

Reasoning:
CrewaiTool has been moved to the new google.adk.integrations.crewai package.

Reference: src/google/adk/integrations/crewai/crewai_tool.py

2. Update LangchainTool import path in example snippet

Doc file: examples/python/snippets/tools/third-party/langchain_tavily_search.py

Current state:

examples/python/snippets/tools/third-party/langchain_tavily_search.py imports LangchainTool from google.adk.tools.langchain_tool.

Proposed Change:

Update the import path to from google.adk.integrations.langchain import LangchainTool.

Reasoning:
LangchainTool has been moved to the new google.adk.integrations.langchain package.

Reference: src/google/adk/integrations/langchain/langchain_tool.py

3. Create documentation for CrewAI and LangChain integrations

Doc file: docs/tools/third-party/crewai-and-langchain.md (New File)

Current state:

No dedicated documentation exists for CrewAI and LangChain integrations beyond code snippets.

Proposed Change:

Create new documentation pages under docs/tools/third-party/ or a new docs/integrations/ folder detailing how to use CrewaiTool and LangchainTool wrappers to adapt their tools for ADK. Include the updated snippet examples.

Reasoning:
The release introduces significant capabilities around these integrations. Documenting the new adapter classes will help users integrate third-party tools seamlessly.

Reference: src/google/adk/integrations/crewai/crewai_tool.py, src/google/adk/integrations/langchain/langchain_tool.py

4. Create documentation for the new Slack integration (SlackRunner)

Doc file: docs/integrations/slack.md (New File)

Current state:

No documentation exists for the Slack integration (SlackRunner).

Proposed Change:

Create a new documentation page detailing how to use SlackRunner to deploy agents on Slack using Socket Mode. The contents can be sourced directly from the newly added src/google/adk/integrations/slack/README.md. It should also be added to the navigation in MkDocs.

Reasoning:
The v1.28.0 release introduces a new Slack integration (SlackRunner), and having user-facing documentation is essential for adoption.

Reference: src/google/adk/integrations/slack/README.md, src/google/adk/integrations/slack/slack_runner.py

5. Regenerate API reference for new integrations packages

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API reference is missing the new google.adk.integrations packages.

Proposed Change:

Regenerate the Python API reference docs to include google.adk.integrations.slack and the updated AgentRegistry classes.

Reasoning:
The SlackRunner and updates to AgentRegistry involve public classes that should be reflected in the auto-generated documentation.

Reference: src/google/adk/integrations/slack/slack_runner.py, src/google/adk/integrations/agent_registry/agent_registry.py

6. Document the new SpannerAdminToolset

Doc file: docs/tools/google-cloud/spanner.md

Current state:

docs/tools/google-cloud/spanner.md only documents SpannerToolset and its data/query tools (e.g. execute_sql, list_table_names).

Proposed Change:

Add a new section for the SpannerAdminToolset explaining that it allows agents to perform administrative operations such as spanner_list_instances, spanner_create_instance, spanner_create_database, etc.

Reasoning:
The v1.28.0 release introduces a new admin toolset for Spanner, expanding its capabilities beyond just querying data into managing database instances.

Reference: src/google/adk/tools/spanner/admin_toolset.py, src/google/adk/tools/spanner/admin_tool.py

7. Regenerate API reference for SpannerAdminToolset

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API reference docs lack admin_tool.py and admin_toolset.py within google.adk.tools.spanner.

Proposed Change:

Regenerate the Python API reference documentation to include SpannerAdminToolset and the individual admin tools.

Reasoning:
The new SpannerAdminToolset is part of the public API for the Spanner integration and needs to be present in the auto-generated documentation.

Reference: src/google/adk/tools/spanner/admin_toolset.py

8. Document new multi-turn evaluators

Doc file: docs/evaluate/criteria.md

Current state:

docs/evaluate/criteria.md lacks documentation for the new multi-turn evaluators: multi_turn_task_success_v1, multi_turn_tool_use_quality_v1, and multi_turn_trajectory_quality_v1.

Proposed Change:

Add rows to the Evaluation Criteria table and new sections for multi_turn_task_success_v1, multi_turn_tool_use_quality_v1, and multi_turn_trajectory_quality_v1. Explain that these delegate to the Vertex AI Gen AI Eval SDK, are reference-free, and use an LLM-as-a-judge to evaluate multi-turn conversations. Provide EvalConfig examples showing how to set thresholds for them.

Reasoning:
The v1.28.0 release introduces these three new pre-built multi-turn evaluators. Users need to know how to configure and use them in their evaluation setups.

Reference: src/google/adk/evaluation/multi_turn_task_success_evaluator.py, src/google/adk/evaluation/multi_turn_tool_use_quality_evaluator.py, src/google/adk/evaluation/multi_turn_trajectory_quality_evaluator.py

9. Create documentation for the new Environment Simulation feature

Doc file: docs/tools/environment-simulation.md (New File)

Current state:

No documentation exists for the new Environment Simulation feature.

Proposed Change:

Create a new documentation page explaining how to configure and use the Environment Simulation engine. Detail how to set up EnvironmentSimulationConfig and ToolSimulationConfig, how to use InjectionConfig to probabilistically inject latency, errors, or predefined responses, and how to use LLM-based mock strategies (MockStrategy.MOCK_STRATEGY_TOOL_SPEC) for dynamic response generation. Explain that the ToolConnectionAnalyzer can automatically analyze stateful dependencies between tools (e.g., one tool creating an ID and another consuming it) to generate consistent mock data. Finally, show how to apply this feature to an agent using either a callback (EnvironmentSimulationFactory.create_callback) or an ADK plugin (EnvironmentSimulationPlugin). Add the new page to the MkDocs navigation.

Reasoning:
The v1.28.0 release introduces a brand-new Environment Simulation toolset and engine for mocking and manipulating tool execution environments. Proper user guide documentation is required for adoption.

Reference: src/google/adk/tools/environment_simulation/environment_simulation_config.py, src/google/adk/tools/environment_simulation/environment_simulation_engine.py, src/google/adk/tools/environment_simulation/environment_simulation_plugin.py

10. Regenerate API reference for Environment Simulation package

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API reference docs do not contain the newly added google.adk.tools.environment_simulation module.

Proposed Change:

Regenerate the Python API reference documentation to include the google.adk.tools.environment_simulation package, specifically EnvironmentSimulationConfig, ToolSimulationConfig, InjectionConfig, EnvironmentSimulationEngine, EnvironmentSimulationPlugin, and related enumerations and strategies.

Reasoning:
The entire environment_simulation module is new in v1.28.0 and provides public classes that need to be discoverable in the API reference.

Reference: src/google/adk/tools/environment_simulation/environment_simulation_config.py

11. Update API reference to reflect agent_simulator deprecation

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API reference documentation reflects the older implementation of google.adk.tools.agent_simulator.

Proposed Change:

Regenerate the Python API reference documentation to capture the deprecation warnings and aliasing updates in google.adk.tools.agent_simulator (such as AgentSimulatorConfig, AgentSimulatorFactory, etc., which now inherit from or point to google.adk.tools.environment_simulation).

Reasoning:
The agent_simulator package has been significantly refactored and deprecated in favor of environment_simulation. The API reference should reflect these deprecations to guide users to the new package.

Reference: src/google/adk/tools/agent_simulator/agent_simulator_config.py, src/google/adk/tools/agent_simulator/agent_simulator_engine.py, src/google/adk/tools/agent_simulator/agent_simulator_factory.py

12. Document --service_type option and default change for adk deploy gke

Doc file: docs/deploy/gke.md

Current state:

The table of "Arguments & Options" for adk deploy gke does not include --service_type. The "How It Works" section states "By default, this is a LoadBalancer service, which provisions a public IP address to expose your agent to the internet." The "Verifying Your Deployment" section assumes LoadBalancer behavior showing an EXTERNAL-IP.

Proposed Change:

1. Add --service_type to the arguments table, explaining it accepts ClusterIP (default) or LoadBalancer.
2. Update "How It Works" to explain that it defaults to ClusterIP (accessible only within the cluster), and --service_type=LoadBalancer is needed to provision a public IP.
3. Update "Verifying Your Deployment" to reflect that EXTERNAL-IP will be <none> by default unless --service_type=LoadBalancer was specified. Add the port-forwarding instruction (kubectl port-forward svc/<service-name> 8080:80) for testing when using ClusterIP.

Reasoning:
The v1.28.0 release changed the default behavior of adk deploy gke to use ClusterIP instead of LoadBalancer. The documentation needs to reflect this breaking change so users know how to expose their service externally or test it locally.

Reference: src/google/adk/cli/cli_deploy.py, src/google/adk/cli/cli_tools_click.py

13. Regenerate CLI reference for conformance and deploy commands

Doc file: docs/api-reference/cli/...

Current state:

The auto-generated CLI reference is missing the new streaming-mode positional argument for adk conformance record, the --streaming-mode option for adk conformance test, and the --service_type option for adk deploy gke. The help text for adk conformance record has broken examples that do not provide the now-required streaming-mode argument.

Proposed Change:

Regenerate the CLI reference documentation to capture changes to adk conformance and adk deploy commands. Make sure the newly added required positional argument streaming-mode is reflected.

Reasoning:
The CLI arguments have been updated. Auto-generated docs need a refresh to stay accurate and help users with the new required inputs for conformance testing.

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

14. Document concurrency handling in DatabaseSessionService

Doc file: docs/sessions/session.md

Current state:

The section on DatabaseSessionService explains that it uses a SQL database for storage and needs an async driver, but it does not mention how it handles concurrent requests.

Proposed Change:

Add a note or a sub-section on Concurrency. Explain that DatabaseSessionService now checks for stale sessions using optimistic concurrency control. If an application tries to append an event (append_event) to a session that has been modified elsewhere (e.g., by another concurrent worker) since it was loaded, it will raise a ValueError indicating the session is stale. Users must catch this error, reload the session (get_session), and retry.

Reasoning:
The v1.28.0 release introduces _storage_update_marker and strictly enforces that events are not appended to a stale session. This is a breaking behavioral change for applications doing concurrent modifications, so it must be documented to help users properly handle concurrent updates.

Reference: src/google/adk/sessions/database_session_service.py

15. Document the new lifespan argument for to_a2a

Doc file: docs/a2a/quickstart-exposing.md

Current state:

The to_a2a function documentation demonstrates how to expose a remote agent and supply an agent_card, but lacks details on managing application lifecycles (like startup/shutdown tasks).

Proposed Change:

Add a section demonstrating the new lifespan argument for the to_a2a wrapper. Include a code snippet showing how to use an @asynccontextmanager to perform setup (like DB initialization) and teardown around the agent execution, e.g.:

@asynccontextmanager
async def lifespan(app):
    app.state.db = await init_db()
    yield
    await app.state.db.close()

app = to_a2a(agent, lifespan=lifespan)

Reasoning:
The v1.28.0 release adds a lifespan parameter to the to_a2a function, allowing developers to safely initialize and clean up resources within the generated Starlette app. Documenting this helps users handle proper state initialization in A2A exposed agents.

Reference: src/google/adk/a2a/utils/agent_to_a2a.py

16. Regenerate API reference for A2A module changes

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API docs don't reflect the new signature of to_a2a or the deprecation/update to A2aAgentExecutor (which now defaults to the new implementation with use_legacy=False).

Proposed Change:

Regenerate the google.adk.a2a module API documentation to reflect the new lifespan argument in to_a2a and changes to A2aAgentExecutor initialization defaults.

Reasoning:
Public APIs in the a2a module have changed and the auto-generated docs must stay in sync with the codebase.

Reference: src/google/adk/a2a/utils/agent_to_a2a.py, src/google/adk/a2a/executor/a2a_agent_executor.py

17. Update AgentEngineSandboxCodeExecutor documentation for auto-creation

Doc file: docs/tools/google-cloud/code-exec-agent-engine.md

Current state:

The documentation states "You must set one of the following resource parameters:" and lists sandbox_resource_name and agent_engine_resource_name. The code examples show sandbox_resource_name as required.

Proposed Change:

1. Update the text to state that both sandbox_resource_name and agent_engine_resource_name are now optional. If neither is provided, the tool will automatically create a new Agent Engine using your default Google Cloud project (GOOGLE_CLOUD_PROJECT environment variable) and location (GOOGLE_CLOUD_LOCATION or default us-central1).
2. Update the code snippets to show that AgentEngineSandboxCodeExecutor() can be instantiated without arguments, while keeping the resource name arguments as optional explicit overrides.

Reasoning:
Release v1.28.0 adds auto-creation logic to AgentEngineSandboxCodeExecutor to simplify the developer onboarding experience. Users no longer need to manually provision an Agent Engine if they are okay with the defaults.

Reference: src/google/adk/code_executors/agent_engine_sandbox_code_executor.py

18. Regenerate API reference for code_executors module

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API docs don't reflect the new timeout_seconds parameter on BaseCodeExecutor and the updated UnsafeLocalCodeExecutor implementation.

Proposed Change:

Regenerate the google.adk.code_executors module API documentation to reflect the new timeout_seconds field on BaseCodeExecutor and its subclasses.

Reasoning:
The base class now supports a timeout which is specifically enforced via multiprocessing in UnsafeLocalCodeExecutor. This is part of the public API and should be documented.

Reference: src/google/adk/code_executors/base_code_executor.py, src/google/adk/code_executors/unsafe_local_code_executor.py

19. Regenerate API reference for DiscoveryEngineSearchTool updates

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API reference docs for DiscoveryEngineSearchTool do not include the new search_result_mode and location parameters or the SearchResultMode enum.

Proposed Change:

Regenerate the Python API reference documentation to include the new search_result_mode and location arguments for DiscoveryEngineSearchTool and the newly added SearchResultMode enum (CHUNKS, DOCUMENTS).

Reasoning:
The DiscoveryEngineSearchTool class was updated to support a search_result_mode parameter (with auto-detection between chunks and documents) and an explicit location override parameter. The public API has changed.

Reference: src/google/adk/tools/discovery_engine_search_tool.py

20. Document Anthropic reasoning (thinking blocks) support via LiteLLM

Doc file: docs/agents/models.md

Current state:

docs/agents/models.md discusses using Anthropic models via LiteLLM but doesn't mention support for Anthropic's reasoning features (thinking blocks).

Proposed Change:

In the "Using Cloud & Proprietary Models via LiteLLM" section where Anthropic is mentioned, add a note explaining that ADK now fully supports Anthropic's structured reasoning ("thinking blocks"). Explain that when using Claude models (like Claude 3.7 Sonnet) via LiteLLM, ADK automatically extracts and preserves the thinking_blocks and their signatures across tool call boundaries.

Reasoning:
The LiteLlm wrapper was updated to specifically detect Anthropic models and preserve their thinking_blocks signature format during multi-turn tool calling. This is a significant capability for users wanting to use Claude's new reasoning features with ADK.

Reference: src/google/adk/models/lite_llm.py

21. Document MCP Server Sampling support

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

Current state:

docs/tools-custom/mcp-tools.md explains how to initialize McpToolset with connection_params and tool_filter but does not mention the newly added MCP sampling capabilities.

Proposed Change:

Add a new sub-section explaining "MCP Server Sampling". Explain that McpToolset now accepts sampling_callback and sampling_capabilities parameters during initialization. This allows the ADK agent to support server-initiated sampling, a powerful MCP capability where the MCP server can request the client (the ADK agent) to perform LLM generations on its behalf.

Reasoning:
The v1.28.0 release introduces support for the MCP Sampling capability in McpToolset and MCPSessionManager. This is an important standard feature of the Model Context Protocol that users should be aware they can now use in ADK.

Reference: src/google/adk/tools/mcp_tool/mcp_toolset.py, src/google/adk/tools/mcp_tool/mcp_session_manager.py

22. Regenerate API reference for McpToolset sampling parameters

Doc file: docs/api-reference/python/...

Current state:

The auto-generated Python API docs for McpToolset and MCPSessionManager do not show the new sampling_callback and sampling_capabilities parameters.

Proposed Change:

Regenerate the Python API reference documentation to include the new sampling_callback and sampling_capabilities constructor arguments for McpToolset, MCPSessionManager, and SessionContext.

Reasoning:
The public API signature for McpToolset has changed to support MCP sampling, which must be reflected in the auto-generated API reference.

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

23. Document RestApiTool timeout behavior change

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

Current state:

docs/tools-custom/openapi-tools.md explains how RestApiTool executes API calls using HTTP but does not discuss timeouts.

Proposed Change:

Add a brief note in the "RestApiTool Functionality" or "Execution" section explaining that RestApiTool (which powers OpenAPIToolset) now executes HTTP requests with no timeout (timeout=None) by default. This change accommodates long-running web services but implies that developers should be aware that the agent will wait indefinitely if the external service hangs.

Reasoning:
The internal httpx.AsyncClient used by RestApiTool was updated to timeout=None, overriding the default 5-second httpx timeout. This is a significant behavioral change for users dealing with slow APIs or APIs that hang.

Reference: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py

24. Document agent naming constraints

Doc file: docs/get-started/python.md

Current state:

The "Create an agent project" sections in docs/get-started/python.md and docs/agents/config.md show how to create an agent (e.g., adk create my_agent) but do not mention naming constraints.

Proposed Change:

Add a note or warning explaining that the agent name (and its corresponding directory or Python file) must be a valid Python identifier. It can only contain letters, numbers, and underscores (e.g., my_agent_1). Names containing dashes or other special characters (like my-agent) will result in a loading error. Make sure to apply this update to docs/agents/config.md as well where adk create --type=config my_agent is discussed.

Reasoning:
The ADK CLI agent_loader now strictly enforces that agent names match ^[a-zA-Z0-9_]+$ to prevent arbitrary module imports and security vulnerabilities. Users must be aware of this constraint to avoid errors during adk run or adk web.

Reference: src/google/adk/cli/utils/agent_loader.py

25. Document A2A experimental warnings suppression environment variable

Doc file: docs/a2a/quickstart-exposing.md

Current state:

The A2A documentation does not mention the ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS environment variable.

Proposed Change:

Add a note to the A2A documentation, likely in a section on experimental features or advanced configuration, mentioning that the ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS environment variable can be set to true to suppress warnings related to experimental A2A features. Explain that this is useful for developers who are knowingly using these features and wish to have cleaner logs.

Reasoning:
A new environment variable was added to give developers control over experimental feature warnings. This should be documented for developers who work with experimental A2A features.

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

26. Review observability docs after agent version field removal

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

Current state:

The documentation may reference the version attribute on agents, which has been removed from BaseAgent and BaseAgentConfig.

Proposed Change:

Review the BigQuery agent analytics documentation to ensure that the agent identification is described correctly now that the version attribute has been removed from BaseAgent and BaseAgentConfig. The agent field in the BigQuery schema now seems to be the sole identifier. The documentation should be checked for any direct or indirect references to an agent version that is no longer available.

Reasoning:
The version attribute has been removed from the core agent classes. This is a significant change that could affect telemetry and observability. The documentation, especially for the BigQuery analytics plugin, should be updated to reflect that agents are now identified only by name, not by name and version.

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

27. Document new experimental feature SNAKE_CASE_SKILL_NAME

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

Current state:

No documentation exists for the SNAKE_CASE_SKILL_NAME experimental feature.

Proposed Change:

Add a new section for the experimental feature SNAKE_CASE_SKILL_NAME. Explain that this feature, when enabled, automatically converts skill names to snake_case. This is important for developers to be aware of, as it can affect how they name their tool functions and how the LLM interacts with them. Provide an example of how to enable the feature and the expected behavior. Since it's an experimental feature, also document that it's off by default and how to enable it.

Reasoning:
A new experimental feature SNAKE_CASE_SKILL_NAME has been added. This feature changes the naming convention of skills and is off by default. It needs to be documented so that users who want to use it know how to enable it and what its effects are. This is important for developers creating custom tools to avoid confusion and potential issues with tool calling.

Reference: src/google/adk/features/_feature_registry.py

28. Create documentation for the FilesRetrieval tool

Doc file: docs/tools/retrieval/files-retrieval.md (New File)

Current state:

No documentation exists for the FilesRetrieval tool.

Proposed Change:

Create a new documentation page for the FilesRetrieval tool. The documentation should explain that this tool allows an agent to perform retrieval over a local directory of files. It should detail how to initialize the tool, specifying the input_dir, and mention that the default embedding model has been updated to gemini-embedding-2-preview. An example of how to use this tool should be provided.

Reasoning:
The FilesRetrieval tool is a user-facing feature that is currently undocumented. Its default embedding model has also been changed in this release, which is a significant behavioral change that users need to be aware of. Creating a new documentation page will make this feature discoverable and usable for developers.

Reference: src/google/adk/tools/retrieval/files_retrieval.py