Skip to content

使用智能体配置构建智能体

ADK 智能体配置功能让你无需编写代码即可构建 ADK 工作流。智能体配置使用 YAML 格式的文本文件，包含智能体的简要描述，允许几乎任何人组装和运行 ADK 智能体。以下是一个基本智能体配置定义的简单示例：

name: assistant_agent
model: gemini-2.5-flash
description: A helper agent that can answer users' questions.
instruction: You are an agent to help answer users' various questions.

你可以使用智能体配置文件构建更复杂的智能体，这些智能体可以集成函数、工具、子智能体等。本页描述了如何使用智能体配置功能构建和运行 ADK 工作流。有关智能体配置格式支持的语法和设置的详细信息，请参阅智能体配置语法参考。

实验性功能

智能体配置功能是实验性的，有一些已知限制。我们欢迎你的反馈！

开始使用

本节描述如何使用 ADK 和智能体配置功能设置和开始构建智能体，包括安装设置、构建智能体和运行你的智能体。

设置

你需要安装 Google 智能体开发工具包库，并为生成式 AI 模型（如 Gemini API）提供访问密钥。本节详细说明在运行智能体配置文件之前必须安装和配置的内容。

Note

智能体配置功能目前仅支持 Gemini 模型。有关其他功能限制的更多信息，请参阅已知限制。

要设置 ADK 以使用智能体配置：

  1. 按照安装说明安装 ADK Python 库。目前需要 Python。 更多信息请参阅已知限制。

  2. 通过在终端中运行以下命令验证 ADK 是否已安装：

    adk --version

    此命令应显示你已安装的 ADK 版本。

Tip

如果 adk 命令无法运行且步骤 2 中未列出版本，请确保你的 Python 环境处于活动状态。在 Mac 和 Linux 的终端中执行 source .venv/bin/activate。有关其他平台命令，请参阅安装页面。

构建智能体

你使用 adk create 命令通过智能体配置构建智能体，创建智能体的项目文件，然后编辑它为你生成的 root_agent.yaml 文件。

要创建用于智能体配置的 ADK 项目：

  1. 在终端窗口中，运行以下命令创建基于配置的智能体：

    adk create --type=config my_agent

    此命令生成一个 my_agent/ 文件夹，包含 root_agent.yaml 文件和 .env 文件。

  2. 在 my_agent/.env 文件中，为你的智能体设置环境变量以访问生成式 AI 模型和其他服务：

    1. 对于通过 Google API 访问 Gemini 模型，在文件中添加一行你的 API 密钥：

      GOOGLE_GENAI_USE_VERTEXAI=0
GOOGLE_API_KEY=<your-Google-Gemini-API-key>

      你可以从 Google AI Studio API 密钥页面获取 API 密钥。

    2. 对于通过 Google Cloud 访问 Gemini 模型，在文件中添加这些行：

      GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<your_gcp_project>
GOOGLE_CLOUD_LOCATION=us-central1

      有关创建 Cloud 项目的信息，请参阅 Google Cloud 文档中的创建和管理项目。

  3. 使用文本编辑器编辑智能体配置文件 my_agent/root_agent.yaml，如下所示：

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: assistant_agent
model: gemini-2.5-flash
description: A helper agent that can answer users' questions.
instruction: You are an agent to help answer users' various questions.

你可以通过参考 ADK 示例仓库或智能体配置语法参考来发现 root_agent.yaml 智能体配置文件的更多配置选项。

运行智能体

完成智能体配置编辑后，你可以使用 Web 界面、命令行终端执行或 API 服务器模式运行你的智能体。

要运行你的智能体配置定义的智能体：

  1. 在终端中，导航到包含 root_agent.yaml 文件的 my_agent/ 目录。
  2. 输入以下命令之一来运行你的智能体：
    • adk web - 为你的智能体运行 Web UI 界面。
    • adk run - 在没有用户界面的终端中运行你的智能体。
    • adk api_server - 将你的智能体作为可被其他应用程序使用的服务运行。

