feat(plugins): Add RateLimitPlugin for global request rate limiting

Add a new RateLimitPlugin that enforces global rate limiting across all
LLM models using a sliding window algorithm. The plugin blocks (waits)
when the rate limit is exceeded, ensuring requests are processed within
the configured limit.

Key features:
- Global rate limiting (default 15 QPM) across all models
- Sliding window algorithm for accurate tracking
- Automatic blocking when limit exceeded (no errors thrown)
- Thread-safe with asyncio locks
- Automatic cleanup of expired timestamps

Example usage:
```python
from google.adk.plugins import RateLimitPlugin

runner = Runner(
    agents=[agent],
    plugins=[RateLimitPlugin(max_requests_per_minute=15)]
)
```

.github/ISSUE_TEMPLATE/bug_report.md

@@ -14,11 +14,12 @@ assignees: ''
 A clear and concise description of what the bug is.
 
 **To Reproduce**
+Please share a minimal code and data to reproduce your problem.
 Steps to reproduce the behavior:
 1. Install '...'
 2. Run '....'
 3. Open '....'
-4. See error
+4. Provie error or stacktrace
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.
@@ -27,12 +28,13 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
- - OS: [e.g. iOS]
+ - OS: [e.g. macOS, Linux, Windows]
  - Python version(python -V):
  - ADK version(pip show google-adk):
 
  **Model Information:**
- For example, which model is being used.
+ - Are you using LiteLLM: Yes/No
+ - Which model is being used(e.g. gemini-2.5-pro)
 
 **Additional context**
 Add any other context about the problem here.

.github/pull_request_template.md

@@ -0,0 +1,52 @@
+**Please ensure you have read the [contribution guide](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) before creating a pull request.**
+
+### Link to Issue or Description of Change
+
+**1. Link to an existing issue (if applicable):**
+
+- Closes: #_issue_number_
+- Related: #_issue_number_
+
+**2. Or, if no issue exists, describe the change:**
+
+_If applicable, please follow the issue templates to provide as much detail as
+possible._
+
+**Problem:**
+_A clear and concise description of what the problem is._
+
+**Solution:**
+_A clear and concise description of what you want to happen and why you choose
+this solution._
+
+### Testing Plan
+
+_Please describe the tests that you ran to verify your changes. This is required
+for all PRs that are not small documentation or typo fixes._
+
+**Unit Tests:**
+
+- [ ] I have added or updated unit tests for my change.
+- [ ] All unit tests pass locally.
+
+_Please include a summary of passed `pytest` results._
+
+**Manual End-to-End (E2E) Tests:**
+
+_Please provide instructions on how to manually test your changes, including any
+necessary setup or configuration. Please provide logs or screenshots to help
+reviewers better understand the fix._
+
+### Checklist
+
+- [ ] I have read the [CONTRIBUTING.md](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) document.
+- [ ] I have performed a self-review of my own code.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] New and existing unit tests pass locally with my changes.
+- [ ] I have manually tested my changes end-to-end.
+- [ ] Any dependent changes have been merged and published in downstream modules.
+
+### Additional context
+
+_Add any other context or screenshots about the feature request here._

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

@@ -0,0 +1,47 @@
+name: Analyze New Release for ADK Docs Updates
+
+on:
+  # Runs on every new release.
+  release:
+    types: [published]
+  # Manual trigger for testing and retrying.
+  workflow_dispatch:
+
+jobs:
+  analyze-new-release-for-adk-docs-updates:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Load adk-bot SSH Private Key
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.ADK_BOT_SSH_PRIVATE_KEY }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install requests google-adk
+
+      - name: Run Analyzing Script
+        env:
+          GITHUB_TOKEN: ${{ secrets.ADK_TRIAGE_AGENT }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GOOGLE_GENAI_USE_VERTEXAI: 0
+          DOC_OWNER: 'google'
+          CODE_OWNER: 'google'
+          DOC_REPO: 'adk-docs'
+          CODE_REPO: 'adk-python'
+          INTERACTIVE: 0
+          PYTHONPATH: contributing/samples/adk_documentation
+        run: python -m adk_release_analyzer.main

.github/workflows/check-file-contents.yml

@@ -89,7 +89,7 @@ jobs:
       - name: Check for import from cli package 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 'cli/.*|tests/.*|contributing/samples/' || true)
+          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"

.github/workflows/copybara-pr-handler.yml

@@ -0,0 +1,134 @@
+name: Copybara PR Handler
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to close (for testing)'
+        required: true
+        type: string
+      commit_sha:
+        description: 'Commit SHA reference (optional, for testing)'
+        required: false
+        type: string
+
+jobs:
+  close-imported-pr:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+      contents: read
+
+    steps:
+      - name: Check for Copybara commits and close PRs
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.ADK_TRIAGE_AGENT }}
+          script: |
+            // Check if this is a manual test run
+            const isManualRun = context.eventName === 'workflow_dispatch';
+
+            let prsToClose = [];
+
+            if (isManualRun) {
+              // Manual testing mode
+              const prNumber = parseInt(context.payload.inputs.pr_number);
+              const commitSha = context.payload.inputs.commit_sha || context.sha.substring(0, 7);
+
+              console.log('=== MANUAL TEST MODE ===');
+              console.log(`Testing with PR #${prNumber}, commit ${commitSha}`);
+
+              prsToClose.push({ prNumber, commitSha });
+            } else {
+              // Normal mode: process commits from push event
+              const commits = context.payload.commits || [];
+              console.log(`Found ${commits.length} commit(s) in this push`);
+
+              // Process each commit
+              for (const commit of commits) {
+                const sha = commit.id;
+                const committer = commit.committer.name;
+                const message = commit.message;
+
+                console.log(`\n--- Processing commit ${sha.substring(0, 7)} ---`);
+                console.log(`Committer: ${committer}`);
+
+                // Check if this is a Copybara commit
+                if (committer !== 'Copybara-Service') {
+                  console.log('Not a Copybara commit, skipping');
+                  continue;
+                }
+
+                // Extract PR number from commit message
+                // Pattern: "Merge https://github.com/google/adk-python/pull/3333"
+                const prMatch = message.match(/Merge https:\/\/github\.com\/google\/adk-python\/pull\/(\d+)/);
+
+                if (!prMatch) {
+                  console.log('No PR number found in Copybara commit message');
+                  continue;
+                }
+
+                const prNumber = parseInt(prMatch[1]);
+                const commitSha = sha.substring(0, 7);
+
+                prsToClose.push({ prNumber, commitSha });
+              }
+            }
+
+            // Process PRs to close
+            for (const { prNumber, commitSha } of prsToClose) {
+              console.log(`\n--- Processing PR #${prNumber} ---`);
+
+              // Get PR details to check if it's open
+              let pr;
+              try {
+                pr = await github.rest.pulls.get({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: prNumber
+                });
+              } catch (error) {
+                console.log(`PR #${prNumber} not found or inaccessible:`, error.message);
+                continue;
+              }
+
+              // Only close if PR is still open
+              if (pr.data.state !== 'open') {
+                console.log(`PR #${prNumber} is already ${pr.data.state}, skipping`);
+                continue;
+              }
+
+              const author = pr.data.user.login;
+
+              try {
+                // Add comment with commit reference
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  body: `Thank you @${author} for your contribution! 🎉\n\nYour changes have been successfully imported and merged via Copybara in commit ${commitSha}.\n\nClosing this PR as the changes are now in the main branch.`
+                });
+
+                // Close the PR
+                await github.rest.pulls.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: prNumber,
+                  state: 'closed'
+                });
+
+                console.log(`Successfully closed PR #${prNumber}`);
+              } catch (error) {
+                console.log(`Error closing PR #${prNumber}:`, error.message);
+              }
+            }
+
+            if (isManualRun) {
+              console.log('\n=== TEST COMPLETED ===');
+            } else {
+              console.log('\n--- Finished processing all commits ---');
+            }

