Skip to content

快速入门：通过 A2A 消费远程智能体

本快速入门涵盖了任何开发者最常见的起点："有一个远程智能体，如何让我的 ADK 智能体通过 A2A 使用它？"。这对于构建复杂的多智能体系统至关重要，其中不同的智能体需要协作和交互。

概述

本示例演示了智能体开发工具包（ADK）中的智能体到智能体（A2A）架构，展示了多个智能体如何协同工作来处理复杂任务。该示例实现了一个可以滚动骰子并检查数字是否为质数的智能体。

┌─────────────────┐    ┌──────────────────┐    ┌────────────────────┐
│   Root Agent    │───▶│   Roll Agent     │    │   Remote Prime     │
│  (Local)        │    │   (Local)        │    │   Agent            │
│                 │    │                  │    │  (localhost:8001)  │
│                 │───▶│                  │◀───│                    │
└─────────────────┘    └──────────────────┘    └────────────────────┘

A2A 基础示例包含：

  • 根智能体（root_agent）：将任务委托给专门子智能体的主协调器
  • 滚动智能体（roll_agent）：处理骰子滚动操作的本地子智能体
  • 质数智能体（prime_agent）：检查数字是否为质数的远程 A2A 智能体，此智能体在单独的 A2A 服务器上运行

使用 ADK 服务器暴露你的智能体

ADK 提供了一个内置的 CLI 命令 adk api_server --a2a 来使用 A2A 协议暴露你的智能体。

在 a2a_basic 示例中，你首先需要通过 A2A 服务器暴露 check_prime_agent，以便本地根智能体可以使用它。

1. 获取示例代码

首先，确保安装了必要的依赖项：

pip install google-adk[a2a]

你可以克隆并导航到 a2a_basic 示例：

git clone https://github.com/google/adk-python.git

正如你将看到的，文件夹结构如下：

a2a_basic/
├── remote_a2a/
│   └── check_prime_agent/
│       ├── __init__.py
│       ├── agent.json
│       └── agent.py
├── README.md
├── __init__.py
└── agent.py # 本地根智能体

主智能体（a2a_basic/agent.py）

  • roll_die(sides: int)：用于滚动骰子的函数工具
  • roll_agent：专门从事骰子滚动的本地智能体
  • prime_agent：远程 A2A 智能体配置
  • root_agent：具有委托逻辑的主协调器

远程质数智能体（a2a_basic/remote_a2a/check_prime_agent/）

  • agent.py：质数检查服务的实现
  • agent.json：A2A 智能体的智能体卡片
  • check_prime(nums: list[int])：质数检查算法

2. 启动远程质数智能体服务器

为了展示你的 ADK 智能体如何通过 A2A 消费远程智能体，你首先需要启动一个远程智能体服务器，它将托管质数智能体（在 check_prime_agent 下）。

# 启动在端口 8001 上提供 check_prime_agent 的远程 a2a 服务器
adk api_server --a2a --port 8001 contributing/samples/a2a_basic/remote_a2a
使用 --log_level debug 添加日志进行调试

要启用调试级日志记录，你可以在 adk api_server 中添加 --log_level debug，如下所示： 

adk api_server --a2a --port 8001 contributing/samples/a2a_basic/remote_a2a --log_level debug
这将为你提供更丰富的日志，以便在测试智能体时进行检查。

为什么使用端口 8001？

在本快速入门中，当在本地测试时，你的智能体将使用 localhost，因此暴露智能体（远程质数智能体）的 A2A 服务器的 port 必须与消费智能体的端口不同。你将与之交互的消费智能体的 adk web 的默认端口是 8000，这就是为什么 A2A 服务器使用单独的端口 8001 创建的原因。

执行后，你应该看到类似以下内容：

INFO:     Started server process [56558]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)

3. 查找远程智能体所需的智能体卡片（agent-card.json）

A2A 协议要求每个智能体都必须有一个描述其功能的智能体卡片。

