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

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

name: assistant_agent
model: gemini-flash-latest
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）提供访问密钥。本节详细说明在运行智能体配置文件之前必须安装和配置的内容。

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

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

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

   adk --version
   

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

构建智能体¶

你可以使用智能体配置通过 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_ENTERPRISE=0
      GOOGLE_API_KEY=<你的-Google-Gemini-API-密钥>
      

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

   2. 要通过 Google Cloud 访问 Gemini 模型，请在文件中添加以下行：

      GOOGLE_GENAI_USE_ENTERPRISE=1
      GOOGLE_CLOUD_PROJECT=<你的_gcp_项目>
      GOOGLE_CLOUD_LOCATION=us-central1
      

      关于创建云项目的信息，请参阅 Google Cloud 文档中的 创建和管理项目。 关于从 ADK 智能体连接到 Google Cloud 的更多信息，请参阅 连接到 Google Cloud 和 Agent Platform。

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-flash-latest
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 参考。

以编程方式运行¶

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

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-flash-latest
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-flash-latest
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-flash-latest
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 Runtime 来部署智能体配置智能体， 操作流程与基于代码的智能体相同。关于如何准备和部署基于智能体配置的 智能体的更多信息，请参阅 Cloud Run 和 Agent Runtime 部署指南。

已知限制¶

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

• 模型支持： 目前仅支持 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：为工具提供基于示例的少样本学习。
• 智能体类型支持： LangGraphAgent 和 A2aAgent 类型 尚不支持。
• 智能体搜索： VertexAiSearchTool 目前在 Python 和 Java 智能体配置中受支持。

下一步¶

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