adk-python/contributing/samples/interactions_api/README.md

Interactions API Sample Agent

This sample agent demonstrates the Interactions API integration in ADK. The Interactions API provides stateful conversation capabilities, allowing chained interactions using previous_interaction_id instead of sending full conversation history.

Features Tested

1. Basic Text Generation - Simple conversation without tools
2. Google Search Tool - Web search using GoogleSearchTool with bypass_multi_tools_limit=True
3. Multi-Turn Conversations - Stateful interactions with context retention via previous_interaction_id
4. Custom Function Tool - Weather lookup using get_current_weather

Important: Tool Compatibility

The Interactions API does NOT support mixing custom function calling tools with built-in tools (like google_search) in the same agent. To work around this limitation:

# Use bypass_multi_tools_limit=True to convert google_search to a function tool
GoogleSearchTool(bypass_multi_tools_limit=True)

This converts the built-in google_search to a function calling tool (via GoogleSearchAgentTool), which allows it to work alongside custom function tools.

How to Run

Prerequisites

# From the adk-python root directory
uv sync --all-extras
source .venv/bin/activate

# Set up authentication (choose one):
# Option 1: Using Google Cloud credentials
export GOOGLE_CLOUD_PROJECT=your-project-id

# Option 2: Using API Key
export GOOGLE_API_KEY=your-api-key

Running Tests

cd contributing/samples

# Run automated tests with Interactions API
python -m interactions_api.main

Key Differences: Interactions API vs Standard API

Interactions API (use_interactions_api=True)

• Uses stateful interactions via previous_interaction_id
• Only sends current turn contents when chaining interactions
• Returns interaction_id in responses for chaining
• Ideal for long conversations with many turns
• Context caching is not used (state maintained via interaction chaining)

Standard API (use_interactions_api=False)

• Uses stateless generate_content calls
• Sends full conversation history with each request
• No interaction IDs in responses
• Context caching can be used

Code Structure

interactions_api/
├── __init__.py                    # Package initialization
├── agent.py                       # Agent definition with Interactions API
├── main.py                        # Test runner
├── test_interactions_curl.sh      # cURL-based API tests
├── test_interactions_direct.py    # Direct API tests
└── README.md                      # This file

Agent Configuration

from google.adk.agents.llm_agent import Agent
from google.adk.models.google_llm import Gemini
from google.adk.tools.google_search_tool import GoogleSearchTool

root_agent = Agent(
    model=Gemini(
        model="gemini-2.5-flash",
        use_interactions_api=True,  # Enable Interactions API
    ),
    name="interactions_test_agent",
    tools=[
        GoogleSearchTool(bypass_multi_tools_limit=True),  # Converted to function tool
        get_current_weather,  # Custom function tool
    ],
)

Example Output

============================================================
TEST 1: Basic Text Generation
============================================================

>> User: Hello! What can you help me with?
<< Agent: Hello! I can help you with: 1) Search the web...
   [Interaction ID: v1_abc123...]
PASSED: Basic text generation works

============================================================
TEST 2: Function Calling (Google Search Tool)
============================================================

>> User: Search for the capital of France.
   [Tool Call] google_search_agent({'request': 'capital of France'})
   [Tool Result] google_search_agent: {'result': 'The capital of France is Paris...'}
<< Agent: The capital of France is Paris.
   [Interaction ID: v1_def456...]
PASSED: Google search tool works

============================================================
TEST 3: Multi-Turn Conversation (Stateful)
============================================================

>> User: Remember the number 42.
<< Agent: I'll remember that number - 42.
   [Interaction ID: v1_ghi789...]

>> User: What number did I ask you to remember?
<< Agent: You asked me to remember the number 42.
   [Interaction ID: v1_jkl012...]
PASSED: Multi-turn conversation works with context retention

============================================================
TEST 5: Custom Function Tool (get_current_weather)
============================================================

>> User: What's the weather like in Tokyo?
   [Tool Call] get_current_weather({'city': 'Tokyo'})
   [Tool Result] get_current_weather: {'city': 'Tokyo', 'temperature_f': 68, ...}
<< Agent: The weather in Tokyo is 68F and Partly Cloudy.
   [Interaction ID: v1_mno345...]
PASSED: Custom function tool works with bypass_multi_tools_limit

ALL TESTS PASSED (Interactions API)