Merge branch 'main' into test/loop-agent-peer-transfer-regression

Author: rohityan

.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
+
+```

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

@@ -37,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:

.github/workflows/continuous-integration.yml

@@ -67,6 +67,8 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
 
       - name: Generate Baseline
         env:
@@ -114,7 +116,7 @@ jobs:
             echo "Great job! No new mypy errors introduced."
           fi
 
-  # 3. Unit testing (Unit Tests with Matrix)
+  # 3a. Unit testing (Unit Tests with Matrix)
   unit-test:
     name: Unit Tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
@@ -134,6 +136,8 @@ jobs:
 
       - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: |
@@ -149,128 +153,42 @@ jobs:
             --ignore=tests/unittests/artifacts/test_artifact_service.py \
             --ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py
 
-  # 4. Custom file content compliance checks (PR only)
-  compliance-check:
-    name: File Content Compliance
+  # 3b. Dual-version A2A coverage: This job pins a2a-sdk to 0.3.x and
+  # runs only the A2A-related tests, so the a2a/_compat.py shim stays
+  # verified against both SDK majors.
+  # TODO: Remove this 0.3.x re-run once a2a-sdk 0.3.x support is dropped.
+  unit-test-a2a-v0-3:
+    name: A2A v0.3 Tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    timeout-minutes: 10
     steps:
-      - name: Checkout Code
+      - name: Checkout code
         uses: actions/checkout@v6
-        with:
-          # Fetch full history (depth: 0) instead of shallow clone (depth: 2) to ensure
-          # git diff origin/${base_ref}...HEAD can reliably find the merge base,
-          # preventing fatal git errors on deep PRs or when the target branch has progressed.
-          fetch-depth: 0
 
-      - name: Check for logger pattern in all changed Python files
-        run: |
-          git fetch origin ${GITHUB_BASE_REF}
-          CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' || true)
-          if [ -n "$CHANGED_FILES" ]; then
-            echo "Changed Python files to check:"
-            echo "$CHANGED_FILES"
-            echo ""
-
-            # Check for 'logger = logging.getLogger(__name__)' in changed .py files.
-            set +e
-            FILES_WITH_FORBIDDEN_LOGGER=$(grep -lE 'logger = logging\.getLogger\(__name__\)' $CHANGED_FILES)
-            GREP_EXIT_CODE=$?
-            set -e
-
-            if [ $GREP_EXIT_CODE -eq 0 ]; then
-              echo "❌ Found forbidden use of 'logger = logging.getLogger(__name__)'. Please use 'logger = logging.getLogger('google_adk.' + __name__)' instead."
-              echo "The following files contain the forbidden pattern:"
-              echo "$FILES_WITH_FORBIDDEN_LOGGER"
-              exit 1
-            elif [ $GREP_EXIT_CODE -eq 1 ]; then
-              echo "✅ No instances of 'logger = logging.getLogger(__name__)' found in changed Python files."
-            fi
-          else
-            echo "✅ No relevant Python files found."
-          fi
-
-      - name: Check for import pattern in certain changed Python files
-        run: |
-          git fetch origin ${GITHUB_BASE_REF}
-          CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' | grep -v -E '__init__.py$|version.py$|tests/.*|contributing/samples/' || true)
-          if [ -n "$CHANGED_FILES" ]; then
-            echo "Changed Python files to check:"
-            echo "$CHANGED_FILES"
-            echo ""
-
-            # Use grep -L to find files that DO NOT contain the pattern.
-            FILES_MISSING_IMPORT=$(grep -L 'from __future__ import annotations' $CHANGED_FILES || true)
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
 
-            if [ -z "$FILES_MISSING_IMPORT" ]; then
-              echo "✅ All modified Python files include 'from __future__ import annotations'."
-              exit 0
-            else
-              echo "❌ The following files are missing 'from __future__ import annotations':"
-              echo "$FILES_MISSING_IMPORT"
-              echo "This import is required to allow forward references in type annotations without quotes."
-              exit 1
-            fi
-          else
-            echo "✅ No relevant Python files found."
-          fi
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
 
-      - name: Check for import from cli package in certain changed Python files
+      - name: Install dependencies
         run: |
-          git fetch origin ${GITHUB_BASE_REF}
-          CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' | grep -v -E 'cli/.*|src/google/adk/tools/apihub_tool/apihub_toolset.py|tests/.*|contributing/samples/' || true)
-          if [ -n "$CHANGED_FILES" ]; then
-            echo "Changed Python files to check:"
-            echo "$CHANGED_FILES"
-            echo ""
-
-            set +e
-            FILES_WITH_FORBIDDEN_IMPORT=$(grep -lE '^from.*\bcli\b.*import.*$' $CHANGED_FILES)
-            GREP_EXIT_CODE=$?
-            set -e
-
-            if [[ $GREP_EXIT_CODE -eq 0 ]]; then
-              echo "❌ Do not import from the cli package outside of the cli package. If you need to reuse the code elsewhere, please move the code outside of the cli package."
-              echo "The following files contain the forbidden pattern:"
-              echo "$FILES_WITH_FORBIDDEN_IMPORT"
-              exit 1
-            else
-              echo "✅ No instances of importing from the cli package found in relevant changed Python files."
-            fi
-          else
-            echo "✅ No relevant Python files found."
-          fi
+          uv venv .venv
+          source .venv/bin/activate
+          uv sync --extra test
 
-      - name: Check for hardcoded googleapis.com endpoints
+      - name: Run A2A tests against a2a-sdk v0.3
         run: |
-          git fetch origin ${GITHUB_BASE_REF}
-          CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' || true)
-          if [ -n "$CHANGED_FILES" ]; then
-            echo "Checking for hardcoded endpoints in: $CHANGED_FILES"
-
-            # 1. Identify files containing any googleapis.com URL.
-            set +e
-            FILES_WITH_ENDPOINTS=$(grep -lE 'https?://[a-zA-Z0-9.-]+\.googleapis\.com' $CHANGED_FILES)
-
-            # 2. From those, identify files that are MISSING the required mTLS version.
-            if [ -n "$FILES_WITH_ENDPOINTS" ]; then
-              FILES_MISSING_MTLS=$(grep -L '.mtls.googleapis.com' $FILES_WITH_ENDPOINTS)
-            fi
-            set -e
-
-            if [ -n "$FILES_MISSING_MTLS" ]; then
-              echo "❌ Found hardcoded googleapis.com endpoints without mTLS support."
-              echo "The following files must define both standard and mTLS (.mtls.googleapis.com) endpoints"
-              echo "to support dynamic endpoint selection as required by security policy:"
-              echo "$FILES_MISSING_MTLS"
-              echo ""
-              echo "To fix this, please follow these steps:"
-              echo "1. Initialize an AuthorizedSession with your credentials."
-              echo "2. Use 'mtls.has_default_client_cert_source() from google-auth' to check for available client certificates."
-              echo "3. If certificates are present, use 'session.configure_mtls_channel()'."
-              echo "4. Dynamically select the '.mtls.' variant of the endpoint when mTLS is active."
-              exit 1
-            else
-              echo "✅ All hardcoded endpoints have corresponding mTLS definitions or no endpoints found."
-            fi
-          fi
+          source .venv/bin/activate
+          uv pip install --reinstall-package a2a-sdk 'a2a-sdk>=0.3.4,<0.4'
+          pytest tests/unittests/a2a \
+            tests/unittests/agents/test_remote_a2a_agent.py \
+            tests/unittests/integrations/agent_registry/test_agent_registry.py