.github/workflows/discussion_answering.yml

@@ -3,10 +3,14 @@ name: ADK Answering Agent for Discussions
 on:
   discussion:
     types: [created]
+  discussion_comment:
+    types: [created]
 
 jobs:
   agent-answer-questions:
-    if: github.event.discussion.category.name == 'Q&A'
+    if: >-
+      (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:
@@ -27,18 +31,24 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install google-adk
+          pip install google-adk google-cloud-discoveryengine
 
       - name: Run Answering Script
         env:
           GITHUB_TOKEN: ${{ secrets.ADK_TRIAGE_AGENT }}
+          ADK_GCP_SA_KEY: ${{ secrets.ADK_GCP_SA_KEY }}
           GOOGLE_CLOUD_PROJECT: ${{ secrets.GOOGLE_CLOUD_PROJECT }}
           GOOGLE_CLOUD_LOCATION: ${{ secrets.GOOGLE_CLOUD_LOCATION }}
           VERTEXAI_DATASTORE_ID: ${{ secrets.VERTEXAI_DATASTORE_ID }}
+          GEMINI_API_DATASTORE_ID: ${{ secrets.GEMINI_API_DATASTORE_ID }}
           GOOGLE_GENAI_USE_VERTEXAI: 1
           OWNER: 'google'
           REPO: 'adk-python'
           INTERACTIVE: 0
-          DISCUSSION_NUMBER: ${{ github.event.discussion.number }}
           PYTHONPATH: contributing/samples
-        run: python -m adk_answering_agent.main
+        run: |
+          # Write discussion data to temporary file to avoid secret masking issues
+          cat > /tmp/discussion.json << 'EOF'
+          ${{ toJson(github.event.discussion) }}
+          EOF
+          python -m adk_answering_agent.main --discussion-file /tmp/discussion.json

.github/workflows/pr-triage.yml

@@ -3,9 +3,16 @@ name: ADK Pull Request Triaging Agent
 on:
   pull_request_target:
     types: [opened, reopened, edited]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'The Pull Request number to triage'
+        required: true
+        type: 'string'
 
 jobs:
   agent-triage-pull-request:
+    if: github.event_name == 'workflow_dispatch' || !contains(github.event.pull_request.labels.*.name, 'google-contributor')
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
@@ -32,7 +39,7 @@ jobs:
           GOOGLE_GENAI_USE_VERTEXAI: 0
           OWNER: 'google'
           REPO: 'adk-python'
-          PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
+          PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number || github.event.inputs.pr_number }}
           INTERACTIVE: ${{ vars.PR_TRIAGE_INTERACTIVE }}
           PYTHONPATH: contributing/samples
         run: python -m adk_pr_triaging_agent.main

.github/workflows/python-unit-tests.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - name: Checkout code

.github/workflows/triage.yml

@@ -3,8 +3,6 @@ name: ADK Issue Triaging Agent
 on:
   issues:
     types: [opened, reopened]
-  schedule:
-    - cron: '0 */6 * * *' # every 6h
 
 jobs:
   agent-triage-issues:

.github/workflows/upload-adk-docs-to-vertex-ai-search.yml

@@ -0,0 +1,51 @@
+name: Upload ADK Docs to Vertex AI Search
+
+on:
+  # Runs once per day at 16:00 UTC
+  schedule:
+   - cron: '00 16 * * *'
+  # Manual trigger for testing and fixing
+  workflow_dispatch:
+
+jobs:
+  upload-adk-docs-to-vertex-ai-search:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Clone adk-docs repository
+        run: git clone https://github.com/google/adk-docs.git /tmp/adk-docs
+
+      - name: Clone adk-python repository
+        run: git clone https://github.com/google/adk-python.git /tmp/adk-python
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Authenticate to Google Cloud
+        id: auth
+        uses: 'google-github-actions/auth@v2'
+        with:
+          credentials_json: '${{ secrets.ADK_GCP_SA_KEY }}'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install google-adk markdown google-cloud-storage google-cloud-discoveryengine
+
+      - name: Run Answering Script
+        env:
+          GITHUB_TOKEN: ${{ secrets.ADK_TRIAGE_AGENT }}
+          GOOGLE_CLOUD_PROJECT: ${{ secrets.GOOGLE_CLOUD_PROJECT }}
+          GOOGLE_CLOUD_LOCATION: ${{ secrets.GOOGLE_CLOUD_LOCATION }}
+          VERTEXAI_DATASTORE_ID: ${{ secrets.VERTEXAI_DATASTORE_ID }}
+          GOOGLE_GENAI_USE_VERTEXAI: 1
+          GCS_BUCKET_NAME: ${{ secrets.GCS_BUCKET_NAME }}
+          ADK_DOCS_ROOT_PATH: /tmp/adk-docs
+          ADK_PYTHON_ROOT_PATH: /tmp/adk-python
+          PYTHONPATH: contributing/samples
+        run: python -m adk_answering_agent.upload_docs_to_vertex_ai_search

