Initial plan

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 833363352

.github/ISSUE_TEMPLATE/bug_report.md

@@ -19,7 +19,7 @@ Steps to reproduce the behavior:
 1. Install '...'
 2. Run '....'
 3. Open '....'
-4. Provie error or stacktrace
+4. Provide error or stacktrace
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.

.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/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/pr-triage.yml

@@ -3,10 +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: "!contains(github.event.pull_request.labels.*.name, 'bot triaged') && !contains(github.event.pull_request.labels.*.name, 'google-contributor')"
+    if: github.event_name == 'workflow_dispatch' || !contains(github.event.pull_request.labels.*.name, 'google-contributor')
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
@@ -33,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/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:

.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.
@@ -21,6 +65,129 @@ Please refer to [ADK Project Overview and Architecture](https://github.com/googl
 - 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.10+ (**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
@@ -37,48 +204,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
@@ -95,39 +282,67 @@ 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
+
+```
+
+### 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
@@ -213,9 +428,118 @@ 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)
+
+## Python Tips
+
+### General Python Best Practices
+
+*   **Constants:** Use immutable global constant collections (tuple, frozenset, immutabledict) to avoid hard-to-find bugs. Prefer constants over wild string/int literals, especially for dictionary keys, pathnames, and enums.
+*   **Naming:** Name mappings like `value_by_key` to enhance readability in lookups (e.g., `item = item_by_id[id]`).
+*   **Readability:** Use f-strings for concise string formatting, but use lazy-evaluated `%`-based templates for logging. Use `repr()` or `pprint.pformat()` for human-readable debug messages. Use `_` as a separator in numeric literals to improve readability.
+*   **Comprehensions:** Use list, set, and dict comprehensions for building collections concisely.
+*   **Iteration:** Iterate directly over containers without indices. Use `enumerate()` when you need the index, `dict.items()` for keys and values, and `zip()` for parallel iteration.
+*   **Built-ins:** Leverage built-in functions like `all()`, `any()`, `reversed()`, `sum()`, etc., to write more concise and efficient code.
+*   **Flattening Lists:** Use `itertools.chain.from_iterable()` to flatten a list of lists efficiently without unnecessary copying.
+*   **String Methods:** Use `startswith()` and `endswith()` with a tuple of strings to check for multiple prefixes or suffixes at once.
+*   **Decorators:** Use decorators to add common functionality (like logging, timing, caching) to functions without modifying their core logic. Use `functools.wraps()` to preserve the original function's metadata.
+*   **Context Managers:** Use `with` statements and context managers (from `contextlib` or custom classes with `__enter__`/`__exit__`) to ensure resources are properly initialized and torn down, even in the presence of exceptions.
+*   **Else Clauses:** Utilize the `else` clause in `try/except` blocks (runs if no exception), and in `for/while` loops (runs if the loop completes without a `break`) to write more expressive and less error-prone code.
+*   **Single Assignment:** Prefer single-assignment form (assign to a variable once) over assign-and-mutate to reduce bugs and improve readability. Use conditional expressions where appropriate.
+*   **Equality vs. Identity:** Use `is` or `is not` for singleton comparisons (e.g., `None`, `True`, `False`). Use `==` for value comparison.
+*   **Object Comparisons:** When implementing custom classes, be careful with `__eq__`. Return `NotImplemented` for unhandled types. Consider edge cases like subclasses and hashing. Prefer using `attrs` or `dataclasses` to handle this automatically.
+*   **Hashing:** If objects are equal, their hashes must be equal. Ensure attributes used in `__hash__` are immutable. Disable hashing with `__hash__ = None` if custom `__eq__` is implemented without a proper `__hash__`.
+*   **`__init__()` vs. `__new__()`:** `__new__()` creates the object, `__init__()` initializes it. For immutable types, modifications must happen in `__new__()`.
+*   **Default Arguments:** NEVER use mutable default arguments. Use `None` as a sentinel value instead.
+*   **`__add__()` vs. `__iadd__()`:** `x += y` (in-place add) can modify the object in-place if `__iadd__` is implemented (like for lists), while `x = x + y` creates a new object. This matters when multiple variables reference the same object.
+*   **Properties:** Use `@property` to create getters and setters only when needed, maintaining a simple attribute access syntax. Avoid properties for computationally expensive operations or those that can fail.
+*   **Modules for Namespacing:** Use modules as the primary mechanism for grouping and namespacing code elements, not classes. Avoid `@staticmethod` and methods that don't use `self`.
+*   **Argument Passing:** Python is call-by-value, where the values are object references (pointers). Assignment binds a name to an object. Modifying a mutable object through one name affects all names bound to it.
+*   **Keyword/Positional Arguments:** Use `*` to force keyword-only arguments and `/` to force positional-only arguments. This can prevent argument transposition errors and make APIs clearer, especially for functions with multiple arguments of the same type.
+*   **Type Hinting:** Annotate code with types to improve readability, debuggability, and maintainability. Use abstract types from `collections.abc` for container annotations (e.g., `Sequence`, `Mapping`, `Iterable`). Annotate return values, including `None`. Choose the most appropriate abstract type for function arguments and return types.
+*   **`NewType`:** Use `typing.NewType` to create distinct types from primitives (like `int` or `str`) to prevent argument transposition and improve type safety.
+*   **`__repr__()` vs. `__str__()`:** Implement `__repr__()` for unambiguous, developer-focused string representations, ideally evaluable. Implement `__str__()` for human-readable output. `__str__()` defaults to `__repr__()`.
+*   **F-string Debug:** Use `f"{expr=}"` for concise debug printing, showing both the expression and its value.
+
+### Libraries and Tools
+
+*   **`collections.Counter`:** Use for efficiently counting hashable objects in an iterable.
+*   **`collections.defaultdict`:** Useful for avoiding key checks when initializing dictionary values, e.g., appending to lists.
+*   **`heapq`:** Use `heapq.nlargest()` and `heapq.nsmallest()` for efficiently finding the top/bottom N items. Use `heapq.merge()` to merge multiple sorted iterables.
+*   **`attrs` / `dataclasses`:** Use these libraries to easily define simple classes with boilerplate methods like `__init__`, `__repr__`, `__eq__`, etc., automatically generated.
+*   **NumPy:** Use NumPy for efficient array computing, element-wise operations, math functions, filtering, and aggregations on numerical data.
+*   **Pandas:** When constructing DataFrames row by row, append to a list of dicts and call `pd.DataFrame()` once to avoid inefficient copying. Use `TypedDict` or `dataclasses` for intermediate row data.
+*   **Flags:** Use libraries like `argparse` or `click` for command-line flag parsing. Access flag values in a type-safe manner.
+*   **Serialization:** For cross-language serialization, consider JSON (built-in), Protocol Buffers, or msgpack. For Python serialization with validation, use `pydantic` for runtime validation and automatic (de)serialization, or `cattrs` for performance-focused (de)serialization with `dataclasses` or `attrs`.
+*   **Regular Expressions:** Use `re.VERBOSE` to make complex regexes more readable with whitespace and comments. Choose the right method (`re.search`, `re.fullmatch`). Avoid regexes for simple string checks (`in`, `startswith`, `endswith`). Compile regexes used multiple times with `re.compile()`.
+*   **Caching:** Use `functools.lru_cache` with care. Prefer immutable return types. Be cautious when memoizing methods, as it can lead to memory leaks if the instance is part of the cache key; consider `functools.cached_property`.
+*   **Pickle:** Avoid using `pickle` due to security risks and compatibility issues. Prefer JSON, Protocol Buffers, or msgpack for serialization.
+*   **Multiprocessing:** Be aware of potential issues with `multiprocessing` on some platforms, especially concerning `fork`. Consider alternatives like threads (`concurrent.futures.ThreadPoolExecutor`) or `asyncio` for I/O-bound tasks.
+*   **Debugging:** Use `IPython.embed()` or `pdb.set_trace()` to drop into an interactive shell for debugging. Use visual debuggers if available. Log with context, including inputs and exception info using `logging.exception()` or `exc_info=True`.
+*   **Property-Based Testing & Fuzzing:** Use `hypothesis` for property-based testing that generates test cases automatically. For coverage-guided fuzzing, consider `atheris` or `python-afl`.
+
+### Testing
+
+*   **Assertions:** Use pytest's native `assert` statements with informative expressions. Pytest automatically provides detailed failure messages showing the values involved. Add custom messages with `assert condition, "helpful message"` when the expression alone isn't clear.
+*   **Custom Assertions:** Write reusable helper functions (not methods) for repeated complex checks. Use `pytest.fail("message")` to explicitly fail a test with a custom message.
+*   **Parameterized Tests:** Use `@pytest.mark.parametrize` to reduce duplication when running the same test logic with different inputs. This is more idiomatic than the `parameterized` library.
+*   **Fixtures:** Use pytest fixtures (with `@pytest.fixture`) for test setup, teardown, and dependency injection. Fixtures are cleaner than class-based setup methods and can be easily shared across tests.
+*   **Mocking:** Use `mock.create_autospec()` with `spec_set=True` to create mocks that match the original object's interface, preventing typos and API mismatch issues. Use context managers (`with mock.patch(...)`) to manage mock lifecycles and ensure patches are stopped. Prefer injecting dependencies via fixtures over patching.
+*   **Asserting Mock Calls:** Use `mock.ANY` and other matchers for partial argument matching when asserting mock calls (e.g., `assert_called_once_with`).
+*   **Temporary Files:** Use pytest's `tmp_path` and `tmp_path_factory` fixtures for creating isolated and automatically cleaned-up temporary files/directories. These are preferred over the `tempfile` module in pytest tests.
+*   **Avoid Randomness:** Do not use random number generators to create inputs for unit tests. This leads to flaky, hard-to-debug tests. Instead, use deterministic, easy-to-reason-about inputs that cover specific behaviors.
+*   **Test Invariants:** Focus tests on the invariant behaviors of public APIs, not implementation details.
+*   **Test Organization:** Prefer simple test functions over class-based tests unless you need to share fixtures across multiple test methods in a class. Use descriptive test names that explain the behavior being tested.
+
+### Error Handling
+
+*   **Re-raising Exceptions:** Use a bare `raise` to re-raise the current exception, preserving the original stack trace. Use `raise NewException from original_exception` to chain exceptions, providing context. Use `raise NewException from None` to suppress the original exception's context.
+*   **Exception Messages:** Always include a descriptive message when raising exceptions.
+*   **Converting Exceptions to Strings:** `str(e)` can be uninformative. `repr(e)` is often better. For full details including tracebacks and chained exceptions, use functions from the `traceback` module (e.g., `traceback.format_exception(e)`, `traceback.format_exc()`).
+*   **Terminating Programs:** Use `sys.exit()` for expected terminations. Uncaught non-`SystemExit` exceptions should signal bugs. Avoid functions that cause immediate, unclean exits like `os.abort()`.
+*   **Returning None:** Be consistent. If a function can return a value, all paths should return a value (use `return None` explicitly). Bare `return` is only for early exit in conceptually void functions (annotated with `-> None`).

CHANGELOG.md

@@ -1,14 +1,267 @@
 # Changelog
 
+## [1.18.0](https://github.com/google/adk-python/compare/v1.17.0...v1.18.0) (2025-11-05)
+
+### Features
+
+* **[ADK Visual Agent Builder]**
+  * Core Features
+    * Visual workflow designer for agent creation
+    * Support for multiple agent types (LLM, Sequential, Parallel, Loop, Workflow)
+    * Agent tool support with nested agent tools
+    * Built-in and custom tool integration
+    * Callback management for all ADK callback types (before/after agent, model, tool)
+    * Assistant to help you build your agents with natural language
+    * Assistant proposes and writes agent configuration yaml files for you
+    * Save to test with chat interfaces as normal
+    * Build and debug at the same time in adk web!
+
+* **[Core]**
+  * Add support for extracting cache-related token counts from LiteLLM usage ([4f85e86](https://github.com/google/adk-python/commit/4f85e86fc3915f0e67312a39fe22451968d4f1b1))
+  * Expose the Python code run by the code interpreter in the logs ([a2c6a8a](https://github.com/google/adk-python/commit/a2c6a8a85cf4f556e9dacfe46cf384d13d964208))
+  * Add run_debug() helper method for quick agent experimentation ([0487eea](https://github.com/google/adk-python/commit/0487eea2abcd05d7efd123962d17b8c6c9a9d975))
+  * Allow injecting a custom Runner into `agent_to_a2a` ([156d235](https://github.com/google/adk-python/commit/156d23547915e8f7f5c6ba55e0362f4b133c3968))
+  * Support MCP prompts via the McpInstructionProvider class ([88032cf](https://github.com/google/adk-python/commit/88032cf5c56bb2d81842353605f9f5ab4b2206ff))
+
+* **[Models]**
+  * Add model tracking to LiteLlm and introduce a LiteLLM with fallbacks demo ([d4c63fc](https://github.com/google/adk-python/commit/d4c63fc5629e7d70ad8b8185be09243a01e3428f))
+  * Add ApigeeLlm as a model that lets ADK Agent developers to connect with an Apigee proxy ([87dcb3f](https://github.com/google/adk-python/commit/87dcb3f7ba344a2ba7d9edfc4817c9e792d90bfc))
+
+* **[Integrations]**
+  * Add example and fix for loading and upgrading old ADK session databases ([338c3c8](https://github.com/google/adk-python/commit/338c3c89c6bce7f3406f729013cedcd78b809a56))
+  * Add support for specifying logging level for adk eval cli command ([b1ff85f](https://github.com/google/adk-python/commit/b1ff85fb2347e3402eedd42e3673be7093a99548))
+  * Propagate LiteLLM finish_reason to LlmResponse for use in callbacks ([71aa564](https://github.com/google/adk-python/commit/71aa5645f6c3d91fd0e0ddb1ed564188c6727080))
+  * Allow LLM request to override the model used in the generate content async method in LiteLLM ([ce8f674](https://github.com/google/adk-python/commit/ce8f674a287368439ba11be3285902671e9bc75a))
+  * Add api key argument to Vertex Session and Memory services for Express Mode support ([9014a84](https://github.com/google/adk-python/commit/9014a849eab9f77b82db4a7f2053fb2a96282f03))
+  * Added support for enums as arguments for function tools ([240ef5b](https://github.com/google/adk-python/commit/240ef5beea9389911e8c03a6039b353befc716ac))
+  * Implement artifact_version related methods in GcsArtifactService ([e194ebb](https://github.com/google/adk-python/commit/e194ebb33c62bc40403ea852a88f77a9511b61a4))
+
+* **[Services]**
+  * Add support for Vertex AI Express Mode when deploying to Agent Engine ([d4b2a8b](https://github.com/google/adk-python/commit/d4b2a8b49f98a9991cb44ac7ec6e538b81a08664))
+  * Remove custom polling logic for Vertex AI Session Service since LRO polling is supported in express mode ([546c2a6](https://github.com/google/adk-python/commit/546c2a68165f54e694664d5b6b6740566301782b))
+  * Make VertexAiSessionService fully asynchronous ([f7e2a7a](https://github.com/google/adk-python/commit/f7e2a7a40ef248dd6fbba9669503b0828a12f0cc))
+
+* **[Tools]**
+  * Add Bigquery detect_anomalies tool ([9851340](https://github.com/google/adk-python/commit/9851340ad1df86d6f5c21e8984199573f239bb2b))
+  * Extend Bigquery detect_anomalies tool to support future data anomaly detection ([38ea749](https://github.com/google/adk-python/commit/38ea749c9cec8e65f5e768f49fd2de79b5545571))
+  * Add get_job_info tool to BigQuery toolset ([6429457](https://github.com/google/adk-python/commit/64294572c1c93590aa3c221015a5cb9b440ee948))
+
+* **[Evals]**
+  * Add "final_session_state" to the EvalCase data model ([2274c4f](https://github.com/google/adk-python/commit/2274c4f3040b20da3690aa03272155776ca330c1))
+  * Marked expected_invocation as optional field on evaluator interface ([b17c8f1](https://github.com/google/adk-python/commit/b17c8f19e5fc67180d1bdc621f84cd43e357571c))
+  * Adds LLM-backed user simulator ([54c4ecc](https://github.com/google/adk-python/commit/54c4ecc73381cffa51cff01c7fb8a2ac59308c53))
+
+* **[Observability]**
+  * Add BigQueryLoggingPlugin for event logging to BigQuery ([b7dbfed](https://github.com/google/adk-python/commit/b7dbfed4a3d4a0165e2c6e51594d1f547bec89d3))
+
+* **[Live]**
+  * Add token usage to live events for bidi streaming ([6e5c0eb](https://github.com/google/adk-python/commit/6e5c0eb6e0474f5b908eb9df20328e7da85ebed9))
+
+### Bug Fixes
+
+* Reduce logging spam for MCP tools without authentication ([11571c3](https://github.com/google/adk-python/commit/11571c37ab948d43cbaa3a1d82522256dfe4d467))
+* Fix typo in several files ([d2888a3](https://github.com/google/adk-python/commit/d2888a3766b87df2baaaa1a67a2235b1b80f138f))
+* Disable SetModelResponseTool workaround for Vertex AI Gemini 2+ models ([6a94af2](https://github.com/google/adk-python/commit/6a94af24bf3367c05a5d405b7e7b79810a1fac4e))
+* Bug when callback_context_invocation_context is missing in GlobalInstructionPlugin ([f81ebdb](https://github.com/google/adk-python/commit/f81ebdb622211031945eb06c3f00ff5208d94f9b))
+* Support models slash prefix in model name extraction ([8dff850](https://github.com/google/adk-python/commit/8dff85099d67623dd6f4a707fb932ea55b8aaf9b))
+* Do not consider events with state delta and no content as final response ([1ee93c8](https://github.com/google/adk-python/commit/1ee93c8bcb7ccd6f33658dc76b2095dd7e58aac9))
+* Parameter filtering for CrewAI functions with **kwargs ([74a3500](https://github.com/google/adk-python/commit/74a3500fc5d4b07e80f914d83a0d91face28086c))
+* Do not treat FinishReason.STOP as error case for LLM responses containing candidates with empty contents ([2f72ceb](https://github.com/google/adk-python/commit/2f72ceb49b452c5a1f257bce6adb004fa5d54472))
+* Fixes null check for reflect_retry plugin sample ([86f0155](https://github.com/google/adk-python/commit/86f01550bd1b52d6d160e8bc54cecc6c4fe8611c))
+* Creates evalset directory on evalset create ([6c3882f](https://github.com/google/adk-python/commit/6c3882f2d66f169d393171be280b6e6218b52a7c))
+* Add ADK_DISABLE_LOAD_DOTENV environment variable that disables automatic loading of .env when running ADK cli, if set to true or 1 ([15afbcd](https://github.com/google/adk-python/commit/15afbcd1587d4102a4dc5c07c0c493917df9d6ea))
+* Allow tenacity 9.0.0 ([ee8acc5](https://github.com/google/adk-python/commit/ee8acc58be7421a3e8eab07b051c45f9319f80dc))
+* Output file uploading to artifact service should handle both base64 encoded and raw bytes ([496f8cd](https://github.com/google/adk-python/commit/496f8cd6bb36d3ba333d7ab1e94e7796d2960300))
+* Correct message part ordering in A2A history ([5eca72f](https://github.com/google/adk-python/commit/5eca72f9bfd05c7c28a3d738391138a59a31167d))
+* Change instruction insertion to respect tool call/response pairs ([1e6a9da](https://github.com/google/adk-python/commit/1e6a9daa63050936ab421f1f684935927aebc63e))
+* DynamicPickleType to support MySQL dialect ([fc15c9a](https://github.com/google/adk-python/commit/fc15c9a0c3c043c0a61dce625b8cd1ee121b4baf))
+* Enable usage metadata in LiteLLM streaming ([f9569bb](https://github.com/google/adk-python/commit/f9569bbb1afbc7f0e8b6e68599590471fd112b9f))
+* Fix issue with MCP tools throwing an error ([1a4261a](https://github.com/google/adk-python/commit/1a4261ad4b66cdeb39d39110a086bd6112b17516))
+* Remove redundant `format` field from LiteLLM content objects ([489c39d](https://github.com/google/adk-python/commit/489c39db01465e38ecbc2c7f32781c349b8cddc9))
+* Update the contribution analysis tool to use original write mode ([54db3d4](https://github.com/google/adk-python/commit/54db3d4434e0706b83a589fa2499d11d439a6e4e))
+* Fix agent evaluations detailed output rows wrapping issue([4284c61](https://github.com/google/adk-python/commit/4284c619010b8246c1ecaa011f14b6cc9de512dd))
+* Update dependency version constraints to be based on PyPI versions([0b1784e](https://github.com/google/adk-python/commit/0b1784e0e493a0e2df1edfe37e5ed5f4247e7d9d))
+
+### Improvements
+
+* Add Community Repo section to README ([432d30a](https://github.com/google/adk-python/commit/432d30af486329aa83f89c5d5752749a85c0b843))
+* Undo adding MCP tools output schema to FunctionDeclaration ([92a7d19](https://github.com/google/adk-python/commit/92a7d1957367d498de773761edd142d8c108d751))
+* Refactor ADK README for clarity and consistency ([b0017ae](https://github.com/google/adk-python/commit/b0017aed4472c73c3b07e71f1d65ae97a5293547))
+* Add support for reversed proxy in adk web ([a0df75b](https://github.com/google/adk-python/commit/a0df75b6fa35d837086decb8802dbf1c0a6637ad))
+* Avoid rendering empty columns as part of detailed results rendering of eval results ([5cb35db](https://github.com/google/adk-python/commit/5cb35db921bf86b5ad0012046bd19fa7cc1e6abb))
+* Clear the behavior of disallow_transfer_to_parent ([48ddd07](https://github.com/google/adk-python/commit/48ddd078941f9240b10f052b6de171c310bc2bc6))
+* Disable the scheduled execution for issue triage workflow ([a02f321](https://github.com/google/adk-python/commit/a02f321f1bdb8be9ad1873db804e0e8393268dc3))
+* Include delimiter when matching events from parent nodes in content processor ([b8a2b6c](https://github.com/google/adk-python/commit/b8a2b6c57080ae29d7a02df7d9fcc2f961d422d2))
+* Improve Tau-bench ADK colab stability ([04dbc42](https://github.com/google/adk-python/commit/04dbc42e50ce40ef3924d1c259e425215e12c2e7))
+* Implement ADK-based agent factory for Tau-bench ([c0c67c8](https://github.com/google/adk-python/commit/c0c67c8698d70ddb9ed958416661f232ef9a5ed8))
+* Add util to run ADK LLM Agent with simulation environment ([87f415a](https://github.com/google/adk-python/commit/87f415a7c36a1f3b6ab84d1fe939726c6ef7f34e))
+* Demonstrate CodeExecutor customization for environment setup ([8eeff35](https://github.com/google/adk-python/commit/8eeff35b35d7e1538a5c9662cc8369f6ff7962f8))
+* Add sample agent for VertexAiCodeExecutor ([edfe553](https://github.com/google/adk-python/commit/edfe5539421d196ca4da14d3a37fac7b598f8c8d))
+* Adds a new sample agent that demonstrates how to integrate PostgreSQL databases using the Model Context Protocol (MCP) ([45a2168](https://github.com/google/adk-python/commit/45a2168e0e6773e595ecfb825d7e4ab0a38c3a38))
+* Add example for using ADK with Fast MCP sampling ([d3796f9](https://github.com/google/adk-python/commit/d3796f9b33251d28d05e6701f11e80f02a2a49e1))
+* Refactor gepa sample code and clean-up user demo colab([63353b2](https://github.com/google/adk-python/commit/63353b2b74e23e97385892415c5a3f2a59c3504f))
+
+## [1.17.0](https://github.com/google/adk-python/compare/v1.16.0...v1.17.0) (2025-10-22)
+
+### Features
+
+* **[Core]**
+  * Add a service registry to provide a generic way to register custom service implementations to be used in FastAPI server. See [short instruction](https://github.com/google/adk-python/discussions/3175#discussioncomment-14745120). ([391628f](https://github.com/google/adk-python/commit/391628fcdc7b950c6835f64ae3ccab197163c990))
+  * Add the ability to rewind a session to before a previous invocation ([9dce06f](https://github.com/google/adk-python/commit/9dce06f9b00259ec42241df4f6638955e783a9d1))
+  * Support resuming a parallel agent with multiple branches paused on tool confirmation requests ([9939e0b](https://github.com/google/adk-python/commit/9939e0b087094038b90d86c2fd35c26dd63f1157))
+  * Support content union as static instruction ([cc24d61](https://github.com/google/adk-python/commit/cc24d616f80c0eba2b09239b621cf3d176f144ea))
+
+* **[Evals]**
+  * ADK cli allows developers to create an eval set and add an eval case ([ae139bb](https://github.com/google/adk-python/commit/ae139bb461c2e7c6be154b04f3f2c80919808d31))
+
+* **[Integrations]**
+  * Allow custom request and event converters in A2aAgentExecutor ([a17f3b2](https://github.com/google/adk-python/commit/a17f3b2e6d2d48c433b42e27763f3d6df80243ca))
+
+* **[Observability]**
+  * Env variable for disabling llm_request and llm_response in spans ([e50f05a](https://github.com/google/adk-python/commit/e50f05a9fc94834796876f7f112f344f788f202e))
+
+* **[Services]**
+  * Allow passing extra kwargs to create_session of VertexAiSessionService ([6a5eac0](https://github.com/google/adk-python/commit/6a5eac0bdc9adc6907a28f65a3d4d7234e863049))
+  * Implement new methods in in-memory artifact service to support custom metadata, artifact versions, etc. ([5a543c0](https://github.com/google/adk-python/commit/5a543c00df2f7a66018df8a67efcf4ce44d4e0e4))
+  * Add create_time and mime_type to ArtifactVersion ([2c7a342](https://github.com/google/adk-python/commit/2c7a34259395b1294319118d0f3d1b3b867b44d6))
+  * Support returning all sessions when user id is none ([141318f](https://github.com/google/adk-python/commit/141318f77554ae4eb5a360bea524e98eff4a086c))
+
+* **[Tools]**
+  * Support additional headers for Google API toolset ([ed37e34](https://github.com/google/adk-python/commit/ed37e343f0c997d3ee5dc98888c5e0dbd7f2a2b6))
+  * 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))
+  * Support dynamic per-request headers in MCPToolset ([6dcbb5a](https://github.com/google/adk-python/commit/6dcbb5aca642290112a7c81162b455526c15cd14))
+  * Add `bypass_multi_tools_limit` option to GoogleSearchTool and VertexAiSearchTool ([9a6b850](https://github.com/google/adk-python/commit/9a6b8507f06d8367488aac653efecf665619516c), [6da7274](https://github.com/google/adk-python/commit/6da727485898137948d72906d86d78b6db6331ac))
+  * Extend `ReflectAndRetryToolPlugin` to support hallucinating function calls ([f51380f](https://github.com/google/adk-python/commit/f51380f9ea4534591eda76bef27407c0aa7c3fae))
+  * Add require_confirmation param for MCP tool/toolset ([78e74b5](https://github.com/google/adk-python/commit/78e74b5bf2d895d72025a44dbcf589f543514a50))
+
+* **[UI]**
+  * Granular per agent speech configuration ([409df13](https://github.com/google/adk-python/commit/409df1378f36b436139aa909fc90a9e9a0776b3a))
+
+### Bug Fixes
+
+* Returns dict as result from McpTool to comply with BaseTool expectations ([4df9263](https://github.com/google/adk-python/commit/4df926388b6e9ebcf517fbacf2f5532fd73b0f71))
+* Fixes the identity prompt to be one line ([7d5c6b9](https://github.com/google/adk-python/commit/7d5c6b9acf0721dd230f08df919c7409eed2b7d0))
+* Fix the broken langchain importing caused their 1.0.0 release ([c850da3](https://github.com/google/adk-python/commit/c850da3a07ec1441037ced1b654d8aacacd277ab))
+* Fix BuiltInCodeExecutor to support visualizations ([ce3418a](https://github.com/google/adk-python/commit/ce3418a69de56570847d45f56ffe7139ab0a47aa))
+* Relax runner app-name enforcement and improve agent origin inference ([dc4975d](https://github.com/google/adk-python/commit/dc4975dea9fb79ad887460659f8f397a537ee38f))
+* Improve error message when adk web is run in wrong directory ([4a842c5](https://github.com/google/adk-python/commit/4a842c5a1334c3ee01406f796651299589fe12ab))
+* Handle App objects in eval and graph endpoints ([0b73a69](https://github.com/google/adk-python/commit/0b73a6937bd84a41f79a9ada3fc782dca1d6fb11))
+* Exclude `additionalProperties` from Gemini schemas ([307896a](https://github.com/google/adk-python/commit/307896aeceeb97efed352bc0217bae10423e5da6))
+* Overall eval status should be NOT_EVALUATED if no invocations were evaluated ([9fbed0b](https://github.com/google/adk-python/commit/9fbed0b15afb94ec8c0c7ab60221bbc97e481b06))
+* Create context cache only when prefix matches with previous request ([9e0b1fb](https://github.com/google/adk-python/commit/9e0b1fb62b06de7ecb79bf77d54a999167d001e1))
+* Handle `App` instances returned by `agent_loader.load_agent` ([847df16](https://github.com/google/adk-python/commit/847df1638cbf1686aa43e8e094121d4e23e40245))
+* Add support for file URIs in LiteLLM content conversion ([85ed500](https://github.com/google/adk-python/commit/85ed500871ff55c74d16e809ddae0d4db66cbc3a))
+* Only exclude scores that are None ([998264a](https://github.com/google/adk-python/commit/998264a5b1b98ac660fcc1359fb2d25c84fa0d87))
+* Better handling the A2A streaming tasks ([bddc70b](https://github.com/google/adk-python/commit/bddc70b5d004ba5304fe05bcbf6e08210f0e6131))
+* Correctly populate context_id in remote_a2a_agent library ([2158b3c](https://github.com/google/adk-python/commit/2158b3c91531e9125761f211f125d9ab41a55e10))
+* Remove unnecessary Aclosing ([2f4f561](https://github.com/google/adk-python/commit/2f4f5611bdb30bd5eb2fdb3a70f43d748371392f))
+* Fix pickle data was truncated error in database session using MySql ([36c96ec](https://github.com/google/adk-python/commit/36c96ec5b356109b7c874c85d8bb24f0bf6c050d))
+
+### Improvements
+
+* Improve hint message in agent loader ([fe1fc75](https://github.com/google/adk-python/commit/fe1fc75c15a7983829bbe0b023f4b612b1e5c018))
+* Fixes MCPToolset --> McpToolset in various places ([d4dc645](https://github.com/google/adk-python/commit/d4dc6454783f747120d407d0dc2cb78f53598d83))
+* Add span for context caching handling and new cache creation ([a2d9f13](https://github.com/google/adk-python/commit/a2d9f13fa1d31e00ba9493fba321ca151cdd9366))
+* Checks gemini version for `2 and above` for gemini-builtin tools ([0df6759](https://github.com/google/adk-python/commit/0df67599c0eb54a9a5df51af06483b40058953bf))
+* Refactor and fix state management in the session service ([8b3ed05](https://github.com/google/adk-python/commit/8b3ed059c24903e8aca0a09d9d503b48af7df850))
+* Update agent builder instructions and remove run command details ([89344da](https://github.com/google/adk-python/commit/89344da81364d921f778c8bbea93e1df6ad1097e))
+* Clarify how to use adk built-in tool in instruction ([d22b8bf](https://github.com/google/adk-python/commit/d22b8bf8907e723f618dfd18e90dd0a5dbc9518c))
+* Delegate the agent state reset logic to LoopAgent ([bb1ea74](https://github.com/google/adk-python/commit/bb1ea74924127d65d763a45b869da3d4ff4d5c5a))
+* Adjust the instruction about default model ([214986e](https://github.com/google/adk-python/commit/214986ebeb53b2ef34c8aa37cd6403106de82c1b))
+* Migrate invocation_context to callback_context ([e2072af](https://github.com/google/adk-python/commit/e2072af69f40474431b6749b7b9dc22fbcbc7730))
+* Correct the callback signatures ([fa84bcb](https://github.com/google/adk-python/commit/fa84bcb5756773eadff486b99c9bd416b4faa9c6))
+* Set default for `bypass_multi_tools_limit` to False for GoogleSearchTool and VertexAiSearchTool ([6da7274](https://github.com/google/adk-python/commit/6da727485898137948d72906d86d78b6db6331ac))
+* Add more clear instruction to the doc updater agent about one PR for each recommended change ([b21d0a5](https://github.com/google/adk-python/commit/b21d0a50d610407be2f10b73a91274840ffdfe18))
+* Add a guideline to avoid content deletion ([16b030b](https://github.com/google/adk-python/commit/16b030b2b25a9b0b489e47b4b148fc4d39aeffcb))
+* Add a sample agent for the `ReflectAndRetryToolPlugin` ([9b8a4aa](https://github.com/google/adk-python/commit/9b8a4aad6fe65ef37885e5c3368d2799a2666534))
+* Improve error message when adk web is run in wrong directory ([4a842c5](https://github.com/google/adk-python/commit/4a842c5a1334c3ee01406f796651299589fe12ab))
+* Add span for context caching handling and new cache creation ([a2d9f13](https://github.com/google/adk-python/commit/a2d9f13fa1d31e00ba9493fba321ca151cdd9366))
+* Disable the scheduled execution for issue triage workflow ([bae2102](https://github.com/google/adk-python/commit/bae21027d9bd7f811bed638ecce692262cb33fe5))
+* Correct the callback signatures ([fa84bcb](https://github.com/google/adk-python/commit/fa84bcb5756773eadff486b99c9bd416b4faa9c6))
+
+### Documentation
+
+* Format README.md for samples ([0bdba30](https://github.com/google/adk-python/commit/0bdba3026345872fb907aedd1ed75e4135e58a30))
+* Bump models in llms and llms-full to Gemini 2.5 ([ce46386](https://github.com/google/adk-python/commit/ce4638651f376fb6579993d8468ae57198134729))
+* Update gemini_llm_connection.py - typo spelling correction ([e6e2767](https://github.com/google/adk-python/commit/e6e2767c3901a14187f5527540f318317dd6c8e3))
+* Announce the first ADK Community Call in the README ([731bb90](https://github.com/google/adk-python/commit/731bb9078d01359ae770719a8f5c003680ed9f3e))
+
+## [1.16.0](https://github.com/google/adk-python/compare/v1.15.1...v1.16.0) (2025-10-08)
+
+### Features
+
+* **[Core]**
+  * Implementation of LLM context compaction ([e0dd06f](https://github.com/google/adk-python/commit/e0dd06ff04f9d3c2f022873ce145aaae2de02f45))
+  * Support pause and resume an invocation in ADK ([ce9c39f](https://github.com/google/adk-python/commit/ce9c39f5a85ed12c22009693b5e6bc65f4641633),
+    [2f1040f](https://github.com/google/adk-python/commit/2f1040f296db365080b62d6372474d90196ce0d6),
+    [1ee01cc](https://github.com/google/adk-python/commit/1ee01cc05add44ce460d2cfd3726dceb0c76dceb),
+    [f005414](https://github.com/google/adk-python/commit/f005414895a57befe880fd58c0d778e499a20d8e),
+    [fbf7576](https://github.com/google/adk-python/commit/fbf75761bb8d89a70b32c43bbd3fa2f48b81d67c))
+* **[Models]**
+  * Add `citation_metadata` to `LlmResponse` ([3f28e30](https://github.com/google/adk-python/commit/3f28e30c6da192e90a8100f270274cb9a55a5348))
+  * Add support for gemma model via gemini api ([2b5acb9](https://github.com/google/adk-python/commit/2b5acb98f577f5349e788bcf9910c8d7107e63b3))
+* **[Tools]**
+  * Add `dry_run` functionality to BigQuery `execute_sql` tool ([960eda3](https://github.com/google/adk-python/commit/960eda3d1f2f46dc93a365eb3de03dc3483fe9bb))
+  * Add BigQuery analyze_contribution tool ([4bb089d](https://github.com/google/adk-python/commit/4bb089d386d4e8133e9aadbba5c42d31ff281cf6))
+  * Spanner ADK toolset supports customizable template SQL and parameterized SQL ([da62700](https://github.com/google/adk-python/commit/da62700d739cb505149554962a8bcfb30f9428cc))
+  * Support OAuth2 client credentials grant type ([5c6cdcd](https://github.com/google/adk-python/commit/5c6cdcd197a6780fc86d9183fa208f78c8a975d9))
+  * Add `ReflectRetryToolPlugin` to reflect from errors and retry with different arguments when tool errors ([e55b894](https://github.com/google/adk-python/commit/e55b8946d6a2e01aaf018d6a79d11d13c5286152))
+  * Support using `VertexAiSearchTool` built-in tool with other tools in the same agent ([4485379](https://github.com/google/adk-python/commit/4485379a049a5c84583a43c85d444ea1f1ba6f12))
+  * Support using google search built-in tool with other tools in the same agent ([d3148da](https://github.com/google/adk-python/commit/d3148dacc97f0a9a39b6d7a9640f7b7b0d6f9a6c))
+* **[Evals]**
+  * Add HallucinationsV1 evaluation metric ([8c73d29](https://github.com/google/adk-python/commit/8c73d29c7557a75d64917ac503da519361d1d762))
+  * Add Rubric based tool use metric ([c984b9e](https://github.com/google/adk-python/commit/c984b9e5529b48fff64865a8b805e7e93942ea53))
+* **[UI]**
+  * Adds `adk web` options for custom logo ([822efe0](https://github.com/google/adk-python/commit/822efe00659607bad2d19ec9a2d14c649fca2d8d))
+* **[Observability]**
+  * **otel:** Switch CloudTraceSpanExporter to telemetry.googleapis.com ([bd76b46](https://github.com/google/adk-python/commit/bd76b46ce296409d929ae69c5c43347c73e7b365))
+
+### Bug Fixes
+
+* Adapt to new computer use tool name in genai sdk 1.41.0 ([c6dd444](https://github.com/google/adk-python/commit/c6dd444fc947571d089b784fde3a81e17b10cf28))
+* Add AuthConfig json serialization in vertex ai session service ([636def3](https://github.com/google/adk-python/commit/636def3687a85e274e3ab44d906f6d92d49e84c0))
+* Added more agent instructions for doc content changes ([7459962](https://github.com/google/adk-python/commit/745996212db156878554386be34f58658482e687))
+* Convert argument to pydantic model when tool declares it accepts pydantic model as argument ([571c802](https://github.com/google/adk-python/commit/571c802fbaa80b3e65f9ce2db772b9db5a13dbc4))
+* Do not re-create `App` object when loader returns an `App` ([d5c46e4](https://github.com/google/adk-python/commit/d5c46e496009eb55d78637f47162df7fcaf3a7ac))
+* Fix compaction logic ([3f2b457](https://github.com/google/adk-python/commit/3f2b457efd27ed47160811705e30efa6dd09d7c0))
+* Fix the instruction in workflow_triage example agent ([8f3ca03](https://github.com/google/adk-python/commit/8f3ca0359e5b1306c1395770759a74aa48a52347))
+* Fixes a bug that causes intermittent `pydantic` validation errors when uploading files ([e680063](https://github.com/google/adk-python/commit/e68006386fdd0da98feb9c3dce9322e44a9c914d))
+* Handle A2A Task Status Update Event when streaming in remote_a2a_agent ([a5cf80b](https://github.com/google/adk-python/commit/a5cf80b952887c07bb1d56b7bdec28808edcc4a9))
+* Make compactor optional in Events Compaction Config and add a default ([3f4bd67](https://github.com/google/adk-python/commit/3f4bd67b49cd60e6a2e43ccd5192efe450a6e009))
+* Rename SlidingWindowCompactor to LlmEventSummarizer and refine its docstring ([f1abdb1](https://github.com/google/adk-python/commit/f1abdb1938e474564a3a76279a1a0a511f74a750))
+* Rollback compaction handling from _get_contents ([84f2f41](https://github.com/google/adk-python/commit/84f2f417f77ead3748c5bbeac7f144164b9a9416))
+* Set `max_output_tokens` for the agent builder ([2e2d61b](https://github.com/google/adk-python/commit/2e2d61b6fecb90cd474d6f51255678ff74b67a9b))
+* Set default response modality to AUDIO in run_session ([68402bd](https://github.com/google/adk-python/commit/68402bda49083f2d56f8e8488fe13aa58b3bc18c))
+* Update remote_a2a_agent to better handle streaming events and avoid duplicate responses ([8e5f361](https://github.com/google/adk-python/commit/8e5f36126498f751171bb2639c7f5a9e7dca2558))
+* Update the load_artifacts tool so that the model can reliably call it for follow up questions about the same artifact ([238472d](https://github.com/google/adk-python/commit/238472d083b5aa67551bde733fc47826ff062679))
+* Fix VertexAiSessionService base_url override to preserve initialized http_options ([8110e41](https://github.com/google/adk-python/commit/8110e41b36cceddb8b92ba17cffaacf701706b36), [c51ea0b](https://github.com/google/adk-python/commit/c51ea0b52e63de8e43d3dccb24f9d20987784aa5))
+* Handle `App` instances returned by `agent_loader.load_agent` ([847df16](https://github.com/google/adk-python/commit/847df1638cbf1686aa43e8e094121d4e23e40245))
+
+### Improvements
+
+* Migrate VertexAiSessionService to use Agent Engine SDK ([90d4c19](https://github.com/google/adk-python/commit/90d4c19c5115c7af361effa8e12c248225ccf6ab))
+* Migrate VertexAiMemoryBankService to use Agent Engine SDK ([d1efc84](https://github.com/google/adk-python/commit/d1efc8461e82fc31df940b701f1d1b5422214296), [97b950b](https://github.com/google/adk-python/commit/97b950b36b9c16467f0f42216b2dc8395346d7fe), [83fd045](https://github.com/google/adk-python/commit/83fd0457188decdabeae58b4e8be25daa89f2943))
+* Add support for resolving $ref and $defs in OpenAPI schemas ([a239716](https://github.com/google/adk-python/commit/a239716930c72a0dbd2ccabeea69be46110ca48d))
+
+### Documentation
+
+* Update BigQuery samples README ([3021266](https://github.com/google/adk-python/commit/30212669ff61f3cbd6603c3dceadfbcc4cec42f8))
+
+## [1.15.1](https://github.com/google/adk-python/compare/v1.15.0...v1.15.1) (2025-09-26)
+
+### Bug Fixes
+
+* Fix the deployment failure for Agent Engine ([e172811](https://github.com/google/adk-python/commit/e172811bc7173b9004572f2a2afc7024145d7713))
+
 ## [1.15.0](https://github.com/google/adk-python/compare/v1.14.1...v1.15.0) (2025-09-24)
 
 ### Features
 
-* [Core]
+* **[Core]**
   * Adding the ContextFilterPlugin ([a06bf27](https://github.com/google/adk-python/commit/a06bf278cbc89f521c187ed51b032d82ffdafe2d))
   * Adds plugin to save artifacts for issue [#2176](https://github.com/google/adk-python/issues/2176) ([657369c](https://github.com/google/adk-python/commit/657369cffe142ef3745cd5950d0d24a49f42f7fd))
   * Expose log probs of candidates in LlmResponse ([f7bd3c1](https://github.com/google/adk-python/commit/f7bd3c111c211e880d7c1954dd4508b952704c68))
-* [Context Caching]
+* **[Context Caching]**
   * Support context caching ([c66245a](https://github.com/google/adk-python/commit/c66245a3b80192c16cb67ee3194f82c9a7c901e5))
     - Support explicit context caching auto creation and lifecycle management.
 
@@ -23,21 +276,21 @@
 
       Usage:
       `LlmAgent(model=...,static_instruction =types.Content(parts=...), ... )`
-* [Telemetry]
+* **[Observability]**
   * Add --otel_to_cloud experimental support ([1ae0b82](https://github.com/google/adk-python/commit/1ae0b82f5602a57ad1ca975ca0b7c85003d1a28a), [b131268](https://github.com/google/adk-python/commit/b1312680f4ea9f21c3246a1d24392619643d71f5), [7870480](https://github.com/google/adk-python/commit/7870480c63bb4fc08cfb3cabc0e1f0458f0e85bd))
   * Add GenAI Instrumentation if --otel_to_cloud is enabled ([cee365a](https://github.com/google/adk-python/commit/cee365a13d0d1b1f2be046c1cc29e24a8d1fdbcc))
   * Support standard OTel env variables for exporter endpoints ([f157b2e](https://github.com/google/adk-python/commit/f157b2ee4caf4055e78f4657254e45913895f5de))
   * Temporarily disable Cloud Monitoring integration in --otel_to_cloud ([3b80337](https://github.com/google/adk-python/commit/3b80337faf427460e4743e25dbb92578f823513f))
-* [Services]
+* **[Services]**
   * Add endpoint to generate memory from session ([2595824](https://github.com/google/adk-python/commit/25958242db890b4d2aac8612f7f7cfbb561727fa))
-* [Tools]
+* **[Tools]**
   * Add Google Maps Grounding Tool to ADK ([6b49391](https://github.com/google/adk-python/commit/6b493915469ecb42068e24818ab547b0856e4709))
-  * **MCP:** Initialize tool_name_prefix in MCPToolse ([86dea5b](https://github.com/google/adk-python/commit/86dea5b53ac305367283b7e353b60d0f4515be3b))
-* [Evals]
+  * **MCP:** Initialize tool_name_prefix in MCPToolset ([86dea5b](https://github.com/google/adk-python/commit/86dea5b53ac305367283b7e353b60d0f4515be3b))
+* **[Evals]**
   * Data model for storing App Details and data model for steps ([01923a9](https://github.com/google/adk-python/commit/01923a9227895906ca8ae32712d65b178e2cd7d5))
   * Adds Rubric based final response evaluator ([5a485b0](https://github.com/google/adk-python/commit/5a485b01cd64cb49735e13ebd5e7fa3da02cd85f))
   * Populate AppDetails to each Invocation ([d486795](https://github.com/google/adk-python/commit/d48679582de91050ca9c5106402319be9a8ae7e8))
-* [Samples]
+* **[Samples]**
   * Make the bigquery sample agent run with ADC out-of-the-box ([10cf377](https://github.com/google/adk-python/commit/10cf37749417856e394e62896231e41b13420f18))
 
 ### Bug Fixes
@@ -65,22 +318,22 @@
 
 ### Features
 
-* [A2A]
+* **[A2A]**
   * Allow users to pass their own agent card to to_a2a method [a1679da](https://github.com/google/adk-python/commit/a1679dae3fef70f1231afba3e97d45b59c314ae3)
   * Allow custom part converters in A2A classes [b05fef9](https://github.com/google/adk-python/commit/b05fef9ba71f95ab2658eb4eb5608c141d49f82f)
-* [Tools]
+* **[Tools]**
   * Allow setting agent/application name and compute project for BigQuery tools [11a2ffe](https://github.com/google/adk-python/commit/11a2ffe35adbae977b49ceccf0e76e20c6dc90b6)
   * Add BigQuery forecast tool [0935a40](https://github.com/google/adk-python/commit/0935a40011a3276ee7f7fa3b91678b4d63f22ba5)
   * Add GkeCodeExecutor for sandboxed code execution on GKE [72ff9c6](https://github.com/google/adk-python/commit/72ff9c64a291aebb50b07446378f375e58882c4e)
   * Add a tool confirmation flow that can guard tool execution with explicit confirmation and custom input [a17bcbb](https://github.com/google/adk-python/commit/a17bcbb2aa0f5c6aca460db96ed1cb7dd86fef84)
   * Add audience and prompt as configurable for OAuth flows [edda922](https://github.com/google/adk-python/commit/edda922791f15ac37830ed95ebf76b9f836d9db4)
   * Allow user specify embedding model for file retrieval [67f23df](https://github.com/google/adk-python/commit/67f23df25ad47aff3cb36d0fc9ce2c9b97bde09b)
-* [Core]
+* **[Core]**
   * Allow all possible values for `agent_class` field in all Agent Configs [3bc2d77](https://github.com/google/adk-python/commit/3bc2d77b4d180e9c42b30d4d1ce580aa75abe501)
   * Allow agent loader to load built-in agents from special directories in adk folder [578fad7](https://github.com/google/adk-python/commit/578fad7034a7b369a490ad0afa4dd2820463c22d)
   * Upgrade ADK runner to use App in addition to root_agent [4df79dd](https://github.com/google/adk-python/commit/4df79dd5c92d96096d031b26470458d0bca79a79)
   * Allow inject artifact into instructions [bb4cfde](https://github.com/google/adk-python/commit/bb4cfdec12370955d4038d6d8c86e04691f2308e)
-* [Misc] Create an initial ADK release analyzer agent to find the doc updates needed between releases [e3422c6](https://github.com/google/adk-python/commit/e3422c616d18ec3850454ee83f2ef286198543ec)
+* **[Misc]** Create an initial ADK release analyzer agent to find the doc updates needed between releases [e3422c6](https://github.com/google/adk-python/commit/e3422c616d18ec3850454ee83f2ef286198543ec)
 
 ### Bug Fixes
 
@@ -99,7 +352,7 @@
 * Fix discussion answering github action workflow to escape the quote in the discussion content JSON [43c9681](https://github.com/google/adk-python/commit/43c96811da891a5b0c9cf1be525665e65f346a13)
 * Send full MIME types for image/video/pdf in get_content [e45c3be](https://github.com/google/adk-python/commit/e45c3be23895b5ec68908ad9ee19bd622dcbd003)
 * Fix flaky unit tests: tests/unittests/flows/llm_flows/test_functions_simple.py [b92b288](https://github.com/google/adk-python/commit/b92b288c978a9b3d1a76c8bcb96cc8f439ce610b)
-* Make UT of a2a consistent about how tests should be skipped when python verison < 3.10 [98b0426](https://github.com/google/adk-python/commit/98b0426cd2dc5e28014ead22b22dbf50d42d0a9a)
+* Make UT of a2a consistent about how tests should be skipped when python version < 3.10 [98b0426](https://github.com/google/adk-python/commit/98b0426cd2dc5e28014ead22b22dbf50d42d0a9a)
 
 ### Improvements
 
@@ -190,7 +443,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 * Using base event's invocation id when merge multiple function response event ([279e4fe](https://github.com/google/adk-python/commit/279e4fedd0b1c0d1499c0f9a4454357af7da490e))
 * Avoid crash when there is no candidates_token_count, which is Optional ([22f34e9](https://github.com/google/adk-python/commit/22f34e9d2c552fbcfa15a672ef6ff0c36fa32619))
 * Fix the packaging version comparison logic in adk cli ([a2b7909](https://github.com/google/adk-python/commit/a2b7909fc36e7786a721f28e2bf75a1e86ad230d))
-* Add Spanner admin scope to Spanner tool default Oauth scopes ([b66054d](https://github.com/google/adk-python/commit/b66054dd0d8c5b3d6f6ad58ac1fbd8128d1da614))
+* Add Spanner admin scope to Spanner tool default OAuth scopes ([b66054d](https://github.com/google/adk-python/commit/b66054dd0d8c5b3d6f6ad58ac1fbd8128d1da614))
 * Fixes SequentialAgent.config_type type hint ([8a9a271](https://github.com/google/adk-python/commit/8a9a271141678996c9b84b8c55d4b539d011391c))
 * Fixes the host in the ansi bracket of adk web ([cd357bf](https://github.com/google/adk-python/commit/cd357bf5aeb01f1a6ae2a72349a73700ca9f1ed2))
 * Add spanner tool name prefix ([a27927d](https://github.com/google/adk-python/commit/a27927dc8197c391c80acb8b2c23d610fba2f887))
@@ -202,7 +455,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 * Update `openai` dependency version, based on correct OPENAI release ([bb8ebd1](https://github.com/google/adk-python/commit/bb8ebd15f90768b518cd0e21a59b269e30d6d944))
 * Add the missing license header for core_callback_config init file ([f8fd6a4](https://github.com/google/adk-python/commit/f8fd6a4f09ab520b8ecdbd8f9fe48228dbff7ebe))
 * Creates yaml_utils.py in utils to allow adk dump yaml in the same style ([1fd58cb](https://github.com/google/adk-python/commit/1fd58cb3633992cd88fa7e09ca6eda0f9b34236f))
-* Return explict None type for DELETE endpoints ([f03f167](https://github.com/google/adk-python/commit/f03f1677790c0a9e59b6ba6f46010d0b7b64be50))
+* Return explicit None type for DELETE endpoints ([f03f167](https://github.com/google/adk-python/commit/f03f1677790c0a9e59b6ba6f46010d0b7b64be50))
 * Add _config suffix to all yaml-based agent examples ([43f302c](https://github.com/google/adk-python/commit/43f302ce1ab53077ee8f1486d5294540678921e6))
 * Rename run related method and request to align with the conventions ([ecaa7b4](https://github.com/google/adk-python/commit/ecaa7b4c9847b478c7cdc37185b1525f733bb403))
 * Update models in samples/ folder to be gemini 2.0+ ([6c217ba](https://github.com/google/adk-python/commit/6c217bad828edf62b41ec06b168f8a6cb7ece2ed))
@@ -227,7 +480,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 
 ### Bug Fixes
 
-* A2A RPC URL got overriden by host and port param of adk api server ([52284b1](https://github.com/google/adk-python/commit/52284b1bae561e0d6c93c9d3240a09f210551b97))
+* A2A RPC URL got overridden by host and port param of adk api server ([52284b1](https://github.com/google/adk-python/commit/52284b1bae561e0d6c93c9d3240a09f210551b97))
 * Aclose all async generators to fix OTel tracing context ([a30c63c](https://github.com/google/adk-python/commit/a30c63c5933a770b960b08a6e2f8bf13eece8a22))
 * Use PreciseTimestamp for create and update time in database session service to improve precision ([585141e](https://github.com/google/adk-python/commit/585141e0b7dda20abb024c7164073862c8eea7ae))
 * Ignore AsyncGenerator return types in function declarations ([e2518dc](https://github.com/google/adk-python/commit/e2518dc371fe77d7b30328d8d6f5f864176edeac))
@@ -255,7 +508,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 * Group FastAPI endpoints with tags ([c323de5](https://github.com/google/adk-python/commit/c323de5c692223e55372c3797e62d4752835774d))
 * Allow implementations to skip defining a close method on Toolset ([944e39e](https://github.com/google/adk-python/commit/944e39ec2a7c9ad7f20c08fd66bf544de94a23d7))
 * Add sample agent to test support of output_schema and tools at the same time for gemini model ([f2005a2](https://github.com/google/adk-python/commit/f2005a20267e1ee8581cb79c37aa55dc8e18c0ea))
-* Add Github workflow config for uploading ADK docs to knowledge store ([5900273](https://github.com/google/adk-python/commit/59002734559d49a46940db9822b9c5f490220a8c))
+* Add GitHub workflow config for uploading ADK docs to knowledge store ([5900273](https://github.com/google/adk-python/commit/59002734559d49a46940db9822b9c5f490220a8c))
 * Update ADK Answering agent to reference doc site instead of adk-docs repo ([b5a8bad](https://github.com/google/adk-python/commit/b5a8bad170e271b475385dac440c7983ed207df8))
 
 ### Documentation
@@ -287,7 +540,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 
 ### Improvements
 
-* Add Github workflow config for the ADK Answering agent ([8dc0c94](https://github.com/google/adk-python/commit/8dc0c949afb9024738ff7ac1b2c19282175c3200))
+* Add GitHub workflow config for the ADK Answering agent ([8dc0c94](https://github.com/google/adk-python/commit/8dc0c949afb9024738ff7ac1b2c19282175c3200))
 * Import AGENT_CARD_WELL_KNOWN_PATH from adk instead of from a2a directly ([37dae9b](https://github.com/google/adk-python/commit/37dae9b631db5060770b66fce0e25cf0ffb56948))
 * Make `LlmRequest.LiveConnectConfig` field default to a factory ([74589a1](https://github.com/google/adk-python/commit/74589a1db7df65e319d1ad2f0676ee0cf5d6ec1d))
 * Update the prompt to make the ADK Answering Agent more objective ([2833030](https://github.com/google/adk-python/commit/283303032a174d51b8d72f14df83c794d66cb605))
@@ -346,14 +599,13 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 ### Features
 
 * [Core]Add agent card builder ([18f5bea](https://github.com/google/adk-python/commit/18f5bea411b3b76474ff31bfb2f62742825b45e5))
-* [Core]Add an to_a2a util to convert adk agent to A2A ASGI application ([a77d689](https://github.com/google/adk-python/commit/a77d68964a1c6b7659d6117d57fa59e43399e0c2))
+* [Core]Add a to_a2a util to convert adk agent to A2A ASGI application ([a77d689](https://github.com/google/adk-python/commit/a77d68964a1c6b7659d6117d57fa59e43399e0c2))
 * [Core]Add camel case converter for agents ([0e173d7](https://github.com/google/adk-python/commit/0e173d736334f8c6c171b3144ac6ee5b7125c846))
 * [Evals]Use LocalEvalService to run all evals in cli and web ([d1f182e](https://github.com/google/adk-python/commit/d1f182e8e68c4a5a4141592f3f6d2ceeada78887))
 * [Evals]Enable FinalResponseMatchV2 metric as an experiment ([36e45cd](https://github.com/google/adk-python/commit/36e45cdab3bbfb653eee3f9ed875b59bcd525ea1))
 * [Models]Add support for `model-optimizer-*` family of models in vertex ([ffe2bdb](https://github.com/google/adk-python/commit/ffe2bdbe4c2ea86cc7924eb36e8e3bb5528c0016))
 * [Services]Added a sample for History Management ([67284fc](https://github.com/google/adk-python/commit/67284fc46667b8c2946762bc9234a8453d48a43c))
-* [Services]Support passing fully qualified agent engine resource name when constructing session service and memory service ([2e77804](https://github.com/google/adk-python/commit/2e778049d0a675e458f4e
-35fe4104ca1298dbfcf))
+* [Services]Support passing fully qualified agent engine resource name when constructing session service and memory service ([2e77804](https://github.com/google/adk-python/commit/2e778049d0a675e458f4e35fe4104ca1298dbfcf))
 * [Tools]Add ComputerUseToolset ([083dcb4](https://github.com/google/adk-python/commit/083dcb44650eb0e6b70219ede731f2fa78ea7d28))
 * [Tools]Allow toolset to process llm_request before tools returned by it ([3643b4a](https://github.com/google/adk-python/commit/3643b4ae196fd9e38e52d5dc9d1cd43ea0733d36))
 * [Tools]Support input/output schema by fully-qualified code reference ([dfee06a](https://github.com/google/adk-python/commit/dfee06ac067ea909251d6fb016f8331065d430e9))
@@ -466,7 +718,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 
 ### Documentation
 
-* Update the a2a exmaple link in README.md [d0fdfb8](https://github.com/google/adk-python/commit/d0fdfb8c8e2e32801999c81de8d8ed0be3f88e76)
+* Update the a2a example link in README.md [d0fdfb8](https://github.com/google/adk-python/commit/d0fdfb8c8e2e32801999c81de8d8ed0be3f88e76)
 * Adds AGENTS.md to provide relevant project context for the Gemini CLI [37108be](https://github.com/google/adk-python/commit/37108be8557e011f321de76683835448213f8515)
 * Update CONTRIBUTING.md [ffa9b36](https://github.com/google/adk-python/commit/ffa9b361db615ae365ba62c09a8f4226fb761551)
 * Add adk project overview and architecture [28d0ea8](https://github.com/google/adk-python/commit/28d0ea876f2f8de952f1eccbc788e98e39f50cf5)
@@ -661,7 +913,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 * Fix typos in README for sample bigquery_agent and oauth_calendar_agent ([9bdd813](https://github.com/google/adk-python/commit/9bdd813be15935af5c5d2a6982a2391a640cab23))
 * Make tool_call one span for telemetry and renamed to execute_tool ([999a7fe](https://github.com/google/adk-python/commit/999a7fe69d511b1401b295d23ab3c2f40bccdc6f))
 * Use media type in chat window. Remove isArtifactImage and isArtifactAudio reference ([1452dac](https://github.com/google/adk-python/commit/1452dacfeb6b9970284e1ddeee6c4f3cb56781f8))
-* Set output_schema correctly for LiteLllm ([6157db7](https://github.com/google/adk-python/commit/6157db77f2fba4a44d075b51c83bff844027a147))
+* Set output_schema correctly for LiteLlm ([6157db7](https://github.com/google/adk-python/commit/6157db77f2fba4a44d075b51c83bff844027a147))
 * Update pending event dialog style ([1db601c](https://github.com/google/adk-python/commit/1db601c4bd90467b97a2f26fe9d90d665eb3c740))
 * Remove the gap between event holder and image ([63822c3](https://github.com/google/adk-python/commit/63822c3fa8b0bdce2527bd0d909c038e2b66dd98))
 
@@ -689,7 +941,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 ## 1.1.1
 
 ### Features
-* Add BigQuery first-party tools. See [here](https://github.com/google/adk-python/commit/d6c6bb4b2489a8b7a4713e4747c30d6df0c07961) for more details.
+* Add [BigQuery first-party tools](https://github.com/google/adk-python/commit/d6c6bb4b2489a8b7a4713e4747c30d6df0c07961).
 
 
 ## 1.1.0
@@ -825,7 +1077,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 * Fix google search reading undefined for `renderedContent`.
 
 ### Miscellaneous Chores
-* Docstring improvements, typo fixings, github action to enfore code styles on formatting and imports, etc.
+* Docstring improvements, typo fixings, github action to enforce code styles on formatting and imports, etc.
 
 ## 0.3.0
 
@@ -864,7 +1116,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 
 ### ⚠ BREAKING CHANGES
 
-* Fix typo in method name in `Event`: has_trailing_code_exeuction_result --> has_trailing_code_execution_result.
+* Fix typo in method name in `Event`: has_trailing_code_execution_result --> has_trailing_code_execution_result.
 
 ### Features
 
@@ -894,7 +1146,7 @@ with Bigtable for building AI Agent applications(experimental feature) ([a953807
 
 ### Miscellaneous Chores
 
-* Adds unit tests in Github action.
+* Adds unit tests in GitHub action.
 * Improves test coverage.
 * Various typo fixes.
 

CONTRIBUTING.md

@@ -57,7 +57,9 @@ information on using pull requests.
 ### Requirement for PRs
 
 -   All PRs, other than small documentation or typo fixes, should have a Issue
-    associated. If not, please create one.
+    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.
@@ -143,7 +145,7 @@ part before or alongside your code PR.
 
 3.  **Create and activate a virtual environment:**
 
-    **NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly
+    **NOTE**: ADK supports Python 3.10+. Python 3.11 and above is strongly
     recommended.
 
     Create a workspace venv using uv.
@@ -232,6 +234,6 @@ has resources that is helpful for contributors.
 
 ## Vibe Coding
 
-If you want to contribute by leveraging viber coding, the AGENTS.md
+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.
+context to your LLM.

README.md

@@ -11,51 +11,54 @@
       <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://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-java">Java ADK</a>,
+      <a href="https://github.com/google/adk-go">Go 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
 
-- **Agent Config**: Build agents without code. Check out the
-  [Agent Config](https://google.github.io/adk-docs/agents/config/) feature.
+- **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](https://github.com/google/adk-python/discussions/3175#discussioncomment-14745120). ([391628f](https://github.com/google/adk-python/commit/391628fcdc7b950c6835f64ae3ccab197163c990))
 
-- **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
+- **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)
@@ -79,6 +82,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
@@ -146,10 +156,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.

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_human_in_loop/README.md

@@ -99,7 +99,7 @@ Agent: ✅ Great news! Your reimbursement has been approved by the manager. Proc
 The human-in-the-loop process follows this pattern:
 
 1. **Initial Call**: Root agent delegates approval request to remote approval agent for amounts >$100
-2. **Pending Response**: Remote approval agent returns immediate response with `status: "pending"` and ticket ID and serface the approval request to root agent
+2. **Pending Response**: Remote approval agent returns immediate response with `status: "pending"` and ticket ID and surface the approval request to root agent
 3. **Agent Acknowledgment**: Root agent informs user about pending approval status
 4. **Human Interaction**: Human manager interacts with root agent to review and approve/reject the request
 5. **Updated Response**: Root agent receives updated tool response with approval decision and send it to remote agent

contributing/samples/adk_agent_builder_assistant/agent_builder_assistant.py

@@ -15,6 +15,8 @@
 """Agent factory for creating Agent Builder Assistant with embedded schema."""
 
 from pathlib import Path
+import textwrap
+from typing import Any
 from typing import Callable
 from typing import Optional
 from typing import Union
@@ -24,6 +26,7 @@ from google.adk.agents.readonly_context import ReadonlyContext
 from google.adk.models import BaseLlm
 from google.adk.tools import AgentTool
 from google.adk.tools import FunctionTool
+from google.genai import types
 
 from .sub_agents.google_search_agent import create_google_search_agent
 from .sub_agents.url_context_agent import create_url_context_agent
@@ -32,7 +35,7 @@ from .tools.delete_files import delete_files
 from .tools.explore_project import explore_project
 from .tools.read_config_files import read_config_files
 from .tools.read_files import read_files
-from .tools.resolve_root_directory import resolve_root_directory
+from .tools.search_adk_knowledge import search_adk_knowledge
 from .tools.search_adk_source import search_adk_source
 from .tools.write_config_files import write_config_files
 from .tools.write_files import write_files
@@ -42,9 +45,28 @@ from .utils import load_agent_config_schema
 class AgentBuilderAssistant:
   """Agent Builder Assistant factory for creating configured instances."""
 
+  _CORE_SCHEMA_DEF_NAMES: tuple[str, ...] = (
+      "LlmAgentConfig",
+      "LoopAgentConfig",
+      "ParallelAgentConfig",
+      "SequentialAgentConfig",
+      "BaseAgentConfig",
+      "AgentRefConfig",
+      "CodeConfig",
+      "ArgumentConfig",
+      "ToolArgsConfig",
+      "google__adk__tools__tool_configs__ToolConfig",
+  )
+  _GEN_CONFIG_FIELDS: tuple[str, ...] = (
+      "temperature",
+      "topP",
+      "topK",
+      "maxOutputTokens",
+  )
+
   @staticmethod
   def create_agent(
-      model: Union[str, BaseLlm] = "gemini-2.5-flash",
+      model: Union[str, BaseLlm] = "gemini-2.5-pro",
       working_directory: Optional[str] = None,
   ) -> LlmAgent:
     """Create Agent Builder Assistant with embedded ADK AgentConfig schema.
@@ -58,9 +80,7 @@ class AgentBuilderAssistant:
       Configured LlmAgent with embedded ADK AgentConfig schema
     """
     # Load full ADK AgentConfig schema directly into instruction context
-    instruction = AgentBuilderAssistant._load_instruction_with_schema(
-        model, working_directory
-    )
+    instruction = AgentBuilderAssistant._load_instruction_with_schema(model)
 
     # TOOL ARCHITECTURE: Hybrid approach using both AgentTools and FunctionTools
     #
@@ -72,7 +92,10 @@ class AgentBuilderAssistant:
     # Built-in ADK tools wrapped as sub-agents
     google_search_agent = create_google_search_agent()
     url_context_agent = create_url_context_agent()
-    agent_tools = [AgentTool(google_search_agent), AgentTool(url_context_agent)]
+    agent_tools = [
+        AgentTool(google_search_agent),
+        AgentTool(url_context_agent),
+    ]
 
     # CUSTOM FUNCTION TOOLS: Agent Builder specific capabilities
     #
@@ -88,8 +111,6 @@ class AgentBuilderAssistant:
             write_config_files
         ),  # Write/validate multiple YAML configs
         FunctionTool(explore_project),  # Analyze project structure
-        # Working directory context tools
-        FunctionTool(resolve_root_directory),
         # File management tools (multi-file support)
         FunctionTool(read_files),  # Read multiple files
         FunctionTool(write_files),  # Write multiple files
@@ -97,6 +118,8 @@ class AgentBuilderAssistant:
         FunctionTool(cleanup_unused_files),
         # ADK source code search (regex-based)
         FunctionTool(search_adk_source),  # Search ADK source with regex
+        # ADK knowledge search
+        FunctionTool(search_adk_knowledge),  # Search ADK knowledge base
     ]
 
     # Combine all tools
@@ -112,6 +135,9 @@ class AgentBuilderAssistant:
         instruction=instruction,
         model=model,
         tools=all_tools,
+        generate_content_config=types.GenerateContentConfig(
+            max_output_tokens=8192,
+        ),
     )
 
     return agent
@@ -120,34 +146,212 @@ class AgentBuilderAssistant:
   def _load_schema() -> str:
     """Load ADK AgentConfig.json schema content and format for YAML embedding."""
 
-    # CENTRALIZED ADK AGENTCONFIG SCHEMA LOADING: Use common utility function
-    # This avoids duplication across multiple files and provides consistent
-    # ADK AgentConfig schema loading with caching and error handling.
-    schema_content = load_agent_config_schema(
-        raw_format=True,  # Get as JSON string
-        escape_braces=True,  # Escape braces for template embedding
+    schema_dict = load_agent_config_schema(raw_format=False)
+    subset = AgentBuilderAssistant._extract_core_schema(schema_dict)
+    return AgentBuilderAssistant._build_schema_reference(subset)
+
+  @staticmethod
+  def _build_schema_reference(schema: dict[str, Any]) -> str:
+    """Create compact AgentConfig reference text for prompt embedding."""
+
+    defs: dict[str, Any] = schema.get("$defs", {})
+    top_level_fields: dict[str, Any] = schema.get("properties", {})
+    wrapper = textwrap.TextWrapper(width=78)
+    lines: list[str] = []
+
+    def add(text: str = "", indent: int = 0) -> None:
+      """Append wrapped text with indentation."""
+      if not text:
+        lines.append("")
+        return
+      indent_str = " " * indent
+      wrapper.initial_indent = indent_str
+      wrapper.subsequent_indent = indent_str
+      lines.extend(wrapper.fill(text).split("\n"))
+
+    add("ADK AgentConfig quick reference")
+    add("--------------------------------")
+
+    add()
+    add("LlmAgent (agent_class: LlmAgent)")
+    add(
+        "Required fields: name, instruction. ADK best practice is to always set"
+        " model explicitly.",
+        indent=2,
+    )
+    add("Optional fields:", indent=2)
+    add("agent_class: defaults to LlmAgent; keep for clarity.", indent=4)
+    add("description: short summary string.", indent=4)
+    add("sub_agents: list of AgentRef entries (see below).", indent=4)
+    add(
+        "before_agent_callbacks / after_agent_callbacks: list of CodeConfig "
+        "entries that run before or after the agent loop.",
+        indent=4,
+    )
+    add("model: string model id (required in practice).", indent=4)
+    add(
+        "disallow_transfer_to_parent / disallow_transfer_to_peers: booleans to "
+        "restrict automatic transfer.",
+        indent=4,
+    )
+    add(
+        "input_schema / output_schema: JSON schema objects to validate inputs "
+        "and outputs.",
+        indent=4,
+    )
+    add("output_key: name to store agent output in session context.", indent=4)
+    add(
+        "include_contents: bool; include tool/LLM contents in response.",
+        indent=4,
+    )
+    add("tools: list of ToolConfig entries (see below).", indent=4)
+    add(
+        "before_model_callbacks / after_model_callbacks: list of CodeConfig "
+        "entries around LLM calls.",
+        indent=4,
+    )
+    add(
+        "before_tool_callbacks / after_tool_callbacks: list of CodeConfig "
+        "entries around tool calls.",
+        indent=4,
+    )
+    add(
+        "generate_content_config: passes directly to google.genai "
+        "GenerateContentConfig (supporting temperature, topP, topK, "
+        "maxOutputTokens, safetySettings, responseSchema, routingConfig,"
+        " etc.).",
+        indent=4,
     )
 
-    # Format as indented code block for instruction embedding
-    #
-    # Why indentation is needed:
-    # - The ADK AgentConfig schema gets embedded into instruction templates using .format()
-    # - Proper indentation maintains readability in the final instruction
-    # - Code block markers (```) help LLMs recognize this as structured data
-    #
-    # Example final instruction format:
-    #   "Here is the ADK AgentConfig schema:
-    #   ```json
-    #     {"type": "object", "properties": {...}}
-    #   ```"
-    lines = schema_content.split("\n")
-    indented_lines = ["  " + line for line in lines]  # 2-space indent
-    return "```json\n" + "\n".join(indented_lines) + "\n  ```"
+    add()
+    add("Workflow agents (LoopAgent, ParallelAgent, SequentialAgent)")
+    add(
+        "Share BaseAgent fields: agent_class, name, description, sub_agents, "
+        "before/after_agent_callbacks. Never declare model, instruction, or "
+        "tools on workflow orchestrators.",
+        indent=2,
+    )
+    add(
+        "LoopAgent adds max_iterations (int) controlling iteration cap.",
+        indent=2,
+    )
+
+    add()
+    add("AgentRef")
+    add(
+        "Used inside sub_agents lists. Provide either config_path (string path "
+        "to another YAML file) or code (dotted Python reference) to locate the "
+        "sub-agent definition.",
+        indent=2,
+    )
+
+    add()
+    add("ToolConfig")
+    add(
+        "Items inside tools arrays. Required field name (string). For built-in "
+        "tools use the exported short name, for custom tools use the dotted "
+        "module path.",
+        indent=2,
+    )
+    add(
+        "args: optional object of additional keyword arguments. Use simple "
+        "key-value pairs (ToolArgsConfig) or structured ArgumentConfig entries "
+        "when a list is required by callbacks.",
+        indent=2,
+    )
+
+    add()
+    add("ArgumentConfig")
+    add(
+        "Represents a single argument. value is required and may be any JSON "
+        "type. name is optional (null allowed). Often used in callback args.",
+        indent=2,
+    )
+
+    add()
+    add("CodeConfig")
+    add(
+        "References Python code for callbacks or dynamic tool creation."
+        " Requires name (dotted path). args is an optional list of"
+        " ArgumentConfig items executed when invoking the function.",
+        indent=2,
+    )
+
+    add()
+    add("GenerateContentConfig highlights")
+    add(
+        "Controls LLM generation behavior. Common fields: maxOutputTokens, "
+        "temperature, topP, topK, candidateCount, responseMimeType, "
+        "responseSchema/responseJsonSchema, automaticFunctionCalling, "
+        "safetySettings, routingConfig; see Vertex AI GenAI docs for full "
+        "semantics.",
+        indent=2,
+    )
+
+    add()
+    add(
+        "All other schema definitions in AgentConfig.json remain available but "
+        "are rarely needed for typical agent setups. Refer to the source file "
+        "for exhaustive field descriptions when implementing advanced configs.",
+    )
+
+    if top_level_fields:
+      add()
+      add("Top-level AgentConfig fields (from schema)")
+      for field_name in sorted(top_level_fields):
+        description = top_level_fields[field_name].get("description", "")
+        if description:
+          add(f"{field_name}: {description}", indent=2)
+        else:
+          add(field_name, indent=2)
+
+    if defs:
+      add()
+      add("Additional schema definitions")
+      for def_name in sorted(defs):
+        description = defs[def_name].get("description", "")
+        if description:
+          add(f"{def_name}: {description}", indent=2)
+        else:
+          add(def_name, indent=2)
+
+    return "```text\n" + "\n".join(lines) + "\n```"
+
+  @staticmethod
+  def _extract_core_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Return only the schema nodes surfaced by the assistant."""
+
+    defs = schema.get("$defs", {})
+    filtered_defs: dict[str, Any] = {}
+    for key in AgentBuilderAssistant._CORE_SCHEMA_DEF_NAMES:
+      if key in defs:
+        filtered_defs[key] = defs[key]
+
+    gen_config = defs.get("GenerateContentConfig")
+    if gen_config:
+      properties = gen_config.get("properties", {})
+      filtered_defs["GenerateContentConfig"] = {
+          "title": gen_config.get("title", "GenerateContentConfig"),
+          "description": (
+              "Common LLM generation knobs exposed by the Agent Builder."
+          ),
+          "type": "object",
+          "additionalProperties": False,
+          "properties": {
+              key: properties[key]
+              for key in AgentBuilderAssistant._GEN_CONFIG_FIELDS
+              if key in properties
+          },
+      }
+
+    return {
+        "$defs": filtered_defs,
+        "properties": schema.get("properties", {}),
+    }
 
   @staticmethod
   def _load_instruction_with_schema(
       model: Union[str, BaseLlm],
-      working_directory: Optional[str] = None,
   ) -> Callable[[ReadonlyContext], str]:
     """Load instruction template and embed ADK AgentConfig schema content."""
     instruction_template = (
@@ -162,19 +366,43 @@ class AgentBuilderAssistant:
         else getattr(model, "model_name", str(model))
     )
 
-    # Fill the instruction template with ADK AgentConfig schema content and default model
-    instruction_text = instruction_template.format(
-        schema_content=schema_content, default_model=model_str
-    )
-
     # Return a function that accepts ReadonlyContext and returns the instruction
     def instruction_provider(context: ReadonlyContext) -> str:
-      return AgentBuilderAssistant._compile_instruction_with_context(
-          instruction_text, context, working_directory
+      # Extract project folder name from session state
+      project_folder_name = AgentBuilderAssistant._extract_project_folder_name(
+          context
       )
 
+      # Fill the instruction template with all variables
+      instruction_text = instruction_template.format(
+          schema_content=schema_content,
+          default_model=model_str,
+          project_folder_name=project_folder_name,
+      )
+      return instruction_text
+
     return instruction_provider
 
+  @staticmethod
+  def _extract_project_folder_name(context: ReadonlyContext) -> str:
+    """Extract project folder name from session state using resolve_file_path."""
+    from .utils.resolve_root_directory import resolve_file_path
+
+    session_state = context._invocation_context.session.state
+
+    # Use resolve_file_path to get the full resolved path for "."
+    # This handles all the root_directory resolution logic consistently
+    resolved_path = resolve_file_path(".", session_state)
+
+    # Extract the project folder name from the resolved path
+    project_folder_name = resolved_path.name
+
+    # Fallback to "project" if we somehow get an empty name
+    if not project_folder_name:
+      project_folder_name = "project"
+
+    return project_folder_name
+
   @staticmethod
   def _load_embedded_schema_instruction_template() -> str:
     """Load instruction template for embedded ADK AgentConfig schema mode."""
@@ -187,70 +415,3 @@ class AgentBuilderAssistant:
 
     with open(template_path, "r", encoding="utf-8") as f:
       return f.read()
-
-  @staticmethod
-  def _compile_instruction_with_context(
-      instruction_text: str,
-      context: ReadonlyContext,
-      working_directory: Optional[str] = None,
-  ) -> str:
-    """Compile instruction with session context and working directory information.
-
-    This method enhances instructions with:
-    1. Working directory information for path resolution
-    2. Session-based root directory binding if available
-
-    Args:
-      instruction_text: Base instruction text
-      context: ReadonlyContext from the agent session
-      working_directory: Optional working directory for path resolution
-
-    Returns:
-      Enhanced instruction text with context information
-    """
-    import os
-
-    # Get working directory (use provided or current working directory)
-    actual_working_dir = working_directory or os.getcwd()
-
-    # Check for existing root directory in session state
-    session_root_directory = context._invocation_context.session.state.get(
-        "root_directory"
-    )
-
-    # Compile additional context information
-    context_info = f"""
-
-## SESSION CONTEXT
-
-**Working Directory**: `{actual_working_dir}`
-- Use this as the base directory for path resolution when calling resolve_root_directory
-- Pass this as the working_directory parameter to resolve_root_directory tool
-
-"""
-
-    if session_root_directory:
-      context_info += f"""**Established Root Directory**: `{session_root_directory}`
-- This session is bound to root directory: {session_root_directory}
-- DO NOT ask the user for root directory - use this established path
-- All agent building should happen within this root directory
-- If user wants to work in a different directory, ask them to start a new chat session
-
-"""
-    else:
-      context_info += f"""**Root Directory**: Not yet established
-- You MUST ask the user for their desired root directory first
-- Use resolve_root_directory tool to validate the path
-- Once confirmed, this session will be bound to that root directory
-
-"""
-
-    context_info += """**Session Binding Rules**:
-- Each chat session is bound to ONE root directory
-- Once established, work only within that root directory
-- To switch directories, user must start a new chat session
-- Always verify paths using resolve_root_directory tool before creating files
-
-"""
-
-    return instruction_text + context_info

contributing/samples/adk_agent_builder_assistant/sub_agents/__init__.py

@@ -17,4 +17,7 @@
 from .google_search_agent import create_google_search_agent
 from .url_context_agent import create_url_context_agent
 
-__all__ = ['create_google_search_agent', 'create_url_context_agent']
+__all__ = [
+    'create_google_search_agent',
+    'create_url_context_agent',
+]

contributing/samples/adk_agent_builder_assistant/tools/__init__.py

@@ -19,7 +19,6 @@ from .delete_files import delete_files
 from .explore_project import explore_project
 from .read_config_files import read_config_files
 from .read_files import read_files
-from .resolve_root_directory import resolve_root_directory
 from .search_adk_source import search_adk_source
 from .write_config_files import write_config_files
 from .write_files import write_files
@@ -33,5 +32,4 @@ __all__ = [
     'write_files',
     'search_adk_source',
     'explore_project',
-    'resolve_root_directory',
 ]

contributing/samples/adk_agent_builder_assistant/tools/cleanup_unused_files.py

@@ -14,44 +14,52 @@
 
 """Cleanup unused files tool for Agent Builder Assistant."""
 
-from pathlib import Path
+from __future__ import annotations
+
 from typing import Any
-from typing import Dict
-from typing import List
-from typing import Optional
+
+from google.adk.tools.tool_context import ToolContext
+
+from ..utils.resolve_root_directory import resolve_file_path
+from ..utils.resolve_root_directory import resolve_file_paths
 
 
 async def cleanup_unused_files(
-    root_directory: str,
-    used_files: List[str],
-    file_patterns: Optional[List[str]] = None,
-    exclude_patterns: Optional[List[str]] = None,
-) -> Dict[str, Any]:
+    used_files: list[str],
+    tool_context: ToolContext,
+    file_patterns: list[str] | None = None,
+    exclude_patterns: list[str] | None = None,
+) -> dict[str, Any]:
   """Identify and optionally delete unused files in project directories.
 
   This tool helps clean up unused tool files when agent configurations change.
   It identifies files that match patterns but aren't referenced in used_files
-  list.
+  list. Paths are resolved automatically using the tool context.
 
   Args:
-    root_directory: Root directory to scan for unused files
     used_files: List of file paths currently in use (should not be deleted)
+    tool_context: Tool execution context (provides session state)
     file_patterns: List of glob patterns to match files (default: ["*.py"])
     exclude_patterns: List of patterns to exclude (default: ["__init__.py"])
 
   Returns:
     Dict containing cleanup results:
       - success: bool indicating if scan succeeded
-      - root_directory: absolute path to scanned directory
       - unused_files: list of unused files found
       - deleted_files: list of files actually deleted
       - backup_files: list of backup files created
       - errors: list of error messages
       - total_freed_space: total bytes freed by deletions
   """
+  session_state = tool_context.state
+  root_path = resolve_file_path(".", session_state)
+
   try:
-    root_path = Path(root_directory).resolve()
-    used_files_set = {Path(f).resolve() for f in used_files}
+    root_path = root_path.resolve()
+    resolved_used_files = {
+        path.resolve()
+        for path in resolve_file_paths(used_files or [], session_state)
+    }
 
     # Set defaults
     if file_patterns is None:
@@ -61,7 +69,6 @@ async def cleanup_unused_files(
 
     result = {
         "success": False,
-        "root_directory": str(root_path),
         "unused_files": [],
         "deleted_files": [],
         "backup_files": [],
@@ -85,7 +92,7 @@ async def cleanup_unused_files(
     # Identify unused files
     unused_files = []
     for file_path in all_files:
-      if file_path not in used_files_set:
+      if file_path.resolve() not in resolved_used_files:
         unused_files.append(file_path)
 
     result["unused_files"] = [str(f) for f in unused_files]
@@ -99,7 +106,6 @@ async def cleanup_unused_files(
   except Exception as e:
     return {
         "success": False,
-        "root_directory": root_directory,
         "unused_files": [],
         "deleted_files": [],
         "backup_files": [],

contributing/samples/adk_agent_builder_assistant/tools/delete_files.py

@@ -21,9 +21,14 @@ from typing import Any
 from typing import Dict
 from typing import List
 
+from google.adk.tools.tool_context import ToolContext
+
+from ..utils.resolve_root_directory import resolve_file_paths
+
 
 async def delete_files(
     file_paths: List[str],
+    tool_context: ToolContext,
     create_backup: bool = False,
     confirm_deletion: bool = True,
 ) -> Dict[str, Any]:
@@ -54,6 +59,10 @@ async def delete_files(
       - errors: list of general error messages
   """
   try:
+    # Resolve file paths using session state
+    session_state = tool_context._invocation_context.session.state
+    resolved_paths = resolve_file_paths(file_paths, session_state)
+
     result = {
         "success": True,
         "files": {},
@@ -68,8 +77,8 @@ async def delete_files(
       result["errors"].append("Deletion not confirmed by user")
       return result
 
-    for file_path in file_paths:
-      file_path_obj = Path(file_path).resolve()
+    for resolved_path in resolved_paths:
+      file_path_obj = resolved_path.resolve()
       file_info = {
           "existed": False,
           "backup_created": False,

contributing/samples/adk_agent_builder_assistant/tools/explore_project.py

@@ -19,23 +19,24 @@ from typing import Any
 from typing import Dict
 from typing import List
 
+from google.adk.tools.tool_context import ToolContext
 
-async def explore_project(root_directory: str) -> Dict[str, Any]:
+from ..utils.resolve_root_directory import resolve_file_path
+
+
+async def explore_project(tool_context: ToolContext) -> Dict[str, Any]:
   """Analyze project structure and suggest optimal file paths for ADK agents.
 
   This tool performs comprehensive project analysis to understand the existing
   structure and recommend appropriate locations for new agent configurations,
   tools, and related files following ADK best practices.
 
-  Args:
-    root_directory: Absolute or relative path to the root directory to explore
-      and analyze
+  The tool automatically determines the project directory from session state.
 
   Returns:
-    Dict containing analysis results:
+    Dict containing analysis results with ALL PATHS RELATIVE TO PROJECT FOLDER:
       Always included:
         - success: bool indicating if exploration succeeded
-        - root_path: absolute path to the analyzed directory
 
       Success cases only (success=True):
         - project_info: dict with basic project metadata. Contains:
@@ -54,8 +55,7 @@ async def explore_project(root_directory: str) -> Dict[str, Any]:
         - existing_configs: list of dicts for found YAML configuration files.
                            Each dict contains:
                            • "filename": name of the config file
-                           • "path": absolute path to the file
-                           • "relative_path": path relative to project root
+                           • "relative_path": path relative to project folder
                            • "size": file size in bytes
                            • "is_valid_yaml": bool indicating if YAML parses
                            correctly
@@ -80,7 +80,7 @@ async def explore_project(root_directory: str) -> Dict[str, Any]:
 
   Examples:
     Basic project exploration:
-      result = await explore_project("/path/to/my_adk_project")
+      result = await explore_project(tool_context)
 
     Check project structure:
       if result["project_info"]["has_tools_directory"]:
@@ -96,20 +96,21 @@ async def explore_project(root_directory: str) -> Dict[str, Any]:
       directories = result["suggestions"]["directories"]["tools"]
   """
   try:
-    root_path = Path(root_directory).resolve()
+    # Resolve root directory using session state (use "." as current project directory)
+    session_state = tool_context._invocation_context.session.state
+    resolved_path = resolve_file_path(".", session_state)
+    root_path = resolved_path.resolve()
 
     if not root_path.exists():
       return {
           "success": False,
-          "error": f"Root directory does not exist: {root_directory}",
-          "root_path": str(root_path),
+          "error": f"Project directory does not exist: {root_path}",
       }
 
     if not root_path.is_dir():
       return {
           "success": False,
-          "error": f"Path is not a directory: {root_directory}",
-          "root_path": str(root_path),
+          "error": f"Path is not a directory: {root_path}",
       }
 
     # Analyze project structure
@@ -121,7 +122,6 @@ async def explore_project(root_directory: str) -> Dict[str, Any]:
 
     return {
         "success": True,
-        "root_path": str(root_path),
         "project_info": project_info,
         "existing_configs": existing_configs,
         "directory_structure": directory_structure,
@@ -132,14 +132,12 @@ async def explore_project(root_directory: str) -> Dict[str, Any]:
   except PermissionError:
     return {
         "success": False,
-        "error": f"Permission denied accessing directory: {root_directory}",
-        "root_path": root_directory,
+        "error": "Permission denied accessing project directory",
     }
   except Exception as e:
     return {
         "success": False,
         "error": f"Error exploring project: {str(e)}",
-        "root_path": root_directory,
     }
 
 
@@ -191,12 +189,12 @@ def _find_existing_configs(root_path: Path) -> List[Dict[str, Any]]:
     # Look for YAML files in root directory (ADK convention)
     for yaml_file in root_path.glob("*.yaml"):
       if yaml_file.is_file():
-        config_info = _analyze_config_file(yaml_file)
+        config_info = _analyze_config_file(yaml_file, root_path)
         configs.append(config_info)
 
     for yml_file in root_path.glob("*.yml"):
       if yml_file.is_file():
-        config_info = _analyze_config_file(yml_file)
+        config_info = _analyze_config_file(yml_file, root_path)
         configs.append(config_info)
 
     # Sort by name for consistent ordering
@@ -209,12 +207,18 @@ def _find_existing_configs(root_path: Path) -> List[Dict[str, Any]]:
   return configs
 
 
-def _analyze_config_file(config_path: Path) -> Dict[str, Any]:
+def _analyze_config_file(config_path: Path, root_path: Path) -> Dict[str, Any]:
   """Analyze a single configuration file."""
+  # Compute relative path from project root
+  try:
+    relative_path = config_path.relative_to(root_path)
+  except ValueError:
+    # Fallback if not relative to root_path
+    relative_path = config_path.name
+
   info = {
       "filename": config_path.name,
-      "path": str(config_path),
-      "relative_path": config_path.name,  # In root directory
+      "relative_path": str(relative_path),
       "size": 0,
       "is_valid_yaml": False,
       "agent_name": None,
@@ -300,10 +304,10 @@ def _generate_path_suggestions(
         "root_agent.yaml",
     ]
 
-  # Directory suggestions
+  # Directory suggestions (relative paths)
   directories = {
       "tools": {
-          "path": str(root_path / "tools"),
+          "path": "tools",
           "exists": (root_path / "tools").exists(),
           "purpose": "Custom tool implementations",
           "example_files": [
@@ -312,7 +316,7 @@ def _generate_path_suggestions(
           ],
       },
       "callbacks": {
-          "path": str(root_path / "callbacks"),
+          "path": "callbacks",
           "exists": (root_path / "callbacks").exists(),
           "purpose": "Custom callback functions",
           "example_files": ["logging.py", "security.py"],