Skip to content

快速入门（流式处理 / Python）

通过本快速入门，你将学习如何创建一个简单的智能体，并使用 ADK 流式处理来实现低延迟、双向的语音和视频通信。我们将安装 ADK，设置一个基础的“Google 搜索”智能体，尝试用 adk web 工具以流式方式运行智能体，然后讲解如何结合 ADK 流式处理和 FastAPI 自己构建一个简单的异步 web 应用。

注意： 本指南假设你有在 Windows、Mac 和 Linux 环境中使用终端的经验。

支持语音/视频流式处理的模型

为了在 ADK 中使用语音/视频流式处理，你需要使用支持 Live API 的 Gemini 模型。你可以在文档中找到支持 Gemini Live API 的模型 ID：

1. 设置环境并安装 ADK

创建并激活虚拟环境（推荐）：

# 创建虚拟环境
python -m venv .venv
# 激活（每次打开新终端时）
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1

安装 ADK：

pip install google-adk

2. 项目结构

创建以下带有空文件的文件夹结构：

adk-streaming/  # 项目文件夹
└── app/ # web 应用文件夹
    ├── .env # Gemini API 密钥
    └── google_search_agent/ # 智能体文件夹
        ├── __init__.py # Python 包
        └── agent.py # 智能体定义

agent.py

将以下代码块复制粘贴到 agent.py。

对于 model，请按照前面模型部分中的描述仔细检查模型 ID。

from google.adk.agents import Agent
from google.adk.tools import google_search  # 导入工具

root_agent = Agent(
   # 智能体的唯一名称
   name="basic_search_agent",
   # 智能体将使用的大型语言模型 (LLM)
   model="gemini-2.0-flash-exp",
   # model="gemini-2.0-flash-live-001",  # 2025 年 2 月起的新流式模型版本
   # 智能体目的的简短描述
   description="Agent to answer questions using Google Search.",
   # 设置智能体行为的指令
   instruction="You are an expert researcher. You always stick to the facts.",
   # 添加 google_search 工具，使用 Google 搜索进行接地
   tools=[google_search]
)

注意： 要启用文本和音频/视频输入，模型必须支持 generateContent（用于文本）和 bidiGenerateContent 方法。通过参考 Gemini 模型列表 (models.list) 文档 验证这些功能。此快速入门使用了 gemini-2.0-flash-exp 模型进行演示。

agent.py 是存储所有智能体逻辑的地方，你必须定义一个 root_agent。

注意你是如何轻松集成 使用 Google 搜索进行基础信息获取 功能的。Agent 类和 google_search 工具处理与 LLM 的复杂交互以及与搜索 API 的基础信息获取，让你可以专注于智能体的目的和行为。

intro_components.png

将以下代码块复制粘贴到 __init__.py 和 main.py 文件中。

__init__.py
from . import agent

3. 设置平台

要运行智能体，请从 Google AI Studio 或 Google Cloud Vertex AI 中选择一个平台：

  1. 从 Google AI Studio 获取 API 密钥。

  2. 打开位于 (app/) 中的 .env 文件并复制粘贴以下代码。

    .env
    GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE

  3. 将 PASTE_YOUR_ACTUAL_API_KEY_HERE 替换为你的实际 API KEY。

  1. 你需要一个现有的 Google Cloud 账户和项目。

  2. 打开位于 (app/) 中的 .env 文件。复制粘贴以下代码并更新项目 ID 和位置。

    .env
    GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=PASTE_YOUR_ACTUAL_PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1

4. 使用 adk web 尝试智能体

现在可以尝试智能体了。运行以下命令来启动开发 UI。首先，确保将当前目录设置为 app：

cd app

同时，使用以下命令设置 SSL_CERT_FILE 变量。这是后面进行语音和视频测试所必需的。

export SSL_CERT_FILE=$(python -m certifi)

然后，运行开发 UI：

adk web

直接在浏览器中打开提供的 URL（通常是 http://localhost:8000 或 http://127.0.0.1:8000）。此连接完全保持在你的本地机器上。选择 google_search_agent。

尝试文本

通过在 UI 中输入以下提示来尝试。

  • 纽约的天气如何？
  • 纽约现在几点？
  • 巴黎的天气如何？
  • 巴黎现在几点？

智能体将使用 google_search 工具获取最新信息来回答这些问题。

尝试语音和视频

要尝试语音功能，重新加载网页浏览器，点击麦克风按钮启用语音输入，并用语音提出相同的问题。你将实时听到回答。

要尝试视频功能，重新加载网页浏览器，点击摄像头按钮启用视频输入，并提出类似“你看到什么？”的问题。智能体将回答它在视频输入中看到的内容。

停止工具

通过在控制台按 Ctrl-C 停止 adk web。

ADK 流式处理说明

以下功能将在未来版本的 ADK 流式处理中支持：回调、长时间运行工具、示例工具和 Shell 智能体（如 SequentialAgent）。

恭喜！你已成功创建并与使用 ADK 的第一个流式处理智能体进行了交互！

下一步：构建自定义流式处理应用

在 自定义音频流式应用 教程中，将介绍如何用 ADK Streaming 和 FastAPI 构建一个支持实时、双向音频和文本通信的自定义异步 web 应用，包括服务器和客户端代码。