Found docs updates needed from ADK python release v1.28.1 to v1.29.0

[adk-bot]

google/adk-python@v1.28.1...v1.29.0

1. Custom Authentication Schemes

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

Current state:

The docs/tools-custom/authentication.md document describes standard OpenAPI authentication schemes (API Key, HTTP, OAuth2, OpenID Connect) but does not mention how to implement custom authentication schemes or that OAuth2Auth supports a nonce.

Proposed Change:

1. Add a section explaining how to define custom authentication schemes by subclassing CustomAuthScheme (ensuring type_ has a default value).
2. Explain that custom auth providers can now define a supported_auth_schemes property (returning a tuple of scheme types) on their BaseAuthProvider implementation for easier registration.
3. Mention that OAuth2Auth now includes a nonce field, which can be used to securely bind the user's session to the authorization request during OIDC flows.

Reasoning:
The framework was expanded to support non-OpenAPI standard authentication flows via CustomAuthScheme and simplified provider registration. Documenting these features empowers developers to integrate with proprietary or legacy enterprise auth systems. The nonce addition is also an important security feature for OAuth/OIDC flows.

Reference: src/google/adk/auth/auth_schemes.py

2. BigQuery AI/ML Skills

Doc file: docs/integrations/bigquery.md

Current state:

The integrations/bigquery.md file describes the BigQuery tools like forecast and detect_anomalies as standalone tools, and does not mention the BigQuery Skill or how it integrates with AI/ML functions.

Proposed Change:

Update the documentation to introduce the new get_bigquery_skill() which provides the bigquery-ai-ml skill. Explain that agents should now PREFER using this skill (which guides the LLM to write standard SQL using AI.* functions like AI.FORECAST, AI.CLASSIFY, AI.DETECT_ANOMALIES, AI.GENERATE, etc., via the execute_sql tool) over using dedicated high-level BigQuery tools. Add a code example showing how to import get_bigquery_skill() and SkillToolset, and pass them together with BigQueryToolset into the agent.

Reasoning:
The new BigQuery AI/ML skill massively expands BigQuery AI capabilities directly through SQL. The internal guidance specifies that this skill-based approach using execute_sql is now preferred over using individual dedicated tools for tasks like anomaly detection or forecasting.

Reference: src/google/adk/tools/bigquery/skills/bigquery-ai-ml/SKILL.md

3. API Server Event Trigger Endpoints

Doc file: docs/runtime/api-server.md

Current state:

The docs/runtime/api-server.md document lists standard endpoints like /run, /run_sse, and /list-apps, but does not mention the new event trigger endpoints or the new app info endpoint.

Proposed Change:

Add a new section for "Event Trigger Endpoints" documenting POST /apps/{app_name}/trigger/pubsub and POST /apps/{app_name}/trigger/eventarc. Explain that these endpoints enable the server to directly process Pub/Sub push messages and Eventarc CloudEvents without requiring pre-created sessions. Mention that they include built-in concurrency limits (via semaphores) and automatic retries with exponential backoff for transient 429 errors. Also, add the new GET /apps/{app_name}/app-info endpoint to the utility endpoints section.

Reasoning:
These endpoints are a major new feature for batch and event-driven agent invocations. Users deploying to Cloud Run or running the API server need to know they can natively handle Pub/Sub and Eventarc webhooks.

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

4. Trigger Sources Deployment

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

Current state:

The deployment guides (docs/deploy/cloud-run.md and docs/deploy/gke.md) and API server docs do not list the --trigger_sources CLI flag.

Proposed Change:

