# Google ADK Companion Guide: Setup, Permissions, Limits > Companion guide for the google-adk.py asset: install steps, run and eval commands, permissions, limits, and a documented install-gap. ## Install Copy the content below into your project: # Google ADK Companion Guide: Setup, Permissions, Limits Companion guide for the google-adk.py asset: install steps, run and eval commands, permissions, limits, and a documented install-gap. ## Quick Use This companion guide documents the existing `google-adk.py` script asset and Google's Agent Development Kit (ADK). The original script stays exactly as shipped; nothing here replaces, patches or repairs it. 1. Confirm Python: ADK requires Python 3.10+ per the upstream README. 2. Install the package using the command recorded in the script's own header: ```bash pip install google-adk ``` 3. Create and run an agent from the CLI, as shown in the script comments: ```bash adk create my_agent adk run my_agent ``` 4. Read the script's `Agent` and `SequentialAgent` examples before adapting them. Executing the script only prints `Google ADK installed. Run: adk create my_agent`; it installs nothing by itself. Source reviewed; runtime not tested. ## Setup, Permissions and Limits The asset is a single documentation-style script, entrypoint `google-adk.py`, tagged for `gemini_cli`. It is an install-and-usage note, not a packaged application, and the snapshot shows no installation file besides the script itself. Upstream concepts named in the README: `Agent` (instructions, tools, behaviour) and `Workflow` (graph-based orchestration with routing, fan-out/fan-in, loops, retry, state). | Item | Detail | | --- | --- | | Python | 3.10+ (upstream README) | | Package manager | `pip` | | Model access | The script's examples use Gemini model names; credentials for whichever model provider you choose are your responsibility | | Deployment | Cloud Run / Vertex AI Agent Engine require a Google Cloud project | | License | Apache 2.0 | From the supplied risk profile: the file executes code, declares no network access, requires no secrets at rest, does not modify global configuration and does not use absolute paths. Upstream claims such as one-command deployment and MCP compatibility are upstream statements; they were not verified here. ## FAQ **Does running the script install ADK?** No. It only prints a message; you must run `pip install google-adk` yourself. **Can the multi-agent example be used as-is?** The `researcher` / `writer` / `SequentialAgent` snippet is illustrative. You need your own agent directory and model credentials before `adk run` works. ## Output Checks and Limitations After `pip install google-adk`, check the CLI is on your path with `adk --help`; a command listing confirms the install. After `adk run my_agent`, an interactive session that answers a prompt confirms the agent loaded. Evaluation upstream uses an `.evalset.json` file and an eval config through `adk eval`; deploy paths are `adk deploy cloud_run --with_ui ` and `adk deploy docker --with_ui `. Limitations: this catalogue ships no `my_agent` directory, no eval set, no Cloud project and no credentials, so none of those paths were executed. The script is documentation, not a runnable agent. The upstream README at the reviewed commit describes ADK 2.0 with a graph-based `Workflow` runtime and Task API; the bundled script's snippets use the earlier `SequentialAgent` style, so treat the script as an illustration and check the current docs at for the exact API of the version you install. ## Source and Thanks Source: `google/adk-python` at commit `61266e5b64362b19631d52dce2576646c3860873`, README , docs and samples . Licensed Apache 2.0. Thanks to the ADK maintainers and contributors. Source reviewed; runtime not tested. ## Complete upstream material # Agent Development Kit (ADK) 2.0 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![PyPI version](https://img.shields.io/pypi/v/google-adk.svg)](https://pypi.org/project/google-adk/) [![Python versions](https://img.shields.io/pypi/pyversions/google-adk.svg)](https://pypi.org/project/google-adk/) [![PyPI downloads](https://static.pepy.tech/badge/google-adk/month)](https://pepy.tech/project/google-adk) [![Continuous Integration](https://github.com/google/adk-python/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/google/adk-python/actions/workflows/continuous-integration.yml) [![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://adk.dev/) [![r/agentdevelopmentkit](https://img.shields.io/badge/Reddit-r%2Fagentdevelopmentkit-FF4500?style=flat&logo=reddit&logoColor=white)](https://www.reddit.com/r/agentdevelopmentkit/) Ask Code Wiki

An open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents with flexibility and control.

Important Links: Docs, Samples & ADK Web.

