Skip to content

Commit 68d7048

Browse files
seanzhougooglecopybara-github
seanzhougoogle
authored and
copybara-github
committed
chore: Add sample agent for interaction api integration
Co-authored-by: Xiang (Sean) Zhou <[email protected]> PiperOrigin-RevId: 843037705
1 parent c6320ca commit 68d7048

File tree

4 files changed

+695
-0
lines changed

4 files changed

+695
-0
lines changed

‎contributing/samples/interactions_api/README.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Interactions API Sample Agent
2+
3+
This sample agent demonstrates the Interactions API integration in ADK. The
4+
Interactions API provides stateful conversation capabilities, allowing chained
5+
interactions using `previous_interaction_id` instead of sending full
6+
conversation history.
7+
8+
## Features Tested
9+
10+
1. **Basic Text Generation** - Simple conversation without tools
11+
2. **Google Search Tool** - Web search using `GoogleSearchTool` with
12+
`bypass_multi_tools_limit=True`
13+
3. **Multi-Turn Conversations** - Stateful interactions with context retention
14+
via `previous_interaction_id`
15+
4. **Custom Function Tool** - Weather lookup using `get_current_weather`
16+
17+
## Important: Tool Compatibility
18+
19+
The Interactions API does **NOT** support mixing custom function calling tools
20+
with built-in tools (like `google_search`) in the same agent. To work around
21+
this limitation:
22+
23+
```python
24+
# Use bypass_multi_tools_limit=True to convert google_search to a function tool
25+
GoogleSearchTool(bypass_multi_tools_limit=True)
26+
```
27+
28+
This converts the built-in `google_search` to a function calling tool (via
29+
`GoogleSearchAgentTool`), which allows it to work alongside custom function
30+
tools.
31+
32+
## How to Run
33+
34+
### Prerequisites
35+
36+
```bash
37+
# From the adk-python root directory
38+
uv sync --all-extras
39+
source .venv/bin/activate
40+
41+
# Set up authentication (choose one):
42+
# Option 1: Using Google Cloud credentials
43+
export GOOGLE_CLOUD_PROJECT=your-project-id
44+
45+
# Option 2: Using API Key
46+
export GOOGLE_API_KEY=your-api-key
47+
```
48+
49+
### Running Tests
50+
51+
```bash
52+
cd contributing/samples
53+
54+
# Run automated tests with Interactions API
55+
python -m interactions_api.main
56+
```
57+
58+
## Key Differences: Interactions API vs Standard API
59+
60+
### Interactions API (`use_interactions_api=True`)
61+
- Uses stateful interactions via `previous_interaction_id`
62+
- Only sends current turn contents when chaining interactions
63+
- Returns `interaction_id` in responses for chaining
64+
- Ideal for long conversations with many turns
65+
- Context caching is not used (state maintained via interaction chaining)
66+
67+
### Standard API (`use_interactions_api=False`)
68+
- Uses stateless `generate_content` calls
69+
- Sends full conversation history with each request
70+
- No interaction IDs in responses
71+
- Context caching can be used
72+
73+
## Code Structure
74+
75+
```
76+
interactions_api/
77+
├── __init__.py # Package initialization
78+
├── agent.py # Agent definition with Interactions API
79+
├── main.py # Test runner
80+
├── test_interactions_curl.sh # cURL-based API tests
81+
├── test_interactions_direct.py # Direct API tests
82+
└── README.md # This file
83+
```
84+
85+
## Agent Configuration
86+
87+
```python
88+
from google.adk.agents.llm_agent import Agent
89+
from google.adk.models.google_llm import Gemini
90+
from google.adk.tools.google_search_tool import GoogleSearchTool
91+
92+
root_agent = Agent(
93+
model=Gemini(
94+
model="gemini-2.5-flash",
95+
use_interactions_api=True, # Enable Interactions API
96+
),
97+
name="interactions_test_agent",
98+
tools=[
99+
GoogleSearchTool(bypass_multi_tools_limit=True), # Converted to function tool
100+
get_current_weather, # Custom function tool
101+
],
102+
)
103+
```
104+
105+
## Example Output
106+
107+
```
108+
============================================================
109+
TEST 1: Basic Text Generation
110+
============================================================
111+
112+
>> User: Hello! What can you help me with?
113+
<< Agent: Hello! I can help you with: 1) Search the web...
114+
[Interaction ID: v1_abc123...]
115+
PASSED: Basic text generation works
116+
117+
============================================================
118+
TEST 2: Function Calling (Google Search Tool)
119+
============================================================
120+
121+
>> User: Search for the capital of France.
122+
[Tool Call] google_search_agent({'request': 'capital of France'})
123+
[Tool Result] google_search_agent: {'result': 'The capital of France is Paris...'}
124+
<< Agent: The capital of France is Paris.
125+
[Interaction ID: v1_def456...]
126+
PASSED: Google search tool works
127+
128+
============================================================
129+
TEST 3: Multi-Turn Conversation (Stateful)
130+
============================================================
131+
132+
>> User: Remember the number 42.
133+
<< Agent: I'll remember that number - 42.
134+
[Interaction ID: v1_ghi789...]
135+
136+
>> User: What number did I ask you to remember?
137+
<< Agent: You asked me to remember the number 42.
138+
[Interaction ID: v1_jkl012...]
139+
PASSED: Multi-turn conversation works with context retention
140+
141+
============================================================
142+
TEST 5: Custom Function Tool (get_current_weather)
143+
============================================================
144+
145+
>> User: What's the weather like in Tokyo?
146+
[Tool Call] get_current_weather({'city': 'Tokyo'})
147+
[Tool Result] get_current_weather: {'city': 'Tokyo', 'temperature_f': 68, ...}
148+
<< Agent: The weather in Tokyo is 68F and Partly Cloudy.
149+
[Interaction ID: v1_mno345...]
150+
PASSED: Custom function tool works with bypass_multi_tools_limit
151+
152+
ALL TESTS PASSED (Interactions API)
153+
```

