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 Agent-to-Agent (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) 中的 Agent-to-Agent (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 - 根智能体 (
root_agent): 将任务委托给专业子智能体的主要协调者 - Roll Agent (
roll_agent): A local sub-agent that handles dice rolling operations - 掷骰子智能体 (
roll_agent): 处理掷骰子操作的本地子智能体 - Prime Agent (
prime_agent): A remote A2A agent that checks if numbers are prime, this agent is running on a separate A2A server - 质数检查智能体 (
prime_agent): 检查数字是否为质数的远程 A2A 智能体,该智能体在单独的 A2A 服务器上运行
Exposing Your Agent with ADK Server¶
使用 ADK 服务器暴露您的智能体¶
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.
在 a2a_basic 示例中,您首先需要通过 A2A 服务器暴露 check_prime_agent,以便本地根智能体可以使用它。
1. Getting the Sample Code¶
1. 获取示例代码¶
First, make sure you have Go installed and your environment is set up.
首先,确保您已安装 Go 并设置了环境。
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/
│ └── main.go
├── go.mod
├── go.sum
└── main.go # local root agent
Main Agent (a2a_basic/main.go)¶
主智能体 (a2a_basic/main.go)¶
rollDieTool: Function tool for rolling dicerollDieTool: 用于掷骰子的函数工具newRollAgent: Local agent specialized in dice rollingnewRollAgent: 专长于掷骰子的本地智能体newPrimeAgent: Remote A2A agent configurationnewPrimeAgent: 远程 A2A 智能体配置newRootAgent: Main orchestrator with delegation logicnewRootAgent: 具有委派逻辑的主要协调者
Remote Prime Agent (a2a_basic/remote_a2a/check_prime_agent/main.go)¶
远程质数检查智能体 (a2a_basic/remote_a2a/check_prime_agent/main.go)¶
checkPrimeTool: Prime number checking algorithmcheckPrimeTool: 质数检查算法main: Implementation of the prime checking service and A2A server.main: 质数检查服务和 A2A 服务器的实现。
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 服务器
go run remote_a2a/check_prime_agent/main.go
Once executed, you should see something like:
执行后,您应该会看到类似以下内容:
2025/11/06 11:00:19 Starting A2A prime checker server on port 8001
2025/11/06 11:00:19 Starting the web server: &{port:8001}
2025/11/06 11:00:19
2025/11/06 11:00:19 Web servers starts on http://localhost:8001
2025/11/06 11:00:19 a2a: you can access A2A using jsonrpc protocol: http://localhost:8001
3. Look out for the required agent card of the remote agent¶
3. 注意远程智能体的必需智能体卡¶
A2A Protocol requires that each agent must have an agent card that describes what it does.
A2A 协议要求每个智能体必须有一个智能体卡来描述它的功能。
In the Go ADK, the agent card is generated dynamically when you expose an agent using the A2A launcher. You can visit http://localhost:8001/.well-known/agent-card.json to see the generated card.
在 Go ADK 中,当您使用 A2A 启动器暴露智能体时,会动态生成智能体卡。您可以访问 http://localhost:8001/.well-known/agent-card.json 来查看生成的卡。
4. Run the Main (Consuming) Agent¶
4. 运行主(消费)智能体¶
How it works¶
工作原理¶
The main agent uses remoteagent.New to consume the remote agent (prime_agent in our example). As you can see below, it requires the Name, Description, and AgentCardSource URL.
主智能体使用 remoteagent.New 来消费远程智能体(在我们的示例中是 prime_agent)。如您在下面所见,它需要 Name、Description 和 AgentCardSource URL。
func newPrimeAgent() (agent.Agent, error) {
remoteAgent, err := remoteagent.NewA2A(remoteagent.A2AConfig{
Name: "prime_agent",
Description: "Agent that handles checking if numbers are prime.",
AgentCardSource: "http://localhost:8001",
})
if err != nil {
return nil, fmt.Errorf("failed to create remote prime agent: %w", err)
}
return remoteAgent, nil
}
Then, you can simply use the remote agent in your root agent. In this case, primeAgent is used as one of the sub-agents in the root_agent below:
然后,您可以在根智能体中简单地使用远程智能体。在这种情况下,primeAgent 被用作下面 root_agent 中的子智能体之一:
func newRootAgent(ctx context.Context, rollAgent, primeAgent agent.Agent) (agent.Agent, error) {
model, err := gemini.NewModel(ctx, "gemini-2.0-flash", &genai.ClientConfig{})
if err != nil {
return nil, err
}
return llmagent.New(llmagent.Config{
Name: "root_agent",
Model: model,
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.
`,
SubAgents: []agent.Agent{rollAgent, primeAgent},
Tools: []tool.Tool{},
})
}
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, Roll Agent:
此交互使用本地智能体 Roll Agent:
User: Roll a 6-sided die
Bot calls tool: transfer_to_agent with args: map[agent_name:roll_agent]
Bot calls tool: roll_die with args: map[sides:6]
Bot: I rolled a 6-sided die and result is 6.
Prime Number Checking: 质数检查:
This interaction uses a remote agent via A2A, Prime Agent:
此交互使用通过 A2A 的远程智能体 Prime Agent:
User: Is 7 a prime number?
Bot calls tool: transfer_to_agent with args: map[agent_name:prime_agent]
Bot calls tool: prime_checking with args: map[nums:[7]]
Bot: Yes, 7 is a prime number.
Combined Operations: 组合操作:
This interaction uses both the local Roll Agent and remote Prime Agent:
此交互同时使用本地 Roll Agent 和远程 Prime Agent:
User: roll a die and check if it's a prime
Bot: Okay, I will first roll a die and then check if the result is a prime number.
Bot calls tool: transfer_to_agent with args: map[agent_name:roll_agent]
Bot calls tool: roll_die with args: map[sides:6]
Bot calls tool: transfer_to_agent with args: map[agent_name:prime_agent]
Bot calls tool: prime_checking with args: map[nums:[3]]
Bot: 3 is 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 expose your own agent.
既然您已经创建了一个通过 A2A 服务器使用远程智能体的智能体,下一步是学习如何暴露您自己的智能体。
- A2A Quickstart (Exposing): Learn how to expose your existing agent so that other agents can use it via the A2A Protocol.
- A2A 快速入门(暴露): 学习如何暴露您现有的智能体,以便其他智能体可以通过 A2A 协议使用它。