Skip to content

Commit 1cf5cf0

Browse files
seanzhougooglecopybara-github
seanzhougoogle
authored and
copybara-github
committed
chore: Add a basic a2a agent demo sample
PiperOrigin-RevId: 776660703
1 parent f0183a9 commit 1cf5cf0

File tree

6 files changed

+362
-0
lines changed

6 files changed

+362
-0
lines changed

‎contributing/samples/a2a_basic/README.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# A2A Basic Sample Agent
2+
3+
This sample demonstrates the **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.
4+
5+
## Overview
6+
7+
The A2A Basic sample consists of:
8+
9+
- **Root Agent** (`root_agent`): The main orchestrator that delegates tasks to specialized sub-agents
10+
- **Roll Agent** (`roll_agent`): A local sub-agent that handles dice rolling operations
11+
- **Prime Agent** (`prime_agent`): A remote A2A agent that checks if numbers are prime, this agent is running on a separate A2A server
12+
13+
## Architecture
14+
15+
```
16+
┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐
17+
│ Root Agent │───▶│ Roll Agent │ │ Remote Prime │
18+
│ (Local) │ │ (Local) │ │ Agent │
19+
│ │ │ │ │ (localhost:8001) │
20+
│ │───▶│ │◀───│ │
21+
└─────────────────┘ └──────────────────┘ └────────────────────┘
22+
```
23+
24+
## Key Features
25+
26+
### 1. **Local Sub-Agent Integration**
27+
- The `roll_agent` demonstrates how to create and integrate local sub-agents
28+
- Handles dice rolling with configurable number of sides
29+
- Uses a simple function tool (`roll_die`) for random number generation
30+
31+
### 2. **Remote A2A Agent Integration**
32+
- The `prime_agent` shows how to connect to remote agent services
33+
- Communicates with a separate service via HTTP at `http://localhost:8001/a2a/check_prime_agent`
34+
- Demonstrates cross-service agent communication
35+
36+
### 3. **Agent Orchestration**
37+
- The root agent intelligently delegates tasks based on user requests
38+
- Can chain operations (e.g., "roll a die and check if it's prime")
39+
- Provides clear workflow coordination between multiple agents
40+
41+
### 4. **Example Tool Integration**
42+
- Includes an `ExampleTool` with sample interactions for context
43+
- Helps the agent understand expected behavior patterns
44+
45+
## Setup and Usage
46+
47+
### Prerequisites
48+
49+
1. **Start the Remote Prime Agent server**:
50+
```bash
51+
# Start the remote a2a server that serves the check prime agent on port 8001
52+
adk api_server --a2a --port 8001 contributing/samples/a2a_basic/remote_a2a
53+
```
54+
55+
2. **Run the Main Agent**:
56+
```bash
57+
# In a separate terminal, run the adk web server
58+
adk web contributing/samples/
59+
```
60+
61+
### Example Interactions
62+
63+
Once both services are running, you can interact with the root agent:
64+
65+
**Simple Dice Rolling:**
66+
```
67+
User: Roll a 6-sided die
68+
Bot: I rolled a 4 for you.
69+
```
70+
71+
**Prime Number Checking:**
72+
```
73+
User: Is 7 a prime number?
74+
Bot: Yes, 7 is a prime number.
75+
```
76+
77+
**Combined Operations:**
78+
```
79+
User: Roll a 10-sided die and check if it's prime
80+
Bot: I rolled an 8 for you.
81+
Bot: 8 is not a prime number.
82+
```
83+
84+
## Code Structure
85+
86+
### Main Agent (`agent.py`)
87+
88+
- **`roll_die(sides: int)`**: Function tool for rolling dice
89+
- **`roll_agent`**: Local agent specialized in dice rolling
90+
- **`prime_agent`**: Remote A2A agent configuration
91+
- **`root_agent`**: Main orchestrator with delegation logic
92+
93+
### Remote Prime Agent (`remote_a2a/check_prime_agent/`)
94+
95+
- **`agent.py`**: Implementation of the prime checking service
96+
- **`agent.json`**: Agent card of the A2A agent
97+
- **`check_prime(nums: list[int])`**: Prime number checking algorithm
98+
99+
100+
## Extending the Sample
101+
102+
You can extend this sample by:
103+
104+
- Adding more mathematical operations (factorization, square roots, etc.)
105+
- Creating additional remote agent
106+
- Implementing more complex delegation logic
107+
- Adding persistent state management
108+
- Integrating with external APIs or databases
109+
110+
## Troubleshooting
111+
112+
**Connection Issues:**
113+
- Ensure the local ADK web server is running on port 8000
114+
- Ensure the remote A2A server is running on port 8001
115+
- Check that no firewall is blocking localhost connections
116+
- Verify the agent.json URL matches the running A2A server
117+
118+
**Agent Not Responding:**
119+
- Check the logs for both the local ADK web server on port 8000 and remote A2A server on port 8001
120+
- Verify the agent instructions are clear and unambiguous

‎contributing/samples/a2a_basic/__init__.py

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from . import agent

