Merge branch 'main' into feat/agent-lifecycle-events

Author: ferponse

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

.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

.github/workflows/discussion_answering.yml

@@ -26,8 +26,10 @@ permissions:
 jobs:
   agent-answer-questions:
     if: >-
+      github.repository == 'google/adk-python' && (
       (github.event_name == 'discussion' && github.event.discussion.category.name == 'Q&A') ||
       (github.event_name == 'discussion_comment' && contains(github.event.comment.body, '@adk-bot') && github.event.sender.login != 'adk-bot')
+      )
     runs-on: ubuntu-latest
 
     steps:
@@ -63,9 +65,7 @@ jobs:
           REPO: 'adk-python'
           INTERACTIVE: 0
           PYTHONPATH: contributing/samples/adk_team
+          DISCUSSION_JSON: ${{ toJson(github.event.discussion) }}
         run: |
-          # Write discussion data to temporary file to avoid secret masking issues
-          cat > /tmp/discussion.json << 'EOF'
-          ${{ toJson(github.event.discussion) }}
-          EOF
+          python -c "import os; open('/tmp/discussion.json', 'w').write(os.environ['DISCUSSION_JSON'])"
           python -m adk_answering_agent.main --discussion-file /tmp/discussion.json

.github/workflows/release-cherry-pick.yml

@@ -34,6 +34,7 @@ on:
 
 jobs:
   cherry-pick:
+    if: github.repository == 'google/adk-python'
     runs-on: ubuntu-latest
     steps:
       - name: Determine Branch Configurations

.github/workflows/release-cut.yml

@@ -47,6 +47,7 @@ permissions:
 
 jobs:
   cut-or-regenerate:
+    if: github.repository == 'google/adk-python'
     runs-on: ubuntu-latest
     steps:
       - name: Determine Branch Configurations
@@ -101,9 +102,54 @@ jobs:
 
       # Run Release Please
       - name: Run Release Please
+        id: release_please
         uses: googleapis/release-please-action@v4
         with:
           token: ${{ secrets.RELEASE_PAT }}
           config-file: ${{ steps.config.outputs.config_file }}
           manifest-file: ${{ steps.config.outputs.manifest_file }}
           target-branch: ${{ steps.config.outputs.candidate_branch }}
+
+      # Curate the changelog: draft a Highlights section on top of the
+      # release-please output and commit it back to the release PR branch. The
+      # script falls back to an empty Highlights template if drafting fails, so
+      # this step never blocks the release.
+      - name: Set up Python
+        if: steps.release_please.outputs.prs_created == 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install changelog curation dependencies
+        if: steps.release_please.outputs.prs_created == 'true'
+        run: pip install --upgrade google-genai
+
+      - name: Curate changelog Highlights
+        if: steps.release_please.outputs.prs_created == 'true'
+        # Curation is a nice-to-have layered on top of the release PR; never let
+        # it turn the release run red (e.g. a push race or a transient error).
+        continue-on-error: true
+        env:
+          RELEASE_PR: ${{ steps.release_please.outputs.pr }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GOOGLE_GENAI_USE_VERTEXAI: '0'
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+        run: |
+          set -euo pipefail
+          PR_BRANCH=$(echo "$RELEASE_PR" | jq -r '.headBranchName')
+          echo "Curating changelog on release PR branch: $PR_BRANCH"
+          git fetch origin "$PR_BRANCH"
+          git checkout -B "$PR_BRANCH" FETCH_HEAD
+          python scripts/curate_changelog.py --changelog CHANGELOG.md
+          if git diff --quiet -- CHANGELOG.md; then
+            echo "No changelog changes to commit."
+            exit 0
+          fi
+          USER_JSON=$(gh api user)
+          git config user.name "$(echo "$USER_JSON" | jq -r '.login')"
+          git config user.email "$(echo "$USER_JSON" | jq -r '.id')+$(echo "$USER_JSON" | jq -r '.login')@users.noreply.github.com"
+          git add CHANGELOG.md
+          git commit -m "chore: add curated highlights to changelog"
+          # Rebase onto any concurrent PR-branch updates so the push doesn't fail on a stale ref.
+          git pull --rebase origin "$PR_BRANCH"
+          git push origin "$PR_BRANCH"

.github/workflows/release-finalize.yml

@@ -29,7 +29,7 @@ permissions:
 
 jobs:
   finalize:
-    if: github.event.pull_request.merged == true
+    if: github.event.pull_request.merged == true && github.repository == 'google/adk-python'
     runs-on: ubuntu-latest
     steps:
       - name: Check for release-please PR