Found docs updates needed from ADK python release v1.16.0 to v1.17.0

[adk-bot]

Between ADK Python releases v1.16.0 and v1.17.0, several new features, enhancements, and bug fixes have been introduced that require documentation updates.

You can see the full list of changes in the release comparison: https://github.com/google/adk-python/compare/v1.16.0...v1.17.0

Here are the detailed instructions for updating the ADK documentation:

New Features

1. ✨ New AgentEngineSandboxCodeExecutor for executing code in a sandbox. A new code executor, AgentEngineSandboxCodeExecutor, has been added to execute code using the Agent Engine Code Execution Sandbox. A new documentation section should be added to explain this feature.

   Proposed Change: In docs/tools/built-in-tools.md, add a new section for the AgentEngineSandboxCodeExecutor.

   ### Agent Engine Sandbox Code Executor
   
   The `AgentEngineSandboxCodeExecutor` provides a secure way to execute LLM-generated code within the Agent Engine Code Execution Sandbox. This is particularly useful for data analysis tasks.
   
   #### How to use
   
   1. Follow the instructions at https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/code-execution/overview to create a code execution sandbox environment.
   2. Replace `SANDBOX_RESOURCE_NAME` with the one you just created.
   
   **Example:**
   ```python
   from google.adk.agents.llm_agent import Agent
   from google.adk.code_executors.agent_engine_sandbox_code_executor import AgentEngineSandboxCodeExecutor
   
   root_agent = Agent(
       model="gemini-2.0-flash-001",
       name="agent_engine_code_execution_agent",
       instruction="<your instruction here>",
       code_executor=AgentEngineSandboxCodeExecutor(
           sandbox_resource_name="SANDBOX_RESOURCE_NAME",
           agent_engine_resource_name="AGENT_ENGINE_RESOURCE_NAME",
       ),
   )
   

   For a complete example, see the agent_engine_code_execution sample.

   
   **Reasoning**:
   This is a new feature that provides a secure way to execute code and needs to be documented for users.
   
   **Reference**:
   - `contributing/samples/agent_engine_code_execution/agent.py`
   
   

2. ✨ New ComputerUseToolset for browser automation. The ComputerUseToolset is a new toolset that allows agents to control a browser using Playwright to complete user tasks. A new documentation page should be created for this toolset.

   Proposed Change: Create a new file docs/tools/computer-use-toolset.md with the following content:

   # Computer Use Toolset
   
   The `ComputerUseToolset` allows an agent to operate a browser to complete user tasks. It uses Playwright to control a Chromium browser and can interact with web pages by taking screenshots, clicking, typing, and navigating.
   
   ## Setup
   
   1.  **Install Python Dependencies**:
       ```bash
       uv pip install -r internal/samples/computer_use/requirements.txt
       ```
   2.  **Install Playwright Dependencies**:
       ```bash
       playwright install-deps chromium
       ```
   3.  **Install Chromium Browser**:
       ```bash
       playwright install chromium
       ```
   
   ## Usage
   
   To use the `ComputerUseToolset`, you need to provide a `Computer` implementation. The `PlaywrightComputer` is provided for this purpose.
   
   **Example:**
   ```python
   from google.adk import Agent
   from google.adk.tools.computer_use.computer_use_toolset import ComputerUseToolset
   from .playwright import PlaywrightComputer
   
   root_agent = Agent(
       model='gemini-2.5-computer-use-preview-10-2025',
       name='computer_use_agent',
       description='A computer use agent that can operate a browser to finish user tasks.',
       instruction="you are a computer use agent",
       tools=[
           ComputerUseToolset(computer=PlaywrightComputer(screen_size=(1280, 936)))
       ],
   )
   

   For a complete example, see the computer_use sample.

   
   **Reasoning**:
   This is a major new feature that enables a whole new class of browser automation agents.
   
   **Reference**:
   - `contributing/samples/computer_use/agent.py`
   - `contributing/samples/computer_use/playwright.py`
   
   