‎contributing/samples/a2a_basic/agent.py

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import random
16+
17+
from google.adk.agents import Agent
18+
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
19+
from google.adk.tools.example_tool import ExampleTool
20+
from google.genai import types
21+
22+
23+
# --- Roll Die Sub-Agent ---
24+
def roll_die(sides: int) -> int:
25+
"""Roll a die and return the rolled result."""
26+
return random.randint(1, sides)
27+
28+
29+
roll_agent = Agent(
30+
name="roll_agent",
31+
description="Handles rolling dice of different sizes.",
32+
instruction="""
33+
You are responsible for rolling dice based on the user's request.
34+
When asked to roll a die, you must call the roll_die tool with the number of sides as an integer.
35+
""",
36+
tools=[roll_die],
37+
generate_content_config=types.GenerateContentConfig(
38+
safety_settings=[
39+
types.SafetySetting( # avoid false alarm about rolling dice.
40+
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
41+
threshold=types.HarmBlockThreshold.OFF,
42+
),
43+
]
44+
),
45+
)
46+
47+
48+
example_tool = ExampleTool([
49+
{
50+
"input": {
51+
"role": "user",
52+
"parts": [{"text": "Roll a 6-sided die."}],
53+
},
54+
"output": [
55+
{"role": "model", "parts": [{"text": "I rolled a 4 for you."}]}
56+
],
57+
},
58+
{
59+
"input": {
60+
"role": "user",
61+
"parts": [{"text": "Is 7 a prime number?"}],
62+
},
63+
"output": [{
64+
"role": "model",
65+
"parts": [{"text": "Yes, 7 is a prime number."}],
66+
}],
67+
},
68+
{
69+
"input": {
70+
"role": "user",
71+
"parts": [{"text": "Roll a 10-sided die and check if it's prime."}],
72+
},
73+
"output": [
74+
{
75+
"role": "model",
76+
"parts": [{"text": "I rolled an 8 for you."}],
77+
},
78+
{
79+
"role": "model",
80+
"parts": [{"text": "8 is not a prime number."}],
81+
},
82+
],
83+
},
84+
])
85+
86+
prime_agent = RemoteA2aAgent(
87+
name="prime_agent",
88+
description="Agent that handles checking if numbers are prime.",
89+
agent_card=(
90+
"http://localhost:8001/a2a/check_prime_agent/.well-known/agent.json"
91+
),
92+
)
93+
94+
95+
root_agent = Agent(
96+
model="gemini-1.5-flash",
97+
name="root_agent",
98+
instruction="""
99+
You are a helpful assistant that can roll dice and check if numbers are prime.
100+
You delegate rolling dice tasks to the roll_agent and prime checking tasks to the prime_agent.
101+
Follow these steps:
102+
1. If the user asks to roll a die, delegate to the roll_agent.
103+
2. If the user asks to check primes, delegate to the prime_agent.
104+
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.
105+
Always clarify the results before proceeding.
106+
""",
107+
global_instruction=(
108+
"You are DicePrimeBot, ready to roll dice and check prime numbers."
109+
),
110+
sub_agents=[roll_agent, prime_agent],
111+
tools=[example_tool],
112+
generate_content_config=types.GenerateContentConfig(
113+
safety_settings=[
114+
types.SafetySetting( # avoid false alarm about rolling dice.
115+
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
116+
threshold=types.HarmBlockThreshold.OFF,
117+
),
118+
]
119+
),
120+
)

‎contributing/samples/a2a_basic/remote_a2a/check_prime_agent/__init__.py

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from . import agent

‎contributing/samples/a2a_basic/remote_a2a/check_prime_agent/agent.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"capabilities": {},
3+
"defaultInputModes": ["text/plain"],
4+
"defaultOutputModes": ["application/json"],
5+
"description": "An agent specialized in checking whether numbers are prime. It can efficiently determine the primality of individual numbers or lists of numbers.",
6+
"name": "check_prime_agent",
7+
"skills": [
8+
{
9+
"id": "prime_checking",
10+
"name": "Prime Number Checking",
11+
"description": "Check if numbers in a list are prime using efficient mathematical algorithms",
12+
"tags": ["mathematical", "computation", "prime", "numbers"]
13+
}
14+
],
15+
"url": "http://localhost:8001/a2a/check_prime_agent",
16+
"version": "1.0.0"
17+
}

‎contributing/samples/a2a_basic/remote_a2a/check_prime_agent/agent.py

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import random
16+
17+
from google.adk import Agent
18+
from google.adk.tools.tool_context import ToolContext
19+
from google.genai import types
20+
21+
22+
async def check_prime(nums: list[int]) -> str:
23+
"""Check if a given list of numbers are prime.
24+
25+
Args:
26+
nums: The list of numbers to check.
27+
28+
Returns:
29+
A str indicating which number is prime.
30+
"""
31+
primes = set()
32+
for number in nums:
33+
number = int(number)
34+
if number <= 1:
35+
continue
36+
is_prime = True
37+
for i in range(2, int(number**0.5) + 1):
38+
if number % i == 0:
39+
is_prime = False
40+
break
41+
if is_prime:
42+
primes.add(number)
43+
return (
44+
'No prime numbers found.'
45+
if not primes
46+
else f"{', '.join(str(num) for num in primes)} are prime numbers."
47+
)
48+
49+
50+
root_agent = Agent(
51+
model='gemini-2.0-flash',
52+
name='check_prime_agent',
53+
description='check prime agent that can check whether numbers are prime.',
54+
instruction="""
55+
You check whether numbers are prime.
56+
When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
57+
You should not rely on the previous history on prime results.
58+
""",
59+
tools=[
60+
check_prime,
61+
],
62+
# planner=BuiltInPlanner(
63+
# thinking_config=types.ThinkingConfig(
64+
# include_thoughts=True,
65+
# ),
66+
# ),
67+
generate_content_config=types.GenerateContentConfig(
68+
safety_settings=[
69+
types.SafetySetting( # avoid false alarm about rolling dice.
70+
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
71+
threshold=types.HarmBlockThreshold.OFF,
72+
),
73+
]
74+
),
75+
)

0 commit comments

Comments
 (0)