.gitignore

@@ -98,3 +98,20 @@ Thumbs.db
 *.bak
 *.tmp
 *.temp
+
+# AI Coding Tools - Project-specific configs
+# Developers should symlink or copy AGENTS.md and add their own overrides locally
+.claude/
+CLAUDE.md
+.cursor/
+.cursorrules
+.cursorignore
+.windsurfrules
+.aider*
+.continue/
+.codeium/
+.githubnext/
+.roo/
+.rooignore
+.bolt/
+.v0/

AGENTS.md

@@ -1,15 +1,59 @@
-# Gemini CLI / Gemini Code Assist Context
+# AI Coding Assistant Context
 
-This document provides context for the Gemini CLI and Gemini Code Assist to understand the project and assist with development.
+This document provides context for AI coding assistants (Claude Code, Gemini CLI, GitHub Copilot, Cursor, etc.) to understand the ADK Python project and assist with development.
 
 ## Project Overview
 
 The Agent Development Kit (ADK) is an open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control. While optimized for Gemini and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and is built for compatibility with other frameworks. ADK was designed to make agent development feel more like software development, to make it easier for developers to create, deploy, and orchestrate agentic architectures that range from simple tasks to complex workflows.
 
+### Key Components
+
+- **Agent** - Blueprint defining identity, instructions, and tools (`LlmAgent`, `LoopAgent`, `ParallelAgent`, `SequentialAgent`, etc.)
+- **Runner** - Execution engine that orchestrates the "Reason-Act" loop, manages LLM calls, executes tools, and handles multi-agent coordination
+- **Tool** - Functions/capabilities agents can call (Python functions, OpenAPI specs, MCP tools, Google API tools)
+- **Session** - Conversation state management (in-memory, Vertex AI, Spanner-backed)
+- **Memory** - Long-term recall across sessions
+
 ## Project Architecture
 
 Please refer to [ADK Project Overview and Architecture](https://github.com/google/adk-python/blob/main/contributing/adk_project_overview_and_architecture.md) for details.
 
+### Source Structure
+
+```
+src/google/adk/
+├── agents/          # Agent implementations (LlmAgent, LoopAgent, ParallelAgent, etc.)
+├── runners.py       # Core Runner orchestration class
+├── tools/           # Tool ecosystem (50+ files)
+│   ├── google_api_tool/
+│   ├── bigtable/, bigquery/, spanner/
+│   ├── openapi_tool/
+│   └── mcp_tool/    # Model Context Protocol
+├── models/          # LLM integrations (Gemini, Anthropic, LiteLLM)
+├── sessions/        # Session management (in-memory, Vertex AI, Spanner)
+├── memory/          # Long-term memory services
+├── evaluation/      # Evaluation framework (47 files)
+├── cli/             # CLI tools and web UI
+├── flows/           # Execution flow orchestration
+├── a2a/             # Agent-to-Agent protocol
+├── telemetry/       # Observability and tracing
+└── utils/           # Utility functions
+```
+
+### Test Structure
+
+```
+tests/
+├── unittests/       # 2600+ unit tests across 236+ files
+│   ├── agents/
+│   ├── tools/
+│   ├── models/
+│   ├── evaluation/
+│   ├── a2a/
+│   └── ...
+└── integration/     # Integration tests
+```
+
 ### ADK Live (Bidi-streaming)
 
 - ADK live feature can be accessed from runner.run_live(...) and corresponding FAST api endpoint.
@@ -17,8 +61,132 @@ Please refer to [ADK Project Overview and Architecture](https://github.com/googl
 - ADK live related configs are in [run_config.py](https://github.com/google/adk-python/blob/main/src/google/adk/agents/run_config.py).
 - ADK live under multi-agent scenario: we convert the audio into text. This text will be passed to next agent as context.
 - Most logics are in [base_llm_flow.py](https://github.com/google/adk-python/blob/main/src/google/adk/flows/llm_flows/base_llm_flow.py) and [gemini_llm_connection.py](https://github.com/google/adk-python/blob/main/src/google/adk/models/gemini_llm_connection.py).
+- Input transcription and output transcription should be added to session as Event.
+- User audio or model audio should be saved into artifacts with a reference in Event to it.
 - Tests are in [tests/unittests/streaming](https://github.com/google/adk-python/tree/main/tests/unittests/streaming).
 
+### Agent Structure Convention (Required)
+
+**All agent directories must follow this structure:**
+```
+my_agent/
+├── __init__.py      # MUST contain: from . import agent
+└── agent.py         # MUST define: root_agent = Agent(...) OR app = App(...)
+```
+
+**Choose one pattern based on your needs:**
+
+**Option 1 - Simple Agent (for basic agents without plugins):**
+```python
+from google.adk.agents import Agent
+from google.adk.tools import google_search
+
+root_agent = Agent(
+    name="search_assistant",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant.",
+    description="An assistant that can search the web.",
+    tools=[google_search]
+)
+```
+
+**Option 2 - App Pattern (when you need plugins, event compaction, custom configuration):**
+```python
+from google.adk import Agent
+from google.adk.apps import App
+from google.adk.plugins import ContextFilterPlugin
+
+root_agent = Agent(
+    name="my_agent",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant.",
+    tools=[...],
+)
+
+app = App(
+    name="my_app",
+    root_agent=root_agent,
+    plugins=[
+        ContextFilterPlugin(num_invocations_to_keep=3),
+    ],
+)
+```
+
+**Rationale:** This structure allows the ADK CLI (`adk web`, `adk run`, etc.) to automatically discover and load agents without additional configuration.
+
+## Development Setup
+
+### Requirements
+
+**Minimum requirements:**
+- Python 3.9+ (**Python 3.11+ strongly recommended** for best performance)
+- `uv` package manager (**required** - faster than pip/venv)
+
+**Install uv if not already installed:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Setup Instructions
+
+**Standard setup for development:**
+```bash
+# Create virtual environment with Python 3.11
+uv venv --python "python3.11" ".venv"
+source .venv/bin/activate
+
+# Install all dependencies for development
+uv sync --all-extras
+```
+
+**Minimal setup for testing only (matches CI):**
+```bash
+uv sync --extra test --extra eval --extra a2a
+```
+
+**Virtual Environment Usage (Required):**
+- **Always use** `.venv/bin/python` or `.venv/bin/pytest` directly
+- **Or activate** with `source .venv/bin/activate` before running commands
+- **Never use** `python -m venv` - always create with `uv venv` if missing
+
+**Rationale:** `uv` is significantly faster and ensures consistent dependency resolution across the team.
+
+### Building
+
+```bash
+# Build wheel
+uv build
+
+# Install local build for testing
+pip install dist/google_adk-<version>-py3-none-any.whl
+```
+
+### Running Agents Locally
+
+**For interactive development and debugging:**
+```bash
+# Launch web UI (recommended for development)
+adk web path/to/agents_dir
+```
+
+**For CLI-based testing:**
+```bash
+# Interactive CLI (prompts for user input)
+adk run path/to/my_agent
+```
+
+**For API/production mode:**
+```bash
+# Start FastAPI server
+adk api_server path/to/agents_dir
+```
+
+**For running evaluations:**
+```bash
+# Run evaluation set against agent
+adk eval path/to/my_agent path/to/eval_set.json
+```
+
 ## ADK: Style Guides
 
 ### Python Style Guide
@@ -35,48 +203,68 @@ The project follows the Google Python Style Guide. Key conventions are enforced
 *   **Imports**: Organized and sorted.
 *   **Error Handling**: Specific exceptions should be caught, not general ones like `Exception`.
 
-### Autoformat
-
-We have autoformat.sh to help solve import organize and formatting issues.
+### Autoformat (Required Before Committing)
 
+**Always run** before committing code:
 ```bash
-# Run in open_source_workspace/
-$ ./autoformat.sh
+./autoformat.sh
 ```
 
+**Manual formatting** (if needed):
+```bash
+# Format imports
+isort src/ tests/ contributing/
+
+# Format code style
+pyink --config pyproject.toml src/ tests/ contributing/
+```
+
+**Check formatting** without making changes:
+```bash
+pyink --check --diff --config pyproject.toml src/
+isort --check src/
+```
+
+**Formatting Standards (Enforced by CI):**
+- **Formatter:** `pyink` (Google-style Python formatter)
+- **Line length:** 80 characters maximum
+- **Indentation:** 2 spaces (never tabs)
+- **Import sorter:** `isort` with Google profile
+- **Linter:** `pylint` with Google Python Style Guide
+
+**Rationale:** Consistent formatting eliminates style debates and makes code reviews focus on logic rather than style.
+
 ### In ADK source
 
-Below styles applies to the ADK source code (under `src/` folder of the Github.
-repo).
+Below styles applies to the ADK source code (under `src/` folder of the GitHub repo).
 
-#### Use relative imports
+#### Use relative imports (Required)
 
 ```python
-# DO
+# DO - Use relative imports
 from ..agents.llm_agent import LlmAgent
 
-# DON'T
+# DON'T - No absolute imports
 from google.adk.agents.llm_agent import LlmAgent
 ```
 
-#### Import from module, not from `__init__.py`
+**Rationale:** Relative imports make the code more maintainable and avoid circular import issues in large codebases.
+
+#### Import from module, not from `__init__.py` (Required)
 
 ```python
-# DO
+# DO - Import directly from module
 from ..agents.llm_agent import LlmAgent
 
-# DON'T
-from ..agents  import LlmAgent # import from agents/__init__.py
+# DON'T - Import from __init__.py
+from ..agents import LlmAgent
 ```
 
-#### Always do `from __future__ import annotations`
+**Rationale:** Direct module imports make dependencies explicit and improve IDE navigation and refactoring.
 
-```python
-# DO THIS, right after the open-source header.
-from __future__ import annotations
-```
+#### Always do `from __future__ import annotations` (Required)
 
-Like below:
+**Rule:** Every source file must include `from __future__ import annotations` immediately after the license header, before any other imports.
 
 ```python
 # Copyright 2025 Google LLC
@@ -93,39 +281,72 @@ Like below:
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from __future__ import annotations
+from __future__ import annotations  # REQUIRED - Always include this
 
-# ... the rest of the file.
+# ... rest of imports ...
 ```
 
-This allows us to forward-reference a class without quotes.
-
-Check out go/pep563 for details.
+**Rationale:** This enables forward-referencing classes without quotes, improving code readability and type hint support (PEP 563).
 
 ### In ADK tests
 
-#### Use absolute imports
+#### Use absolute imports (Required)
 
-In tests, we use `google.adk` same as how our users uses.
+**Rule:** Test code must use absolute imports (`google.adk.*`) to match how users import ADK.
 
 ```python
-# DO
+# DO - Use absolute imports
 from google.adk.agents.llm_agent import LlmAgent
 
-# DON'T
+# DON'T - No relative imports in tests
 from ..agents.llm_agent import LlmAgent
 ```
 
-## ADK: Local testing
+**Rationale:** Tests should exercise the same import paths that users will use, catching issues with the public API.
 
-### Unit tests
+## ADK: Local Testing
 
-Run below command:
+### Unit Tests
 
+**Quick start:** Run all tests with:
 ```bash
-$ pytest tests/unittests
+pytest tests/unittests
 ```
 
+**Recommended:** Match CI configuration before submitting PRs:
+```bash
+uv sync --extra test --extra eval --extra a2a && pytest tests/unittests
+```
+
+**Additional options:**
+```bash
+# Run tests in parallel for faster execution
+pytest tests/unittests -n auto
+
+# Run a specific test file during development
+pytest tests/unittests/agents/test_llm_agent.py
+
+# Python 3.9 compatibility mode (excludes features requiring 3.10+)
+pytest tests/unittests \
+  --ignore=tests/unittests/a2a \
+  --ignore=tests/unittests/tools/mcp_tool \
+  --ignore=tests/unittests/artifacts/test_artifact_service.py
+```
+
+### Testing Philosophy
+
+**Use real code over mocks:** ADK tests should use real implementations as much as possible instead of mocking. Only mock external dependencies like network calls or cloud services.
+
+**Test interface behavior, not implementation details:** Tests should verify that the public API behaves correctly, not how it's implemented internally. This makes tests resilient to refactoring and ensures the contract with users remains intact.
+
+**Test Requirements:**
+- Fast and isolated tests where possible
+- Use real ADK components; mock only external dependencies (LLM APIs, cloud services, etc.)
+- Focus on testing public interfaces and behavior, not internal implementation
+- Descriptive test names that explain what behavior is being tested
+- High coverage for new features, edge cases, and error conditions
+- Location: `tests/unittests/` following source structure
+
 ## Docstring and comments
 
 ### Comments - Explaining the Why, Not the What
@@ -211,9 +432,49 @@ The following changes are considered breaking and necessitate a MAJOR version
 - Dependency Removal: Removing support for a previously integrated third-party
  library or tool type.
 
-## Commit Message Format
+## Commit Message Format (Required)
 
-- Please use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
-format.
-- If it's not a breaking change, please add #non-breaking tag. If it's a
-breaking change, please add #breaking.
+**All commits must** follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.
+
+**Format:**
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Common types:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
+
+**Examples:**
+```
+feat(agents): Add support for App pattern with plugins
+
+fix(sessions): Prevent memory leak in session cleanup
+
+refactor(tools): Unify environment variable enabled checks
+```
+
+**Rationale:** Conventional commits enable automated changelog generation and version management.
+
+## Key Files and Locations
+
+Quick reference to important project files:
+
+- **Main config:** `pyproject.toml` (uses `flit_core` build backend)
+- **Dependencies:** `uv.lock` (managed by `uv`)
+- **Linting:** `pylintrc` (Google Python Style Guide)
+- **Auto-format:** `autoformat.sh` (runs isort + pyink)
+- **CLI entry point:** `src/google/adk/cli/cli_tools_click.py`
+- **Web UI backend:** `src/google/adk/cli/adk_web_server.py`
+- **Main exports:** `src/google/adk/__init__.py` (exports Agent, Runner)
+- **Examples:** `contributing/samples/` (100+ agent implementations)
+
+## Additional Resources
+
+- **Documentation:** https://google.github.io/adk-docs
+- **Samples:** https://github.com/google/adk-samples
+- **Architecture Details:** `contributing/adk_project_overview_and_architecture.md`
+- **Contributing Guide:** `CONTRIBUTING.md`
+- **LLM Context:** `llms.txt` (summarized), `llms-full.txt` (comprehensive)

CONTRIBUTING.md

@@ -2,25 +2,24 @@
 
 We'd love to accept your patches and contributions to this project.
 
-- [How to contribute](#how-to-contribute)
-- [Before you begin](#before-you-begin)
-  - [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)
-  - [Review our community guidelines](#review-our-community-guidelines)
-- [Contribution workflow](#contribution-workflow)
-  - [Finding Issues to Work On](#finding-issues-to-work-on)
-  - [Requirement for PRs](#requirement-for-prs)
-  - [Large or Complex Changes](#large-or-complex-changes)
-  - [Testing Requirements](#testing-requirements)
-    - [Unit Tests](#unit-tests)
-    - [Manual End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
-  - [Documentation](#documentation)
-  - [Development Setup](#development-setup)
-  - [Code reviews](#code-reviews)
+-   [How to contribute](#how-to-contribute)
+-   [Before you begin](#before-you-begin)
+    -   [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)
+    -   [Review our community guidelines](#review-our-community-guidelines)
+-   [Contribution workflow](#contribution-workflow)
+    -   [Finding Issues to Work On](#finding-issues-to-work-on)
+    -   [Requirement for PRs](#requirement-for-prs)
+    -   [Large or Complex Changes](#large-or-complex-changes)
+    -   [Testing Requirements](#testing-requirements)
+    -   [Unit Tests](#unit-tests)
+    -   [Manual End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
+    -   [Documentation](#documentation)
+    -   [Development Setup](#development-setup)
+    -   [Code reviews](#code-reviews)
 
+## Before you begin
 
-# Before you begin
-
-## Sign our Contributor License Agreement
+### Sign our Contributor License Agreement
 
 Contributions to this project must be accompanied by a
 [Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
@@ -34,74 +33,104 @@ was for a different project), you probably don't need to do it again.
 Visit <https://cla.developers.google.com/> to see your current agreements or to
 sign a new one.
 
-## Review our community guidelines
+### Review our community guidelines
 
 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
 
-# Contribution workflow
+### Code reviews
 
-## Finding Issues to Work On
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
 
-- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help wanted`** (general contributions).
-- For other issues, please kindly ask before contributing to avoid duplication.
+## Contribution workflow
 
+### Finding Issues to Work On
 
-## Requirement for PRs
+-   Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help
+    wanted`** (general contributions).
+-   For other issues, please kindly ask before contributing to avoid
+    duplication.
 
-- Each PR should only have one commit. Please squash it if there are multiple PRs.
-- All PRs, other than small documentation or typo fixes, should have a Issue assoicated. If not, please create one.
-- Small, focused PRs. Keep changes minimal—one concern per PR.
-- For bug fixes or features, please provide logs or screenshot after the fix is applied to help reviewers better understand the fix.
-- Please include a `testing plan` section in your PR to talk about how you will test. This will save time for PR review. See `Testing Requirements` section for more details.
+### Requirement for PRs
+
+-   All PRs, other than small documentation or typo fixes, should have a Issue
+    associated. If a relevant issue doesn't exist, please create one first or
+    you may instead describe the bug or feature directly within the PR
+    description, following the structure of our issue templates.
+-   Small, focused PRs. Keep changes minimal—one concern per PR.
+-   For bug fixes or features, please provide logs or screenshot after the fix
+    is applied to help reviewers better understand the fix.
+-   Please include a `testing plan` section in your PR to talk about how you
+    will test. This will save time for PR review. See `Testing Requirements`
+    section for more details.
+
+### Large or Complex Changes
 
-## Large or Complex Changes
 For substantial features or architectural revisions:
 
-- Open an Issue First: Outline your proposal, including design considerations and impact.
-- Gather Feedback: Discuss with maintainers and the community to ensure alignment and avoid duplicate work
+-   Open an Issue First: Outline your proposal, including design considerations
+    and impact.
+-   Gather Feedback: Discuss with maintainers and the community to ensure
+    alignment and avoid duplicate work
 
-## Testing Requirements
+### Testing Requirements
 
-To maintain code quality and prevent regressions, all code changes must include comprehensive tests and verifiable end-to-end (E2E) evidence.
+To maintain code quality and prevent regressions, all code changes must include
+comprehensive tests and verifiable end-to-end (E2E) evidence.
 
+#### Unit Tests
 
-### Unit Tests
-
-Please add or update unit tests for your change. Please include a summary of passed `pytest` results.
+Please add or update unit tests for your change. Please include a summary of
+passed `pytest` results.
 
 Requirements for unit tests:
 
-- **Coverage:** Cover new features, edge cases, error conditions, and typical use cases.
-- **Location:** Add or update tests under `tests/unittests/`, following existing naming conventions (e.g., `test_<module>_<feature>.py`).
-- **Framework:** Use `pytest`. Tests should be:
-  - Fast and isolated.
-  - Written clearly with descriptive names.
-  - Free of external dependencies (use mocks or fixtures as needed).
-- **Quality:** Aim for high readability and maintainability; include docstrings or comments for complex scenarios.
+-   **Coverage:** Cover new features, edge cases, error conditions, and typical
+    use cases.
+-   **Location:** Add or update tests under `tests/unittests/`, following
+    existing naming conventions (e.g., `test_<module>_<feature>.py`).
+-   **Framework:** Use `pytest`. Tests should be:
+    -   Fast and isolated.
+    -   Written clearly with descriptive names.
+    -   Free of external dependencies (use mocks or fixtures as needed).
+-   **Quality:** Aim for high readability and maintainability; include
+    docstrings or comments for complex scenarios.
 
-### Manual End-to-End (E2E) Tests
+#### Manual End-to-End (E2E) Tests
 
-Manual E2E tests ensure integrated flows work as intended. Your tests should cover all scenarios. Sometimes, it's also good to ensure relevant functionality is not impacted.
+Manual E2E tests ensure integrated flows work as intended. Your tests should
+cover all scenarios. Sometimes, it's also good to ensure relevant functionality
+is not impacted.
 
 Depending on your change:
 
-- **ADK Web:**
-  - Use the `adk web` to verify functionality.
-  - Capture and attach relevant screenshots demonstrating the UI/UX changes or outputs.
-  - Label screenshots clearly in your PR description.
+-   **ADK Web:**
 
-- **Runner:**
-  - Provide the testing setup. For example, the agent definition, and the runner setup.
-  - Execute the `runner` tool to reproduce workflows.
-  - Include the command used and console output showing test results.
-  - Highlight sections of the log that directly relate to your change.
+    -   Use the `adk web` to verify functionality.
+    -   Capture and attach relevant screenshots demonstrating the UI/UX changes
+        or outputs.
+    -   Label screenshots clearly in your PR description.
 
-## Documentation
+-   **Runner:**
 
-For any changes that impact user-facing documentation (guides, API reference, tutorials), please open a PR in the [adk-docs](https://github.com/google/adk-docs) repository to update relevant part before or alongside your code PR.
+    -   Provide the testing setup. For example, the agent definition, and the
+        runner setup.
+    -   Execute the `runner` tool to reproduce workflows.
+    -   Include the command used and console output showing test results.
+    -   Highlight sections of the log that directly relate to your change.
+
+### Documentation
+
+For any changes that impact user-facing documentation (guides, API reference,
+tutorials), please open a PR in the
+[adk-docs](https://github.com/google/adk-docs) repository to update relevant
+part before or alongside your code PR.
 
 ## Development Setup
+
 1.  **Clone the repository:**
 
     ```shell
@@ -111,11 +140,13 @@ For any changes that impact user-facing documentation (guides, API reference, tu
 
 2.  **Install uv:**
 
-    Check out [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+    Check out
+    [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
 3.  **Create and activate a virtual environment:**
 
-    **NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly recommended.
+    **NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly
+    recommended.
 
     Create a workspace venv using uv.
 
@@ -129,10 +160,7 @@ For any changes that impact user-facing documentation (guides, API reference, tu
     source .venv/bin/activate
     ```
 
-    **windows**
-    ```shell
-    source .\.venv\Scripts\activate
-    ```
+    **windows** `shell source .\.venv\Scripts\activate`
 
 4.  **Install dependencies:**
 
@@ -148,7 +176,7 @@ For any changes that impact user-facing documentation (guides, API reference, tu
     pytest ./tests/unittests
     ```
 
-    NOTE: for accurate repro of test failure, only include `test`, `eval` and 
+    NOTE: for accurate repro of test failure, only include `test`, `eval` and
     `a2a` as extra dependencies.
 
     ```shell
@@ -165,14 +193,14 @@ For any changes that impact user-facing documentation (guides, API reference, tu
     ./autoformat.sh
     ```
 
-7. **Build the wheel file:**
+7.  **Build the wheel file:**
 
     ```shell
     uv build
     ```
 
-8.  **Test the locally built wheel file:**
-    Have a simple testing folder setup as mentioned in the
+8.  **Test the locally built wheel file:** Have a simple testing folder setup as
+    mentioned in the
     [quickstart](https://google.github.io/adk-docs/get-started/quickstart/).
 
     Then following below steps to test your changes:
@@ -201,16 +229,11 @@ For any changes that impact user-facing documentation (guides, API reference, tu
 
 ## Contributing Resources
 
-[Contributing folder](https://github.com/google/adk-python/tree/main/contributing) has resources that is helpful for contributors.
+[Contributing folder](https://github.com/google/adk-python/tree/main/contributing)
+has resources that is helpful for contributors.
 
+## Vibe Coding
 
-## Code reviews
-
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
-
-# Vibe Coding
-
-If you want to contribute by leveraging viber coding, the AGENTS.md (https://github.com/google/adk-python/tree/main/AGENTS.md) could be used as context to your LLM.
+If you want to contribute by leveraging vibe coding, the AGENTS.md
+(https://github.com/google/adk-python/tree/main/AGENTS.md) could be used as
+context to your LLM.

README.md

@@ -1,6 +1,7 @@
 # Agent Development Kit (ADK)
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/google-adk)](https://pypi.org/project/google-adk/)
 [![Python Unit Tests](https://github.com/google/adk-python/actions/workflows/python-unit-tests.yml/badge.svg)](https://github.com/google/adk-python/actions/workflows/python-unit-tests.yml)
 [![r/agentdevelopmentkit](https://img.shields.io/badge/Reddit-r%2Fagentdevelopmentkit-FF4500?style=flat&logo=reddit&logoColor=white)](https://www.reddit.com/r/agentdevelopmentkit/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/google/adk-python)
@@ -10,44 +11,53 @@
       <img src="https://raw.githubusercontent.com/google/adk-python/main/assets/agent-development-kit.png" width="256"/>
     </h2>
     <h3 align="center">
-      An open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
+      An open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
     </h3>
     <h3 align="center">
       Important Links:
-      <a href="https://google.github.io/adk-docs/">Docs</a>, 
+      <a href="https://google.github.io/adk-docs/">Docs</a>,
       <a href="https://github.com/google/adk-samples">Samples</a>,
       <a href="https://github.com/google/adk-java">Java ADK</a> &
       <a href="https://github.com/google/adk-web">ADK Web</a>.
     </h3>
 </html>
 
-Agent Development Kit (ADK) is a flexible and modular framework for developing and deploying AI agents. While optimized for Gemini and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and is built for compatibility with other frameworks. ADK was designed to make agent development feel more like software development, to make it easier for developers to create, deploy, and orchestrate agentic architectures that range from simple tasks to complex workflows.
-
+Agent Development Kit (ADK) is a flexible and modular framework that applies
+software development principles to AI agent creation. It is designed to
+simplify building, deploying, and orchestrating agent workflows, from simple
+tasks to complex systems. While optimized for Gemini, ADK is model-agnostic,
+deployment-agnostic, and compatible with other frameworks.
 
 ---
 
+## 🔥 What's new
+
+- **Custom Service Registration**: Add a service registry to provide a generic way to register custom service implementations to be used in FastAPI server. See short instruction [here](https://github.com/google/adk-python/discussions/3175#discussioncomment-14745120). ([391628f](https://github.com/google/adk-python/commit/391628fcdc7b950c6835f64ae3ccab197163c990))
+
+- **Rewind**: Add the ability to rewind a session to before a previous invocation ([9dce06f](https://github.com/google/adk-python/commit/9dce06f9b00259ec42241df4f6638955e783a9d1)).
+
+- **New CodeExecutor**: Introduces a new AgentEngineSandboxCodeExecutor class that supports executing agent-generated code using the Vertex AI Code Execution Sandbox API ([ee39a89](https://github.com/google/adk-python/commit/ee39a891106316b790621795b5cc529e89815a98))
+
 ## ✨ Key Features
 
 - **Rich Tool Ecosystem**: Utilize pre-built tools, custom functions,
-  OpenAPI specs, or integrate existing tools to give agents diverse
+  OpenAPI specs, MCP tools or integrate existing tools to give agents diverse
   capabilities, all for tight integration with the Google ecosystem.
 
 - **Code-First Development**: Define agent logic, tools, and orchestration
   directly in Python for ultimate flexibility, testability, and versioning.
 
+- **Agent Config**: Build agents without code. Check out the
+  [Agent Config](https://google.github.io/adk-docs/agents/config/) feature.
+
+- **Tool Confirmation**: A [tool confirmation flow(HITL)](https://google.github.io/adk-docs/tools/confirmation/) that can guard tool execution with explicit confirmation and custom input.
+
 - **Modular Multi-Agent Systems**: Design scalable applications by composing
   multiple specialized agents into flexible hierarchies.
 
 - **Deploy Anywhere**: Easily containerize and deploy agents on Cloud Run or
   scale seamlessly with Vertex AI Agent Engine.
 
-## 🤖 Agent2Agent (A2A) Protocol and ADK Integration
-
-For remote agent-to-agent communication, ADK integrates with the
-[A2A protocol](https://github.com/google-a2a/A2A/).
-See this [example](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents)
-for how they can work together.
-
 ## 🚀 Installation
 
 ### Stable Release (Recommended)
@@ -58,7 +68,7 @@ You can install the latest stable version of ADK using `pip`:
 pip install google-adk
 ```
 
-The release cadence is weekly.
+The release cadence is roughly bi-weekly.
 
 This version is recommended for most users as it represents the most recent official release.
 
@@ -71,6 +81,13 @@ pip install git+https://github.com/google/adk-python.git@main
 
 Note: The development version is built directly from the latest code commits. While it includes the newest fixes and features, it may also contain experimental changes or bugs not present in the stable release. Use it primarily for testing upcoming changes or accessing critical fixes before they are officially released.
 
+## 🤖 Agent2Agent (A2A) Protocol and ADK Integration
+
+For remote agent-to-agent communication, ADK integrates with the
+[A2A protocol](https://github.com/google-a2a/A2A/).
+See this [example](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents)
+for how they can work together.
+
 ## 📚 Documentation
 
 Explore the full documentation for detailed guides on building, evaluating, and
@@ -88,7 +105,7 @@ from google.adk.tools import google_search
 
 root_agent = Agent(
     name="search_assistant",
-    model="gemini-2.0-flash", # Or your preferred Gemini model
+    model="gemini-2.5-flash", # Or your preferred Gemini model
     instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",
     description="An assistant that can search the web.",
     tools=[google_search]
@@ -103,13 +120,13 @@ Define a multi-agent system with coordinator agent, greeter agent, and task exec
 from google.adk.agents import LlmAgent, BaseAgent
 
 # Define individual agents
-greeter = LlmAgent(name="greeter", model="gemini-2.0-flash", ...)
-task_executor = LlmAgent(name="task_executor", model="gemini-2.0-flash", ...)
+greeter = LlmAgent(name="greeter", model="gemini-2.5-flash", ...)
+task_executor = LlmAgent(name="task_executor", model="gemini-2.5-flash", ...)
 
 # Create parent agent and assign children via sub_agents
 coordinator = LlmAgent(
     name="Coordinator",
-    model="gemini-2.0-flash",
+    model="gemini-2.5-flash",
     description="I coordinate greetings and tasks.",
     sub_agents=[ # Assign sub_agents here
         greeter,
@@ -138,10 +155,20 @@ We welcome contributions from the community! Whether it's bug reports, feature r
 - [General contribution guideline and flow](https://google.github.io/adk-docs/contributing-guide/).
 - Then if you want to contribute code, please read [Code Contributing Guidelines](./CONTRIBUTING.md) to get started.
 
+## Community Repo
+
+We have [adk-python-community repo](https://github.com/google/adk-python-community)that is home to a growing ecosystem of community-contributed tools, third-party
+service integrations, and deployment scripts that extend the core capabilities
+of the ADK.
+
 ## Vibe Coding
 
 If you are to develop agent via vibe coding the [llms.txt](./llms.txt) and the [llms-full.txt](./llms-full.txt) can be used as context to LLM. While the former one is a summarized one and the later one has the full information in case your LLM has big enough context window.
 
+## Community Events
+
+- [Completed] ADK's 1st community meeting on Wednesday, October 15, 2025. Remember to [join our group](https://groups.google.com/g/adk-community) to get access to the [recording](https://drive.google.com/file/d/1rpXDq5NSH8-MyMeYI6_5pZ3Lhn0X9BQf/view), and [deck](https://docs.google.com/presentation/d/1_b8LG4xaiadbUUDzyNiapSFyxanc9ZgFdw7JQ6zmZ9Q/edit?slide=id.g384e60cdaca_0_658&resourcekey=0-tjFFv0VBQhpXBPCkZr0NOg#slide=id.g384e60cdaca_0_658).
+
 ## 📄 License
 
 This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.

autoformat.sh

@@ -52,16 +52,16 @@ echo '---------------------------------------'
 echo '|  Auto-formatting src/...'
 echo '---------------------------------------'
 
-find -L src/ -type f -name "*.py" -exec pyink --config pyproject.toml {} +
+find -L src/ -not -path "*/.*" -type f -name "*.py" -exec pyink --config pyproject.toml {} +
 
 echo '---------------------------------------'
 echo '|  Auto-formatting tests/...'
 echo '---------------------------------------'
 
-find -L tests/ -type f -name "*.py" -exec pyink --config pyproject.toml {} +
+find -L tests/ -not -path "*/.*" -type f -name "*.py" -exec pyink --config pyproject.toml {} +
 
 echo '---------------------------------------'
 echo '|  Auto-formatting contributing/...'
 echo '---------------------------------------'
 
-find -L contributing/ -type f -name "*.py" -exec pyink --config pyproject.toml {} +
+find -L contributing/ -not -path "*/.*" -type f -name "*.py" -exec pyink --config pyproject.toml {} +

contributing/samples/a2a_auth/README.md

@@ -157,12 +157,43 @@ You can extend this sample by:
 - Adding audit logging for authentication events
 - Implementing multi-tenant OAuth token management
 
+## Deployment to Other Environments
+
+When deploying the remote BigQuery A2A agent to different environments (e.g., Cloud Run, different hosts/ports), you **must** update the `url` field in the agent card JSON file:
+
+### Local Development
+```json
+{
+  "url": "http://localhost:8001/a2a/bigquery_agent",
+  ...
+}
+```
+
+### Cloud Run Example
+```json
+{
+  "url": "https://your-bigquery-service-abc123-uc.a.run.app/a2a/bigquery_agent",
+  ...
+}
+```
+
+### Custom Host/Port Example
+```json
+{
+  "url": "https://your-domain.com:9000/a2a/bigquery_agent",
+  ...
+}
+```
+
+**Important:** The `url` field in `remote_a2a/bigquery_agent/agent.json` must point to the actual RPC endpoint where your remote BigQuery A2A agent is deployed and accessible.
+
 ## Troubleshooting
 
 **Connection Issues:**
 - Ensure the local ADK web server is running on port 8000
 - Ensure the remote A2A server is running on port 8001
 - Check that no firewall is blocking localhost connections
+- **Verify the `url` field in `remote_a2a/bigquery_agent/agent.json` matches the actual deployed location of your remote A2A server**
 - Verify the agent card URL passed to RemoteA2AAgent constructor matches the running A2A server
 
 
@@ -182,3 +213,4 @@ You can extend this sample by:
 - Check the logs for both the local ADK web server and remote A2A server
 - Verify OAuth tokens are properly passed between agents
 - Ensure agent instructions are clear about authentication requirements
+- **Double-check that the RPC URL in the agent.json file is correct and accessible**

contributing/samples/a2a_auth/remote_a2a/bigquery_agent/agent.json

@@ -24,6 +24,6 @@
       "tags": ["authentication", "oauth", "security"]
     }
   ],
-  "url": "http://localhost:8000/a2a/bigquery_agent",
+  "url": "http://localhost:8001/a2a/bigquery_agent",
   "version": "1.0.0"
 }

contributing/samples/a2a_auth/remote_a2a/bigquery_agent/agent.py

@@ -46,7 +46,7 @@ root_agent = Agent(
       Use the provided tools to conduct various operations on users' data in Google BigQuery.
 
       Scenario 1:
-      The user wants to query their biguqery datasets
+      The user wants to query their bigquery datasets
       Use bigquery_datasets_list to query user's datasets
 
       Scenario 2:

contributing/samples/a2a_basic/README.md

@@ -107,15 +107,47 @@ You can extend this sample by:
 - Adding persistent state management
 - Integrating with external APIs or databases
 
+## Deployment to Other Environments
+
+When deploying the remote A2A agent to different environments (e.g., Cloud Run, different hosts/ports), you **must** update the `url` field in the agent card JSON file:
+
+### Local Development
+```json
+{
+  "url": "http://localhost:8001/a2a/check_prime_agent",
+  ...
+}
+```
+
+### Cloud Run Example
+```json
+{
+  "url": "https://your-service-abc123-uc.a.run.app/a2a/check_prime_agent",
+  ...
+}
+```
+
+### Custom Host/Port Example
+```json
+{
+  "url": "https://your-domain.com:9000/a2a/check_prime_agent",
+  ...
+}
+```
+
+**Important:** The `url` field in `remote_a2a/check_prime_agent/agent.json` must point to the actual RPC endpoint where your remote A2A agent is deployed and accessible.
+
 ## Troubleshooting
 
 **Connection Issues:**
 - Ensure the local ADK web server is running on port 8000
 - Ensure the remote A2A server is running on port 8001
 - Check that no firewall is blocking localhost connections
+- **Verify the `url` field in `remote_a2a/check_prime_agent/agent.json` matches the actual deployed location of your remote A2A server**
 - Verify the agent card URL passed to RemoteA2AAgent constructor matches the running A2A server
 
 
 **Agent Not Responding:**
 - Check the logs for both the local ADK web server on port 8000 and remote A2A server on port 8001
 - Verify the agent instructions are clear and unambiguous
+- **Double-check that the RPC URL in the agent.json file is correct and accessible**