‎contributing/samples/interactions_api/__init__.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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+
"""Sample agent for testing the Interactions API integration."""
16+
17+
from . import agent

‎contributing/samples/interactions_api/agent.py‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
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+
"""Agent definition for testing the Interactions API integration.
16+
17+
NOTE: The Interactions API does NOT support mixing custom function calling tools
18+
with built-in tools in the same agent. To work around this limitation, we use
19+
bypass_multi_tools_limit=True on GoogleSearchTool, which converts the built-in
20+
google_search to a function calling tool (via GoogleSearchAgentTool).
21+
22+
The bypass is only triggered when len(agent.tools) > 1, so we include multiple
23+
tools in the agent (GoogleSearchTool + get_current_weather).
24+
25+
With bypass_multi_tools_limit=True and multiple tools, all tools become function
26+
calling tools, which allows mixing google_search with custom function tools.
27+
"""
28+
29+
from google.adk.agents.llm_agent import Agent
30+
from google.adk.models.google_llm import Gemini
31+
from google.adk.tools.google_search_tool import GoogleSearchTool
32+
33+
34+
def get_current_weather(city: str) -> dict:
35+
"""Get the current weather for a city.
36+
37+
This is a mock implementation for testing purposes.
38+
39+
Args:
40+
city: The name of the city to get weather for.
41+
42+
Returns:
43+
A dictionary containing weather information.
44+
"""
45+
# Mock weather data for testing
46+
weather_data = {
47+
"new york": {"temperature": 72, "condition": "Sunny", "humidity": 45},
48+
"london": {"temperature": 59, "condition": "Cloudy", "humidity": 78},
49+
"tokyo": {
50+
"temperature": 68,
51+
"condition": "Partly Cloudy",
52+
"humidity": 60,
53+
},
54+
"paris": {"temperature": 64, "condition": "Rainy", "humidity": 85},
55+
"sydney": {"temperature": 77, "condition": "Clear", "humidity": 55},
56+
}
57+
58+
city_lower = city.lower()
59+
if city_lower in weather_data:
60+
data = weather_data[city_lower]
61+
return {
62+
"city": city,
63+
"temperature_f": data["temperature"],
64+
"condition": data["condition"],
65+
"humidity": data["humidity"],
66+
}
67+
else:
68+
return {
69+
"city": city,
70+
"temperature_f": 70,
71+
"condition": "Unknown",
72+
"humidity": 50,
73+
"note": "Weather data not available, using defaults",
74+
}
75+
76+
77+
# Main agent with google_search (via bypass) and custom function tools
78+
# Using bypass_multi_tools_limit=True converts google_search to a function calling tool.
79+
# We need len(tools) > 1 to trigger the bypass, so we include get_current_weather directly.
80+
# This allows mixing google_search with custom function tools via the Interactions API.
81+
#
82+
# NOTE: code_executor is not compatible with function calling mode because the model
83+
# tries to call a function (e.g., run_code) instead of outputting code in markdown.
84+
root_agent = Agent(
85+
model=Gemini(
86+
model="gemini-2.5-flash",
87+
use_interactions_api=True,
88+
),
89+
name="interactions_test_agent",
90+
description="An agent for testing the Interactions API integration",
91+
instruction="""You are a helpful assistant that can:
92+
93+
1. Search the web for information using google_search
94+
2. Get weather information using get_current_weather
95+
96+
When users ask for information that requires searching, use google_search.
97+
When users ask about weather, use get_current_weather.
98+
99+
Be concise and helpful in your responses. Always confirm what you did.
100+
""",
101+
tools=[
102+
GoogleSearchTool(bypass_multi_tools_limit=True),
103+
get_current_weather,
104+
],
105+
)

0 commit comments

Comments
 (0)