Quickstart: Consuming a remote agent via A2A¶
快速入门：通过 A2A 消费远程智能体¶
This quickstart covers the most common starting point for any developer: "There is a remote agent, how do I let my ADK agent use it via A2A?". This is crucial for building complex multi-agent systems where different agents need to collaborate and interact.
本快速入门涵盖了任何开发者最常见的起点："有一个远程智能体，我如何让我的 ADK 智能体通过 A2A 使用它？"。这对于构建需要不同智能体协作和交互的复杂多智能体系统至关重要。
Overview¶
概述¶
This sample demonstrates the Agent2Agent (A2A) architecture in the Agent Development Kit (ADK), showcasing how multiple agents can work together to handle complex tasks. The sample implements an agent that can roll dice and check if numbers are prime.
此示例演示了 Agent Development Kit (ADK) 中的 Agent2Agent (A2A) 架构，展示了多个智能体如何协同工作以处理复杂任务。该示例实现了一个可以掷骰子并检查数字是否为质数的智能体。
┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐
│ Root Agent │───▶│ Roll Agent │ │ Remote Prime │
│ (Local) │ │ (Local) │ │ Agent │
│ │ │ │ │ (localhost:8001) │
│ │───▶│ │◀───│ │
└─────────────────┘ └──────────────────┘ └────────────────────┘
The A2A Basic sample consists of:
A2A 基本示例由以下部分组成：
- Root Agent (
root_agent): The main orchestrator that delegates tasks to specialized sub-agents - Roll Agent (
roll_agent): A local sub-agent that handles dice rolling operations -
Prime Agent (
prime_agent): A remote A2A agent that checks if numbers are prime, this agent is running on a separate A2A server -
根智能体 (
root_agent)：将任务委托给专业子智能体的主要协调者 - 掷骰子智能体 (
roll_agent)：处理掷骰子操作的本地子智能体 - 质数检查智能体 (
prime_agent)：检查数字是否为质数的远程 A2A 智能体，该智能体在单独的 A2A 服务器上运行
Exposing Your Agent with the ADK Server¶
使用 ADK 服务器暴露您的智能体¶
The ADK comes with a built-in CLI command, adk api_server --a2a to expose your agent using the A2A protocol.
In the a2a_basic example, you will first need to expose the check_prime_agent via an A2A server, so that the local root agent can use it.
ADK 附带一个内置的 CLI 命令 adk api_server --a2a，用于使用 A2A 协议暴露您的智能体。
在 a2a_basic 示例中，您首先需要通过 A2A 服务器暴露 check_prime_agent，以便本地根智能体可以使用它。
1. Getting the Sample Code¶
1. 获取示例代码¶
First, make sure you have the necessary dependencies installed:
首先，确保您已安装必要的依赖项：
You can clone and navigate to the a2a_basic sample here:
您可以克隆并导航到这里的 a2a_basic 示例：
As you'll see, the folder structure is as follows:
如您所见，文件夹结构如下：
a2a_basic/
├── remote_a2a/
│ └── check_prime_agent/
│ ├── __init__.py
│ ├── agent.json
│ └── agent.py
├── README.md
├── __init__.py
└── agent.py # local root agent
Main Agent (a2a_basic/agent.py)¶
主智能体 (a2a_basic/agent.py)¶
roll_die(sides: int): Function tool for rolling diceroll_agent: Local agent specialized in dice rollingprime_agent: Remote A2A agent configuration-
root_agent: Main orchestrator with delegation logic -
roll_die(sides: int)：用于掷骰子的函数工具 roll_agent：专用于掷骰子的本地智能体prime_agent：远程 A2A 智能体配置root_agent：具有委托逻辑的主要协调者
Remote Prime Agent (a2a_basic/remote_a2a/check_prime_agent/)¶
远程质数检查智能体 (a2a_basic/remote_a2a/check_prime_agent/)¶
agent.py: Implementation of the prime checking serviceagent.json: Agent card of the A2A agent-
check_prime(nums: list[int]): Prime number checking algorithm -
agent.py：质数检查服务的实现 agent.json：A2A 智能体的智能体卡check_prime(nums: list[int])：质数检查算法
2. Start the Remote Prime Agent server¶
2. 启动远程质数检查智能体服务器¶
To show how your ADK agent can consume a remote agent via A2A, you'll first need to start a remote agent server, which will host the prime agent (under check_prime_agent).
为了展示您的 ADK 智能体如何通过 A2A 消费远程智能体，您首先需要启动一个远程智能体服务器，该服务器将托管质数检查智能体（在 check_prime_agent 下）。
# Start the remote a2a server that serves the check_prime_agent on port 8001
# 启动在端口 8001 上为 check_prime_agent 服务的远程 a2a 服务器
adk api_server --a2a --port 8001 contributing/samples/a2a_basic/remote_a2a
Adding logging for debugging with --log_level debug
To enable debug-level logging, you can add --log_level debug to your adk api_server, as in:
使用 --log_level debug 添加调试日志
要启用调试级别的日志记录，您可以在 adk api_server 中添加 --log_level debug，如下所示：
Why use port 8001?
In this quickstart, when testing locally, your agents will be using localhost, so the port for the A2A server for the exposed agent (the remote, prime agent) must be different from the consuming agent's port. The default port for adk web where you will interact with the consuming agent is 8000, which is why the A2A server is created using a separate port, 8001.
为什么使用端口 8001？
在本快速入门中，当在本地测试时，您的智能体将使用 localhost，因此暴露的智能体（远程质数检查智能体）的 A2A 服务器的 port 必须与消费智能体的端口不同。您将与消费智能体交互的 adk web 的默认端口是 8000，这就是为什么 A2A 服务器使用单独的端口 8001 创建的原因。
Once executed, you should see something like:
执行后，您应该看到类似以下内容：
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. Look out for the required agent card (agent-card.json) of the remote agent¶
3. 注意远程智能体所需的智能体卡 (agent-card.json)¶
A2A Protocol requires that each agent must have an agent card that describes what it does.
A2A 协议要求每个智能体都必须有一个智能体卡来描述它的作用。
If someone else has already built the remote A2A agent that you are looking to consume in your agent, then you should confirm that they have an agent card (agent-card.json).
如果其他人已经构建了您希望在自己的智能体中消费的远程 A2A 智能体，那么您应该确认他们有一个智能体卡 (agent-card.json)。
In the sample, the check_prime_agent already has an agent card provided:
在该示例中，check_prime_agent 已经提供了一个智能体卡：
{
"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"
}
More info on agent cards in ADK
In ADK, you can use a to_a2a(root_agent) wrapper which automatically generates an agent card for you. If you're interested in learning more about how to expose your existing agent so others can use it, then please look at the A2A Quickstart (Exposing) tutorial.
有关 ADK 中智能体卡的更多信息
在 ADK 中，您可以使用 to_a2a(root_agent) 包装器，它会自动为您生成智能体卡。如果您有兴趣了解更多关于如何暴露现有智能体以便其他人可以使用它的信息，请查看 A2A 快速入门（暴露） 教程。
4. Run the Main (Consuming) Agent¶
4. 运行主（消费）智能体¶
# In a separate terminal, run the adk web server
# 在单独的终端中，运行 adk web 服务器
adk web contributing/samples/
How it works¶
工作原理¶
The main agent uses the RemoteA2aAgent() function to consume the remote agent (prime_agent in our example). As you can see below, RemoteA2aAgent() requires the name, description, and the URL of the agent_card.
主智能体使用 RemoteA2aAgent() 函数来消费远程智能体（在我们的示例中是 prime_agent）。正如您在下面看到的，RemoteA2aAgent() 需要 name、description 和 agent_card 的 URL。
<...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>
Then, you can simply use the RemoteA2aAgent in your agent. In this case, prime_agent is used as one of the sub-agents in the root_agent below:
然后，您可以简单地在您的智能体中使用 RemoteA2aAgent。在这种情况下，prime_agent 用作下面的 root_agent 的子智能体之一：
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,
),
]
),
)
Example Interactions¶
示例交互¶
Once both your main and remote agents are running, you can interact with the root agent to see how it calls the remote agent via A2A:
一旦您的主智能体和远程智能体都运行起来了，您可以与根智能体交互，看看它如何通过 A2A 调用远程智能体：
Simple Dice Rolling: This interaction uses a local agent, the Roll Agent:
简单的掷骰子： 此交互使用本地智能体，即掷骰子智能体：
Prime Number Checking:
This interaction uses a remote agent via A2A, the Prime Agent:
质数检查：
此交互通过 A2A 使用远程智能体，即质数检查智能体：
Combined Operations:
This interaction uses both the local Roll Agent and the remote Prime Agent:
组合操作：
此交互使用本地掷骰子智能体和远程质数检查智能体：
User: Roll a 10-sided die and check if it's prime
Bot: I rolled an 8 for you.
Bot: 8 is not a prime number.
Next Steps¶
Now that you have created an agent that's using a remote agent via an A2A server, the next step is to learn how to connect to it from another agent.
- A2A Quickstart (Exposing): Learn how to expose your existing agent so that other agents can use it via the A2A Protocol.
下一步¶
现在您已经创建了一个通过 A2A 服务器使用远程智能体的智能体，下一步是学习如何从另一个智能体连接到它。
- A2A 快速入门（暴露）：学习如何暴露您的现有智能体，以便其他智能体可以通过 A2A 协议使用它。