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

Supported in ADKPython v1.11.0Java v0.3.0Experimental

ADK 智能体配置 (Agent Config) 功能让你可以无需编写代码即可构建 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）提供访问密钥。本节详细说明在运行智能体配置文件之前必须安装和配置的内容。

注意

智能体配置功能目前仅支持 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: 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 服务器模式运行你的智能体。

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

在终端中，导航到包含 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.agents 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: '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 和 Java 代码编写工具及其他需要编程代码的功能。
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
- ExampleTool

下一步¶

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

设置给定智能体运行的总 LLM 调用次数限制。

大于 0 且小于 sys.maxsize 的值：对 LLM 调用实施限制
小于或等于 0 的值：允许无限制的 LLM 调用（不推荐用于生产环境）

此参数防止过度 API 使用和潜在的失控进程。由于 LLM 调用通常会产生成本并消耗资源，设置适当的限制至关重要。

验证规则¶

Supported in ADKPython v0.1.0Typescript v0.2.0Go v0.1.0Java v0.1.0

RunConfig 类验证其参数以确保智能体操作正确。虽然 Python ADK 使用 Pydantic 进行自动类型验证，Java 和 TypeScript ADK 依赖其静态类型系统，并可能在 RunConfig 的构造函数中包含显式检查。对于 max_llm_calls 参数：

通常不允许极大的值（如 Python 中的 sys.maxsize、Java 中的 Integer.MAX_VALUE 或 TypeScript 中的 Number.MAX_SAFE_INTEGER），以防止出现问题。

示例¶

基本运行时配置¶

PythonTypeScriptGoJava

from google.genai.adk import RunConfig, StreamingMode

config = RunConfig(
    streaming_mode=StreamingMode.NONE,
    max_llm_calls=100
)

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
  streamingMode: StreamingMode.NONE,
  maxLlmCalls: 100,
};

import "google.golang.org/adk/agent"

config := agent.RunConfig{
    StreamingMode: agent.StreamingModeNone,
}

import com.google.adk.agents.RunConfig;
import com.google.adk.agents.RunConfig.StreamingMode;

RunConfig config = RunConfig.builder()
        .setStreamingMode(StreamingMode.NONE)
        .setMaxLlmCalls(100)
        .build();

此配置创建一个非流式智能体，限制为 100 次 LLM 调用，适用于简单的面向任务的智能体，在这种情况下完整的响应是首选。

启用流式处理¶

PythonTypeScriptGoJava

from google.genai.adk import RunConfig, StreamingMode

config = RunConfig(
    streaming_mode=StreamingMode.SSE,
    max_llm_calls=200
)

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
  streamingMode: StreamingMode.SSE,
  maxLlmCalls: 200,
};

import "google.golang.org/adk/agent"

config := agent.RunConfig{
    StreamingMode: agent.StreamingModeSSE,
}

import com.google.adk.agents.RunConfig;
import com.google.adk.agents.RunConfig.StreamingMode;

RunConfig config = RunConfig.builder()
    .setStreamingMode(StreamingMode.SSE)
    .setMaxLlmCalls(200)
    .build();

使用 SSE 流式处理允许用户在生成响应时查看响应，为聊天机器人和助手提供更响应式的感受。

启用语音支持¶

PythonTypeScriptJava

from google.genai.adk import RunConfig, StreamingMode
from google.genai import types

config = RunConfig(
    speech_config=types.SpeechConfig(
        language_code="en-US",
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(
                voice_name="Kore"
            )
        ),
    ),
    response_modalities=["AUDIO", "TEXT"],
    save_input_blobs_as_artifacts=True,
    support_cfc=True,
    streaming_mode=StreamingMode.SSE,
    max_llm_calls=1000,
)

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
    speechConfig: {
        languageCode: "en-US",
        voiceConfig: {
            prebuiltVoiceConfig: {
                voiceName: "Kore"
            }
        },
    },
    responseModalities: [
      { modality: "AUDIO" },
      { modality: "TEXT" }
    ],
    saveInputBlobsAsArtifacts: true,
    supportCfc: true,
    streamingMode: StreamingMode.SSE,
    maxLlmCalls: 1000,
};

import com.google.adk.agents.RunConfig;
import com.google.adk.agents.RunConfig.StreamingMode;
import com.google.common.collect.ImmutableList;
import com.google.genai.types.Content;
import com.google.genai.types.Modality;
import com.google.genai.types.Part;
import com.google.genai.types.PrebuiltVoiceConfig;
import com.google.genai.types.SpeechConfig;
import com.google.genai.types.VoiceConfig;

RunConfig runConfig =
    RunConfig.builder()
        .setStreamingMode(StreamingMode.SSE)
        .setMaxLlmCalls(1000)
        .setSaveInputBlobsAsArtifacts(true)
        .setResponseModalities(ImmutableList.of(new Modality("AUDIO"), new Modality("TEXT")))
        .setSpeechConfig(
            SpeechConfig.builder()
                .voiceConfig(
                    VoiceConfig.builder()
                        .prebuiltVoiceConfig(
                            PrebuiltVoiceConfig.builder().voiceName("Kore").build())
                        .build())
                .languageCode("en-US")
                .build())
        .build();

此综合示例配置一个具有以下功能的智能体：

使用 "Kore" 语音的语音功能（美式英语）
音频和文本输出模态
输入 blob 的制品保存（用于调试）
实验性 CFC 支持已启用 (Python 和 TypeScript)
用于响应式交互的 SSE 流式处理
1000 次 LLM 调用限制

启用 CFC 支持¶

Supported in ADKPython v0.1.0Typescript v0.2.0Experimental

PythonTypeScript

from google.genai.adk import RunConfig, StreamingMode

config = RunConfig(
    streaming_mode=StreamingMode.SSE,
    support_cfc=True,
    max_llm_calls=150
)

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
    streamingMode: StreamingMode.SSE,
    supportCfc: true,
    maxLlmCalls: 150,
};

启用组合函数调用 (CFC) 会创建一个能够根据模型输出动态执行函数的智能体，对于需要复杂工作流的应用程序非常强大。

实验性发布

组合函数调用 (CFC) 流式功能是实验性发布。