Found docs updates needed from ADK python release v1.24.1 to v1.25.0

[adk-bot]

Found docs updates needed from ADK python release v1.24.1 to v1.25.0

Compare Link: google/adk-python@v1.24.1...v1.25.0

1. Create documentation for the new Skills Framework and SkillToolset.

Doc file: docs/agents/skills.md

Current state:

(New feature, no existing documentation)

Proposed Change:

Create a new page documenting the Skills Framework.

Include:

• Concept: Explain that Skills are modular packages of instructions and resources that agents can load on demand.
• Structure: Detail the L1 (metadata), L2 (instructions), and L3 (resources) levels.
  • SKILL.md with frontmatter and body.
  • references/, assets/, scripts/ directories.
• Usage:
  • How to define a Skill using the Skill model.
  • How to use SkillToolset to expose skills to an agent.
  • How the load_skill and load_skill_resource tools work.
• Benefits: Modular design, context window optimization (loading instructions only when needed).

Reasoning:
The Skills Framework is a major new feature introducing a structured way to build agent capabilities. It requires dedicated documentation to explain the concepts and usage.

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

2. Link to the new Skills Framework documentation from the Agents index.

Doc file: docs/agents/index.md

Current state:

(Does not mention Skills)

Proposed Change:

Add a new section or link to the 'Skills Framework' page (docs/agents/skills.md).
Mention that agents can be extended with modular Skills using the SkillToolset.

Reasoning:
Users looking for agent capabilities should be able to find the Skills Framework documentation from the main Agents index.

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

3. Document the new Token-based Compaction feature in Context Compaction.

Doc file: docs/context/compaction.md

Current state:

The documentation only covers sliding window compaction using compaction_interval and overlap_size.

Proposed Change:

Add a new section 'Token-based Compaction'.
Explain that you can alternatively configure compaction based on the estimated token count of the session history.

• token_threshold: The token count that triggers compaction.
• event_retention_size: The number of recent raw events to keep uncompressed.
  Mention that if token-based compaction is configured and triggered, it takes precedence over sliding window compaction for that turn.
  Update the EventsCompactionConfig example to show these new parameters.

Reasoning:
The new token-based compaction feature allows for more dynamic context management based on actual token usage rather than just event count. Users need to know how to configure this.

Reference: src/google/adk/apps/compaction.py

4. Create documentation for the new Simple Prompt Optimizer.

Doc file: docs/agents/prompt-optimization.md

Current state:

(New feature, no existing documentation)

Proposed Change:

Create a new page documenting the SimplePromptOptimizer.
Include:

• Purpose: Iteratively improve agent system prompts using an LLM.
• How it works: Uses an optimizer LLM (default gemini-2.5-flash) to critique and rewrite the prompt based on evaluation scores.
• Usage:
  • Define an Agent and a Sampler (for evaluation).
  • Configure SimplePromptOptimizerConfig (num_iterations, batch_size).
  • Run optimizer.optimize(agent, sampler).
• Key Classes: SimplePromptOptimizer, SimplePromptOptimizerConfig.

Reasoning:
The Simple Prompt Optimizer is a new tool for improving agent performance. It needs documentation to help users leverage this capability.

Reference: src/google/adk/optimization/simple_prompt_optimizer.py

5. Document MCP Resource support in McpToolset.

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

Current state:

The documentation for McpToolset describes Connection Management, Tool Discovery, Exposure to Agent, Proxying Tool Calls, and Filtering. It does not mention MCP Resources support.

Proposed Change:

Add a new item to the McpToolset feature list:
"6. Resource Access (Optional): If configured with use_mcp_resources=True, the toolset injects a list of available resources into the system prompt and provides a load_mcp_resource tool for the agent to retrieve resource content."

Add a code example showing how to enable resources:

McpToolset(
    connection_params=...,
    use_mcp_resources=True
)

Explain that this allows the agent to see and read resources like files or data objects exposed by the MCP server.

Reasoning:
The use_mcp_resources parameter and LoadMcpResourceTool are new features that enable agents to access MCP resources, not just tools. This capability needs to be documented.

Reference: src/google/adk/tools/mcp_tool/mcp_toolset.py

6. Document adk conformance and adk api_server CLI commands.

Doc file: docs/runtime/command-line.md

Current state:

The documentation lists adk run command. It does not mention adk conformance commands or the api_server command.

Proposed Change:

Add sections for:

1. Conformance Testing (adk conformance):
   • adk conformance test: Explain how to run conformance tests.
   • Mention the new flags --generate_report and --report_dir to generate Markdown reports.
2. API Server (adk api_server):
   • Explain how to start the API server.
   • Mention the new --auto_create_session flag to simplify session management.

Reasoning:
New CLI commands and flags have been added (adk conformance, adk api_server). Users need to know how to use these tools, especially the new reporting and session creation features.

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

7. Document external_access_token_key for Google credentials.

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

Current state:

The documentation describes supported credential types (API_KEY, HTTP, OAUTH2, OPEN_ID_CONNECT, SERVICE_ACCOUNT). It doesn't mention the option to use an external access token stored in the session state.

Proposed Change:

Add a section "Using External Access Tokens".
Explain that for Google credentials, you can configure external_access_token_key to instruct the tool to retrieve an existing access token from tool_context.state instead of performing authentication itself.
This is useful when the agent is invoked in an environment where the user is already authenticated (e.g., a frontend passing the token).
Example:

AuthCredential(
    auth_type=AuthCredentialTypes.GOOGLE_CREDENTIALS,
    google_credentials_config=GoogleCredentialsConfig(
        external_access_token_key="my_access_token"
    )
)

Reasoning:
The external_access_token_key feature was added to BaseGoogleCredentialsConfig to allow using pre-existing access tokens from the session state. This is an important authentication pattern that needs documentation.

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

8. Document incremental memory updates and custom metadata support in MemoryService.

Doc file: docs/sessions/memory.md

Current state:

The documentation describes add_session_to_memory and search_memory as the primary methods. It doesn't mention add_events_to_memory or custom metadata support.

Proposed Change:

Add a section "Incremental Memory Updates".
Explain that add_events_to_memory(events=...) can be used to add specific events (deltas) to memory without re-ingesting the entire session. This is more efficient for long-running sessions.

Add a section "Custom Metadata (Vertex AI Memory Bank)".
Explain that VertexAiMemoryBankService now supports passing custom_metadata to add_session_to_memory and add_events_to_memory. This metadata is passed to the underlying Vertex AI Agent Engine API.
List supported metadata keys (e.g., ttl, revision_ttl).

Reasoning:
New features have been added to BaseMemoryService and VertexAiMemoryBankService to support incremental updates and custom metadata. These are important for performance and advanced configuration.

Reference: src/google/adk/memory/base_memory_service.py

9. Document concurrency and locking improvements in DatabaseSessionService.

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

Current state:

The documentation for DatabaseSessionService mentions it connects to relational databases and requires an async driver. It doesn't mention concurrency handling.

Proposed Change:

Add a note about Concurrency and Locking under the DatabaseSessionService section.
Explain that the service now implements internal locking (in-process) and uses row-level locking (for PostgreSQL, MySQL, MariaDB) to prevent race conditions when multiple requests try to update the same session simultaneously. This ensures data consistency in concurrent environments.

Reasoning:
Significant improvements were made to DatabaseSessionService to handle concurrency and locking, which is critical for production deployments. Users should be aware of these robustness features.

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