Skip to content

Python Quickstart for ADK

ADK Python 快速入门

This guide shows you how to get up and running with Agent Development Kit (ADK) for Python. Before you start, make sure you have the following installed:

本指南向您展示如何开始使用 Python 版智能体开发工具包 (ADK)。在开始之前,请确保您已安装以下内容:

  • Python 3.10 or later Python 3.10 或更高版本
  • pip for installing packages 用于安装包的 pip

Installation

安装

Install ADK by running the following command:

通过运行以下命令安装 ADK:

pip install google-adk
Recommended: create and activate a Python virtual environment

推荐:创建并激活 Python 虚拟环境

Create a Python virtual environment:

创建 Python 虚拟环境:

python -m venv .venv

Activate the Python virtual environment:

激活 Python 虚拟环境:

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

source .venv/bin/activate

Create an agent project

创建智能体项目

Run adk create command to start a new agent project.

运行 adk create 命令以启动新的智能体项目。

adk create my_agent

Explore the agent project

探索智能体项目

The created agent project has the following structure, with the agent.py file containing the main control code for the agent.

创建的智能体项目具有以下结构,其中 agent.py 文件包含智能体的主要控制代码。

my_agent/
    agent.py      # main agent code
                 # 主要智能体代码
    .env          # API keys or project IDs
                  # API 密钥或项目 ID
    __init__.py

Update your agent project

更新您的智能体项目

The agent.py file contains a root_agent definition which is the only required element of an ADK agent. You can also define tools for the agent to use. Update the generated agent.py code to include a get_current_time tool for use by the agent, as shown in the following code:

agent.py 文件包含 root_agent 定义,这是 ADK 智能体的唯一必需元素。您还可以为智能体定义要使用的工具。更新生成的 agent.py 代码以包含 get_current_time 工具供智能体使用,如以下代码所示:

from google.adk.agents.llm_agent import Agent

# Mock tool implementation
# 模拟工具实现
def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    """返回指定城市的当前时间。"""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='root_agent',
    description="Tells the current time in a specified city.",
    instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.",
    tools=[get_current_time],
)

Set your API key

设置您的 API 密钥

This project uses the Gemini API, which requires an API key. If you don't already have a Gemini API key, create a key in Google AI Studio on the API Keys page.

本项目使用 Gemini API,该 API 需要 API 密钥。如果您还没有 Gemini API 密钥,请前往 Google AI Studio 在 API 密钥 页面创建密钥。

In a terminal window, write your API key into an .env file as an environment variable:

在终端窗口中,将您的 API 密钥写入 .env 文件作为环境变量:

Update: my_agent/.env
echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env
Using other AI models with ADK

在 ADK 中使用其他 AI 模型

ADK supports the use of many generative AI models. For more information on configuring other models in ADK agents, see Models & Authentication.

ADK 支持使用多种生成式 AI 模型。有关在 ADK 智能体中配置其他模型的更多信息,请参阅模型和身份验证。

Run your agent

运行您的智能体

You can run your ADK agent with an interactive command-line interface using the adk run command or the ADK web user interface provided by ADK using the adk web command. Both these options allow you to test and interact with your agent.

您可以使用 adk run 命令通过交互式命令行界面运行您的 ADK 智能体,或使用 ADK 提供的 adk web 命令使用 ADK Web 用户界面。这两个选项都允许您测试和与智能体交互。

Run with command-line interface

使用命令行界面运行

Run your agent using the adk run command-line tool.

使用 adk run 命令行工具运行您的智能体。

adk run my_agent

adk-run.png

Run with web interface

使用 Web 界面运行

The ADK framework provides a web interface that you can use to test and interact with your agent. You can start the web interface using the following command:

ADK 框架提供了一个 Web 界面,您可以使用它来测试和与智能体交互。您可以使用以下命令启动 Web 界面:

adk web --port 8000

Note

Run this command from the parent directory that contains your my_agent/ folder. For example, if your agent is inside agents/my_agent/, run adk web from the agents/ directory.

从包含 my_agent/ 文件夹的父目录运行此命令。例如,如果您的智能体位于 agents/my_agent/ 中,请从 agents/ 目录运行 adk web。

This command starts a web server with a chat interface for your agent. You can access the web interface at (http://localhost:8000). Select the agent at the upper left corner and type a request.

此命令启动一个带有智能体聊天界面的 Web 服务器。您可以在 (http://localhost:8000) 访问 Web 界面。在左上角选择智能体并输入请求。

adk-web-dev-ui-chat.png

Caution: ADK Web for development only

警告:ADK Web 仅用于开发

ADK Web is not meant for use in production deployments. You should use ADK Web for development and debugging purposes only.

ADK Web 不适用于生产环境部署。您应该仅将 ADK Web 用于开发和调试目的。

Next: Build your agent

下一步:构建您的智能体

Now that you have ADK installed and your first agent running, try building your own agent with our build guides:

既然您已经安装了 ADK 并运行了第一个智能体,请尝试使用我们的构建指南构建您自己的智能体: