Building agents with the ADK and the new Interactions API
- Google Developers Blog
Community/Events
Learn
Blog
YouTube
Search
Community/Events
Learn
Blog
YouTube
Building agents with the ADK and the new Interactions API
DEC. 11, 2025
Mike Smith
Staff Software Engineer
Xiang (Sean) Zhou
Software Engineer
Cloud AI ADK
Alan Blount
Senior Technical Product Manager
Share
Facebook
Twitter
LinkedIn
Mail
The landscape of AI development is shifting from stateless request-response cycles to stateful, multi-turn agentic workflows. With the beta launch of the Interactions API, Google is providing a unified interface designed specifically for this new era—offering a single gateway to both raw models and the fully managed Gemini Deep Research Agent.
For developers already working with the Agent Development Kit (ADK) and the Agent2Agent (A2A) protocol, this raises an exciting question: How does this new API fit into my existing ecosystem?
The answer is two-fold. The Interactions API acts as both an alternative to the existing generateContent inference API endpoint and as a powerful primitive you can use within an existing agent framework.
In this post, we’ll explore two primary patterns for integration:
Powering your ADK Agents: Using the Interactions API as the inference engine for your custom agents.
The Transparent Bridge: Collaborating with built-in agents (like Gemini Deep Research Agent) at standard remote A2A agents using the Interactions API.
Pattern 1: Writing Agents with ADK and Interactions API
When you build an agent using the ADK (Agent Development Kit), you need a LLM like Gemini which generates the thoughts, plans, tool calls and responses. Previously, this was handled by generateContent.
The new Interactions API offers a native interface for complex state management. By upgrading your inference calls to use this new endpoint, your ADK agents gain access to capabilities designed specifically for agentic loops.Why switch?
Unified Model & Agent Access: The same API endpoint works for a standard model (model=”gemini-3-pro-preview”) or a built-in Gemini agent (agent=”deep-research-pro-preview-12-2025”).
Simplified State Management: You can optionally offload conversation history management to the server using previous_interaction_id, reducing the boilerplate code in your ADK agent.
Background Execution: The API supports long-running tasks (such as those performed by the Deep Research agent) via a background execution mode. By setting background=True, the API immediately returns an interaction ID and offloads the reasoning loop to the server. This allows the client to disconnect without hitting timeouts and asynchronously poll the endpoint to retrieve the final output.
Native Thought Handling: The API explicitly models "thoughts" separate from final responses, allowing your ADK agent to process reasoning chains more effectively.How it looks
Instead of managing a raw list of messages and sending them to generateContent, your ADK agent can maintain a lighter-weight pointer to the server-side state.
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",
# Enable Interactions API
use_interactions_api=True,
),
name="interactions_test_agent",
tools=[
# Converted Google Search to a function tool
GoogleSearchTool(bypass_multi_tools_limit=True),
get_current_weather,
],
)
Python
Copied
For step by step instructions see the full ADK sample with the Interactions API.
This pattern allows you to keep the control flow and routing logic within the ADK while delegating the heavy lifting of context management and inference state to the Interactions API.
We often describe an inner loop (inside the API) and an outer loop (in your agent code), and this new API gives you more control over both.
Pattern 2: Using Interactions API Agents as Remote A2A Agents
This is where the interoperability of the Agent2Agent (A2A) protocol shines.
If you have an existing ecosystem of A2A clients or agents, you might want them to consult the new Gemini Deep Research Agent. Historically, integrating a new third-party API would require writing a custom wrapper or adapter.
With the new InteractionsApiTransport, we have mapped the A2A protocol surface directly onto the Interactions API surface. It “speaks” A2A. This means you can treat an Interactions API endpoint as just another remote A2A agent. Your existing clients don't need to know they are talking to a Google-hosted agent; they just see an AgentCard and send messages as usual.How the Bridge Works
The InteractionsApiTransport layer performs a translation to A2A:
A2A SendMessage → Interactions create
A2A Task → Interaction ID
A2A TaskStatus → Interaction Status (e.g., IN_PROGRESS maps to TASK_STATE_WORKING)
Note: A2A push notifications, A2A extensions, and Interactions API callbacks are not yet supported in this mapping.Code Example: The Transparent Integration
To use this,simply configure your A2A client factory with the new transport and create a card that points to the model or agent you want to use.
from interactions_api_transport import InteractionsApiTransport
from a2a.client import ClientFactory, ClientConfig
# 1. Configure the factory to support Interactions API
client_config = ClientConfig()
client_factory = ClientFactory(client_config)
# Setup the transport (handles API keys and auth transparently)
InteractionsApiTransport.setup(client_factory)
# 2. Create an AgentCard for the Deep Research agent
# This helper method constructs the card with the necessary 'smuggled' config
card = InteractionsApiTransport.make_card(
url="https://generativelanguage.googleapis.com",
agent="deep-research-pro-preview-12-2025"
)
# 2a. You can also interact directly with a Gemini model
card = InteractionsApiTransport.make_card(
url="https://generativelanguage.googleapis.com",
model="gemini-3-pro-preview",
request_opts={
"generation_config": { "thinking_summaries": "auto" }
}
)
# 3. Create a regular A2A client
client = client_factory.create(card)
# 4. Use it exactly like any other A2A agent
async for event in client.send_message(new_text_message("Research the history of Google TPUs")):
# The transport converts Interactions API 'Thoughts' and 'Content'
# into standard A2A Task events.
print(event)
Python
Copied
Why this matters
This approach makes the Interactions API "transparent" to your developer experience. You gain immediate access to powerful new tools like Deep Research without refactoring your multi-agent system.
And the best part, it just works.
No new SDKs to learn: Your A2A client code stays the same.
Streaming Support: The transport handles mapping streaming events, so you get real-time updates from the agent.
Configuration Smuggling: We use A2A extensions to pass specific configurations (like thinking_summaries) inside the AgentCard without breaking the standard protocol.Conclusion
The Gemini Interactions API represents a major step forward in how we model AI communication. Whether you are building custom agents from scratch using any framework like the ADK or connecting existing agents together via A2A, this is a new set of capabilities to start exploring today.
By treating the API as both a superior inference engine and a compliant remote agent, you can rapidly expand the capabilities of your agentic mesh with minimal friction. Expect many more ADK and A2A resources over the next few weeks to help developers adopt this new API.Get started today
Read the announcement for Gemini Interactions API and docs
Read the announcement for Gemini Deep Research Agent and docs
Check out the ADK release notes, docs and the ADK sample with the Interactions API
Check out the A2A sample which uses the Interactions API
posted in:
AI
Cloud
Announcements
Solutions
Explore
Learn
Previous
Next
Related Posts
AI
Cloud
Announcements
Solutions
Expanding Choice in Gemini Enterprise Agent Platform: Introducing Grounding with Parallel Web Search
JULY 16, 2026
AI
Best Practices
Industry Trends
Building scalable AI agents with modular prompt transpilation
JULY 16, 2026
AI
Announcements
Solutions
Evolving Spec-Driven Development: Conductor Now Supports Antigravity
JULY 16, 2026
Connect
Blog
Bluesky
Instagram
LinkedIn
X (Twitter)
YouTube
Programs
Google Developer Program
Google Developer Groups
Google Developer Experts
Accelerators
Women Techmakers
Google Cloud & NVIDIA
Developer consoles
Google API Console
Google Cloud Platform Console
Google Play Console
Firebase Console
Actions on Google Console
Cast SDK Developer Console
Chrome Web Store Dashboard
Google Home Developer Console
Android
Chrome
Firebase
Google Cloud Platform
All products
Manage cookies
Terms
Privacy