3. ✨ New ReflectAndRetryToolPlugin for error recovery. The ReflectAndRetryToolPlugin provides a self-healing mechanism for tool failures by reflecting on errors and retrying with different arguments. A new documentation page should be created for this plugin.

   Proposed Change: Create a new file docs/plugins/reflect-and-retry.md with the following content:

   # Reflect and Retry Tool Plugin
   
   The `ReflectAndRetryToolPlugin` provides self-healing, concurrent-safe error recovery for tool failures.
   
   **Key Features:**
   - **Concurrency Safe**: Uses locking to safely handle parallel tool executions.
   - **Configurable Scope**: Tracks failures per-invocation (default) or globally.
   - **Granular Tracking**: Failure counts are tracked per-tool.
   - **Custom Error Extraction**: Supports detecting errors in normal tool responses.
   
   ## Basic Usage
   
   The following example shows how to use the plugin to retry a tool that can fail.
   
   ```python
   from google.adk.apps.app import App
   from google.adk.plugins import ReflectAndRetryToolPlugin
   
   app = App(
       name="my_app",
       root_agent=root_agent,
       plugins=[
           ReflectAndRetryToolPlugin(
               max_retries=6, throw_exception_if_retry_exceeded=False
           ),
       ],
   )
   

   For a complete example, see the plugin_reflect_tool_retry sample.

   
   **Reasoning**:
   This is a useful new plugin that improves the reliability of agents.
   
   **Reference**:
   - `contributing/samples/plugin_reflect_tool_retry/basic/agent.py`
   
   

4. ✨ New rewind_session feature. A new feature has been added to allow rewinding a session to a previous state. This should be documented in the sessions documentation.

   Proposed Change: In docs/sessions/index.md (or a more appropriate page), add a new section:

   ## Rewinding a Session
   
   You can rewind a session to a previous state using the `runner.rewind_async` method. This is useful for debugging or re-running parts of a conversation.
   
   **Example:**
   ```python
   await runner.rewind_async(
       user_id="test_user",
       session_id="test_session",
       rewind_before_invocation_id="<invocation_id>"
   )
   

   For a complete example, see the rewind_session sample.

   
   **Reasoning**:
   This is a new and powerful feature for session management that needs to be documented.
   
   **Reference**:
   - `contributing/samples/rewind_session/agent.py`
   
   

Feature Updates

5. 🚀 McpToolset now supports dynamic headers. The McpToolset now accepts a header_provider to dynamically generate headers for each MCP request.

   Proposed Change: In docs/tools/mcp-tools.md, add a subsection explaining the header_provider.

   Current state: The documentation for McpToolset does not mention header_provider.

   Proposed Change:

   ### Dynamic Headers with `header_provider`
   
   You can provide a `header_provider` to the `McpToolset` to dynamically generate headers for each request. This is useful for multi-tenancy or other scenarios where headers need to change based on the context.
   
   **Example:**
   ```python
   from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
   from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
   
   root_agent = LlmAgent(
       model='gemini-2.0-flash',
       name='tenant_agent',
       instruction="...",
       tools=[
           McpToolset(
               connection_params=StreamableHTTPConnectionParams(
                   url='http://localhost:3000/mcp',
               ),
               tool_filter=['get_tenant_data'],
               header_provider=lambda ctx: {'X-Tenant-ID': 'tenant1'},
           )
       ],
   )
   

   For a complete example, see the mcp_dynamic_header_agent sample.

   
   **Reasoning**:
   This is a new feature for `McpToolset` that enhances its capabilities.
   
   **Reference**:
   - `contributing/samples/mcp_dynamic_header_agent/agent.py`
   
   

6. 🚀 GoogleSearchTool and VertexAiSearchTool can now be used with other tools. The GoogleSearchTool and VertexAiSearchTool now have a bypass_multi_tools_limit parameter that allows them to be used with other tools in the same agent.

   Proposed Change: In docs/tools/built-in-tools.md, update the "Use Built-in tools with other tools" section and the "Limitations" section.

   Current state: The documentation states that built-in tools cannot be used with other tools in the same agent.

   Proposed Change: Update the documentation to explain the bypass_multi_tools_limit parameter and provide an example.

   ### Use Built-in tools with other tools
   
   You can now use `GoogleSearchTool` and `VertexAiSearchTool` with other tools by setting `bypass_multi_tools_limit=True`.
   
   **Example:**
   ```python
   from google.adk.tools.google_search_tool import GoogleSearchTool
   from google.adk.tools.vertex_ai_search_tool import VertexAiSearchTool
   
   root_agent = Agent(
       name="MyAgent",
       model="gemini-2.5-flash",
       tools=[
           my_custom_tool,
           GoogleSearchTool(bypass_multi_tools_limit=True),
           VertexAiSearchTool(data_store_id="my-data-store", bypass_multi_tools_limit=True),
       ],
   )
   

   The limitation about using only one built-in tool should be updated to reflect this change.

   
   **Reasoning**:
   This is an important update that removes a previous limitation of built-in tools.
   
   **Reference**:
   - `contributing/samples/built_in_multi_tools/agent.py`
   
   