Add --trigger_sources to the list of Options in the CLI deployment commands. Explain that it accepts a comma-separated list of trigger sources (e.g., pubsub,eventarc) to enable the /trigger/* webhook endpoints on the deployed server for event-driven agent invocations. (Make a similar update to docs/deploy/gke.md and the api_server command reference if applicable).

Reasoning:
This CLI flag is required to actually expose the new Pub/Sub and Eventarc webhook endpoints in production deployments, so it must be documented in the deployment guides.

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

5. Vertex AI Model Names

Doc file: docs/agents/models/vertex.md

Current state:

The documentation states how to use Vertex AI by setting environment variables and providing the base model name (like gemini-2.5-flash or claude-3-5-sonnet@20240620). It does not mention that fully qualified Vertex resource names are directly supported as model names.

Proposed Change:

Add a section or note explaining that developers can now pass fully qualified Vertex AI model or endpoint resource names (e.g., projects/YOUR_PROJECT/locations/YOUR_REGION/publishers/google/models/gemini-2.5-flash or projects/.../endpoints/YOUR_ENDPOINT_ID) directly into the model parameter when creating an Agent, a Gemini instance, or an Anthropic Claude instance. Explain that ADK will automatically parse the Project ID, Location, and base model name from this string, and properly configure the SDK client for Vertex AI mode without requiring external environment variables.

Reasoning:
This is a major quality-of-life and usability improvement that allows developers to seamlessly drop in Vertex AI endpoint strings directly into their code. This is particularly useful when working with Model Garden endpoints or switching between different projects.

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

6. AgentTool propagate_grounding_metadata

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

Current state:

The docs/tools-custom/function-tools.md document lists skip_summarization as the only customization attribute for AgentTool.

Proposed Change:

Add propagate_grounding_metadata: bool (default: False) to the list of AgentTool customization attributes in the "Agent-as-a-Tool" section. Explain that when set to True, the tool will automatically forward any grounding metadata (such as Google Search or Vertex AI Search citations) generated by the sub-agent up to the parent agent's session state. This ensures that citations are preserved when using specialized search agents as tools.

Reasoning:
The AgentTool was updated to support propagate_grounding_metadata, which drastically simplifies writing agents that delegate grounded searches to specialized sub-agents (as evidenced by the simplification of GoogleSearchAgentTool). Users building multi-agent systems with grounding need to know about this new attribute to retain citation data.

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

7. Environment Toolset

Doc file: docs/tools-custom/environment-toolset.md

Current state:

The Environment Toolset is a new feature in this release and currently has no documentation. It provides a structured way for agents to run shell commands and read/write files in an execution environment.

Proposed Change:

Create a new documentation page explaining the EnvironmentToolset. Describe the underlying BaseEnvironment and the provided LocalEnvironment. Detail the 4 core tools it provides to the agent: ExecuteTool, ReadFileTool, WriteFileTool, and EditFileTool. Include code examples showing how to instantiate a LocalEnvironment, pass it to the EnvironmentToolset, and assign the toolset to an agent. Additionally, explain that the toolset injects a specific system instruction (ENVIRONMENT_INSTRUCTION) to guide the LLM on using these tools properly.

Reasoning:
This is a major new feature highlighted in the release notes. Without documentation, users will not know how to empower their agents to execute local commands safely or interact with local file systems seamlessly.

Reference: src/google/adk/tools/environment/_environment_toolset.py

8. BigQuery Agent Analytics Plugin

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

Current state:

The BigQuery Agent Analytics plugin documentation describes configuration options like create_views but does not mention view_prefix. Additionally, the documentation explains how to avoid sensitive credentials using custom content formatters, but does not state that the plugin automatically redacts certain keys.

Proposed Change:

1. Add view_prefix (default: "v") to the list of BigQueryLoggerConfig parameters, explaining that it is used to prefix auto-created view names to prevent collisions when multiple plugin instances share a dataset.
2. Update the security/credential section to note that the plugin now automatically redacts sensitive keys (client_secret, access_token, refresh_token, id_token, api_key, password) and any state keys starting with temp: before they are logged to BigQuery.

Reasoning:
These are new features and configuration parameters added to the BigQueryAgentAnalyticsPlugin. Documenting the automatic redaction is particularly important so users know they have out-of-the-box protection for common credential fields.

Reference: src/google/adk/plugins/bigquery_agent_analytics_plugin.py

9. SkillToolset script execution

Doc file: docs/skills/index.md

Current state:

The docs/skills/index.md page explicitly states that script execution (scripts/ directory) is not supported and lists it as a known limitation.

Proposed Change:

Remove the warning block "Script execution not supported" and remove script execution from the "Known limitations" section. Instead, update the documentation to state that SkillToolset now supports running scripts from a skill's scripts/ directory via the run_skill_script tool. Mention that the executor now accepts command line arguments, including standard args (as a list or dict), short_options, and positional_args.

Reasoning:
The execute_script_async feature has been implemented and enhanced in skill_toolset.py, and the default system prompt now instructs the LLM to use run_skill_script to execute scripts. Keeping the "not supported" warning contradicts the newly added capabilities.

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

10. Visual Builder Security

Doc file: docs/visual-builder/index.md

Current state:

The Visual Builder documentation does not mention any security restrictions regarding the args key in uploaded YAML configurations.

Proposed Change:

Add a security note specifying that when uploading or providing YAML agent configurations (e.g., root_agent.yaml), the args key (used in CodeConfig.args or ToolConfig.args) is strictly blocked and will result in an upload error. Explain that this is a security measure to prevent arbitrary Remote Code Execution (RCE).

Reasoning:
A security check was added to fast_api.py that raises a ValueError if args is present anywhere in the YAML document during the build process. Users using the visual builder need to be aware of this restriction so their deployments/uploads do not unexpectedly fail.

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

11. Eval Scenario Generation

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

Current state:

The docs/evaluate/user-sim.md document explains how to add eval cases manually using adk eval_set add_eval_case but does not mention automated generation.

Proposed Change:

Add documentation for the new adk eval_set generate_eval_cases command. Explain that this command uses the Vertex AI Eval SDK (ScenarioGenerator) to dynamically generate a suite of conversation scenarios and automatically adds them to the specified eval set based on a user simulation config file. Provide an example of how to use it: adk eval_set generate_eval_cases <agent_path> <eval_set_id> --user_simulation_config_file <path>.

Reasoning:
This is a powerful new CLI capability that automates the tedious process of writing manual conversation scenarios for evaluation by leveraging an LLM to generate them.

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

12. Express Mode Onboarding

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

Current state:

The docs/get-started/python.md guide shows running adk create my_agent but does not mention the interactive backend selection prompt or the warnings.

Proposed Change:

Update the adk create instructions to explain the new interactive prompt: users can now choose between Google AI, Vertex AI, or "Login with Google". Explain that "Login with Google" uses Application Default Credentials (ADC) and can automatically provision a Vertex AI Express Mode project. Also, add a note echoing the CLI's new security warning: users must ensure the generated .env file is added to their .gitignore to prevent accidentally committing secrets like GOOGLE_API_KEY.

Reasoning:
The CLI creation flow has been significantly enhanced to streamline onboarding via Express Mode and improve security awareness regarding .env files. Users following the quickstart will encounter these prompts and should know what they mean.

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

13. Secret Manager Integration

Doc file: docs/integrations/secret-manager.md

Current state:

The documentation advises users to use Google Cloud Secret Manager for storing credentials, but there is no documentation on the new built-in ADK SecretManagerClient.

Proposed Change:

Create a new integration page for Google Cloud Secret Manager. Explain that ADK now includes a SecretManagerClient (google.adk.integrations.secret_manager.secret_client) which simplifies retrieving secrets. Provide an example of how to instantiate it (using ADC, an auth token, or a service account JSON string) and how to call get_secret(resource_name) to securely fetch API keys or tokens for use with ADK tools.

Reasoning:
This is a new official integration (mentioned in the release summary) that makes it much easier for developers to securely load credentials in production deployments without having to manually set up the standard GCP SDK clients.

Reference: src/google/adk/integrations/secret_manager/secret_client.py

14. Agent Registry Enhancements

Doc file: docs/integrations/agent-registry.md

Current state:

The AgentRegistry client has new capabilities that are currently undocumented, including endpoint retrieval and auth support for MCP toolsets.

Proposed Change:

Create (or update if a similar page exists) documentation for the Google Cloud Agent Registry integration. Explain that the AgentRegistry client now supports interacting with "Endpoints" via list_endpoints(), get_endpoint(), and get_model_name(). Additionally, document that get_mcp_toolset() now accepts auth_scheme and auth_credential parameters to attach authentication to the retrieved MCP toolset, and that get_remote_a2a_agent() supports custom httpx_client injection.

Reasoning:
These are major functional enhancements to how the ADK interacts with the Agent Registry service, particularly the ability to resolve model endpoints and apply authentication to dynamically loaded MCP toolsets.

Reference: src/google/adk/integrations/agent_registry/agent_registry.py