they lay the groundwork for a more structured approach to building interactive, AI-driven applications. One of the most interesting results of this effort was the liberation of their youth Interactions API a few weeks ago.
As major language models (LLMs) come and go, it often appears that an API developed by an LLM provider can get more time. After all, it can be difficult for an API designer to anticipate all the various changes and tweaks that might be implemented in whatever system the API is designed to use. This is doubly true in AI, where the pace of change is unlike anything seen in the IT world before.
We've seen this before with OpenAI, for example. Their first API for their models was called Termination API. As their models evolved, they had to develop and release a new API called Answers.
Google takes a slightly different approach with the Interactions API. They are not complete replacements for their elders generate content API, but rather an extension of it.
As Google states in its documentation…
“The Interactions API (Beta) is an integrated interface for interacting with Gemini models and agents. It simplifies landscape management, tool tuning, and long-running operations.”
The rest of this article explores the architectural need for the Interactions API. We'll start in a simple way by showing how the Interactions API can do everything its predecessor could, and then conclude with how it enables great performance, transparent integration of Google's long-delayed Deep Research capabilities, and long-running task management. We will move beyond the “Hello World” example to build systems that require critical thinking and asynchronous research planning.
The Building Gap: Why “Discussion” Is Not Enough
To understand why the Interactions API exists, we have to analyze why the standard LLM conversation loop is not enough.
In a typical chat app, “status” is obvious. It only exists as a sliding window of token history. If the user is at step 3 of the onboarding wizard and asks an off-topic question, the model may recognize a new path, effectively breaking the wizard. The developer has no system guarantee that the user is where they should be.
With the development of modern AI systems, this is not enough. To counter that, Google's new API provides ways to reference previous context in subsequent LLM interactions. We will see an example of that later.
Critical Research Problem
The power of Google Deep Search (powered by Gemini) is at work. It doesn't just extract information; create a plan, do a lot of research, read hundreds of pages, and compile an answer. This process is asynchronous and high-latency.
You can't just tell a standard dialog model to “do some research” inside a concurrency loop without risking a timeout or content window overflow. The Interactions API allows you to combine this dynamic agent process into a stable, managed one Stepto pause the interactive state. At the same time, heavy lifting occurs and starts again only when the programmed data is restored. However, if a deep research agent is taking a long time to do their research, the last thing you want to do is sit there twiddling your thumbs waiting for them to finish. The Interactions API allows you to perform background research and poll its results periodically, so you are immediately notified when an agent returns their results.
Setting Up the Development Environment
Let's see the Interactions API up close by looking at a few examples of its implementation code. As with any development project, it's best to isolate your surroundings, so let's do that now. I use Windows and UV package manager for this, but use whatever tool you're comfortable with. My code was used in a Jupyter notebook.
uv init interactions_demo --python 3.12
cd interactions_demo
uv add google-genai jupyter
# To run the notebook, type this in
uv run jupyter notebookTo run my example code, you'll also need a Google API key. If you don't have one, go to Google's AI Studio website and sign in. Near the bottom left of the screen, you'll see a Get an API key link. Click that and follow the instructions to get your key. Once you have the key, create a named local variable GOOGLE_API_KEY on your system and set its value to your API key.
Example 1: Hello World equivalent
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-2.5-flash",
input="What is the capital of France"
)
print(interaction.outputs[-1].text)
#
# Output
#
The capital of France is **Paris**.Example 2: Using a Nano Banana to create an image
Before we explore some of the state-handling and deep-search capabilities offered by the new Interactions API, I want to point out that again a general-purpose, multi-purpose tool. In this case, we will use the API to create an image for us using Nano Banana, officially known as Gemini 3 Pro Image Preview.
import base64
import os
from google import genai
# 1. Ensure the directory exists
output_dir = r"c:temp"
if not os.path.exists(output_dir):
os.makedirs(output_dir)
print(f"Created directory: {output_dir}")
client = genai.Client()
print("Sending request...")
try:
# 2. Correct Syntax: Pass 'response_modalities' directly (not inside config)
interaction = client.interactions.create(
model="gemini-3-pro-image-preview", # Ensure you have access to this model
input="Generate an image of a hippo wearing a top-hat riding a uni-cycle.",
response_modalities=["IMAGE"]
)
found_image = False
# 3. Iterate through outputs and PRINT everything
for i, output in enumerate(interaction.outputs):
# Debug: Print the type so we know what we got
print(f"n--- Output {i+1} Type: {output.type} ---")
if output.type == "text":
# If the model refused or chatted back, this will print why
print(f"📝 Text Response: {output.text}")
elif output.type == "image":
print(f"Image Response: Mime: {output.mime_type}")
# Construct filename
file_path = os.path.join(output_dir, f"hippo_{i}.png")
# Save the image
with open(file_path, "wb") as f:
# The SDK usually returns base64 bytes or string
if isinstance(output.data, bytes):
f.write(output.data)
else:
f.write(base64.b64decode(output.data))
print(f"Saved to: {file_path}")
found_image = True
if not found_image:
print("nNo image was returned. Check the 'Text Response' above for the reason.")
except Exception as e:
print(f"nError: {e}")This was my result.
Example 3: Country Management
Conditional handling in the Interactions API is built in “Interaction” resource, which acts as a session record that contains the entire history of activity, from user input to tool output.
To continue a conversation that remembers the previous context, you pass the ID of the previous interaction to previous_interaction_id new request parameter.
The server uses this ID to automatically retrieve the full context of a specific session associated with it, eliminating the need for the developer to retransmit the entire conversation history. A side effect is that, in this way, caching can be used more efficiently, resulting in improved performance and reduced token costs.
Conditional interactions require data to be stored on Google servers. By default, the store parameter is set to true, which enables this feature. If the developer sets store=false, it will not be able to use properties with a state like previous_interaction_id.
Organized mode also allows combining different models and agents into one music. For example, you can use a Deep Research agent to collect data and refer to that ID of the interaction to have a common (cheap) Gemini model that summarizes the findings.
Here's a quick example where we start a simple task by telling the model our name and asking it simple questions. We record the Interaction ID generated by the session, and later, we ask the model what our name was and what the second question we asked was.
from google import genai
client = genai.Client()
# 1. First turn
interaction1 = client.interactions.create(
model="gemini-3-flash-preview",
input="""
Hi,It's Tom here, can you tell me the chemical name for water.
Also, which is the smallest recognised country in the world?
And how tall in feet is Mt Everest
"""
)
print(f"Response: {interaction1.outputs[-1].text}")
print(f"ID: {interaction1.id}")
#
# Output
#
Response: Hi Tom! Here are the answers to your questions:
* **Chemical name for water:** The most common chemical name is **dihydrogen monoxide** ($H_2O$), though in formal chemistry circles, its systematic name is **oxidane**.
* **Smallest recognized country:** **Vatican City**. It covers only about 0.17 square miles (0.44 square kilometers) and is an independent city-state enclaved within Rome, Italy.
* **Height of Mt. Everest:** According to the most recent official measurement (confirmed in 2020), Mt. Everest is **29,031.7 feet** (8,848.86 meters) tall.
ID: v1_ChdqamxlYVlQZ01jdmF4czBQbTlmSHlBOBIXampsZWFZUGdNY3ZheHMwUG05Zkh5QTgAfter a few hours…
from google import genai
client = genai.Client()
# 2. Second turn (passing previous_interaction_id)
interaction2 = client.interactions.create(
model="gemini-3-flash-preview",
input="Can you tell me my name and what was the second question I asked you",
previous_interaction_id='v1_ChdqamxlYVlQZ01jdmF4czBQbTlmSHlBOBIXampsZWFZUGdNY3ZheHMwUG05Zkh5QTg'
)
print(f"Model: {interaction2.outputs[-1].text}")
#
# Output
#
Model: Hi Tom!
Your name is **Tom**, and the second question you asked was:
**"Which is the smallest recognised country in the world?"**
(to which the answer is Vatican City).Example 4: Asynchronous Deep Research Orchestrator
Now, on to something that Google's old API can't do. One of the key benefits of the Interactions API is that you can use it to call special agents, such as deep-research-pro-preview-12-2025, difficult tasks.
In this example, we will build a competitive intelligence engine. The user specifies a business competitor, and the system triggers a Deep Research agent to scan the web, read annual reports, and create a Strengths, Weaknesses, Opportunities and Threats (SWOT) analysis. We divide this into two parts. First, we can delete our survey request using code like this.
import time
import sys
from google import genai
def competitive_intelligence_engine():
client = genai.Client()
print("--- Deep Research Competitive Intelligence Engine ---")
competitor_name = input("Enter the name of the competitor to analyze (e.g., Nvidia, Coca-Cola): ")
# We craft a specific prompt to force the agent to look for specific document types
prompt = f"""
Conduct a deep research investigation into '{competitor_name}'.
Your specific tasks are:
1. Scour the web for the most recent Annual Report (10-K) and latest Quarterly Earnings transcripts.
2. Search for recent news regarding product launches, strategic partnerships, and legal challenges in the last 12 months.
3. Synthesize all findings into a detailed SWOT Analysis (Strengths, Weaknesses, Opportunities, Threats).
Format the output as a professional executive summary with the SWOT section clearly defined in Markdown.
"""
print(f"n Deploying Deep Research Agent for: {competitor_name}...")
# 1. Start the Deep Research Agent
# We use the specific agent ID provided in your sample
try:
initial_interaction = client.interactions.create(
input=prompt,
agent="deep-research-pro-preview-12-2025",
background=True
)
except Exception as e:
print(f"Error starting agent: {e}")
return
print(f" Research started. Interaction ID: {initial_interaction.id}")
print("⏳ The agent is now browsing the web and reading reports. This may take several minutes.")This will produce the following output.
--- Deep Research Competitive Intelligence Engine ---
Enter the name of the competitor to analyze (e.g., Nvidia, Coca-Cola): Nvidia
Deploying Deep Research Agent for: Nvidia...
Research started. Interaction ID: v1_ChdDdXhiYWN1NEJLdjd2ZElQb3ZHdTBRdxIXQ3V4YmFjdTRCS3Y3dmRJUG92R3UwUXc
The agent is now browsing the web and reading reports. This may take several minutes.Next, since we know that the survey work will take some time to complete, we can use the Transaction ID printed above to monitor it and check it from time to time to see if it has finished.
Usually, this will be done through a separate process that will send you an email or text when the survey work is completed so that you can continue with other work in the meantime.
try:
while True:
# Refresh the interaction status
interaction = client.interactions.get(initial_interaction.id)
# Calculate elapsed time
elapsed = int(time.time() - start_time)
# Print a dynamic status line so we know it's working
sys.stdout.write(f"r Status: {interaction.status.upper()} | Time Elapsed: {elapsed}s")
sys.stdout.flush()
if interaction.status == "completed":
print("nn" + "="*50)
print(f" INTELLIGENCE REPORT: {competitor_name.upper()}")
print("="*50 + "n")
# Print the content
print(interaction.outputs[-1].text)
break
elif interaction.status in ["failed", "cancelled"]:
print(f"nnJob ended with status: {interaction.status}")
# Sometimes error details are in the output text even on failure
if interaction.outputs:
print(f"Error details: {interaction.outputs[-1].text}")
break
# Wait before polling again to respect rate limits
time.sleep(10)
except KeyboardInterrupt:
print("nUser interrupted. Research may continue in background.")I will not show the complete result of the research, as it was too long, but here is part of it.
==================================================
📝 INTELLIGENCE REPORT: NVIDIA
==================================================
# Strategic Analysis & Executive Review: Nvidia Corporation (NVDA)
### Key Findings
* **Financial Dominance:** Nvidia reported record Q3 FY2026 revenue of **$57.0 billion** (+62% YoY), driven by a staggering **$51.2 billion** in Data Center revenue. The company has effectively transitioned from a hardware manufacturer to the foundational infrastructure provider for the "AI Industrial Revolution."
* **Strategic Expansion:** Major moves in late 2025 included a **$100 billion investment roadmap with OpenAI** to deploy 10 gigawatts of compute and a **$20 billion acquisition of Groq's assets**, pivoting Nvidia aggressively into the AI inference market.
* **Regulatory Peril:** The company faces intensifying geopolitical headwinds. In September 2025, China's SAMR found Nvidia in violation of antitrust laws regarding its Mellanox acquisition. Simultaneously, the U.S. Supreme Court allowed a class-action lawsuit regarding crypto-revenue disclosures to proceed.
* **Product Roadmap:** The launch of the **GeForce RTX 50-series** (Blackwell architecture) and **Project DIGITS** (personal AI supercomputer) at CES 2025 signals a push to democratize AI compute beyond the data center to the desktop.
---
## 1. Executive Summary
Nvidia Corporation (NASDAQ: NVDA) stands at the apex of the artificial intelligence transformation, having successfully evolved from a graphics processing unit (GPU) vendor into a full-stack computing platform company. As of early 2026, Nvidia is not merely selling chips; it is building "AI Factories"-entire data centers integrated with its proprietary networking, software (CUDA), and hardware.
The fiscal year 2025 and the first three quarters of fiscal 2026 have demonstrated unprecedented financial acceleration. The company's "Blackwell" architecture has seen demand outstrip supply, creating a backlog that extends well into 2026. However, this dominance has invited intense scrutiny. The geopolitical rift between the U.S. and China poses the single greatest threat to Nvidia's long-term growth, evidenced by recent antitrust findings by Chinese regulators and continued smuggling controversies involving restricted chips like the Blackwell B200.
Strategically, Nvidia is hedging against the commoditization of AI training by aggressively entering the **inference** market-the phase where AI models are used rather than built. The acquisition of Groq's technology in December 2025 is a defensive and offensive maneuver to secure low-latency processing capabilities.
---
## 2. Financial Performance Analysis
**Sources:** [cite: 1, 2, 3, 4, 5]
### 2.1. Fiscal Year 2025 Annual Report (10-K) Highlights
Nvidia's Fiscal Year 2025 (ending January 2025) marked a historic inflection point in the technology sector.
* **Total Revenue:** $130.5 billion, a **114% increase** year-over-year.
* **Net Income:** $72.9 billion, soaring **145%**.
* **Data Center Revenue:** $115.2 billion (+142%), confirming the complete shift of the company's gravity away from gaming and toward enterprise AI.
* **Gross Margin:** Expanded to **75.0%** (up from 72.7%), reflecting pricing power and the high value of the Hopper architecture.
...
...
...
## 5. SWOT Analysis
### **Strengths**
* **Technological Monopoly:** Nvidia possesses an estimated 80-90% market share in AI training chips. The **Blackwell** and upcoming **Vera Rubin** architectures maintain a multi-year lead over competitors.
* **Ecosystem Lock-in (CUDA):** The CUDA software platform remains the industry standard. The recent expansion into "AI Factories" and full-stack solutions (networking + hardware + software) makes switching costs prohibitively high for enterprise customers.
* **Financial Fortress:** With gross margins exceeding **73%** and free cash flow in the tens of billions, Nvidia has immense capital to reinvest in R&D ($100B OpenAI commitment) and acquire emerging tech (Groq).
* **Supply Chain Command:** By pre-booking massive capacity at TSMC (CoWoS packaging), Nvidia effectively controls the faucet of global AI compute supply.
### **Weaknesses**
* **Revenue Concentration:** A significant portion of revenue is derived from a handful of "Hyperscalers" (Microsoft, Meta, Google, Amazon). If these clients successfully pivot to their own custom silicon (TPUs, Trainium, Maia), Nvidia's revenue could face a cliff.
* **Pricing Alienation:** The high cost of Nvidia hardware (e.g., $1,999 for consumer GPUs, $30k+ for enterprise chips) is pushing smaller developers and startups toward cheaper alternatives or cloud-based inference solutions.
* **Supply Chain Single Point of Failure:** Total reliance on **TSMC** in Taiwan exposes Nvidia to catastrophic risk in the event of a cross-strait conflict or natural disaster.
### **Opportunities**
* **The Inference Market:** The $20B Groq deal positions Nvidia to dominate the *inference* phase (running models), which is expected to be a larger market than training in the long run.
* **Sovereign AI:** Nations (Japan, France, Middle Eastern states) are building their own "sovereign clouds" to protect data privacy. This creates a new, massive customer base outside of US Big Tech.
* **Physical AI & Robotics:** With **Project GR00T** and the **Jetson** platform, Nvidia is positioning itself as the brain for humanoid robots and autonomous industrial systems, a market still in its infancy.
* **Software & Services (NIMs):** Nvidia is transitioning to a software-as-a-service model with Nvidia Inference Microservices (NIMs), creating recurring revenue streams that are less cyclical than hardware sales.
### **Threats**
* **Geopolitical Trade War:** The US-China tech war is the existential threat. Further tightening of export controls (e.g., banning H20 chips) or aggressive retaliation from China (SAMR antitrust penalties) could permanently sever access to one of the world's largest semiconductor markets.
* **Regulatory Antitrust Action:** Beyond China, Nvidia faces scrutiny in the EU and US (DOJ) regarding its bundling practices and market dominance. A forced breakup or behavioral remedies could hamper its "full-stack" strategy.
* **Smuggling & IP Theft:** As seen with the DeepSeek controversy, export bans may inadvertently fuel a black market and accelerate Chinese domestic innovation (e.g., Huawei Ascend), creating a competitor that operates outside Western IP laws.
* **"Good Enough" Competition:** For many inference workloads, cheaper chips from AMD or specialized ASICs may eventually become "good enough," eroding Nvidia's pricing power at the lower end of the market.
...
...
...There's a lot more you can do with the Interaction API than I've shown, including tool and function calling, MCP integration, structured output and streaming.
But please note that, as of the time of writing, the Interactions API still exists Beta, and Google's deep research agent is inside preview. This will undoubtedly change in the coming weeks, but it is best to test before using this tool in a production system.
For more information, see the link below for Google's official API documentation page.
Summary
The Google Interactions API shows growth in the AI engineering ecosystem. It admits that the “Everything Prompt”, a single, large block of text that attempts to manage personality, logic, tools, and security, is a contradictory pattern.
Using this API, developers using Google AI can effectively separate Consulting (LLM work) from Architecture (engineer work).
Unlike regular chat loops, where the situation is obvious and prone to fallacy, this API uses a structured approach. “Interaction” a resource that will serve as a permanent session record of all input, output, and output of the tools. With robust management, developers can reference the Interaction ID from a previous conversation and get the full context automatically. This can improve caching, improve performance, and lower costs by eliminating the need to resend all histories.
In addition, the Interactions API is uniquely capable of integrating asynchronous, high-latency agent processes, such as Google Deep Research, which can explore the web and aggregate large amounts of data into complex reports. This research can be done in a similar way, which means you can delete tasks that have taken a long time and write simple code that will be notified when the task is finished, allowing you to work on other tasks in the meantime.
If you're building a smart writing assistant, a simple chat loop is fine. But if you're building a financial analyst, medical examiner, or deep research engine, the Interactions API provides the scaffolding needed to turn a probabilistic model into a reliable product.
