Found docs updates needed from ADK python release v1.21.0 to v1.22.0


[Compare link](https://github.com/google/adk-python/compare/v1.21.0...v1.22.0)

### 1. **New `DatabaseSessionService` schema and migration guide.**

**Doc file**: docs/upgrading/v1-22-0.md

**Current state**:
The file does not exist.

**Proposed Change**:
# Upgrading to v1.22.0: Database Schema Migration

<div class="language-support-tag">
  <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.22.0</span>
</div>

Starting with version 1.22.0, the `DatabaseSessionService` in the ADK for Python uses a new database schema (v1) that improves security and interoperability by switching from `pickle` to `JSON` for data serialization.

## What Changed?

The previous schema (v0) used Python's `pickle` to store `EventActions` objects in the database. While convenient, using `pickle` can pose a security risk if the data source is not trusted.

The new v1 schema addresses this by storing all event data, including `EventActions`, as `JSON`. This makes the stored data more secure, human-readable, and easier to integrate with other systems and languages.

The new schema also introduces a `adk_internal_metadata` table to track the schema version, which will simplify future migrations.

## Do I Need to Migrate?

If you are using `DatabaseSessionService` to store session data in a relational database (like SQLite, PostgreSQL, or MySQL) and you are upgrading from a version prior to 1.22.0, you **must** migrate your database to the new schema.

If you are starting a new project with v1.22.0 or later, or if you are using `InMemorySessionService` or `VertexAiSessionService`, you do not need to do anything.

## How to Migrate

The ADK provides a migration script to help you move your data from the old schema to the new one.

### 1. Before you begin

*   **Backup your database:** Before running the migration, create a backup of your existing database.
*   **Install the latest ADK:** Make sure you have upgraded to the latest version of the `google-adk` package:
    ```bash
    pip install --upgrade google-adk
    ```

### 2. Run the migration script

The migration script is located in `google.adk.sessions.migration.migrate_from_sqlalchemy_pickle`. You can run it from the command line:

```bash
python -m google.adk.sessions.migration.migrate_from_sqlalchemy_pickle \
    --source_db_url \"<your-old-database-connection-string>\" \
    --dest_db_url \"<your-new-database-connection-string>\"
```

*   `--source_db_url`: The SQLAlchemy connection string for your **existing** database.
*   `--dest_db_url`: The SQLAlchemy connection string for your **new** database. You can migrate to a new database or the same one. If you use the same database, the script will create new tables for the v1 schema.

For example, to migrate a local SQLite database:

```bash
python -m google.adk.sessions.migration.migrate_from_sqlalchemy_pickle \
    --source_db_url \"sqlite+aiosqlite:///./my_agent_data_v0.db\" \
    --dest_db_url \"sqlite+aiosqlite:///./my_agent_data_v1.db\"
```

The script will:
1.  Connect to both databases.
2.  Create the new v1 schema tables in the destination database.
3.  Copy and transform the data from the v0 tables to the v1 tables.
4.  Commit the changes to the destination database.

After the migration is complete, update your agent's configuration to use the new database connection string.


**Reasoning**:
The database schema for `DatabaseSessionService` has changed in v1.22.0, and users need a guide on how to migrate their existing data. The docstring of the new file `src/google/adk/sessions/schemas/v0.py` in the release mentions a non-existent file for upgrading, which indicates that this documentation is needed.

**Reference**: src/google/adk/sessions/migration/migrate_from_sqlalchemy_pickle.py

### 2. **Add a note to the `DatabaseSessionService` section about the v1.22.0 database schema change, the new `close()` method and link to the new migration guide.**

**Doc file**: docs/sessions/session.md

**Current state**:
The `DatabaseSessionService` section is minimal and does not mention schema versions, migration, or the `close()` method.

**Proposed Change**:
    <div class="admonition note">
    <p class="admonition-title">Database Schema Migration for v1.22.0</p>
    <p>Starting with v1.22.0, `DatabaseSessionService` uses a new, more secure database schema. If you are upgrading from a previous version, you will need to migrate your database. Please see the [Upgrading to v1.22.0 Guide](../upgrading/v1-22-0.md) for detailed instructions.</p>
    </div>

    It is recommended to close the `DatabaseSessionService` when it is no longer needed to release database connections. The service can be used as an async context manager to automatically handle closing the connection.

    ```python
    async with DatabaseSessionService(db_url=db_url) as session_service:
        # use the session service
        ...
    ```

    Alternatively, you can manually call the `close()` method:

    ```python
    session_service = DatabaseSessionService(db_url=db_url)
    # use the session service
    ...
    await session_service.close()
    ```


**Reasoning**:
Users of `DatabaseSessionService` need to be aware of the schema change and how to migrate their data. This note provides a clear pointer to the migration guide. Additionally, the new `close()` method and async context manager are important for proper resource management and should be documented.

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

### 3. **New Pub/Sub tools.**

**Doc file**: docs/tools/google-cloud/pubsub.md

**Current state**:
The file does not exist.

**Proposed Change**:
# Google Cloud Pub/Sub Tools

<div class="language-support-tag">
  <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.22.0</span>
</div>

The Pub/Sub toolset provides a set of tools for interacting with Google Cloud Pub/Sub, allowing your agents to publish messages to topics, and pull and acknowledge messages from subscriptions.

## Prerequisites

Before using the Pub/Sub tools, you need to:

1.  **Enable the Pub/Sub API** in your Google Cloud project.
2.  **Create a Pub/Sub topic and subscription.**
3.  **Set up authentication.** The tools require Google Cloud credentials to be configured. You can do this by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, or by running `gcloud auth application-default login`.

## Using the Pub/Sub Toolset

To use the Pub/Sub tools, you need to add the `PubSubToolset` to your agent's `tools` list.

```python
from google.adk.agents import LlmAgent
from google.adk.tools.pubsub import PubSubToolset

# Initialize the toolset
pubsub_toolset = PubSubToolset()

# Create an agent with the toolset
agent = LlmAgent(
    instruction="You are a helpful assistant with access to Pub/Sub tools.",
    tools=[pubsub_toolset],
)
```

The toolset includes the following tools:

*   `publish_message`: Publishes a message to a Pub/Sub topic.
*   `pull_messages`: Pulls messages from a Pub/Sub subscription.
*   `acknowledge_messages`: Acknowledges one or more messages from a subscription.

### `publish_message`

Publishes a message to the specified topic.

**Arguments:**

*   `topic_name` (str): The name of the Pub/Sub topic (e.g., `projects/my-project/topics/my-topic`).
*   `message` (str): The message content to publish.
*   `attributes` (Optional[dict[str, str]]): A dictionary of attributes to attach to the message.
*   `ordering_key` (str): An optional ordering key for the message.

**Returns:**

A dictionary containing the `message_id` of the published message.

### `pull_messages`

Pulls messages from the specified subscription.

**Arguments:**

*   `subscription_name` (str): The name of the Pub/Sub subscription (e.g., `projects/my-project/subscriptions/my-sub`).
*   `max_messages` (int): The maximum number of messages to pull. Defaults to 1.
*   `auto_ack` (bool): Whether to automatically acknowledge the messages. Defaults to `False`.

**Returns:**

A dictionary containing a list of pulled `messages`. Each message is a dictionary with the following keys:
* `message_id`
* `data`
* `attributes`
* `ordering_key`
* `publish_time`
* `ack_id`

### `acknowledge_messages`

Acknowledges one or more messages on a subscription.

**Arguments:**

*   `subscription_name` (str): The name of the Pub/Sub subscription.
*   `ack_ids` (list[str]): A list of acknowledgment IDs to acknowledge.

**Returns:**

A dictionary with the status of the operation (`SUCCESS` or `ERROR`).


**Reasoning**:
The new Pub/Sub tools need to be documented so that users can discover and use them. This new page provides a central place for this documentation.

**Reference**: src/google/adk/tools/pubsub/message_tool.py

### 4. **Add Pub/Sub tools to the Google Cloud and main tools indexes.**

**Doc file**: docs/tools/google-cloud/index.md, docs/tools/index.md

**Current state**:
The pages do not contain a card for Pub/Sub tools.

**Proposed Change**:
<a href="/adk-docs/tools/google-cloud/pubsub/" class="tool-card">
  <img src="/adk-docs/assets/tools-pubsub.png" alt="Pub/Sub">
  <div class="tool-card-content">
    <h3>Pub/Sub Tools</h3>
    <p>Publish and subscribe to message streams</p>
  </div>
</a>

**Reasoning**:
To make the new Pub/Sub tools discoverable, they need to be added to the tools index pages.

**Reference**: src/google/adk/tools/pubsub/pubsub_toolset.py

### 5. **New environment variables for local storage and `.env` file loading.**

**Doc file**: docs/reference/environment-variables.md

**Current state**:
The file does not exist.

**Proposed Change**:
# Environment Variables

You can use the following environment variables to configure the behavior of the Agent Development Kit (ADK).

| Variable | Description |
|---|---|
| `ADK_DISABLE_LOCAL_STORAGE` | If set to `1`, this variable disables the use of local storage for session and artifact services, forcing the use of in-memory services. This is useful for environments where local file storage is not available or desired. |
| `ADK_FORCE_LOCAL_STORAGE` | If set to `1`, this variable forces the use of local storage, even in environments where the ADK would normally default to in-memory services (like Cloud Run or Kubernetes). Use this with caution and ensure that the storage path is writable and persistent if needed. |
| `ADK_DISABLE_LOAD_DOTENV` | If set to `1`, this variable disables the loading of `.env` files. |
| `GOOGLE_APPLICATION_CREDENTIALS` | The path to your Google Cloud service account key file. This is used for authenticating with Google Cloud services. |
| `GOOGLE_CLOUD_PROJECT` | The ID of your Google Cloud project. |
| `GOOGLE_CLOUD_LOCATION` | The Google Cloud location (region) to use for services like Vertex AI. |


**Reasoning**:
The new environment variables for controlling local storage and `.env` file loading are a user-facing feature and should be documented. This new page provides a central place for all environment variables.

**Reference**: src/google/adk/cli/utils/service_factory.py, src/google/adk/cli/utils/envs.py

### 6. **Add a note to the Cloud Run and GKE deployment guides about local storage.**

**Doc file**: docs/deploy/cloud-run.md, docs/deploy/gke.md

**Current state**:
The guides do not mention the new local storage behavior.

**Proposed Change**:
<div class="admonition note">
<p class="admonition-title">Local Storage in Cloud Run/GKE</p>
<p>By default, the ADK will use in-memory storage for sessions and artifacts when it detects that it is running in a Cloud Run or Kubernetes environment. This is because the local filesystem is ephemeral and not suitable for persistent storage.</p>
<p>If you need to use local storage (for example, for temporary files), you can force the ADK to use it by setting the `ADK_FORCE_LOCAL_STORAGE=1` environment variable in your service configuration. However, for persistent storage, it is recommended to use a persistent volume and configure the `session_service_uri` and `artifact_service_uri` to point to a database or a GCS bucket.</p>
</div>


**Reasoning**:
Users deploying to Cloud Run or GKE need to be aware of the default in-memory storage behavior and how to override it if needed, as well as the recommended approach for persistent storage.

**Reference**: src/google/adk/cli/utils/service_factory.py

### 7. **New `custom_instructions` for `LlmBackedUserSimulatorConfig`.**

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

**Current state**:
The documentation does not mention the `custom_instructions` option.

**Proposed Change**:
    #### Custom Instructions

    You can provide custom instructions to the user simulator by setting the `custom_instructions` field in the `user_simulator_config`. This allows you to completely change the behavior of the user simulator.

    The custom instructions must be a string containing the following placeholders:
    * `{stop_signal}`: The text that the user simulator will output to signal the end of the conversation.
    * `{conversation_plan}`: The high-level conversation plan that the user simulator must follow.
    * `{conversation_history}`: The conversation history between the user and the agent so far.

    **Example `EvalConfig` entry:**

    ```json
    {
      "criteria": {
        ...
      },
      "user_simulator_config": {
        "model": "gemini-1.5-flash",
        "custom_instructions": "You are a very angry user. You are always complaining. The conversation plan is: {conversation_plan}. The conversation history is: {conversation_history}. When you are done, say '{stop_signal}'."
      }
    }
    ```


**Reasoning**:
The new `custom_instructions` option is a user-facing feature that should be documented. This will help users customize the user simulator for their specific needs.

**Reference**: src/google/adk/evaluation/simulation/llm_backed_user_simulator.py

### 8. **New `set_default_model` for `LlmAgent`.**

**Doc file**: docs/agents/llm-agents.md

**Current state**:
The documentation does not mention the `set_default_model` method.

**Proposed Change**:
    ### Setting a Default Model

    You can set a default model for all `LlmAgent` instances using the `set_default_model` class method. This is useful when you want to use the same model for all your agents without having to explicitly set it on each one.

    The default model is used when an agent does not have a model set and none of its ancestors have a model set. The built-in default model is `gemini-1.5-flash`.

    **Example:**

    ```python
    from google.adk.agents import LlmAgent

    # Set a default model for all agents
    LlmAgent.set_default_model("gemini-1.0-pro")

    # This agent will use the default model "gemini-1.0-pro"
    agent1 = LlmAgent(instruction="You are a helpful assistant.")

    # This agent will use the model "gemini-1.5-pro"
    agent2 = LlmAgent(
        instruction="You are a creative assistant.",
        model="gemini-1.5-pro"
    )
    ```


**Reasoning**:
The new `set_default_model` method is a user-facing feature that should be documented. This will help users configure a default model for their agents.

**Reference**: src/google/adk/agents/llm_agent.py

### 9. **New `override_feature_enabled` for feature flags.**

**Doc file**: docs/reference/feature-flags.md

**Current state**:
The file does not exist.

**Proposed Change**:
# Feature Flags

The Agent Development Kit (ADK) uses feature flags to enable or disable experimental or work-in-progress features. This allows you to try out new features before they are generally available, and it allows the ADK team to release new features gradually.

## Enabling and Disabling Features

You can enable or disable features in two ways:

1.  **Environment Variables:** You can use environment variables to enable or disable features. The environment variable name is constructed by prefixing the feature name with `ADK_ENABLE_` or `ADK_DISABLE_`. For example, to enable the `JSON_SCHEMA_FOR_FUNC_DECL` feature, you would set the following environment variable:

    ```bash
    export ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL=1
    ```

2.  **Programmatic Override:** You can programmatically override the enabled state of a feature using the `override_feature_enabled` function. This can be useful in environments where setting environment variables is not practical.

    ```python
    from google.adk.features import FeatureName, override_feature_enabled

    # Enable a feature programmatically
    override_feature_enabled(FeatureName.JSON_SCHEMA_FOR_FUNC_DECL, True)
    ```

Programmatic overrides have the highest priority, followed by environment variables, and then the default setting for the feature.

## Available Features

The following features are currently available:

| Feature Name | Description | Default |
|---|---|---|
| `JSON_SCHEMA_FOR_FUNC_DECL` | Use JSON schema for function declarations. | Off |
| `PROGRESSIVE_SSE_STREAMING` | Enable progressive Server-Sent Events (SSE) streaming. | On |
| `PUBSUB_TOOLSET` | Enable the Pub/Sub toolset. | On |
| `SPANNER_TOOLSET` | Enable the Spanner toolset. | On |
| `BIGTABLE_TOOLSET` | Enable the Bigtable toolset. | On |
| `BIGQUERY_TOOLSET` | Enable the BigQuery toolset. | On |
| `VERTEXAI_SEARCH_TOOL` | Enable the Vertex AI Search tool. | On |


**Reasoning**:
The new `override_feature_enabled` function is a user-facing feature that should be documented. This new page provides a central place for all information about feature flags.

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

### 10. **New `httpx_client_factory` for `McpToolset`.**

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

**Current state**:
The documentation for `McpToolset` does not mention the `httpx_client_factory` option.

**Proposed Change**:
    #### Advanced: Custom HTTPX Client

    For advanced use cases, you can provide a custom `httpx.AsyncClient` factory to the `StreamableHTTPConnectionParams`. This allows you to configure custom timeouts, transport, event hooks, and other `httpx` settings.

    The factory function should return an `httpx.AsyncClient` instance.

    ```python
    import httpx
    from google.adk.tools.mcp_tool import McpToolset
    from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

    def my_httpx_client_factory():
        return httpx.AsyncClient(timeout=10.0)

    toolset = McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="http://localhost:8080",
            httpx_client_factory=my_httpx_client_factory,
        )
    )
    ```


**Reasoning**:
The new `httpx_client_factory` option is a user-facing feature for advanced users and should be documented.

**Reference**: src/google/adk/tools/mcp_tool/mcp_session_manager.py

### 11. **New Enterprise Web Search tool.**

**Doc file**: docs/tools/google-cloud/enterprise-web-search.md

**Current state**:
The file does not exist.

**Proposed Change**:
# Enterprise Web Search Tool

<div class="language-support-tag">
  <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.22.0</span>
</div>

The Enterprise Web Search tool is a built-in tool that uses web grounding for enterprise compliance. It is important to note that this tool is **not** the same as the [Vertex AI Search tool](./vertex-ai-search.md), which is used to search over private enterprise documents.

The Enterprise Web Search tool is designed to ground the model's responses in web search results, which can be useful for ensuring that the model's responses are up-to-date and based on publicly available information.

## Prerequisites

To use the Enterprise Web Search tool, you need to be using a Gemini 2+ model.

## Using the Enterprise Web Search Tool

To use the Enterprise Web Search tool, you need to add it to your agent's `tools` list.

```python
from google.adk.agents import LlmAgent
from google.adk.tools import EnterpriseWebSearchTool

# Initialize the tool
enterprise_web_search_tool = EnterpriseWebSearchTool()

# Create an agent with the tool
agent = LlmAgent(
    instruction="You are a helpful assistant that can search the web for information.",
    tools=[enterprise_web_search_tool],
    model="gemini-1.5-pro-latest"
)
```

## Limitations

*   The Enterprise Web Search tool cannot be used with other tools in Gemini 1.x models.
*   The tool is only supported for Gemini 2+ models.


**Reasoning**:
The Enterprise Web Search tool is a new user-facing feature that should be documented. This new page provides a central place for this documentation.

**Reference**: src/google/adk/tools/enterprise_search_tool.py

### 12. **Regex support for `--allow-origins` in `adk web`.**

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

**Current state**:
The documentation for `adk web` does not mention regex support for `--allow-origins`.

**Proposed Change**:
    The `--allow-origins` option supports regular expressions for more flexible control over allowed origins. To use a regex, prefix the origin with `regex:`.

    For example, to allow all subdomains of `example.com`:

    ```bash
    adk web --allow-origins "regex:https://.*\\.example\\.com"
    ```


**Reasoning**:
The new regex support for CORS origins is a user-facing feature that should be documented. This will help advanced users who need more control over the allowed origins for the web server.

**Reference**: src/google/adk/cli/adk_web_server.py

### 13. **`custom_metadata` in `RunConfig`.**

**Doc file**: docs/runtime/runconfig.md

**Current state**:
The documentation for `RunConfig` is minimal and does not mention `custom_metadata`.

**Proposed Change**:
    ### `custom_metadata`

    You can use the `custom_metadata` field to attach custom metadata to the events generated during the agent run. This metadata can be used for logging, analytics, or any other custom purpose.

    The `custom_metadata` is a dictionary of key-value pairs. The keys and values can be any JSON-serializable type.

    **Example:**

    ```python
    from google.genai.adk import RunConfig

    config = RunConfig(
        custom_metadata={
            "user_tier": "premium",
            "request_id": "12345"
        }
    )

    async for event in runner.run_async(..., run_config=config):
        # event.custom_metadata will now contain the custom metadata
        print(event.custom_metadata)
    ```


**Reasoning**:
The new `custom_metadata` field in `RunConfig` is a user-facing feature that should be documented. This will help users understand how to attach custom metadata to events.

**Reference**: src/google/adk/runners.py

### 14. **Update `RunConfig` documentation for `StreamingMode`.**

**Doc file**: docs/runtime/runconfig.md

**Current state**:
The documentation for `StreamingMode` is minimal, just listing the enum values.

**Proposed Change**:
Replace the existing `streaming_mode` section with a more detailed one that includes the explanations and examples from the new docstrings.

**Reasoning**:
The new docstrings in `run_config.py` provide valuable information about the different streaming modes, especially `SSE` mode, which is not well-documented. This information will help users understand how to handle streaming events correctly.

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


Variable	Description
`ADK_DISABLE_LOCAL_STORAGE`	If set to `1`, this variable disables the use of local storage for session and artifact services, forcing the use of in-memory services. This is useful for environments where local file storage is not available or desired.
`ADK_FORCE_LOCAL_STORAGE`	If set to `1`, this variable forces the use of local storage, even in environments where the ADK would normally default to in-memory services (like Cloud Run or Kubernetes). Use this with caution and ensure that the storage path is writable and persistent if needed.
`ADK_DISABLE_LOAD_DOTENV`	If set to `1`, this variable disables the loading of `.env` files.
`GOOGLE_APPLICATION_CREDENTIALS`	The path to your Google Cloud service account key file. This is used for authenticating with Google Cloud services.
`GOOGLE_CLOUD_PROJECT`	The ID of your Google Cloud project.
`GOOGLE_CLOUD_LOCATION`	The Google Cloud location (region) to use for services like Vertex AI.

Feature Name	Description	Default
`JSON_SCHEMA_FOR_FUNC_DECL`	Use JSON schema for function declarations.	Off
`PROGRESSIVE_SSE_STREAMING`	Enable progressive Server-Sent Events (SSE) streaming.	On
`PUBSUB_TOOLSET`	Enable the Pub/Sub toolset.	On
`SPANNER_TOOLSET`	Enable the Spanner toolset.	On
`BIGTABLE_TOOLSET`	Enable the Bigtable toolset.	On
`BIGQUERY_TOOLSET`	Enable the BigQuery toolset.	On
`VERTEXAI_SEARCH_TOOL`	Enable the Vertex AI Search tool.	On

Found docs updates needed from ADK python release v1.21.0 to v1.22.0 #76

Description

1. New DatabaseSessionService schema and migration guide.

Upgrading to v1.22.0: Database Schema Migration

What Changed?

Do I Need to Migrate?

How to Migrate

1. Before you begin

2. Run the migration script

2. Add a note to the DatabaseSessionService section about the v1.22.0 database schema change, the new close() method and link to the new migration guide.

3. New Pub/Sub tools.

Google Cloud Pub/Sub Tools

Prerequisites

Using the Pub/Sub Toolset

publish_message

pull_messages

acknowledge_messages

4. Add Pub/Sub tools to the Google Cloud and main tools indexes.

Pub/Sub Tools

5. New environment variables for local storage and .env file loading.

Environment Variables

6. Add a note to the Cloud Run and GKE deployment guides about local storage.

7. New custom_instructions for LlmBackedUserSimulatorConfig.

8. New set_default_model for LlmAgent.

9. New override_feature_enabled for feature flags.

Feature Flags

Enabling and Disabling Features

Available Features

10. New httpx_client_factory for McpToolset.

11. New Enterprise Web Search tool.

Enterprise Web Search Tool

Prerequisites

Using the Enterprise Web Search Tool

Limitations

12. Regex support for --allow-origins in adk web.

13. custom_metadata in RunConfig.

14. Update RunConfig documentation for StreamingMode.

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

1. New `DatabaseSessionService` schema and migration guide.

2. Add a note to the `DatabaseSessionService` section about the v1.22.0 database schema change, the new `close()` method and link to the new migration guide.

`publish_message`

`pull_messages`

`acknowledge_messages`

5. New environment variables for local storage and `.env` file loading.

7. New `custom_instructions` for `LlmBackedUserSimulatorConfig`.

8. New `set_default_model` for `LlmAgent`.

9. New `override_feature_enabled` for feature flags.

10. New `httpx_client_factory` for `McpToolset`.

12. Regex support for `--allow-origins` in `adk web`.

13. `custom_metadata` in `RunConfig`.

14. Update `RunConfig` documentation for `StreamingMode`.