如果其他人已经构建了你想要在你的智能体中消费的远程 A2A 智能体，那么你应该确认他们有一个智能体卡片（agent-card.json）。

在示例中，check_prime_agent 已经提供了一个智能体卡片：

a2a_basic/remote_a2a/check_prime_agent/agent-card.json
{
  "capabilities": {},
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "description": "An agent specialized in checking whether numbers are prime. It can efficiently determine the primality of individual numbers or lists of numbers.",
  "name": "check_prime_agent",
  "skills": [
    {
      "id": "prime_checking",
      "name": "Prime Number Checking",
      "description": "Check if numbers in a list are prime using efficient mathematical algorithms",
      "tags": ["mathematical", "computation", "prime", "numbers"]
    }
  ],
  "url": "http://localhost:8001/a2a/check_prime_agent",
  "version": "1.0.0"
}
关于 ADK 中智能体卡片的更多信息

在 ADK 中，你可以使用 to_a2a(root_agent) 包装器，它会自动为你生成智能体卡片。如果你有兴趣了解更多关于如何暴露现有智能体以便其他人可以使用它的信息，请查看 A2A 快速入门（暴露） 教程。

4. 运行主（消费）智能体

# 在单独的终端中，运行 adk web 服务器
adk web contributing/samples/

工作原理

主智能体使用 RemoteA2aAgent() 函数来消费远程智能体（在我们的示例中为 prime_agent）。正如你在下面看到的，RemoteA2aAgent() 需要 name、description 和 agent_card 的 URL。

a2a_basic/agent.py
<...code truncated...>

from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

prime_agent = RemoteA2aAgent(
    name="prime_agent",
    description="Agent that handles checking if numbers are prime.",
    agent_card=(
        f"http://localhost:8001/a2a/check_prime_agent{AGENT_CARD_WELL_KNOWN_PATH}"
    ),
)

<...code truncated>

然后，你可以简单地在你的智能体中使用 RemoteA2aAgent。在这种情况下，prime_agent 被用作下面 root_agent 中的子智能体之一：

a2a_basic/agent.py
from google.adk.agents.llm_agent import Agent
from google.genai import types

root_agent = Agent(
    model="gemini-2.0-flash",
    name="root_agent",
    instruction="""
      <You are a helpful assistant that can roll dice and check if numbers are prime.
      You delegate rolling dice tasks to the roll_agent and prime checking tasks to the prime_agent.
      Follow these steps:
      1. If the user asks to roll a die, delegate to the roll_agent.
      2. If the user asks to check primes, delegate to the prime_agent.
      3. If the user asks to roll a die and then check if the result is prime, call roll_agent first, then pass the result to prime_agent.
      Always clarify the results before proceeding.>
    """,
    global_instruction=(
        "You are DicePrimeBot, ready to roll dice and check prime numbers."
    ),
    sub_agents=[roll_agent, prime_agent],
    tools=[example_tool],
    generate_content_config=types.GenerateContentConfig(
        safety_settings=[
            types.SafetySetting(  # avoid false alarm about rolling dice.
                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
                threshold=types.HarmBlockThreshold.OFF,
            ),
        ]
    ),
)

示例交互

一旦你的主智能体和远程智能体都在运行，你就可以与根智能体交互，看看它如何通过 A2A 调用远程智能体：

简单骰子滚动： 此交互使用本地智能体，滚动智能体：

用户：滚动一个 6 面骰子
机器人：我为你滚动了一个 4。

质数检查：

此交互通过 A2A 使用远程智能体，质数智能体：

用户：7 是质数吗？
机器人：是的，7 是质数。

组合操作：

此交互同时使用本地滚动智能体和远程质数智能体：

用户：滚动一个 10 面骰子并检查它是否是质数
机器人：我为你滚动了一个 8。
机器人：8 不是质数。

下一步

现在你已经创建了一个通过 A2A 服务器使用远程智能体的智能体，下一步是学习如何从另一个智能体连接到它。