7. 🚀 LlmAgent.static_instruction now supports types.ContentUnion. The static_instruction parameter of LlmAgent now accepts a wider range of types.

   Proposed Change: In docs/agents/llm-agents.md, update the description of static_instruction.

   Current state: The documentation may not fully describe the supported types for static_instruction.

   Proposed Change:

   **`static_instruction` (Optional[types.ContentUnion]):** Static instruction content sent literally as system instruction.
   ...
   **Content Support:**
   Accepts `types.ContentUnion` which includes:
   - `str`: Simple text instruction
   - `types.Content`: Rich content object
   - `types.Part`: Single part (text, inline_data, file_data, etc.)
   - `PIL.Image.Image`: Image object
   - `types.File`: File reference
   - `list[PartUnion]`: List of parts
   

   Reasoning: To accurately reflect the enhanced capabilities of the static_instruction parameter.

   Reference:

   • src/google/adk/agents/llm_agent.py

8. 🚀 RunConfig now supports context_window_compression. A new attribute context_window_compression has been added to RunConfig.

   Proposed Change: In docs/runtime/runconfig.md, add the new attribute to the table and provide a description.

   Current state: context_window_compression is not documented.

   Proposed Change:

   | `context_window_compression` | `Optional[types.ContextWindowCompressionConfig]` | | `None` | Configuration for context window compression. |
   

   Reasoning: To document the new context_window_compression feature.

   Reference:

   • src/google/adk/agents/run_config.py

9. 🚀 Artifact Service has new methods. The BaseArtifactService now includes list_artifact_versions and get_artifact_version methods.

   Proposed Change: In docs/artifacts/index.md, update the "Artifact Service (BaseArtifactService)" section.

   Current state: The documentation for BaseArtifactService is missing the new methods.

   Proposed Change:

   * `list_artifact_versions`: Lists all versions and their metadata for a specific artifact.
   * `get_artifact_version`: Gets the metadata for a specific version of an artifact.
   

   Reasoning: To keep the API documentation for BaseArtifactService up to date.

   Reference:

   • src/google/adk/artifacts/base_artifact_service.py

10. 📝 Docstrings added to LangChain tools. The docstrings in the langchain_structured_tool_agent sample have been updated.

    Proposed Change: In docs/tools/third-party/index.md, ensure the example code for LangChain tools includes the new docstrings.

    Reasoning: To provide better documentation and examples for using LangChain tools.

    Reference:

    • contributing/samples/langchain_structured_tool_agent/agent.py

11. ⚙️ Model name updates. Numerous occurrences of gemini-2.0-flash should be updated to gemini-2.5-flash.

    Proposed Change: Globally replace gemini-2.0-flash with gemini-2.5-flash in the documentation where appropriate, to reflect the use of the newer model.

    Reasoning: To keep the documentation current with the recommended models.

    Reference:

    • llms-full.txt (and many other files)

[joefernandez]

In progress: Reviewing these suggestions and associated updates.