Found docs updates needed from ADK python release v1.15.0 to v1.15.1
- Dominant language
- Shell
- Stars
- 1.5k
- Forks
- 1.3k
- Avg merge
- 7d 1h
- Merged PRs (30d)
- 34
Description
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**: https://github.com/google/adk-python/compare/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:**
>
> ```python
> 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:**
>
> ```python
> 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`
Contributor guide
Assessment
This issue has not been assessed yet.