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

[xuanyang15]

Compare v1.21.0...v1.22.0

1. Create new documentation for the experimental Pub/Sub toolset.

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

Current state:

File does not exist.

Proposed Change:

Google Cloud Pub/Sub Tool

The ADK provides a toolset for interacting with Google Cloud Pub/Sub. This toolset is experimental and may change in the future.

Features

• Publish messages to a Pub/Sub topic.
• Pull messages from a Pub/Sub subscription.
• Acknowledge messages from a Pub/Sub subscription.

Configuration

To use the Pub/Sub toolset, you need to configure it in your agent.

PubSubToolConfig

This class is used to configure the Pub/Sub tools.

• project_id (Optional[str]): The GCP project ID to use for the Pub/Sub operations. If not set, the project ID will be inferred from the environment or credentials.

PubSubCredentialsConfig

This class is used to configure the credentials for the Pub/Sub toolset. It inherits from BaseGoogleCredentialsConfig and sets the default OAuth scope to https://www.googleapis.com/auth/pubsub.

Usage

The PubSubToolset provides the following tools:

publish_message

Publishes a message to a Pub/Sub topic.

Arguments:

• topic_name (str): The Pub/Sub topic name (e.g. projects/my-project/topics/my-topic).
• message (str): The message content to publish.
• attributes (Optional[dict[str, str]]): Attributes to attach to the message.
• ordering_key (str): Ordering key for the message.

Returns:

• dict: A dictionary with the message_id of the published message.

pull_messages

Pulls messages from a Pub/Sub subscription.

Arguments:

