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

Supported in ADKPython v1.11.0Java v0.3.0Go v0.3.0Experimental

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

name: assistant_agent
model: gemini-2.5-flash
description: 一个可以回答用户问题的助手智能体。
instruction: 你是一个帮助回答用户各种问题的智能体。

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

实验性功能

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

开始使用¶

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

设置¶

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

注意

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

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

按照安装说明安装 ADK Python 库。目前需要 Python。 更多信息请参阅已知限制。
通过在终端中运行以下命令验证 ADK 是否已安装：
```
adk --version
```
此命令应显示你已安装的 ADK 版本。

提示

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

构建智能体¶

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

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

在终端窗口中，运行以下命令创建基于配置的智能体：
```
adk create --type=config my_agent
```
此命令生成一个 my_agent/ 文件夹，包含 root_agent.yaml 文件和 .env 文件。
在 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 文档中的创建和管理项目。
使用文本编辑器编辑智能体配置文件 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: 一个可以回答用户问题的助手智能体。
instruction: 你是一个帮助回答用户各种问题的智能体。

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

运行智能体¶

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

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

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

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

以编程方式运行¶

你也可以绕过 CLI，直接在代码中动态加载并执行基于配置的智能体。该工具类会透明地加载配置并实例化合适的智能体类（如 LlmAgent）作为 BaseAgent 的子类。

PythonJava

import asyncio
from google.adk.agents import config_agent_utils
from google.adk.runners import Runner

async def main():
    # 直接从 YAML 配置文件加载智能体
    agent = config_agent_utils.from_config("my_agent/root_agent.yaml")
    # ...

if __name__ == "__main__":
    asyncio.run(main())

import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.ConfigAgentUtils;

public class AgentApp {
    public static void main(String[] args) throws Exception {
        // 直接从 YAML 配置文件加载智能体
        BaseAgent agent = ConfigAgentUtils.fromConfig("my_agent/root_agent.yaml");
        # ...
    }
}

配置示例¶

本节显示智能体配置文件的示例，帮助你开始构建智能体格式。有关其他更完整的示例，请参阅 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: '一个负责执行 Google 搜索查询并回答相关结果问题的智能体。'
instruction: 你是一个负责执行 Google 搜索查询并回答相关结果问题的智能体。
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: 处理质数检查任务。
instruction: |
  你负责检查数字是否为质数。
  当被要求检查质数时，你必须调用 check_prime 工具并传入一个整数列表。
  永远不要尝试手动确定质数。
  将质数结果返回给根智能体。
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: 提供代码和数学辅导的学习助手。
instruction: |
  你是一个学习助手，帮助学生解决编程和数学问题。

  你将编程问题委托给 code_tutor_agent 和数学问题委托给 math_tutor_agent。

  遵循以下步骤：
  1. 如果用户询问有关编程或代码的问题，请委托给 code_tutor_agent。
  2. 如果用户询问有关数学概念或问题，请委托给 math_tutor_agent。
  3. 始终提供清晰的解释并鼓励学习。
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 和 Java 代码编写工具及其他需要编程代码的功能。
ADK 工具支持：智能体配置功能支持以下 ADK 工具，但并非所有工具都得到了完整支持：
- google_search
- google_maps_grounding
- load_artifacts
- url_context
- exit_loop
- preload_memory
- get_user_choice
- enterprise_web_search
- load_web_page: 需要完全限定路径才能访问网页。
- AgentTool: 允许智能体调用另一个智能体。
- LongRunningFunctionTool: 支持长时间运行的函数。
- McpToolset: 连接到模型上下文协议 (MCP) 服务器。
- ExampleTool: 为工具提供基于示例的少样本学习 (few-shot learning)。
智能体类型支持：尚不支持 LangGraphAgent 和 A2aAgent 类型。
Vertex AI Search：VertexAiSearchTool 目前在 Python 和 Java 智能体配置中得到支持。

下一步¶

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