Merge branch 'main' into fix/memory-non-latin-search

Author: yodeee9

.agents/skills/adk-agent-builder/SKILL.md

@@ -5,27 +5,37 @@ description: Central hub for building, testing, and iterating on ADK agents. Tri
 
 # ADK Agent Builder
 
-This file serves as a directory of specialized reference guides for developing agents with ADK. To avoid context pollution, read only the relevant reference file based on your current task.
+This file serves as a directory of specialized reference guides for developing
+agents with ADK. To avoid context pollution, read only the relevant reference
+file based on your current task.
 
 ## Core Concepts Directory
 
 Refer to these files for foundational knowledge:
+
 - **Getting Started & Basic Agents**: [getting-started.md](references/getting-started.md)
   - Environment setup, API key configuration, and minimal agent definitions.
 - **Tool Catalog**: [tool-catalog.md](references/tool-catalog.md)
   - How to bind function tools, MCP tools, OpenAPI specs, and Google API tools.
 - **Agent Modes (Task / Single-Turn)**: [task-mode.md](references/task-mode.md)
   - Multi-turn structured delegation and autonomous single-turn execution patterns.
+-   **Import Paths**: [import-paths.md](references/import-paths.md)
+    -   Canonical and verbose import paths for core components, tools, and
+        events.
 
 ## Workflow & Graph Orchestration
 
 Refer to these files when building complex graphs:
+
 - **Function Nodes**: [function-nodes.md](references/function-nodes.md)
   - How to use functions as nodes, type resolution, and generators.
 - **Routing & Conditions**: [routing-and-conditions.md](references/routing-and-conditions.md)
   - Edge patterns, dict-based routing, self-loops, and conditional execution.
 - **LLM Agent Nodes**: [llm-agent-nodes.md](references/llm-agent-nodes.md)
   - How to use LLM agents as workflow nodes, task wrappers, and handling output schemas.
+-   **Advanced Patterns**:
+    [advanced-patterns.md](references/advanced-patterns.md)
+    -   Nested workflows, custom node types, and graph validation rules.
 
 ## Advanced Orchestration Patterns
 
@@ -40,6 +50,14 @@ Refer to these files when building complex graphs:
 
 - **State & Events**: [state-and-events.md](references/state-and-events.md)
   - Using context API, sharing global state, and yield event structures.
+-   **Session & Memory**:
+    [session-and-state.md](references/session-and-state.md)
+    -   Session state mutation, scope conventions, and database session
+        services.
+-   **Callbacks & Plugins**:
+    [callbacks-and-plugins.md](references/callbacks-and-plugins.md)
+    -   Implementing callbacks, plugin manager integration, and override
+        behavior.
 - **Multi-Agent Systems**: [multi-agent.md](references/multi-agent.md)
   - Hierarchical execution (e.g., `SequentialAgent`, `LoopAgent`, `ParallelAgent`).
 - **Testing Strategies**: [testing.md](references/testing.md)

.agents/skills/adk-sample-creator/SKILL.md

@@ -89,7 +89,7 @@ Each sample should have a `README.md` with the following structure:
 
 - **Overview**: What the sample does.
 - **Sample Inputs**: Examples of inputs to test with. Each prompt must be wrapped in backticks. If a prompt has an explanation, always add a blank line between the prompt and the explanation, and indent the explanation by two spaces.
-- **Graph**: Visualization of the graph flow (Mermaid recommended for workflows).
+- **Graph**: Visualization of the graph flow (Mermaid recommended). For Workflow root agents, visualize the graph flow of nodes. For LlmAgent root agents that orchestrate tools or sub-agents, visualize the topology of the agent and its tools/sub-agents instead of internal workflow nodes.
 - **How To**: Explanation of key techniques used (e.g., `ctx.run_node`).
 - **Related Guides**: Links to relevant developer guides in `docs/guides/` that explain the concepts or classes used.
 
@@ -112,11 +112,18 @@ Brief description.
 
 ## Graph
 
+For Workflow root agents:
 ```mermaid
 graph TD
     START --> MyNode
 ```
 
+For LlmAgent root agents:
+```mermaid
+graph TD
+    MyAgent[my_agent] -->|calls| MyTool(my_tool)
+```
+
 ## How To
 
 Explain the details.