• subscription_name (str): The Pub/Sub subscription name (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:

• dict: A dictionary with the list of pulled messages.

acknowledge_messages

Acknowledges messages on a Pub/Sub subscription.

Arguments:

• subscription_name (str): The Pub/Sub subscription name (e.g. projects/my-project/subscriptions/my-sub).
• ack_ids (list[str]): List of acknowledgment IDs to acknowledge.

Returns:

• dict: A dictionary with the status of the operation.

Reasoning:

This is a new experimental feature that is not yet documented. Users will need to know how to configure and use this new toolset.

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

2. Create new documentation for the database session migration feature.

Doc file: docs/guides/database-session-migration.md

Current state:

File does not exist.

Proposed Change:

Database Session Migration

The ADK provides a tool to migrate your session database from an older schema to the latest version. This is necessary when there are breaking changes to the database schema.

When to Migrate

You should migrate your database when you upgrade to a new version of the ADK that includes a new database schema. The ADK will log a warning if it detects an outdated schema.

How to Migrate

The migration is performed using the adk migrate session command.

adk migrate session --source_db_url <SOURCE_DB_URL> --dest_db_url <DEST_DB_URL>

Arguments:

• --source_db_url (str): The SQLAlchemy URL of the database to migrate from.
• --dest_db_url (str): The SQLAlchemy URL of the database to migrate to. This must be different from the source URL, as in-place migration is not supported.

Example:

adk migrate session --source_db_url sqlite:///old_sessions.db --dest_db_url sqlite:///new_sessions.db

Migration Path

The migration tool supports upgrading from schema version 0 (pickle-based) to version 1 (JSON-based). If multiple migration steps are required in the future, the tool will handle them automatically, using temporary SQLite databases for intermediate steps if necessary.

Reasoning:

This is a new feature that allows users to migrate their session database to the latest schema. This is a critical workflow for users who are upgrading their ADK version and have existing session data. The documentation should explain how to use the migration tool and what to expect from the process.

Reference: src/google/adk/sessions/migration/migration_runner.py

3. Document the new local storage options for deployment commands.

Doc file: docs/deploy/cloud-run.md

Current state:

The documentation for adk deploy cloud_run, adk deploy gke, and adk deploy agent_engine does not mention the --use_local_storage flag or the new default behavior for session and artifact storage.

Proposed Change:

Add a new section to docs/deploy/cloud-run.md, docs/deploy/gke.md, and docs/deploy/agent-engine/deploy.md that explains the new local storage behavior. This section should cover the following points:

• By default, when deploying to Cloud Run or GKE, the ADK now uses in-memory session and artifact services to avoid issues with non-writable file systems.
• The --use_local_storage flag can be used to force the use of local .adk storage in the container.
• The --no_use_local_storage flag can be used to explicitly disable local storage.
• The ADK_FORCE_LOCAL_STORAGE and ADK_DISABLE_LOCAL_STORAGE environment variables can be used to override the default behavior.

Also, update the command documentation for adk deploy cloud_run, adk deploy gke, and adk deploy agent_engine to include the --use_local_storage and --no_use_local_storage flags.

Reasoning:

The new local storage behavior is a significant change that affects how agents are deployed. Users need to be aware of the new defaults and how to control them using the new flags and environment variables. This will help them avoid unexpected behavior and configure their deployments correctly.

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

4. Document new local storage and CORS options for CLI commands.

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

Current state:

The documentation for adk run, adk web, and adk api_server does not mention the --use_local_storage flag or the regex support for --allow_origins.

Proposed Change:

Update the get-started/python.md and runtime/api-server.md files to include the following information:

• In the sections for adk run, adk web, and adk api_server, add a description of the --use_local_storage/--no_use_local_storage flags. Explain that these flags control whether to use local .adk storage or in-memory services for session and artifact storage. Explain the default behavior for each command.
• Add a note about the ADK_FORCE_LOCAL_STORAGE and ADK_DISABLE_LOCAL_STORAGE environment variables and how they can be used to override the default local storage behavior.
• In the section for adk web, update the description of the --allow_origins flag to mention that it now supports regex patterns prefixed with regex:.

Reasoning:

The new local storage options provide more control over how session and artifact data is stored, which is especially important when deploying agents to different environments. The regex support for CORS origins is a useful feature for developers who need more flexible security policies. These new features need to be documented so that users can take advantage of them.

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

5. Update evaluation criteria documentation with more detailed descriptions.

Doc file: docs/evaluate/criteria.md

Current state:

The table of evaluation criteria provides only a brief description for each metric. The detailed descriptions for each metric are also brief and could be more descriptive.

Proposed Change:

Update the descriptions for each metric in docs/evaluate/criteria.md to be more detailed, using the descriptions from the MetricInfoProvider classes in src/google/adk/evaluation/metric_info_providers.py. Also, add a more detailed description for the new per_turn_user_simulator_quality_v1 metric.

Reasoning:

The new MetricInfoProvider classes provide more detailed and useful descriptions for each of the evaluation metrics. Updating the documentation with these descriptions will make it easier for users to understand what each metric does and when to use it. The new per_turn_user_simulator_quality_v1 metric is a complex new feature, and it requires detailed documentation to be used effectively.

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

6. Document the new custom_instructions field for the user simulator.

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

Current state:

The "User simulator configuration" section only documents the model, model_configuration, and max_allowed_invocations fields.

Proposed Change:

Add a new sub-section under "User simulator configuration" to document the custom_instructions field in LlmBackedUserSimulatorConfig. This new section should explain that users can provide their own prompt template for the user simulator, and it should specify the required placeholders ({stop_signal}, {conversation_plan}, {conversation_history}). An example of how to use custom_instructions in the EvalConfig should also be provided.

Reasoning:

A new custom_instructions field has been added to LlmBackedUserSimulatorConfig, which allows users to provide their own prompt template for the user simulator. This is a significant new feature that gives users more control over the user simulator's behavior, and it needs to be documented so that users know how to use it.

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

7. Document the new set_default_model class method and default model behavior for LlmAgent.

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

Current state:

The documentation for LlmAgent does not mention the set_default_model class method or the new default model behavior.

Proposed Change:

Add a new section to docs/agents/llm-agents.md that explains the new set_default_model class method. This section should explain how to use this method to override the default model for all LlmAgent instances that do not have a model explicitly set. It should also mention the default model is gemini-2.5-flash.

Also, update the description of the model parameter to mention that if no model is set on the agent or its ancestors, it will use the default model configured via LlmAgent.set_default_model.

Reasoning:

The new set_default_model class method provides a convenient way to configure the default model for all agents. This is a significant new feature that gives users more control over their agents' behavior and should be documented.

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

8. Update streaming documentation with detailed explanations of StreamingMode.

Doc file: docs/runtime/runconfig.md

Current state:

The documentation for StreamingMode in runtime/runconfig.md and the streaming dev guide is very brief and does not explain the different modes in detail.

Proposed Change:

Update the docs/runtime/runconfig.md file to include the detailed explanations of the StreamingMode enum from the src/google/adk/agents/run_config.py file. This should include the explanations for NONE, SSE, and BIDI modes, the code examples, and the information about the ADK_ENABLE_PROGRESSIVE_SSE_STREAMING environment variable.

Also, update the streaming dev guide (docs/streaming/dev-guide/part4.md) to include this new information, or a link to the updated runconfig.md page.

Reasoning:

The new docstrings for the StreamingMode enum provide a wealth of information that is critical for users to understand how to properly use streaming in their agents. This information needs to be included in the documentation to avoid confusion and to help users build robust streaming applications.

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