Build agents with Agent Config¶

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

Supported in ADKPython v1.11.0Experimental

The ADK Agent Config feature lets you build an ADK workflow without writing code. An Agent Config uses a YAML format text file with a brief description of the agent, allowing just about anyone to assemble and run an ADK agent. The following is a simple example of an basic Agent Config definition:

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.

You can use Agent Config files to build more complex agents which can incorporate Functions, Tools, Sub-Agents, and more. This page describes how to build and run ADK workflows with the Agent Config feature. For detailed information on the syntax and settings supported by the Agent Config format, see the Agent Config syntax reference.

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

Experimental

The Agent Config feature is experimental and has some known limitations. We welcome your feedback!

实验性

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

Get started¶

入门¶

This section describes how to set up and start building agents with the ADK and the Agent Config feature, including installation setup, building an agent, and running your agent.

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

Setup¶

设置¶

You need to install the Google Agent Development Kit libraries, and provide an access key for a generative AI model such as Gemini API. This section provides details on what you must install and configure before you can run agents with the Agent Config files.

您需要安装 Google Agent Development Kit 库，并为生成式 AI 模型（如 Gemini API）提供访问密钥。本部分提供了在使用智能体配置文件运行智能体之前必须安装和配置的详细信息。

Setup¶

设置¶

You need to install the Google Agent Development Kit libraries, and provide an access key for a generative AI model such as Gemini API. This section provides details on what you must install and configure before you can run agents with the Agent Config files.

您需要安装 Google Agent Development Kit 库，并为生成式 AI 模型（如 Gemini API）提供访问密钥。本部分提供了在使用智能体配置文件运行智能体之前必须安装和配置的详细信息。

Note

The Agent Config feature currently only supports Gemini models. For more information about additional; functional restrictions, see Known limitations.

Note

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

To setup ADK for use with Agent Config:

要设置 ADK 以便与智能体配置一起使用：

Install the ADK Python libraries by following the Installation instructions. Python is currently required. For more information, see the Known limitations.
Verify that ADK is installed by running the following command in your terminal:
```
adk --version
```
This command should show the ADK version you have installed.
按照安装说明安装 ADK Python 库。目前需要 Python。 有关更多信息，请参阅已知限制。
通过在终端中运行以下命令来验证 ADK 是否已安装:
```
adk --version
```
此命令应显示您安装的 ADK 版本。

Tip

If the adk command fails to run and the version is not listed in step 2, make sure your Python environment is active. Execute source .venv/bin/activate in your terminal on Mac and Linux. For other platform commands, see the Installation

提示

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

Build an agent¶

构建智能体¶

You build an agent with Agent Config using the adk create command to create the project files for an agent, and then editing the root_agent.yaml file it generates for you.

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

To create an ADK project for use with Agent Config:

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

In your terminal window, run the following command to create a config-based agent:
```
adk create --type=config my_agent
```
This command generates a my_agent/ folder, containing a root_agent.yaml file and an .env file.
In the my_agent/.env file, set environment variables for your agent to access generative AI models and other services:
1. For Gemini model access through Google API, add a line to the file with your API key:
```
GOOGLE_GENAI_USE_VERTEXAI=0
GOOGLE_API_KEY=<your-Google-Gemini-API-key>
```
  You can get an API key from the Google AI Studio API Keys page.
2. For Gemini model access through Google Cloud, add these lines to the file:
```
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<your_gcp_project>
GOOGLE_CLOUD_LOCATION=us-central1
```
  For information on creating a Cloud Project, see the Google Cloud docs for Creating and managing projects.
Using text editor, edit the Agent Config file my_agent/root_agent.yaml, as shown below:

# 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.

You can discover more configuration options for your root_agent.yaml agent configuration file by referring to the ADK samples repository or the Agent Config syntax reference.

Run the agent¶

运行智能体¶

Once you have completed editing your Agent Config, you can run your agent using the web interface, command line terminal execution, or API server mode.

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

To run your Agent Config-defined agent:

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

In your terminal, navigate to the my_agent/ directory containing the root_agent.yaml file.
Type one of the following commands to run your agent:
- adk web - Run web UI interface for your agent.
- adk run - Run your agent in the terminal without a user interface.
- adk api_server - Run your agent as a service that can be used by other applications.

For more information on the ways to run your agent, see the Run Your Agent topic in the Quickstart. For more information about the ADK command line options, see the ADK CLI reference.

Example configs¶

示例配置¶

This section shows examples of Agent Config files to get you started building agents. For additional and more complete examples, see the ADK samples repository.

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

Built-in tool example¶

The following example uses a built-in ADK tool function for using google search to provide functionality to the agent. This agent automatically uses the search tool to reply to user requests.

# 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

For more details, see the full code for this sample in the ADK sample repository.

Custom tool example¶

The following example uses a custom tool built with Python code and listed in the tools: section of the config file. The agent uses this tool to check if a list of numbers provided by the user are prime numbers.

# 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

For more details, see the full code for this sample in the ADK sample repository.

Sub-agents example¶

The following example shows an agent defined with two sub-agents in the sub_agents: section, and an example tool in the tools: section of the config file. This agent determines what the user wants, and delegates to one of the sub-agents to resolve the request. The sub-agents are defined using Agent Config YAML files.

# 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

For more details, see the full code for this sample in the ADK sample repository.

Deploy agent configs¶

部署智能体配置¶

You can deploy Agent Config agents with Cloud Run and Agent Engine, using the same procedure as code-based agents. For more information on how to prepare and deploy Agent Config-based agents, see the Cloud Run and Agent Engine deployment guides.

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

Known limitations¶

已知限制¶

The Agent Config feature is experimental and includes the following limitations:

Model support: Only Gemini models are currently supported. Integration with third-party models is in progress.
Programming language: The Agent Config feature currently supports only Python code for tools and other functionality requiring programming code.
ADK Tool support: The following ADK tools are supported by the Agent Config feature, but not all tools are fully supported:
- google_search
- load_artifacts
- url_context
- exit_loop
- preload_memory
- get_user_choice
- enterprise_web_search
- load_web_page: Requires a fully-qualified path to access web pages.
Agent Type Support: The LangGraphAgent and A2aAgent types are not yet supported.
- AgentTool
- LongRunningFunctionTool
- VertexAiSearchTool
- McpToolset
- ExampleTool

Next steps¶

下一步¶

For ideas on how and what to build with ADK Agent Configs, see the yaml-based agent definitions in the ADK adk-samples repository. For detailed information on the syntax and settings supported by the Agent Config format, see the Agent Config syntax reference.

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