有关运行智能体方式的更多信息，请参阅快速开始中的运行你的智能体主题。有关 ADK 命令行选项的更多信息，请参阅ADK CLI 参考。

配置示例

本节显示智能体配置文件的示例，帮助你开始构建智能体。有关其他更完整的示例，请参阅 ADK 示例仓库。

内置工具示例

以下示例使用内置的 ADK 工具函数进行 Google 搜索，为智能体提供功能。此智能体自动使用搜索工具回复用户请求。

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: search_agent
model: gemini-2.0-flash
description: 'an agent whose job it is to perform Google search queries and answer questions about the results.'
instruction: You are an agent whose job is to perform Google search queries and answer questions about the results.
tools:
  - name: google_search

更多详细信息，请参阅 ADK 示例仓库中此示例的完整代码。

自定义工具示例

以下示例使用用 Python 代码构建的自定义工具，并在配置文件的 tools: 部分中列出。智能体使用此工具检查用户提供的数字列表是否为质数。

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
agent_class: LlmAgent
model: gemini-2.5-flash
name: prime_agent
description: Handles checking if numbers are prime.
instruction: |
  You are responsible for checking whether numbers are prime.
  When asked to check primes, you must call the check_prime tool with a list of integers.
  Never attempt to determine prime numbers manually.
  Return the prime number results to the root agent.
tools:
  - name: ma_llm.check_prime

更多详细信息，请参阅 ADK 示例仓库中此示例的完整代码。

子智能体示例

以下示例显示在 sub_agents: 部分中定义了两个子智能体的智能体，以及在配置文件的 tools: 部分中的示例工具。此智能体确定用户想要什么，并委托给其中一个子智能体来解决请求。子智能体使用智能体配置 YAML 文件定义。

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
agent_class: LlmAgent
model: gemini-2.5-flash
name: root_agent
description: Learning assistant that provides tutoring in code and math.
instruction: |
  You are a learning assistant that helps students with coding and math questions.

  You delegate coding questions to the code_tutor_agent and math questions to the math_tutor_agent.

  Follow these steps:
  1. If the user asks about programming or coding, delegate to the code_tutor_agent.
  2. If the user asks about math concepts or problems, delegate to the math_tutor_agent.
  3. Always provide clear explanations and encourage learning.
sub_agents:
  - config_path: code_tutor_agent.yaml
  - config_path: math_tutor_agent.yaml

更多详细信息，请参阅 ADK 示例仓库中此示例的完整代码。

部署智能体配置

你可以使用 Cloud Run 和 Agent Engine 部署智能体配置智能体，使用与基于代码的智能体相同的程序。有关如何准备和部署基于智能体配置的智能体的更多信息，请参阅 Cloud Run 和 Agent Engine 部署指南。

已知限制

智能体配置功能是实验性的，包括以下限制：

  • 模型支持： 目前仅支持 Gemini 模型。与第三方模型的集成正在进行中。
  • 编程语言： 智能体配置功能目前仅支持 Python 代码用于需要编程代码的工具和其他功能。
  • ADK 工具支持： 以下 ADK 工具受智能体配置功能支持，但并非所有工具都完全支持：
  • google_search
  • load_artifacts
  • url_context
  • exit_loop
  • preload_memory
  • get_user_choice
  • enterprise_web_search
  • load_web_page：需要完全限定的路径来访问网页。
  • 智能体类型支持： LangGraphAgent 和 A2aAgent 类型尚不支持。
  • AgentTool
  • LongRunningFunctionTool
  • VertexAiSearchTool
  • MCPToolset
  • CrewaiTool
  • LangchainTool
  • ExampleTool

下一步

有关如何使用 ADK 智能体配置构建什么以及如何构建的想法，请参阅 ADK adk-samples 仓库中基于 yaml 的智能体定义。有关智能体配置格式支持的语法和设置的详细信息，请参阅智能体配置语法参考。