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

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

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

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

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

实验性功能

智能体配置功能是实验性的，有一些[已知限制](#known-limitations)。我们欢迎你的[反馈](https://github.com/google/adk-python/issues/new?template=feature_request.md&labels=agent%20config)！

## 开始使用

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

### 设置

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

注意

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

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

1. 按照[安装](https://adk.wiki/get-started/installation/#python)说明安装 ADK Python 库。*目前需要 Python。* 更多信息请参阅[已知限制](#known-limitations)。

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

   ```text
   adk --version
   ```

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

提示

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

### 构建智能体

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

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

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

   ```text
   adk create --type=config my_agent
   ```

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

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

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

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

      你可以从 Google AI Studio [API 密钥](https://aistudio.google.com/app/apikey)页面获取 API 密钥。

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

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

      有关创建 Cloud 项目的信息，请参阅 Google Cloud 文档中的[创建和管理项目](https://cloud.google.com/resource-manager/docs/creating-managing-projects)。

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

```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 [示例仓库](https://github.com/search?q=repo%3Agoogle%2Fadk-python+path%3A%2F%5Econtributing%5C%2Fsamples%5C%2F%2F+.yaml&type=code)或[智能体配置语法](/api-reference/agentconfig/)参考来发现 `root_agent.yaml` 智能体配置文件的更多配置选项。

### 运行智能体

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

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

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

有关运行智能体方式的更多信息，请参阅[快速开始](https://adk.wiki/agents/get-started/quickstart.md#run-your-agent)中的*运行你的智能体*主题。有关 ADK 命令行选项的更多信息，请参阅[ADK CLI 参考](/api-reference/cli/)。

### 以编程方式运行

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

```python
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())
```

```java
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 [示例仓库](https://github.com/search?q=repo%3Agoogle%2Fadk-python+path%3A%2F%5Econtributing%5C%2Fsamples%5C%2F%2F+root_agent.yaml&type=code)。

### 内置工具示例

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

```yaml
# 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 示例仓库](https://github.com/google/adk-python/blob/main/contributing/samples/tool_builtin_config/root_agent.yaml)中此示例的完整代码。

### 自定义工具示例

以下示例使用用 Python 代码构建的自定义工具，并在配置文件的 `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: prime_agent
description: 处理质数检查任务。
instruction: |
  你负责检查数字是否为质数。
  当被要求检查质数时，你必须调用 check_prime 工具并传入一个整数列表。
  永远不要尝试手动确定质数。
  将质数结果返回给根智能体。
tools:
  - name: ma_llm.check_prime
```

更多详细信息，请参阅 [ADK 示例仓库](https://github.com/google/adk-python/blob/main/contributing/samples/multi_agent_llm_config/prime_agent.yaml)中此示例的完整代码。

### 子智能体示例

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

```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 示例仓库](https://github.com/google/adk-python/blob/main/contributing/samples/multi_agent_basic_config/root_agent.yaml)中此示例的完整代码。

## 部署智能体配置

你可以使用 [Cloud Run](https://adk.wiki/deploy/cloud-run/index.md) 和 [Agent Engine](https://adk.wiki/deploy/agent-engine/index.md) 部署智能体配置智能体，使用与基于代码的智能体相同的程序。有关如何准备和部署基于智能体配置的智能体的更多信息，请参阅 [Cloud Run](https://adk.wiki/deploy/cloud-run/index.md) 和 [Agent Engine](https://adk.wiki/deploy/agent-engine/index.md) 部署指南。

## 已知限制

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

- **模型支持**：目前仅支持 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](https://github.com/search?q=repo:google/adk-python+path:/%5Econtributing%5C/samples%5C//+root_agent.yaml&type=code) 仓库中基于 YAML 的智能体定义。有关智能体配置格式支持的语法和设置的详细信息，请参阅[智能体配置语法参考](/api-reference/agentconfig/)。