.agents/skills/adk-unit-design/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: adk-unit-design
+description: Creates or updates code unit design documents for source code documentation.
+---
+
+# ADK Code Unit Design
+
+This skill creates or updates a detailed software engineering design document for new or updated code file or specified code unit. The design document it generates is meant to explain the code to a developer who wants to modify or extend the code unit as part of the ADK development framework. Similar to a *unit test*, a *unit design* provides a generated software engineering design based on the *actual, implemented code* rather than any proposed code design or proposed software architecture.
+
+## Input
+
+- Code files containing new functionality
+- Names of new methods and classes (optional)
+- Code files for base classes or interfaces that the new functionality depends on (optional)
+- Code unit tests (optional)
+- Example code files (optional)
+
+## Analysis
+
+- Review specified code files for changes and named methods to determine:
+  - Purpose and intended use of the new or updated code units
+  - Any data flows handled by the new or updated code units
+  - Dependencies required by the new or updated code units
+  - Approaches for extending or customizing the code unit to add new capabilities
+  - Classes that depend on the new or updated code units
+  - Operational limitations of the new or updated code units
+
+## Output
+
+- Look for an existing design document in the `/docs/design/***` directory of this repository.
+  - If a design already exists, update the existing design incrementally and prioritize preserving the previous content as much as possible.
+  - If no design document exists, create a design file for the new code unit in the `/docs/design/***` directory of this repository, using the relative path of the code unit. For example, if the code unit is called `/topic/function/class.ext`, create a design document in the location `/docs/design/topic/function/class/index.md`.
+- Any links to local code files should be translated to URL links to the `google/adk-python` repository on GitHub. For example, if the local code unit path is `***/adk-python/topic/function/class.ext#L93`, the URL to the code file should be `https://github.com/google/adk-python/blob/main/topic/function/class.ext#L93`.
+
+### Design document structure and content
+
+Use the following structure and instructions to create the design document for the code unit:
+
+```
+# (name of code unit or code file) - Code Unit Design
+
+- 2-sentence summary of the code unit
+
+## Introduction
+
+- Paragraph(s) explaining:
+  - The purpose and application of the code unit, including intended use cases
+  - Developer problems solved by this code unit
+  - Agent capabilities enabled by this code unit
+
+## High-level architecture
+
+- Describe the software architecture of this code unit and how it fits into the larger ADK framework
+- Explain general execution flow of this code unit
+- Describe any data flows handled by the code unit including inputs and outputs
+- Explain any cross-class dependencies of the code unit, including upstream dependencies and downstream dependencies
+
+### Extension points
+
+- Describe how the code unit could be extended or customized to add new features or capabilities
+- Note specific parts of the code unit that are designed to be extended or customized, including:
+  - Abstract classes
+  - Interfaces
+  - Hooks
+  - Callbacks
+  - Configurable parameters
+  - Plugin architecture
+  - Other extension points
+
+### Extension constraints
+
+- Describe what parts of the code unit should not be modified, based on:
+  - architectural constraints
+  - implementation limitations
+  - cross-class dependencies
+  - other constraints
+
+## Limitations
+
+- Mention any limitations of the code unit, if known, such as:
+  - input constraints
+  - data structure constraints
+  - output constraints
+  - performance limitations
+  - memory limitations
+  - other limitations
+
+```

.agents/skills/adk-unit-guide/SKILL.md

@@ -53,6 +53,7 @@ Use the following structure and instructions to create the guide for the code un
 - Use unit test code as a starting point for the code example, if available.
 - When writing a sample agent, do not set the `model` attribute.
 - For workflow node samples, prefer using a simple Python function rather than extending `BaseNode` to demonstrate the node's logic, unless class extension is explicitly required for the use case.
+- When wrapping Python functions as workflow nodes, prefer using the `@node` decorator instead of `FunctionNode` directly, whenever possible.
 
 ## How it works
 
@@ -64,6 +65,8 @@ Use the following structure and instructions to create the guide for the code un
 ## Configuration options
 
 - If the code unit has configuration options (e.g., settings, configuration objects), document them in a table detailing parameters, types, default values, and descriptions.
+- **Do NOT** list options inherited from base classes. Focus only on options introduced by the code unit itself.
+- Dive into each option to provide detailed description and usage patterns, rather than just repeating the type and a brief description.
 - **Do NOT** list references of all attributes or methods of the classes. Exhaustive API references belong in auto-generated reference documentation, not in guides. Guides should focus on how to use the code unit.
 
 ## Advanced applications

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.2.0"
+  ".": "2.3.0"
 }

.github/header-checker-lint.yml

@@ -1,3 +1,16 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 allowedCopyrightHolders:
   - 'Google LLC'
 allowedLicenses:
@@ -9,5 +22,7 @@ sourceFileExtensions:
   - 'js'
   - 'java'
   - 'py'
+  - 'yaml'
+  - 'yml'
 ignoreFiles:
   - 'src/google/adk/cli/browser/**'

.github/release-please-config-v1.json

@@ -25,7 +25,8 @@
         },
         {
           "type": "refactor",
-          "section": "Code Refactoring"
+          "section": "Code Refactoring",
+          "hidden": true
         },
         {
           "type": "docs",

.github/release-please-config.json

@@ -22,7 +22,8 @@
         },
         {
           "type": "refactor",
-          "section": "Code Refactoring"
+          "section": "Code Refactoring",
+          "hidden": true
         },
         {
           "type": "docs",
@@ -56,5 +57,5 @@
       ]
     }
   },
-  "last-release-sha": "cd81f7bde91df78d6cece539a6f98dda2aa8c9c0"
+  "last-release-sha": "0cb4c814928f579bfbac9b9e1f95669e4304e089"
 }

.github/workflows/analyze-releases-for-adk-docs-updates.yml

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 name: Analyze New Release for ADK Docs Updates
 
 on:
@@ -23,6 +37,7 @@ on:
 
 jobs:
   analyze-new-release-for-adk-docs-updates:
+    if: github.repository == 'google/adk-python'
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/block-merge.yml

@@ -16,10 +16,12 @@ name: Do Not Merge on GitHub
 
 on:
   pull_request:
+    branches: [main]
     types: [opened, reopened, synchronize]
 
 jobs:
   block-merge:
+    if: github.repository == 'google/adk-python'
     name: maintainers will submit via Copybara
     runs-on: ubuntu-latest
     steps: