Found docs updates needed from ADK python release v1.15.0 to v1.15.1

[adk-bot]

I have analyzed the changes between ADK Python releases v1.15.0 and v1.15.1 and identified the following documentation updates that are needed.

Compare Link: google/adk-python@v1.15.0...v1.15.1

Here are the recommended changes:

1. New Feature: App Resumability

Summary: The ADK now supports pausing and resuming agent invocations. This is a major feature that needs to be documented.

Details: A new ResumabilityConfig has been added to the App model. When enabled, this feature allows an agent invocation to be paused upon a long-running function call and resumed at a later time. This is managed through a new BaseAgentState class and additions to the InvocationContext.

Proposed Change:

Add a new section in the documentation that covers the resumability feature. This section should include:

• An explanation of what resumability is and its use cases (e.g., human-in-the-loop).
• How to enable resumability by setting the resumability_config on the App object.
• A description of how agent state is managed using the BaseAgentState class and how to create custom agent states.
• An explanation of how the should_pause_invocation method in InvocationContext works and how it affects the lifecycle of different agent types (LlmAgent, SequentialAgent, ParallelAgent, LoopAgent).

Reasoning: This is a significant new feature that is not yet documented. Users need to be aware of this capability and how to use it.

Reference:

• src/google/adk/apps/app.py
• src/google/adk/agents/base_agent.py
• src/google/adk/agents/invocation_context.py

2. Enhancement: OAuth2 Auto-discovery

Summary: The configuration of OAuth2 has been simplified with the introduction of auto-discovery.

Details: A new ExtendedOAuth2 scheme is available that allows for the auto-discovery of authorizationUrl and tokenUrl via an issuer_url. This simplifies the setup for developers, as they no longer need to manually provide these URLs.

Proposed Change:

Update the docs/tools/authentication.md file to include:

• A new subsection that introduces the ExtendedOAuth2 scheme.
• An explanation of how to use the issuer_url to enable auto-discovery.
• A code example that contrasts the old manual configuration with the new auto-discovery method.

Current state:
The documentation only describes the manual way of configuring OAuth2 by providing authorizationUrl and tokenUrl.

Proposed Change:
Add a new section that explains the auto-discovery feature, for example:

Simplified OAuth2 Configuration with Auto-Discovery

To simplify the setup process, ADK now supports auto-discovery for OAuth2 endpoints. By using the ExtendedOAuth2 scheme and providing an issuer_url, you can let ADK automatically discover the authorizationUrl and tokenUrl from the provider's metadata.

Example:

from google.adk.auth.auth_schemes import ExtendedOAuth2

auth_scheme = ExtendedOAuth2(
    issuer_url="https://accounts.google.com",
    flows=OAuthFlows(...)
)

Reasoning: This enhancement simplifies the authentication process for developers and should be documented as the recommended approach.

Reference:

• src/google/adk/auth/auth_schemes.py
• src/google/adk/auth/credential_manager.py

3. Enhancement: Static Instruction with GCS/HTTPS Files

Summary: The LlmAgent now supports using GCS URIs and HTTPS URLs in file_data for static instructions with Vertex AI.

Details: When using Vertex AI, developers can now provide file_data in static instructions that point to files in Google Cloud Storage or any public HTTPS URL. This allows for more dynamic and powerful contextual information to be provided to agents.

Proposed Change:

Update the docs/agents/llm-agents.md file to add a new subsection under "Static Instructions" that explains this feature. The new section should include:

• A clear statement that this feature is available for Vertex AI.
• Examples of how to use gs:// URIs and https:// URLs in file_data.
• An explanation of how this can be used to provide dynamic content to agents.

Current state:
The documentation for static instructions does not mention the ability to use GCS or HTTPS URLs for file_data.

Proposed Change:
Add a new subsection with a title like "Using GCS and HTTPS Files in Static Instructions" with content similar to the following:

Using GCS and HTTPS Files in Static Instructions (Vertex AI)

When using Vertex AI, you can make your static instructions even more powerful by providing file_data that references files in Google Cloud Storage (GCS) or any public HTTPS URL. This allows you to include documents, images, or other data without needing to load them into memory first.

Example:

from google.genai import types
from google.adk.agents import LlmAgent

static_instruction_with_files = types.Content(
    parts=[
        types.Part(text="Please answer questions based on the provided document."),
        types.Part(
            file_data=types.FileData(
                file_uri="gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
                mime_type="application/pdf",
            )
        ),
    ]
)

agent = LlmAgent(
    model="gemini-1.5-pro-preview-0409",
    static_instruction=static_instruction_with_files,
)

Reasoning: This is a useful new feature that enhances the capabilities of static instructions. The documentation should be updated to reflect this.

Reference:

• contributing/samples/static_non_text_content/agent.py
• contributing/samples/static_non_text_content/README.md