ADK in other languages: ADK Java, ADK Kotlin, ADK Go & ADK Typescript.

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. ## ✨ Key Features - **Workflow Runtime**: A graph-based execution engine for composing deterministic execution flows for agentic apps, with support for routing, fan-out/fan-in, loops, retry, state management, dynamic nodes, human-in-the-loop, and nested workflows. - **Task API**: Structured agent-to-agent delegation with multi-turn task mode, single-turn controlled output, mixed delegation patterns, human-in-the-loop, and task agents as workflow nodes. - **Modular Multi-Agent Systems**: Design scalable applications by composing multiple specialized agents into flexible hierarchies. - **Rich Tool Ecosystem**: Utilize pre-built tools, custom functions, 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://adk.dev/agents/config/) feature. - **Tool Confirmation**: A [tool confirmation flow (HITL)](https://adk.dev/tools-custom/confirmation/) that can guard tool execution with explicit confirmation and custom input. - **Deploy Anywhere**: Easily containerize and deploy agents on Cloud Run or scale seamlessly with Vertex AI Agent Engine. ## 🚀 Installation ### Stable Release (Recommended) You can install the latest stable version of ADK using `pip`: ```bash pip install google-adk ``` **Requirements:** Python 3.10+. For transitive dependency protection, we recommend to install with our companion constraints files (for python 3.10 to 3.14). Choose the constraints file matching your Python version: ```bash # For example, for Python 3.10 curl -o constraints-3.10.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.10.txt pip install google-adk -c constraints-3.10.txt rm constraints-3.10.txt ``` To install optional integrations, you can use the following command: ```bash pip install "google-adk[extensions]" ``` The release cadence is roughly bi-weekly. ### Development Version Bug fixes and new features are merged into the main branch on GitHub first. If you need access to changes that haven't been included in an official PyPI release yet, you can install directly from the main branch: ```bash 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. ## Quick Start > **Beginner Note:** ADK applications are built using two main classes: > **`Agent`** (defines an AI's instructions, tools, and behavior) and > **`Workflow`** (orchestrates agents and tasks in a graph-based flow). ### Agent ```python from google.adk import Agent root_agent = Agent( name="greeting_agent", model="gemini-3.5-flash", instruction="You are a helpful assistant. Greet the user warmly.", ) ``` ### Workflow ```python from google.adk import Agent, Workflow generate_fruit_agent = Agent( name="generate_fruit_agent", instruction="Return the name of a random fruit. Return only the name.", ) generate_benefit_agent = Agent( name="generate_benefit_agent", instruction="Tell me a health benefit about the specified fruit.", ) root_agent = Workflow( name="root_agent", edges=[("START", generate_fruit_agent, generate_benefit_agent)], ) ``` ### Run Locally ```bash # Interactive CLI adk run path/to/my_agent # Web UI (supports multi-agent directories or pointing directly to a single agent folder) adk web path/to/agents_dir ``` ### Development UI A built-in development UI to help you test, evaluate, debug, and showcase your agent(s). [![ADK Web UI](https://raw.githubusercontent.com/google/adk-python/main/assets/adk-web-dev-ui.png)](https://youtu.be/TEjqk0eeNy8) [![Watch on YouTube](https://img.shields.io/badge/YouTube-Watch%20ADK%20Web%20Demo-FF0000?style=flat&logo=youtube&logoColor=white)](https://youtu.be/TEjqk0eeNy8) ### Evaluate Agents Run the bundled evaluation sample from the repo root: ```bash adk eval \ contributing/samples/evaluation/home_automation_agent \ contributing/samples/evaluation/basic_criteria/home_automation.evalset.json \ --config_file_path contributing/samples/evaluation/basic_criteria/eval_config.json ``` ### 🚀 Deployment Options Deploying the Agent Locally with Docker Container: ```bash adk deploy docker --with_ui ``` Deploying the Agent in Google Cloud (Cloud Run) ```bash adk deploy cloud_run --with_ui ``` You may set the following environment variables in adk command, or in a .env file instead. ```bash adk deploy cloud_run --with_ui --env GOOGLE_GENAI_USE_ENTERPRISE=1 ``` ## 📚 Documentation - **Getting Started**: https://adk.dev/ - **Guides**: See [`docs/guides/`](https://github.com/google/adk-python/tree/main/docs/guides) for task-oriented walkthroughs of agents, tools, events, plugins, and workflows. - **Samples**: See [`contributing/samples/`](https://github.com/google/adk-python/tree/main/contributing/samples) for runnable example agents. ## 🤝 Contributing We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please see our: - [General contribution guideline and flow](https://adk.dev/community/contributing-guide/). - [Code Contributing Guidelines](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/CONTRIBUTING.md) to get started. ## Community Repo We have the [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 an agent via vibe coding the [llms.txt](https://adk.dev/llms.txt) and the [llms-full.txt](https://adk.dev/llms-full.txt) published on the ADK documentation site can be used as context to an LLM. While the former one is a summarized one and the latter one has the full information in case your LLM has a 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](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/LICENSE) file for details. ______________________________________________________________________ *Happy Agent Building!* ## Source and license [Source](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/README.md) · [License](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/LICENSE) · `61266e5b64362b19631d52dce2576646c3860873` Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] 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. --- # Google ADK 双语配套指南：安装、权限与限制 为 google-adk.py 资产撰写的配套指南：安装步骤、运行与评估命令、权限、限制，以及已记录的安装缺口。 ## 快速使用 本配套指南说明已有的 `google-adk.py` 脚本资产，以及 Google 的 Agent Development Kit（ADK）。原脚本保持原样发布，本文不替换、不修补也不修复它。 1. 确认 Python 版本：按上游 README，ADK 需要 Python 3.10+。 2. 使用脚本头部注释中记录的安装命令安装软件包： ```bash pip install google-adk ``` 3. 按脚本注释从命令行创建并运行 agent： ```bash adk create my_agent adk run my_agent ``` 4. 在改造成自己的项目之前，先阅读脚本里的 `Agent` 与 `SequentialAgent` 示例。执行该脚本只会打印 `Google ADK installed. Run: adk create my_agent`，它本身不会安装任何东西。 已审阅源码；未做运行时测试。 ## 安装、权限与限制 该资产是一个文档型脚本，入口为 `google-adk.py`，标记面向 `gemini_cli`。它是安装与用法的说明，而不是打包好的应用，且快照显示除该脚本外没有安装文件。 上游 README 提到的核心概念：`Agent`（指令、工具、行为）与 `Workflow`（基于图的编排，支持路由、fan-out/fan-in、循环、重试、状态）。 | 项目 | 说明 | | --- | --- | | Python | 3.10+（上游 README） | | 包管理器 | `pip` | | 模型访问 | 脚本示例使用 Gemini 模型名；无论你选择哪个模型服务商，凭据都需自行准备 | | 部署 | Cloud Run / Vertex AI Agent Engine 需要 Google Cloud 项目 | | 许可证 | Apache 2.0 | 脚本自带的风险档案：该文件会执行代码，声明不使用网络，不需要静态密钥，不修改全局配置，也不使用绝对路径。上游宣称的一键部署、兼容 MCP 等属于上游说法，本文未做验证。 ## 常见问题 **运行脚本就会安装 ADK 吗？** 不会。它只打印提示信息，你需要自己执行 `pip install google-adk`。 **多 agent 示例可以直接用吗？** `researcher` / `writer` / `SequentialAgent` 片段只是示例。要让 `adk run` 生效，你需要自己的 agent 目录和模型凭据。 ## 输出检查与限制 执行 `pip install google-adk` 后，可用 `adk --help` 检查 CLI 是否已在路径中；能列出命令即说明安装成功。执行 `adk run my_agent` 后，若能进入交互会话并回答提示，说明 agent 已加载。上游的评估流程使用 `.evalset.json` 文件与 eval 配置，通过 `adk eval` 调用；部署路径为 `adk deploy cloud_run --with_ui ` 与 `adk deploy docker --with_ui `。 限制：本目录不包含 `my_agent` 目录、评估集、Cloud 项目和凭据，因此这些路径都未实际执行。该脚本是文档而非可直接运行的 agent，请把其中的片段当作待改造的示例。所审阅 commit 的上游 README 描述的是 ADK 2.0，采用基于图的 `Workflow` 运行时与 Task API；而随附脚本自身的片段使用的是更早的 `SequentialAgent` 写法，因此只把脚本当作示意，安装后请以当前文档 为准核对你所用版本的确切 API。 ## 来源与致谢 来源：`google/adk-python`，commit `61266e5b64362b19631d52dce2576646c3860873`，README 链接 ，文档 ，示例 。许可证 Apache 2.0。感谢 ADK 维护者与贡献者。已审阅源码；未做运行时测试。 ## 完整上游材料译文 # Agent Development Kit（ADK）2.0 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![PyPI version](https://img.shields.io/pypi/v/google-adk.svg)](https://pypi.org/project/google-adk/) [![Python versions](https://img.shields.io/pypi/pyversions/google-adk.svg)](https://pypi.org/project/google-adk/) [![PyPI downloads](https://static.pepy.tech/badge/google-adk/month)](https://pepy.tech/project/google-adk) [![Continuous Integration](https://github.com/google/adk-python/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/google/adk-python/actions/workflows/continuous-integration.yml) [![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://adk.dev/) [![r/agentdevelopmentkit](https://img.shields.io/badge/Reddit-r%2Fagentdevelopmentkit-FF4500?style=flat&logo=reddit&logoColor=white)](https://www.reddit.com/r/agentdevelopmentkit/) Ask Code Wiki

