diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 05b80168..7c2ffdd9 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -7,7 +7,7 @@ assignees: ''
---
-** Please make sure you read the contribution guide and file the issues in the rigth place. **
+** 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**
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 099f7b30..2db63185 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -7,7 +7,7 @@ assignees: ''
---
-** Please make sure you read the contribution guide and file the issues in the rigth place. **
+** 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/)
**Is your feature request related to a problem? Please describe.**
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae23e2ef..8afca246 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,91 @@
# Changelog
+## 1.1.1
+
+### Features
+* Add BigQuery first-party tools. See [here](https://github.com/google/adk-python/commit/d6c6bb4b2489a8b7a4713e4747c30d6df0c07961) for more details.
+
+
+## 1.1.0
+
+### Features
+
+* Extract agent loading logic from fast_api.py to a separate AgentLoader class and support more agent definition folder/file structure.
+* Added audio play in web UI.
+* Added input transcription support for live/streaming.
+* Added support for storing eval run history locally in adk eval cli.
+* Image artifacts can now be clicked directly in chat message to view.
+* Left side panel can now be resized.
+
+### Bug Fixes
+
+* Avoid duplicating log in stderr.
+* Align event filtering and ordering logic.
+* Add handling for None param.annotation.
+* Fixed several minor bugs regarding eval tab in web UI.
+
+### Miscellaneous Chores
+
+* Updates mypy config in pyproject.toml.
+* Add google search agent in samples.
+* Update filtered schema parameters for Gemini API.
+* Adds autoformat.sh for formatting codebase.
+
+## 1.0.0
+
+### ⚠ BREAKING CHANGES
+
+* Evaluation dataset schema is finalized with strong-type pydantic models.
+ (previously saved eval file needs re-generation, for both adk eval cli and
+ the eval tab in adk web UI).
+* `BuiltInCodeExecutor` (in code_executors package) replaces
+ `BuiltInCodeExecutionTool` (previously in tools package).
+* All methods in services are now async, including session service, artifact
+ service and memory service.
+ * `list_events` and `close_session` methods are removed from session service.
+* agent.py file structure with MCP tools are now easier and simpler ([now](https://github.com/google/adk-python/blob/3b5232c14f48e1d5b170f3698d91639b079722c8/contributing/samples/mcp_stdio_server_agent/agent.py#L33) vs [before](https://github.com/google/adk-python/blob/a4adb739c0d86b9ae4587547d2653d568f6567f2/contributing/samples/mcp_agent/agent.py#L41)).
+ Old format is not working anymore.
+* `Memory` schema and `MemoryService` is redesigned.
+* Mark various class attributes as private in the classes in the `tools` package.
+* Disabled session state injection if instruction provider is used.
+ (so that you can have `{var_name}` in the instruction, which is required for code snippets)
+* Toolbox integration is revamped: tools/toolbox_tool.py → tools/toolbox_toolset.py.
+* Removes the experimental `remote_agent.py`. We'll redesign it and bring it back.
+
+### Features
+
+* Dev UI:
+ * A brand new trace view for overall agent invocation.
+ * A revamped evaluation tab and comparison view for checking eval results.
+* Introduced `BaseToolset` to allow dynamically add/remove tools for agents.
+ * Revamped MCPToolset with the new BaseToolset interface.
+ * Revamped GoogleApiTool, GoogleApiToolset and ApplicationIntegrationToolset with the new BaseToolset interface.
+ * Resigned agent.py file structure when needing MCPToolset.
+ * Added ToolboxToolset.
+* Redesigned strong-typed agent evaluation schema.
+ * Allows users to create more cohesive eval sets.
+ * Allows evals to be extended for non-text modality.
+ * Allows for a structured interaction with the uber eval system.
+* Redesigned Memory schema and MemoryService interfaces.
+* Added token usage to LlmResponse.
+* Allowed specifying `--adk_version` in `adk deploy cloud_run` cli. Default is the current version.
+
+### Bug Fixes
+
+* Fixed `adk deploy cloud_run` failing bug.
+* Fixed logs not being printed due to `google-auth` library.
+
+### Miscellaneous Chores
+
+* Display full help text when adk cli receives invalid arguments.
+* `adk web` now binds `127.0.0.1` by default, instead of 0.0.0.0.
+* `InMemoryRunner` now takes `BaseAgent` in constructor.
+* Various docstring improvements.
+* Various UI tweaks.
+* Various bug fixes.
+* Update various contributing/samples for contributors to validate the implementation.
+
+
## 0.5.0
### ⚠ BREAKING CHANGES
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e9ae04f6..bd7f772d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,8 +2,7 @@
We'd love to accept your patches and contributions to this project.
-## Table of Contents
-
+- [How to contribute](#how-to-contribute)
- [Before you begin](#before-you-begin)
- [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)
- [Review our community guidelines](#review-our-community-guidelines)
@@ -12,16 +11,16 @@ We'd love to accept your patches and contributions to this project.
- [Requirement for PRs](#requirement-for-prs)
- [Large or Complex Changes](#large-or-complex-changes)
- [Testing Requirements](#testing-requirements)
- - [Unit Tests](#unit-tests)
- - [End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
+ - [Unit Tests](#unit-tests)
+ - [Manual End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
- [Documentation](#documentation)
- [Development Setup](#development-setup)
-- [Code reviews](#code-reviews)
+ - [Code reviews](#code-reviews)
-## Before you begin
+# Before you begin
-### Sign our Contributor License Agreement
+## Sign our Contributor License Agreement
Contributions to this project must be accompanied by a
[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
@@ -35,38 +34,38 @@ was for a different project), you probably don't need to do it again.
Visit to see your current agreements or to
sign a new one.
-### Review our community guidelines
+## Review our community guidelines
This project follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
-## Contribution workflow
+# Contribution workflow
-### Finding Issues to Work On
+## Finding Issues to Work On
- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help wanted`** (general contributions).
- For other issues, please kindly ask before contributing to avoid duplication.
-### Requirement for PRs
+## Requirement for PRs
- All PRs, other than small documentation or typo fixes, should have a Issue assoicated. If not, please create one.
- Small, focused PRs. Keep changes minimal—one concern per PR.
- For bug fixes or features, please provide logs or screenshot after the fix is applied to help reviewers better understand the fix.
- Please include a `testing plan` section in your PR to talk about how you will test. This will save time for PR review. See `Testing Requirements` section for more details.
-### Large or Complex Changes
+## Large or Complex Changes
For substantial features or architectural revisions:
- Open an Issue First: Outline your proposal, including design considerations and impact.
- Gather Feedback: Discuss with maintainers and the community to ensure alignment and avoid duplicate work
-### Testing Requirements
+## Testing Requirements
To maintain code quality and prevent regressions, all code changes must include comprehensive tests and verifiable end-to-end (E2E) evidence.
-#### Unit Tests
+### Unit Tests
Please add or update unit tests for your change. Please include a summary of passed `pytest` results.
@@ -80,7 +79,7 @@ Requirements for unit tests:
- Free of external dependencies (use mocks or fixtures as needed).
- **Quality:** Aim for high readability and maintainability; include docstrings or comments for complex scenarios.
-#### Manual End-to-End (E2E) Tests
+### Manual End-to-End (E2E) Tests
Manual E2E tests ensure integrated flows work as intended. Your tests should cover all scenarios. Sometimes, it's also good to ensure relevant functionality is not impacted.
@@ -97,23 +96,34 @@ Depending on your change:
- Include the command used and console output showing test results.
- Highlight sections of the log that directly relate to your change.
-### Documentation
+## Documentation
For any changes that impact user-facing documentation (guides, API reference, tutorials), please open a PR in the [adk-docs](https://github.com/google/adk-docs) repository to update relevant part before or alongside your code PR.
-### Development Setup
+## Development Setup
1. **Clone the repository:**
```shell
- git clone git@github.com:google/adk-python.git
+ gh repo clone google/adk-python
cd adk-python
```
-2. **Create and activate a virtual environment:**
+
+2. **Install uv:**
+
+ Check out [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+3. **Create and activate a virtual environment:**
+
+ **NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly recommended.
+
+ Create a workspace venv using uv.
```shell
- python -m venv .venv
+ uv venv --python "python3.11" ".venv"
```
+ Activate the workspace venv.
+
```shell
source .venv/bin/activate
```
@@ -123,39 +133,74 @@ For any changes that impact user-facing documentation (guides, API reference, tu
source .\.venv\Scripts\activate
```
-3. **Install dependencies:**
+4. **Install dependencies:**
```shell
- pip install uv
uv sync --all-extras
```
-4. **Run unit tests:**
+
+ **NOTE**: for convenience, installing all extra deps as a starting point.
+
+5. **Run unit tests:**
```shell
- uv run pytest ./tests/unittests
+ pytest ./tests/unittests
```
-5. **Run pyink to format codebase:**
+
+ NOTE: for accurately repro test failure, only include `test` and `eval` as
+ extra dependencies.
```shell
- uv run pyink --config pyproject.toml ./src
+ uv sync --extra test --extra eval
+ pytest ./tests/unittests
```
-6. **Build the package**
+6. **Auto-format the code:**
+
+ **NOTE**: We use `isort` and `pyink` for styles. Use the included
+ autoformat.sh to auto-format.
+
+ ```shell
+ ./autoformat.sh
+ ```
+
+7. **Build the wheel file:**
+
```shell
uv build
```
-7. **Local Testing**
- Have a simple testing folder setup as mentioned in the [quickstart](https://google.github.io/adk-docs/get-started/quickstart/)
- then install the local package with changes after building it using the below command to test the changes.
+8. **Test the locally built wheel file:**
+ Have a simple testing folder setup as mentioned in the
+ [quickstart](https://google.github.io/adk-docs/get-started/quickstart/).
+
+ Then following below steps to test your changes:
+
+ Create a clean venv and activate it:
```shell
- uv pip install
-
- [eg]: uv pip install /dist/google_adk-0.4.0-py3-none-any.whl
+ VENV_PATH=~/venvs/adk-quickstart
```
-### Code reviews
+ ```shell
+ command -v deactivate >/dev/null 2>&1 && deactivate
+ ```
+
+ ```shell
+ rm -rf $VENV_PATH \
+ && python3 -m venv $VENV_PATH \
+ && source $VENV_PATH/bin/activate
+ ```
+
+ Install the locally built wheel file:
+
+ ```shell
+ pip install dist/google_adk--py3-none-any.whl
+ ```
+
+
+
+## Code reviews
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
diff --git a/README.md b/README.md
index a5fcbd88..d117602d 100644
--- a/README.md
+++ b/README.md
@@ -13,8 +13,10 @@