Skip to content

快速入门：通过 A2A 暴露远程智能体

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

概述

本示例演示了如何轻松暴露 ADK 智能体，以便其他智能体可以使用 A2A 协议来消费它。

通过 A2A 暴露 ADK 智能体有两种主要方式。

  • 通过使用 to_a2a(root_agent) 函数：如果你只想将现有智能体转换为与 A2A 兼容，并能够通过 uvicorn 服务器暴露它，而不是 adk deploy api_server，请使用此函数。这意味着当你想要生产化你的智能体时，你可以对通过 uvicorn 暴露的内容进行更严格的控制。此外，to_a2a() 函数会根据你的智能体代码自动生成智能体卡片。
  • 通过创建你自己的智能体卡片（agent.json）并使用 adk api_server --a2a 托管它：使用这种方法有两个主要好处。首先，adk api_server --a2a 与 adk web 配合工作，使你可以轻松使用、调试和测试你的智能体。其次，使用 adk api_server，你可以指定包含多个独立智能体的父文件夹。那些有智能体卡片（agent.json）的智能体将通过同一服务器自动可供其他智能体通过 A2A 使用。但是，你需要创建自己的智能体卡片。要创建智能体卡片，你可以按照 A2A Python 教程 进行操作。

本快速入门将专注于 to_a2a()，因为这是暴露你的智能体的最简单方法，并且还会在后台自动生成智能体卡片。如果你想使用 adk api_server 方法，你可以在 A2A 快速入门（消费）文档 中看到它的使用。

之前：
                                                ┌────────────────────┐
                                                │ Hello World Agent  │
                                                │  (Python Object)   │
                                                | without agent card │
                                                └────────────────────┘

                                                          │
                                                          │ to_a2a()
                                                          ▼

之后：
┌────────────────┐                             ┌───────────────────────────────┐
│   Root Agent   │       A2A Protocol          │ A2A-Exposed Hello World Agent │
│(RemoteA2aAgent)│────────────────────────────▶│      (localhost: 8001)         │
│(localhost:8000)│                             └───────────────────────────────┘
└────────────────┘

示例包含：

  • 远程 Hello World 智能体（remote_a2a/hello_world/agent.py）：这是你想要暴露的智能体，以便其他智能体可以通过 A2A 使用它。它是一个处理骰子滚动和质数检查的智能体。它使用 to_a2a() 函数暴露，并通过 uvicorn 提供服务。
  • 根智能体（agent.py）：一个简单的智能体，只是调用远程 Hello World 智能体。

使用 to_a2a(root_agent) 函数暴露远程智能体

你可以使用 to_a2a() 函数简单地包装使用 ADK 构建的现有智能体，使其与 A2A 兼容。例如，如果你有一个在 root_agent 中定义的智能体，如下所示：

# 你的智能体代码在这里
root_agent = Agent(
    model='gemini-2.0-flash',
    name='hello_world_agent',

    <...你的智能体代码...>
)

然后你可以简单地使用 to_a2a(root_agent) 使其与 A2A 兼容：

from google.adk.a2a.utils.agent_to_a2a import to_a2a

# 使你的智能体与 A2A 兼容
a2a_app = to_a2a(root_agent, port=8001)

to_a2a() 函数甚至会在后台通过 从 ADK 智能体中提取技能、能力和元数据 在内存中自动生成智能体卡片，这样当使用 uvicorn 提供智能体端点时，众所周知的智能体卡片就可用。

你也可以通过使用 agent_card 参数提供你自己的智能体卡片。该值可以是 AgentCard 对象或智能体卡片 JSON 文件的路径。

使用 AgentCard 对象的示例： 

from google.adk.a2a.utils.agent_to_a2a import to_a2a
from a2a.types import AgentCard

# Define A2A agent card
my_agent_card = AgentCard(
    "name": "file_agent",
    "url": "http://example.com",
    "description": "Test agent from file",
    "version": "1.0.0",
    "capabilities": {},
    "skills": [],
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain"],
    "supportsAuthenticatedExtendedCard": False,
)
a2a_app = to_a2a(root_agent, port=8001, agent_card=my_agent_card)

使用 JSON 文件路径的示例： 