一个开源的、代码优先的 Python 框架，用于以灵活性和控制力构建、评估和部署复杂的 AI agent。

重要链接： 文档、 示例 与 ADK Web。

其他语言版本的 ADK： ADK Java、 ADK Kotlin、 ADK Go 与 ADK Typescript。

Agent Development Kit（ADK）是一个灵活且模块化的框架，将软件开发原则应用于 AI agent 的创建。它旨在简化 agent 工作流的构建、部署与编排，覆盖从简单任务到复杂系统的场景。虽然针对 Gemini 进行了优化，但 ADK 与模型无关、与部署方式无关，并与其他框架兼容。 ## ✨ 核心特性 - **Workflow 运行时**：一个基于图的执行引擎，用于为 agentic 应用组合确定性的执行流程，支持路由、fan-out/fan-in、循环、重试、状态管理、动态节点、human-in-the-loop 以及嵌套工作流。 - **Task API**：结构化的 agent 到 agent 委派，支持多轮任务模式、单轮受控输出、混合委派模式、human-in-the-loop，以及将任务 agent 作为工作流节点。 - **模块化多 Agent 系统**：通过将多个专用 agent 组合为灵活的层级结构来设计可扩展的应用。 - **丰富的工具生态**：利用预构建工具、自定义函数、OpenAPI 规范、MCP 工具，或集成现有工具，赋予 agent 多样化的能力，实现与 Google 生态的紧密集成。 - **代码优先开发**：直接在 Python 中定义 agent 逻辑、工具与编排，以获得极致的灵活性、可测试性和版本管理。 - **Agent 配置**：无需代码即可构建 agent。请查看 [Agent Config](https://adk.dev/agents/config/) 功能。 - **工具确认**：一种[工具确认流程（HITL）](https://adk.dev/tools-custom/confirmation/)，可通过显式确认和自定义输入来防护工具执行。 - **随处部署**：轻松地将 agent 容器化并部署到 Cloud Run，或使用 Vertex AI Agent Engine 无缝扩展。 ## 🚀 安装 ### 稳定版（推荐） 你可以使用 `pip` 安装 ADK 的最新稳定版本： ```bash pip install google-adk ``` **要求：** Python 3.10+。 为防止传递依赖带来的问题，我们建议配合我们的配套约束文件进行安装（适用于 Python 3.10 到 3.14）。 选择与你的 Python 版本匹配的约束文件： ```bash # For example, for Python 3.10 curl -o constraints-3.10.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.10.txt pip install google-adk -c constraints-3.10.txt rm constraints-3.10.txt ``` 要安装可选集成，可以使用以下命令： ```bash pip install "google-adk[extensions]" ``` 发布节奏大约为每两周一次。 ### 开发版本 Bug 修复和新功能会先合入 GitHub 上的 main 分支。如果你需要使用尚未包含在 PyPI 正式发布版本中的改动，可以直接从 main 分支安装： ```bash pip install git+https://github.com/google/adk-python.git@main ``` 注意：开发版本直接基于最新的代码提交构建。它包含最新的修复和功能，但也可能含有稳定版本中不存在的实验性变更或缺陷。请主要将其用于测试即将发布的变更，或在正式发布前获取关键修复。 ## 快速开始 > **新手提示：** ADK 应用由两个主要类构建： > **`Agent`**（定义 AI 的指令、工具和行为）以及 > **`Workflow`**（以基于图的流程编排 agent 和任务）。 ### Agent ```python from google.adk import Agent root_agent = Agent( name="greeting_agent", model="gemini-3.5-flash", instruction="You are a helpful assistant. Greet the user warmly.", ) ``` ### Workflow ```python from google.adk import Agent, Workflow generate_fruit_agent = Agent( name="generate_fruit_agent", instruction="Return the name of a random fruit. Return only the name.", ) generate_benefit_agent = Agent( name="generate_benefit_agent", instruction="Tell me a health benefit about the specified fruit.", ) root_agent = Workflow( name="root_agent", edges=[("START", generate_fruit_agent, generate_benefit_agent)], ) ``` ### 本地运行 ```bash # Interactive CLI adk run path/to/my_agent # Web UI (supports multi-agent directories or pointing directly to a single agent folder) adk web path/to/agents_dir ``` ### 开发 UI 内置的开发 UI，帮助你测试、评估、调试和展示你的 agent。 [![ADK Web UI](https://raw.githubusercontent.com/google/adk-python/main/assets/adk-web-dev-ui.png)](https://youtu.be/TEjqk0eeNy8) [![Watch on YouTube](https://img.shields.io/badge/YouTube-Watch%20ADK%20Web%20Demo-FF0000?style=flat&logo=youtube&logoColor=white)](https://youtu.be/TEjqk0eeNy8) ### 评估 Agent 从仓库根目录运行随附的评估示例： ```bash adk eval \ contributing/samples/evaluation/home_automation_agent \ contributing/samples/evaluation/basic_criteria/home_automation.evalset.json \ --config_file_path contributing/samples/evaluation/basic_criteria/eval_config.json ``` ### 🚀 部署选项 使用 Docker 容器将 Agent 部署到本地： ```bash adk deploy docker --with_ui ``` 在 Google Cloud（Cloud Run）中部署 Agent ```bash adk deploy cloud_run --with_ui ``` 你可以在 adk 命令中设置以下环境变量，也可以改为在 .env 文件中设置。 ```bash adk deploy cloud_run --with_ui --env GOOGLE_GENAI_USE_ENTERPRISE=1 ``` ## 📚 文档 - **入门指南**：https://adk.dev/ - **指南**：请参阅 [`docs/guides/`](https://github.com/google/adk-python/tree/main/docs/guides)， 其中包含面向任务的智能体、工具、事件、插件与工作流的使用讲解。 - **示例**：请参阅 [`contributing/samples/`](https://github.com/google/adk-python/tree/main/contributing/samples)， 其中包含可运行的示例智能体。 ## 🤝 贡献 我们欢迎社区的贡献！无论是缺陷报告、功能请求、文档改进还是代码贡献，请参阅我们的： - [通用贡献指南与流程](https://adk.dev/community/contributing-guide/)。 - [代码贡献指南](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/CONTRIBUTING.md) 以开始贡献。 ## 社区仓库 我们有 [adk-python-community 仓库](https://github.com/google/adk-python-community)，它是不断壮大的社区贡献生态的家园，涵盖扩展 ADK 核心能力的社区贡献工具、第三方 服务集成以及部署脚本。 ## Vibe Coding 如果你希望通过 vibe coding 开发智能体，ADK 文档站点上发布的 [llms.txt](https://adk.dev/llms.txt) 与 [llms-full.txt](https://adk.dev/llms-full.txt) 可以作为 LLM 的上下文使用。前者是概要版本，后者包含完整信息，前提是你的 LLM 拥有足够大的上下文窗口。 ## 社区活动 - [已完成] ADK 首次社区会议于 2025 年 10 月 15 日（星期三）举行。记得[加入我们的群组](https://groups.google.com/g/adk-community)，以获取[录像](https://drive.google.com/file/d/1rpXDq5NSH8-MyMeYI6_5pZ3Lhn0X9BQf/view)与[幻灯片](https://docs.google.com/presentation/d/1_b8LG4xaiadbUUDzyNiapSFyxanc9ZgFdw7JQ6zmZ9Q/edit?slide=id.g384e60cdaca_0_658&resourcekey=0-tjFFv0VBQhpXBPCkZr0NOg#slide=id.g384e60cdaca_0_658)。 ## 📄 许可证 本项目采用 Apache 2.0 许可证授权——详情请参阅 [LICENSE](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/LICENSE) 文件。 ______________________________________________________________________ *祝你构建智能体愉快！* ## 来源与许可证 [Source](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/README.md) · [License](https://github.com/google/adk-python/blob/61266e5b64362b19631d52dce2576646c3860873/LICENSE) · `61266e5b64362b19631d52dce2576646c3860873` Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] 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. --- Source: https://tokrepo.com/en/workflows/google-adk-companion-guide-setup-permissions-limits-2a0fd7e0 Author: Agent Toolkit