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

### 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 `` by default unless `--service_type=LoadBalancer` was specified. Add the port-forwarding instruction (`kubectl port-forward svc/ 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.:
> ```python
> @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