from google.adk.a2a.utils.agent_to_a2a import to_a2a

# Load A2A agent card from a file
a2a_app = to_a2a(root_agent, port=8001, agent_card="/path/to/your/agent-card.json")

现在让我们深入示例代码。

1. 获取示例代码

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

pip install google-adk[a2a]

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

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

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

a2a_root/
├── remote_a2a/
│   └── hello_world/    
│       ├── __init__.py
│       └── agent.py    # 远程 Hello World 智能体
├── README.md
└── agent.py            # 根智能体

根智能体（a2a_root/agent.py）

  • root_agent：连接到远程 A2A 服务的 RemoteA2aAgent
  • 智能体卡片 URL：指向远程服务器上众所周知的智能体卡片端点

远程 Hello World 智能体（a2a_root/remote_a2a/hello_world/agent.py）

  • roll_die(sides: int)：用于滚动骰子的函数工具，具有状态管理
  • check_prime(nums: list[int])：用于质数检查的异步函数
  • root_agent：具有全面指令的主智能体
  • a2a_app：使用 to_a2a() 工具创建的 A2A 应用程序

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

你现在可以启动远程智能体服务器，它将在 hello_world 智能体内托管 a2a_app：

# 确保当前工作目录是 adk-python/
# 使用 uvicorn 启动远程智能体
uvicorn contributing.samples.a2a_root.remote_a2a.hello_world.agent:a2a_app --host localhost --port 8001

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

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

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

3. 检查你的远程智能体是否正在运行

你可以通过访问在 a2a_root/remote_a2a/hello_world/agent.py 中作为 to_a2a() 函数的一部分自动生成的智能体卡片来检查你的智能体是否正在运行：

http://localhost:8001/.well-known/agent-card.json

你应该看到智能体卡片的内容，它应该看起来像：

{"capabilities":{},"defaultInputModes":["text/plain"],"defaultOutputModes":["text/plain"],"description":"hello world agent that can roll a dice of 8 sides and check prime numbers.","name":"hello_world_agent","protocolVersion":"0.2.6","skills":[{"description":"hello world agent that can roll a dice of 8 sides and check prime numbers. \n      I roll dice and answer questions about the outcome of the dice rolls.\n      I can roll dice of different sizes.\n      I can use multiple tools in parallel by calling functions in parallel(in one request and in one round).\n      It is ok to discuss previous dice roles, and comment on the dice rolls.\n      When I are asked to roll a die, I must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.\n      I should never roll a die on my own.\n      When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. I should never pass in a string.\n      I should not check prime numbers before calling the tool.\n      When I are asked to roll a die and check prime numbers, I should always make the following two function calls:\n      1. I should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.\n      2. After I get the function response from roll_die tool, I should call the check_prime tool with the roll_die result.\n        2.1 If user asks I to check primes based on previous rolls, make sure I include the previous rolls in the list.\n      3. When I respond, I must include the roll_die result from step 1.\n      I should always perform the previous 3 steps when asking for a roll and checking prime numbers.\n      I should not rely on the previous history on prime results.\n    ","id":"hello_world_agent","name":"model","tags":["llm"]},{"description":"Roll a die and return the rolled result.\n\nArgs:\n  sides: The integer number of sides the die has.\n  tool_context: the tool context\nReturns:\n  An integer of the result of rolling the die.","id":"hello_world_agent-roll_die","name":"roll_die","tags":["llm","tools"]},{"description":"Check if a given list of numbers are prime.\n\nArgs:\n  nums: The list of numbers to check.\n\nReturns:\n  A str indicating which number is prime.","id":"hello_world_agent-check_prime","name":"check_prime","tags":["llm","tools"]}],"supportsAuthenticatedExtendedCard":false,"url":"http://localhost:8001","version":"0.0.1"}

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

现在你的远程智能体正在运行，你可以启动开发 UI 并选择 "a2a_root" 作为你的智能体。

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

要打开 adk web 服务器，请访问：http://localhost:8000。

示例交互

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

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

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

质数检查：

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

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

组合操作：

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

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

下一步

现在你已经创建了一个通过 A2A 服务器暴露远程智能体的智能体，下一步是学习如何从另一个智能体消费它。