Compare commits

..

1 Commits

Author SHA1 Message Date
Jack Sun 8b0581f5c5 feat(plugins): Add RateLimitPlugin for global request rate limiting
Add a new RateLimitPlugin that enforces global rate limiting across all
LLM models using a sliding window algorithm. The plugin blocks (waits)
when the rate limit is exceeded, ensuring requests are processed within
the configured limit.

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

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

runner = Runner(
    agents=[agent],
    plugins=[RateLimitPlugin(max_requests_per_minute=15)]
)
```
2025-11-05 10:21:45 -08:00
1230 changed files with 13362 additions and 70705 deletions
+17 -52
View File
@@ -7,69 +7,34 @@ assignees: ''
---
## šŸ”“ Required Information
*Please ensure all items in this section are completed to allow for efficient
triaging. Requests without complete information may be rejected / deprioritized.
If an item is not applicable to you - please mark it as N/A*
** Please make sure you read the contribution guide and file the issues in the right place. **
[Contribution guide.](https://google.github.io/adk-docs/contributing-guide/)
**Describe the Bug:**
**Describe the bug**
A clear and concise description of what the bug is.
**Steps to Reproduce:**
Please provide a numbered list of steps to reproduce the behavior:
**To Reproduce**
Please share a minimal code and data to reproduce your problem.
Steps to reproduce the behavior:
1. Install '...'
2. Run '....'
3. Open '....'
4. Provide error or stacktrace
4. Provie error or stacktrace
**Expected Behavior:**
**Expected behavior**
A clear and concise description of what you expected to happen.
**Observed Behavior:**
What actually happened? Include error messages or crash stack traces here.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Environment Details:**
- ADK Library Version (pip show google-adk):
- Desktop OS:** [e.g., macOS, Linux, Windows]
- Python Version (python -V):
**Model Information:**
**Desktop (please complete the following information):**
- OS: [e.g. macOS, Linux, Windows]
- Python version(python -V):
- ADK version(pip show google-adk):
**Model Information:**
- Are you using LiteLLM: Yes/No
- Which model is being used: (e.g., gemini-2.5-pro)
- Which model is being used(e.g. gemini-2.5-pro)
---
## 🟔 Optional Information
*Providing this information greatly speeds up the resolution process.*
**Regression:**
Did this work in a previous version of ADK? If so, which one?
**Logs:**
Please attach relevant logs. Wrap them in code blocks (```) or attach a
text file.
```text
// Paste logs here
```
**Screenshots / Video:**
If applicable, add screenshots or screen recordings to help explain
your problem.
**Additional Context:**
**Additional context**
Add any other context about the problem here.
**Minimal Reproduction Code:**
Please provide a code snippet or a link to a Gist/repo that isolates the issue.
```python
// Code snippet here
```
**How often has this issue occurred?:**
- Always (100%)
- Often (50%+)
- Intermittently (<50%)
- Once / Rare
+8 -33
View File
@@ -10,39 +10,14 @@ assignees: ''
** Please make sure you read the contribution guide and file the issues in the right place. **
[Contribution guide.](https://google.github.io/adk-docs/contributing-guide/)
## šŸ”“ Required Information
*Please ensure all items in this section are completed to allow for efficient
triaging. Requests without complete information may be rejected / deprioritized.
If an item is not applicable to you - please mark it as N/A*
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
### Is your feature request related to a specific problem?
Please describe the problem you are trying to solve. (Ex: "I'm always frustrated
when I have to manually handle X...")
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
### Describe the Solution You'd Like
A clear and concise description of the feature or API change you want.
Be specific about input/outputs if this involves an API change.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
### Impact on your work
How does this feature impact your work and what are you trying to achieve?
If this is critical for you, tell us if there is a timeline by when you need
this feature.
### Willingness to contribute
Are you interested in implementing this feature yourself or submitting a PR?
(Yes/No)
---
## 🟔 Recommended Information
### Describe Alternatives You've Considered
A clear and concise description of any alternative solutions or workarounds
you've considered and why they didn't work for you.
### Proposed API / Implementation
If you have ideas on how this should look in code, please share a
pseudo-code example.
### Additional Context
Add any other context or screenshots about the feature request here.
**Additional context**
Add any other context or screenshots about the feature request here.
@@ -16,10 +16,10 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.11'
+3 -3
View File
@@ -1,4 +1,4 @@
# Copyright 2026 Google LLC
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v6
uses: actions/checkout@v4
with:
fetch-depth: 2
@@ -96,7 +96,7 @@ jobs:
echo ""
set +e
FILES_WITH_FORBIDDEN_IMPORT=$(grep -lE '^from.*\bcli\b.*import.*$' $CHANGED_FILES)
FILES_WITH_FORBIDDEN_IMPORT=$(grep -lE '^from.*cli.*import.*$' $CHANGED_FILES)
GREP_EXIT_CODE=$?
set -e
+1 -1
View File
@@ -25,7 +25,7 @@ jobs:
steps:
- name: Check for Copybara commits and close PRs
uses: actions/github-script@v8
uses: actions/github-script@v7
with:
github-token: ${{ secrets.ADK_TRIAGE_AGENT }}
script: |
+3 -3
View File
@@ -15,16 +15,16 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Authenticate to Google Cloud
id: auth
uses: 'google-github-actions/auth@v3'
uses: 'google-github-actions/auth@v2'
with:
credentials_json: '${{ secrets.ADK_GCP_SA_KEY }}'
+3 -3
View File
@@ -1,4 +1,4 @@
# Copyright 2026 Google LLC
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -26,12 +26,12 @@ jobs:
steps:
- name: Checkout code
uses: actions/checkout@v6
uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.x'
-74
View File
@@ -1,74 +0,0 @@
name: Mypy New Error Check
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
mypy-diff:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ['3.10', '3.11', '3.12', '3.13',]
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install uv
uses: astral-sh/setup-uv@v5
- name: Generate Baseline (Main)
run: |
# Switch to main branch to generate baseline
git checkout origin/main
git checkout ${{ github.sha }} -- pyproject.toml
# Install dependencies for main
uv venv .venv
source .venv/bin/activate
uv sync --all-extras
# Run mypy, filter for errors only, remove line numbers (file:123: -> file::), and sort
# We ignore exit code (|| true) because we expect errors on main
uv run mypy . | grep "error:" | sed 's/:\([0-9]\+\):/::/g' | sort > main_errors.txt || true
echo "Found $(wc -l < main_errors.txt) errors on main."
- name: Check PR Branch
run: |
# Switch back to the PR commit
git checkout ${{ github.sha }}
# Re-sync dependencies in case the PR changed them
source .venv/bin/activate
uv sync --all-extras
# Run mypy on PR code, apply same processing
uv run mypy . | grep "error:" | sed 's/:\([0-9]\+\):/::/g' | sort > pr_errors.txt || true
echo "Found $(wc -l < pr_errors.txt) errors on PR branch."
- name: Compare and Fail on New Errors
run: |
# 'comm -13' suppresses unique lines in file1 (main) and common lines,
# leaving only lines unique to file2 (PR) -> The new errors.
comm -13 main_errors.txt pr_errors.txt > new_errors.txt
if [ -s new_errors.txt ]; then
echo "::error::The following NEW mypy errors were introduced:"
cat new_errors.txt
exit 1
else
echo "Great job! No new mypy errors introduced."
fi
-32
View File
@@ -1,32 +0,0 @@
name: Mypy Type Check
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
mypy:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ['3.10', '3.11', '3.12', '3.13',]
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v1
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: uv sync --all-extras
- name: Run mypy
run: uv run mypy . --strict
+2 -2
View File
@@ -20,10 +20,10 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.11'
+3 -3
View File
@@ -1,4 +1,4 @@
# Copyright 2026 Google LLC
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -26,12 +26,12 @@ jobs:
steps:
- name: Checkout code
uses: actions/checkout@v6
uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.x'
+15 -7
View File
@@ -1,4 +1,4 @@
# Copyright 2026 Google LLC
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -25,14 +25,14 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13"]
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- name: Checkout code
uses: actions/checkout@v6
uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
@@ -48,6 +48,14 @@ jobs:
- name: Run unit tests with pytest
run: |
source .venv/bin/activate
pytest tests/unittests \
--ignore=tests/unittests/artifacts/test_artifact_service.py \
--ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py
if [[ "${{ matrix.python-version }}" == "3.9" ]]; then
pytest tests/unittests \
--ignore=tests/unittests/a2a \
--ignore=tests/unittests/tools/mcp_tool \
--ignore=tests/unittests/artifacts/test_artifact_service.py \
--ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py
else
pytest tests/unittests \
--ignore=tests/unittests/artifacts/test_artifact_service.py \
--ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py
fi
-58
View File
@@ -1,58 +0,0 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
name: ADK Stale Issue Auditor
on:
workflow_dispatch:
schedule:
# This runs at 6:00 AM UTC (10 PM PST)
- cron: '0 6 * * *'
jobs:
audit-stale-issues:
if: github.repository == 'google/adk-python'
runs-on: ubuntu-latest
timeout-minutes: 60
permissions:
issues: write
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install requests google-adk
- name: Run Auditor Agent Script
env:
GITHUB_TOKEN: ${{ secrets.ADK_TRIAGE_AGENT }}
GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
OWNER: ${{ github.repository_owner }}
REPO: adk-python
CONCURRENCY_LIMIT: 3
LLM_MODEL_NAME: "gemini-2.5-flash"
PYTHONPATH: contributing/samples
run: python -m adk_stale_agent.main
+5 -18
View File
@@ -2,34 +2,21 @@ name: ADK Issue Triaging Agent
on:
issues:
types: [opened, labeled]
schedule:
# Run every 6 hours to triage untriaged issues
- cron: '0 */6 * * *'
types: [opened, reopened]
jobs:
agent-triage-issues:
runs-on: ubuntu-latest
# Run for:
# - Scheduled runs (batch processing)
# - New issues (need component labeling)
# - Issues labeled with "planned" (need owner assignment)
if: >-
github.repository == 'google/adk-python' && (
github.event_name == 'schedule' ||
github.event.action == 'opened' ||
github.event.label.name == 'planned'
)
permissions:
issues: write
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.11'
@@ -43,8 +30,8 @@ jobs:
GITHUB_TOKEN: ${{ secrets.ADK_TRIAGE_AGENT }}
GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
GOOGLE_GENAI_USE_VERTEXAI: 0
OWNER: ${{ github.repository_owner }}
REPO: ${{ github.event.repository.name }}
OWNER: 'google'
REPO: 'adk-python'
INTERACTIVE: 0
EVENT_NAME: ${{ github.event_name }} # 'issues', 'schedule', etc.
ISSUE_NUMBER: ${{ github.event.issue.number }}
@@ -9,12 +9,11 @@ on:
jobs:
upload-adk-docs-to-vertex-ai-search:
if: github.repository == 'google/adk-python'
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v4
- name: Clone adk-docs repository
run: git clone https://github.com/google/adk-docs.git /tmp/adk-docs
@@ -23,13 +22,13 @@ jobs:
run: git clone https://github.com/google/adk-python.git /tmp/adk-python
- name: Set up Python
uses: actions/setup-python@v6
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Authenticate to Google Cloud
id: auth
uses: 'google-github-actions/auth@v3'
uses: 'google-github-actions/auth@v2'
with:
credentials_json: '${{ secrets.ADK_GCP_SA_KEY }}'
-1
View File
@@ -101,7 +101,6 @@ Thumbs.db
# AI Coding Tools - Project-specific configs
# Developers should symlink or copy AGENTS.md and add their own overrides locally
.adk/
.claude/
CLAUDE.md
.cursor/
+207 -324
View File
File diff suppressed because it is too large Load Diff
+14 -489
View File
File diff suppressed because it is too large Load Diff
+6 -22
View File
@@ -56,14 +56,14 @@ information on using pull requests.
### Requirement for PRs
- All PRs, other than small documentation or typo fixes, should have an Issue
- All PRs, other than small documentation or typo fixes, should have a Issue
associated. If a relevant issue doesn't exist, please create one first or
you may instead describe the bug or feature directly within the PR
description, following the structure of our issue templates.
- Small, focused PRs. Keep changes minimal—one concern per PR.
- For bug fixes or features, please provide logs or screenshot after the fix
is applied to help reviewers better understand the fix.
- Please include a `testing plan` section in your PR to describe how you
- Please include a `testing plan` section in your PR to talk about how you
will test. This will save time for PR review. See `Testing Requirements`
section for more details.
@@ -126,7 +126,7 @@ Depending on your change:
For any changes that impact user-facing documentation (guides, API reference,
tutorials), please open a PR in the
[adk-docs](https://github.com/google/adk-docs) repository to update the relevant
[adk-docs](https://github.com/google/adk-docs) repository to update relevant
part before or alongside your code PR.
## Development Setup
@@ -145,7 +145,7 @@ part before or alongside your code PR.
3. **Create and activate a virtual environment:**
**NOTE**: ADK supports Python 3.10+. Python 3.11 and above is strongly
**NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly
recommended.
Create a workspace venv using uv.
@@ -160,11 +160,7 @@ part before or alongside your code PR.
source .venv/bin/activate
```
**Windows**
```shell
source .\.venv\Scripts\activate
```
**windows** `shell source .\.venv\Scripts\activate`
4. **Install dependencies:**
@@ -188,18 +184,6 @@ part before or alongside your code PR.
pytest ./tests/unittests
```
**Alternatively**, use the included `unittests.sh` script which handles
environment setup and restoration automatically:
```shell
./scripts/unittests.sh
```
This script will:
- Set up the test environment with minimal dependencies (`test`, `eval`, `a2a`)
- Run the unit tests
- Restore the full development environment (`--all-extras`)
6. **Auto-format the code:**
**NOTE**: We use `isort` and `pyink` for styles. Use the included
@@ -246,7 +230,7 @@ part before or alongside your code PR.
## Contributing Resources
[Contributing folder](https://github.com/google/adk-python/tree/main/contributing)
has resources that are helpful for contributors.
has resources that is helpful for contributors.
## Vibe Coding
+6 -7
View File
@@ -4,7 +4,7 @@
[![PyPI](https://img.shields.io/pypi/v/google-adk)](https://pypi.org/project/google-adk/)
[![Python Unit Tests](https://github.com/google/adk-python/actions/workflows/python-unit-tests.yml/badge.svg)](https://github.com/google/adk-python/actions/workflows/python-unit-tests.yml)
[![r/agentdevelopmentkit](https://img.shields.io/badge/Reddit-r%2Fagentdevelopmentkit-FF4500?style=flat&logo=reddit&logoColor=white)](https://www.reddit.com/r/agentdevelopmentkit/)
<a href="https://codewiki.google/github.com/google/adk-python"><img src="https://www.gstatic.com/_/boq-sdlc-agents-ui/_/r/Mvosg4klCA4.svg" alt="Ask Code Wiki" height="20"></a>
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/google/adk-python)
<html>
<h2 align="center">
@@ -17,8 +17,7 @@
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-go">Go ADK</a> &
<a href="https://github.com/google/adk-java">Java ADK</a> &
<a href="https://github.com/google/adk-web">ADK Web</a>.
</h3>
</html>
@@ -33,7 +32,7 @@ deployment-agnostic, and compatible with other frameworks.
## šŸ”„ What's new
- **Custom Service Registration**: Add a service registry to provide a generic way to register custom service implementations to be used in FastAPI server. See [short instruction](https://github.com/google/adk-python/discussions/3175#discussioncomment-14745120). ([391628f](https://github.com/google/adk-python/commit/391628fcdc7b950c6835f64ae3ccab197163c990))
- **Custom Service Registration**: Add a service registry to provide a generic way to register custom service implementations to be used in FastAPI server. See short instruction [here](https://github.com/google/adk-python/discussions/3175#discussioncomment-14745120). ([391628f](https://github.com/google/adk-python/commit/391628fcdc7b950c6835f64ae3ccab197163c990))
- **Rewind**: Add the ability to rewind a session to before a previous invocation ([9dce06f](https://github.com/google/adk-python/commit/9dce06f9b00259ec42241df4f6638955e783a9d1)).
@@ -115,7 +114,7 @@ root_agent = Agent(
### Define a multi-agent system:
Define a multi-agent system with coordinator agent, greeter agent, and task execution agent. Then ADK engine and the model will guide the agents to work together to accomplish the task.
Define a multi-agent system with coordinator agent, greeter agent, and task execution agent. Then ADK engine and the model will guide the agents works together to accomplish the task.
```python
from google.adk.agents import LlmAgent, BaseAgent
@@ -158,13 +157,13 @@ We welcome contributions from the community! Whether it's bug reports, feature r
## 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
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 want 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.
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

Some files were not shown because too many files have changed in this diff Show More