diff --git a/examples/src/main/java/com/google/genai/examples/FileSearchCallContentExample.java b/examples/src/main/java/com/google/genai/examples/FileSearchCallContentExample.java
new file mode 100644
index 00000000000..a535d7fbae7
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/FileSearchCallContentExample.java
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai.examples;
+
+import com.google.genai.types.interactions.content.FileSearchCallContent;
+
+/**
+ * Example demonstrating the usage of FileSearchCallContent.
+ *
+ *
FileSearchCallContent represents a file search operation call in the Interactions API.
+ * Unlike other tool calls, FileSearchCallContent contains only the type and call ID.
+ * All search configuration (stores, top_k, filters) is defined in the FileSearch.
+ */
+public class FileSearchCallContentExample {
+
+ public static void main(String[] args) {
+ // Example 1: Create FileSearchCallContent using builder
+ FileSearchCallContent content1 =
+ FileSearchCallContent.builder()
+ .id("file-search-call-123")
+ .build();
+
+ System.out.println("FileSearchCallContent (using builder) JSON:");
+ System.out.println(content1.toJson());
+ System.out.println();
+
+ // Example 2: Create FileSearchCallContent using convenience method
+ FileSearchCallContent content2 =
+ FileSearchCallContent.of("call-456");
+
+ System.out.println("FileSearchCallContent (using of() method) JSON:");
+ System.out.println(content2.toJson());
+ System.out.println();
+
+ // Example 3: Deserialize from JSON
+ String json = content2.toJson();
+ FileSearchCallContent deserialized = FileSearchCallContent.fromJson(json);
+
+ System.out.println("Deserialized FileSearchCallContent:");
+ System.out.println(" ID: " + deserialized.id());
+ System.out.println();
+
+ // Example 4: Create FileSearchCallContent without ID (optional)
+ FileSearchCallContent content3 =
+ FileSearchCallContent.builder()
+ .build();
+
+ System.out.println("FileSearchCallContent (no ID) JSON:");
+ System.out.println(content3.toJson());
+ }
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsAsyncCreate.java b/examples/src/main/java/com/google/genai/examples/InteractionsAsyncCreate.java
new file mode 100644
index 00000000000..e4a5c82f395
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsAsyncCreate.java
@@ -0,0 +1,124 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import com.google.genai.types.interactions.content.Content;
+import com.google.genai.types.interactions.content.TextContent;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Example: Async Create with the Interactions API
+ *
+ *
Demonstrates async operations using CompletableFuture for non-blocking requests.
+ *
+ *
To run this example:
+ *
+ *
Set the GOOGLE_API_KEY environment variable: {@code export GOOGLE_API_KEY=YOUR_API_KEY}
+ *
Compile the examples: {@code mvn clean compile}
+ *
Demonstrates how to use the CodeExecution to enable the model to execute code as part of
+ * generation. The model can write and run code to solve problems.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsCodeExecution {
+
+ public static void main(String[] args) {
+ // Instantiate the client. The client gets the API key from the environment variable
+ // `GOOGLE_API_KEY`.
+ //
+ Client client = new Client();
+
+ System.out.println("=== Interactions API: Code Execution Tool Example ===\n");
+
+ // ===== STEP 1: Create CodeExecution =====
+ System.out.println("STEP 1: Create CodeExecution\n");
+
+ CodeExecution codeTool = CodeExecution.builder().build();
+
+ System.out.println("CodeExecution created successfully\n");
+
+ // ===== STEP 2: Create interaction with Code Execution enabled =====
+ System.out.println("---\n");
+ System.out.println("STEP 2: Create interaction with Code Execution enabled\n");
+
+ String userQuestion =
+ "Calculate the first 20 Fibonacci numbers and find their sum. "
+ + "Show me the code and the result.";
+ System.out.println("User: " + userQuestion + "\n");
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(userQuestion)
+ .tools(codeTool)
+ .build();
+
+ // Print the request JSON
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ Interaction response = client.interactions.create(config);
+
+ // Print the response JSON
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ // ===== STEP 3: Extract and display the results =====
+ System.out.println("---\n");
+ System.out.println("STEP 3: Extract and display the results\n");
+
+ System.out.println("Response received. Interaction ID: " + response.id());
+ System.out.println();
+
+ if (response.outputs().isPresent()) {
+ for (Content content : response.outputs().get()) {
+ if (content instanceof TextContent) {
+ System.out.println("Text: " + ((TextContent) content).text().orElse("(empty)"));
+ System.out.println();
+ } else if (content instanceof CodeExecutionCallContent) {
+ CodeExecutionCallContent codeCall = (CodeExecutionCallContent) content;
+ System.out.println("Code Execution Call:");
+ System.out.println(" ID: " + codeCall.id());
+ if (codeCall.arguments().isPresent()) {
+ System.out.println(" Language: " + codeCall.arguments().get().language().orElse("N/A"));
+ System.out.println(" Code:");
+ System.out.println(" ---");
+ System.out.println(codeCall.arguments().get().code().orElse("(empty)"));
+ System.out.println(" ---");
+ }
+ System.out.println();
+ } else if (content instanceof CodeExecutionResultContent) {
+ CodeExecutionResultContent codeResult = (CodeExecutionResultContent) content;
+ System.out.println("Code Execution Result:");
+ System.out.println(" Call ID: " + codeResult.callId().orElse("N/A"));
+ System.out.println(" Is Error: " + codeResult.isError().orElse(false));
+ System.out.println(" Result:");
+ System.out.println(" ---");
+ System.out.println(codeResult.result().orElse("(empty)"));
+ System.out.println(" ---");
+ System.out.println();
+ }
+ }
+ }
+
+ System.out.println("\n=== Example completed ===");
+ }
+
+ private InteractionsCodeExecution() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsComputerUse.java b/examples/src/main/java/com/google/genai/examples/InteractionsComputerUse.java
new file mode 100644
index 00000000000..18f6d265a22
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsComputerUse.java
@@ -0,0 +1,172 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Usage:
+ *
+ *
Note: The Interactions API is currently only available via the Gemini Developer API (not
+ * Vertex AI).
+ *
+ *
IMPORTANT: Computer Use tool may require special API access. This example demonstrates the
+ * configuration but may not work without proper authorization.
+ *
+ *
1. Set an API key environment variable. You can find a list of available API keys here:
+ * https://aistudio.google.com/app/apikey
+ *
+ *
export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ *
2. Compile the java package and run the sample code.
+ *
+ *
mvn clean compile
+ *
+ *
mvn exec:java -Dexec.mainClass="com.google.genai.examples.InteractionsComputerUse"
+ */
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import com.google.genai.types.interactions.content.Content;
+import com.google.genai.types.interactions.content.TextContent;
+import com.google.genai.types.interactions.tools.ComputerUse;
+
+/**
+ * Example: Computer Use Tool with the Interactions API
+ *
+ *
Demonstrates how to use the ComputerUse to enable the model to interact with a computer
+ * environment. This tool allows the model to control applications, browse web pages, and perform
+ * other computer-based tasks.
+ *
+ *
IMPORTANT NOTES:
+ *
+ *
This feature may require special API access and authorization.
+ *
ComputerUse is a configuration-only tool - it enables a capability but does not
+ * have explicit call/result content types in the SDK.
+ *
Results from computer use operations are returned as standard content types like
+ * TextContent or ImageContent (e.g., screenshots).
+ *
Unlike FunctionCallContent or CodeExecutionCallContent, there are no
+ * ComputerUseCallContent or ComputerUseResultContent types.
+ *
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsComputerUse {
+
+ public static void main(String[] args) {
+ // Instantiate the client. The client gets the API key from the environment variable
+ // `GOOGLE_API_KEY`.
+ //
+ Client client = new Client();
+
+ System.out.println("=== Interactions API: Computer Use Tool Example ===\n");
+
+ System.out.println(
+ "IMPORTANT: Computer Use tool may require special API access and authorization.\n");
+
+ // ===== STEP 1: Create ComputerUse =====
+ System.out.println("STEP 1: Create ComputerUse\n");
+
+ // Configure the computer use environment
+ // Common environments: "browser" for web browsing, "desktop" for full desktop access
+ //
+ // IMPORTANT: ComputerUse is a configuration that enables computer use capabilities.
+ // Unlike FunctionCall or CodeExecution, it does NOT have corresponding
+ // ComputerUseCallContent or ComputerUseResultContent types.
+ // Results are returned as standard content types (TextContent, ImageContent, etc.)
+ ComputerUse computerTool =
+ ComputerUse.builder()
+ .environment("browser")
+ // Optionally exclude predefined functions
+ // .excludedPredefinedFunctions("function1", "function2")
+ .build();
+
+ System.out.println("ComputerUse created successfully");
+ System.out.println("Environment: " + computerTool.environment().orElse("default"));
+ System.out.println();
+
+ // ===== STEP 2: Create interaction with Computer Use enabled =====
+ System.out.println("---\n");
+ System.out.println("STEP 2: Create interaction with Computer Use enabled\n");
+
+ String userQuestion = "Navigate to https://www.example.com and tell me what you see.";
+ System.out.println("User: " + userQuestion + "\n");
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(userQuestion)
+ .tools(computerTool)
+ .build();
+
+ // Print the request JSON
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ try {
+ Interaction response = client.interactions.create(config);
+
+ // Print the response JSON
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ // ===== STEP 3: Extract and display the results =====
+ System.out.println("---\n");
+ System.out.println("STEP 3: Extract and display the results\n");
+
+ System.out.println("Response received. Interaction ID: " + response.id());
+ System.out.println();
+
+ if (response.outputs().isPresent()) {
+ for (Content content : response.outputs().get()) {
+ System.out.println("Content Type: " + content.getClass().getSimpleName());
+
+ if (content instanceof TextContent) {
+ System.out.println("Text: " + ((TextContent) content).text().orElse("(empty)"));
+ System.out.println();
+ }
+
+ // IMPORTANT: ComputerUse does NOT have dedicated content types
+ // (no ComputerUseCallContent or ComputerUseResultContent).
+ //
+ // Instead, computer use operations return results as:
+ // - TextContent: For textual responses and descriptions
+ // - ImageContent: For screenshots of computer actions
+ // - Other standard content types as needed
+ //
+ // This is different from tools like FunctionCall, CodeExecution, etc.,
+ // which have explicit call/result content type pairs.
+ }
+ }
+
+ System.out.println("\n=== Example completed successfully ===");
+
+ } catch (Exception e) {
+ System.err.println("\n=== Error occurred ===");
+ System.err.println("Error: " + e.getMessage());
+ System.err.println(
+ "\nNote: Computer Use tool may require special API access or authorization.");
+ System.err.println("Please check:");
+ System.err.println(" 1. Your API key has Computer Use permissions");
+ System.err.println(" 2. The feature is enabled for your account");
+ System.err.println(" 3. You're using a model that supports Computer Use");
+ e.printStackTrace();
+ }
+ }
+
+ private InteractionsComputerUse() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsCreateExample.java b/examples/src/main/java/com/google/genai/examples/InteractionsCreateExample.java
new file mode 100644
index 00000000000..a54de14389e
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsCreateExample.java
@@ -0,0 +1,290 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Usage:
+ *
+ *
Note: The Interactions API is currently only available via the Gemini Developer API (not
+ * Vertex AI).
+ *
+ *
1. Set an API key environment variable. You can find a list of available API keys here:
+ * https://aistudio.google.com/app/apikey
+ *
+ *
export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ *
2. Compile the java package and run the sample code.
+ *
+ *
Demonstrates how to use the FileSearch to enable the model to search through file stores.
+ * This is useful for RAG (Retrieval-Augmented Generation) use cases where you want the model to
+ * answer questions based on your documents.
+ *
+ *
IMPORTANT: Requires file search stores to be created beforehand. See usage instructions
+ * above.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsFileSearch {
+
+ public static void main(String[] args) {
+ // Instantiate the client. The client gets the API key from the environment variable
+ // `GOOGLE_API_KEY`.
+ //
+ Client client = new Client();
+
+ System.out.println("=== Interactions API: File Search Tool Example ===\n");
+
+ System.out.println("IMPORTANT: This example requires file search stores to be created.\n");
+ System.out.println("See the file header comments for setup instructions.\n");
+
+ // ===== STEP 1: Create FileSearch =====
+ System.out.println("STEP 1: Create FileSearch\n");
+
+ // Configure the file search tool
+ // Update the store names to match your created file search stores
+ FileSearch fileSearchTool =
+ FileSearch.builder()
+ .fileSearchStoreNames(
+ "my-document-store-1",
+ "my-document-store-2" // You can search across multiple stores
+ )
+ .topK(10) // Maximum number of results to return
+ // Optional: Add metadata filter
+ // .metadataFilter(ImmutableMap.of("category", "technical", "year", 2025))
+ .build();
+
+ System.out.println("FileSearch created successfully");
+ System.out.println(
+ "Store Names: " + fileSearchTool.fileSearchStoreNames().orElse(java.util.List.of()));
+ System.out.println("Top K: " + fileSearchTool.topK().orElse(10));
+ System.out.println();
+
+ // ===== STEP 2: Create interaction with File Search enabled =====
+ System.out.println("---\n");
+ System.out.println("STEP 2: Create interaction with File Search enabled\n");
+
+ String userQuestion =
+ "What are the main features described in the documentation? "
+ + "Please search through the uploaded files.";
+ System.out.println("User: " + userQuestion + "\n");
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(userQuestion)
+ .tools(fileSearchTool)
+ .build();
+
+ // Print the request JSON
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ try {
+ Interaction response = client.interactions.create(config);
+
+ // Print the response JSON
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ // ===== STEP 3: Extract and display the results =====
+ System.out.println("---\n");
+ System.out.println("STEP 3: Extract and display the results\n");
+
+ System.out.println("Response received. Interaction ID: " + response.id());
+ System.out.println();
+
+ if (response.outputs().isPresent()) {
+ for (Content content : response.outputs().get()) {
+ if (content instanceof TextContent) {
+ System.out.println("Text: " + ((TextContent) content).text().orElse("(empty)"));
+ System.out.println();
+ } else if (content instanceof FileSearchResultContent) {
+ FileSearchResultContent searchResult = (FileSearchResultContent) content;
+ System.out.println("File Search Result:");
+
+ if (searchResult.result().isPresent()) {
+ for (FileSearchResult result : searchResult.result().get()) {
+ System.out.println(" Title: " + result.title().orElse("N/A"));
+ System.out.println(" File Search Store: " + result.fileSearchStore().orElse("N/A"));
+
+ if (result.text().isPresent()) {
+ String text = result.text().get();
+ System.out.println(" Text (first 500 chars):");
+ System.out.println(" ---");
+ System.out.println(text.length() > 500 ? text.substring(0, 500) + "..." : text);
+ System.out.println(" ---");
+ System.out.println(" Total text length: " + text.length() + " chars");
+ }
+ }
+ }
+ System.out.println();
+ }
+ }
+ }
+
+ System.out.println("\n=== Example completed successfully ===");
+
+ } catch (Exception e) {
+ System.err.println("\n=== Error occurred ===");
+ System.err.println("Error: " + e.getMessage());
+ System.err.println("\nNote: This example requires file search stores to be created.");
+ System.err.println("Please check:");
+ System.err.println(" 1. File search stores exist with the names specified");
+ System.err.println(" 2. Files have been uploaded to the stores");
+ System.err.println(" 3. Your API key has access to the stores");
+ System.err.println(" 4. The store names in this example match your actual store names");
+ e.printStackTrace();
+ }
+ }
+
+ private InteractionsFileSearch() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsFunctionCalling.java b/examples/src/main/java/com/google/genai/examples/InteractionsFunctionCalling.java
new file mode 100644
index 00000000000..aedfdacb3a5
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsFunctionCalling.java
@@ -0,0 +1,190 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai.examples;
+
+import com.google.common.collect.ImmutableMap;
+import com.google.genai.Client;
+import com.google.genai.types.Schema;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import com.google.genai.types.interactions.content.Content;
+import com.google.genai.types.interactions.content.FunctionCallContent;
+import com.google.genai.types.interactions.content.FunctionResultContent;
+import com.google.genai.types.interactions.content.TextContent;
+import com.google.genai.types.interactions.tools.Function;
+import java.util.Map;
+
+/**
+ * Example: Function Calling with the Interactions API
+ *
+ *
Demonstrates manual function calling where you define functions, extract calls from responses,
+ * execute them, and send results back.
+ *
+ *
To run this example:
+ *
+ *
Set the GOOGLE_API_KEY environment variable: {@code export GOOGLE_API_KEY=YOUR_API_KEY}
+ *
Compile the examples: {@code mvn clean compile}
+ *
Demonstrates how to use the McpServer to enable the model to interact with an MCP (Model
+ * Context Protocol) server. This allows integration with external tools and services that implement
+ * the MCP protocol.
+ *
+ *
IMPORTANT: Requires a running MCP server. See usage instructions above.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsMcpServer {
+
+ public static void main(String[] args) {
+ // Instantiate the client. The client gets the API key from the environment variable
+ // `GOOGLE_API_KEY`.
+ //
+ Client client = new Client();
+
+ System.out.println("=== Interactions API: MCP Server Tool Example ===\n");
+
+ System.out.println("IMPORTANT: This example requires a running MCP server.\n");
+ System.out.println("See the file header comments for setup instructions.\n");
+
+ // ===== STEP 1: Create McpServer =====
+ System.out.println("STEP 1: Create McpServer\n");
+
+ // Configure the MCP server connection
+ // Update these values to match your MCP server setup
+ McpServer mcpTool =
+ McpServer.builder()
+ .name("my-mcp-server")
+ .url("http://localhost:8080/mcp") // Update this URL to your MCP server
+ // Optional: Add custom headers if your MCP server requires authentication
+ .headers(
+ ImmutableMap.of(
+ "Content-Type", "application/json"
+ // "Authorization", "Bearer YOUR_TOKEN"
+ ))
+ // Optional: Restrict to specific tools from the MCP server
+ // .allowedTools("weather", "calculator")
+ .build();
+
+ System.out.println("McpServer created successfully");
+ System.out.println("Name: " + mcpTool.name().orElse("N/A"));
+ System.out.println("URL: " + mcpTool.url().orElse("N/A"));
+ System.out.println();
+
+ // ===== STEP 2: Create interaction with MCP Server enabled =====
+ System.out.println("---\n");
+ System.out.println("STEP 2: Create interaction with MCP Server enabled\n");
+
+ String userQuestion =
+ "What's the weather like in San Francisco? "
+ + "(This uses the MCP server's weather tool)";
+ System.out.println("User: " + userQuestion + "\n");
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(userQuestion)
+ .tools(mcpTool)
+ .build();
+
+ // Print the request JSON
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ try {
+ Interaction response = client.interactions.create(config);
+
+ // Print the response JSON
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ // ===== STEP 3: Extract and display the results =====
+ System.out.println("---\n");
+ System.out.println("STEP 3: Extract and display the results\n");
+
+ System.out.println("Response received. Interaction ID: " + response.id());
+ System.out.println();
+
+ if (response.outputs().isPresent()) {
+ for (Content content : response.outputs().get()) {
+ if (content instanceof TextContent) {
+ System.out.println("Text: " + ((TextContent) content).text().orElse("(empty)"));
+ System.out.println();
+ } else if (content instanceof McpServerToolCallContent) {
+ McpServerToolCallContent mcpCall = (McpServerToolCallContent) content;
+ System.out.println("MCP Server Tool Call:");
+ System.out.println(" ID: " + mcpCall.id());
+ System.out.println(" Tool Name: " + mcpCall.name());
+ System.out.println(" Server Name: " + mcpCall.serverName());
+ System.out.println(" Arguments: " + mcpCall.arguments());
+ System.out.println();
+ } else if (content instanceof McpServerToolResultContent) {
+ McpServerToolResultContent mcpResult = (McpServerToolResultContent) content;
+ System.out.println("MCP Server Tool Result:");
+ System.out.println(" Call ID: " + mcpResult.callId());
+ System.out.println(" Tool Name: " + mcpResult.name().orElse("N/A"));
+ System.out.println(" Server Name: " + mcpResult.serverName().orElse("N/A"));
+ System.out.println(" Result: " + mcpResult.result());
+ System.out.println();
+ }
+ }
+ }
+
+ System.out.println("\n=== Example completed successfully ===");
+
+ } catch (Exception e) {
+ System.err.println("\n=== Error occurred ===");
+ System.err.println("Error: " + e.getMessage());
+ System.err.println("\nNote: This example requires a running MCP server.");
+ System.err.println("Please check:");
+ System.err.println(" 1. Your MCP server is running and accessible");
+ System.err.println(" 2. The URL in this example matches your MCP server endpoint");
+ System.err.println(" 3. Any required authentication headers are configured");
+ System.err.println(" 4. Your firewall allows connections to the MCP server");
+ e.printStackTrace();
+ }
+ }
+
+ private InteractionsMcpServer() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsMediaResolution.java b/examples/src/main/java/com/google/genai/examples/InteractionsMediaResolution.java
new file mode 100644
index 00000000000..ab1b25894dc
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsMediaResolution.java
@@ -0,0 +1,106 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import com.google.genai.types.interactions.MediaResolution;
+import com.google.genai.types.interactions.content.Content;
+import com.google.genai.types.interactions.content.ImageContent;
+import com.google.genai.types.interactions.content.TextContent;
+
+/**
+ * Example demonstrating MediaResolution with ImageContent in the Interactions API.
+ *
+ *
This example shows how to specify image resolution when analyzing images.
+ *
+ *
To run this example:
+ *
+ *
Set the GOOGLE_API_KEY environment variable: {@code export GOOGLE_API_KEY=YOUR_API_KEY}
+ *
Compile the examples: {@code mvn clean compile}
+ *
This method is public and static so it can be invoked via reflection for AFC.
+ */
+ public static Map getWeather(String location) {
+ System.out.println(" [AFC] Executing getWeather(\"" + location + "\")");
+ return ImmutableMap.of(
+ "location", location,
+ "temperature", "18",
+ "unit", "celsius",
+ "condition", "partly cloudy",
+ "humidity", "65%");
+ }
+
+ private static void printStepHeader(String stepTitle, String description) {
+ System.out.println(SEPARATOR);
+ System.out.println(stepTitle + ": " + description);
+ System.out.println(SEPARATOR);
+ System.out.println();
+ }
+
+ private static void printSubSection(String title) {
+ System.out.println(SUB_SEPARATOR);
+ System.out.println(title);
+ System.out.println(SUB_SEPARATOR);
+ }
+
+ private static void printInteractionDetails(Interaction interaction, long duration) {
+ System.out.println("Duration: " + duration + "ms");
+ System.out.println("ID: " + interaction.id());
+ System.out.println("Status: " + interaction.status());
+ System.out.println("Model: " + interaction.model().orElse("N/A"));
+ System.out.println("Created: " + interaction.created().map(Object::toString).orElse("N/A"));
+ System.out.println("Updated: " + interaction.updated().map(Object::toString).orElse("N/A"));
+
+ // Print outputs
+ if (interaction.outputs().isPresent() && !interaction.outputs().get().isEmpty()) {
+ System.out.println();
+ System.out.println("Outputs (" + interaction.outputs().get().size() + "):");
+ int index = 1;
+ for (Content output : interaction.outputs().get()) {
+ System.out.println(" [" + index + "] " + getContentTypeDescription(output));
+ if (output instanceof TextContent) {
+ TextContent textContent = (TextContent) output;
+ String text = textContent.text().orElse("(empty)");
+ // Truncate long text
+ if (text.length() > 100) {
+ System.out.println(" " + text.substring(0, 100) + "...");
+ } else {
+ System.out.println(" " + text);
+ }
+ } else if (output instanceof FunctionCallContent) {
+ FunctionCallContent fc = (FunctionCallContent) output;
+ System.out.println(" Function: " + fc.name());
+ System.out.println(" Arguments: " + fc.arguments());
+ }
+ index++;
+ }
+ } else {
+ System.out.println("Outputs: (none)");
+ }
+
+ // Print AFC history if present
+ if (interaction.automaticFunctionCallingHistory().isPresent()) {
+ List history = interaction.automaticFunctionCallingHistory().get();
+ System.out.println();
+ System.out.println("AFC History (" + history.size() + " interactions):");
+ for (int i = 0; i < history.size(); i++) {
+ System.out.println(" [" + (i + 1) + "] " + history.get(i).id());
+ }
+ }
+
+ System.out.println();
+ }
+
+ private static String getContentTypeDescription(Content content) {
+ if (content instanceof TextContent) {
+ return "TextContent";
+ } else if (content instanceof FunctionCallContent) {
+ return "FunctionCallContent";
+ } else {
+ return content.getClass().getSimpleName();
+ }
+ }
+
+ private static void validateInteractions(
+ Interaction expected, Interaction actual, String expectedLabel, String actualLabel) {
+ boolean allPassed = true;
+
+ // Validate ID
+ if (expected.id().equals(actual.id())) {
+ System.out.println("✅ ID matches: " + expected.id());
+ } else {
+ System.out.println(
+ "❌ ID mismatch: " + expectedLabel + "=" + expected.id() + ", " + actualLabel + "="
+ + actual.id());
+ allPassed = false;
+ }
+
+ // Validate Status
+ String expectedStatus = expected.status().toString();
+ String actualStatus = actual.status().toString();
+ if (expectedStatus.equals(actualStatus)) {
+ System.out.println("✅ Status matches: " + expectedStatus);
+ } else {
+ System.out.println(
+ "❌ Status mismatch: " + expectedLabel + "=" + expectedStatus + ", " + actualLabel + "="
+ + actualStatus);
+ allPassed = false;
+ }
+
+ // Validate Model
+ String expectedModel = expected.model().orElse("N/A");
+ String actualModel = actual.model().orElse("N/A");
+ if (expectedModel.equals(actualModel)) {
+ System.out.println("✅ Model matches: " + expectedModel);
+ } else {
+ System.out.println(
+ "❌ Model mismatch: " + expectedLabel + "=" + expectedModel + ", " + actualLabel + "="
+ + actualModel);
+ allPassed = false;
+ }
+
+ // Summary
+ System.out.println();
+ if (allPassed) {
+ System.out.println("✅ ALL VALIDATIONS PASSED");
+ } else {
+ System.out.println("❌ SOME VALIDATIONS FAILED");
+ }
+ }
+
+ private static void saveResponse(String filename, String content) {
+ String timestamp = LocalDateTime.now().format(TIMESTAMP_FORMAT);
+ System.out.println("📝 Response saved to: interaction_lifecycle_logs/" + filename);
+ System.out.println(" Timestamp: " + timestamp);
+ // In a real implementation, you would write to file here
+ // For now, just log that we would save it
+ }
+
+ private InteractionsMultipleToolsLifecycle() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsPreviousInteractionId.java b/examples/src/main/java/com/google/genai/examples/InteractionsPreviousInteractionId.java
new file mode 100644
index 00000000000..984c7ccb237
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsPreviousInteractionId.java
@@ -0,0 +1,177 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import com.google.genai.types.interactions.Usage;
+import com.google.genai.types.interactions.content.Content;
+import com.google.genai.types.interactions.content.TextContent;
+
+/**
+ * Example: Conversation Continuity with previousInteractionId
+ *
+ *
Demonstrates how to link interactions using previousInteractionId to maintain conversation
+ * context across separate API calls. This example verifies context is preserved by asking for
+ * 10 random numbers, then asking the model to perform various math operations on them:
+ * addition, multiplication, and calculating mean/median/mode.
+ *
+ *
To run this example:
+ *
+ *
+ *
Set the GOOGLE_API_KEY environment variable: {@code export GOOGLE_API_KEY=YOUR_API_KEY}
+ *
Compile the examples: {@code mvn clean compile}
+ *
This example demonstrates testing for the annotations field in TextContent responses
+ * from the Interactions API. The annotations field provides citation information for
+ * model-generated content.
+ *
+ *
Structure: TextContent contains:
+ * - type: "text"
+ * - text: The actual text content
+ * - annotations: Optional array of Annotation objects for citations
+ *
+ *
Each Annotation contains:
+ * - start_index: Start byte position of cited segment
+ * - end_index: End byte position of cited segment (exclusive)
+ * - source: Source reference (URL, title, etc.)
+ *
+ *
This example tests various prompts to see if the API returns annotations.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsTextAnnotations {
+
+ public static void main(String[] args) {
+ Client client = new Client();
+
+ System.out.println("=== TextContent Annotations Testing Example ===\n");
+ System.out.println("Testing if the Interactions API returns annotations in TextContent\n");
+
+ // Test Case 1: Simple factual question
+ testAnnotations(
+ client,
+ "Test Case 1: Simple Factual Question",
+ "What is the capital of France?");
+
+ // Test Case 2: Question that might trigger citations
+ testAnnotations(
+ client,
+ "Test Case 2: Request with Explicit Citation Request",
+ "Tell me about climate change and cite your sources.");
+
+ // Test Case 3: Research-oriented question
+ testAnnotations(
+ client,
+ "Test Case 3: Research Question",
+ "What are the latest advancements in quantum computing? Please provide citations.");
+
+ // Test Case 4: Grounding/search request
+ testAnnotations(
+ client,
+ "Test Case 4: Grounding Request",
+ "Search for information about the Paris Agreement and summarize it with citations.");
+
+ System.out.println("\n=== All test cases completed ===");
+ }
+
+ /**
+ * Test helper that makes an API call and checks for annotations in the response.
+ */
+ private static void testAnnotations(Client client, String testName, String prompt) {
+ System.out.println("\n--- " + testName + " ---\n");
+
+ try {
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(prompt)
+ .build();
+
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ Interaction response = client.interactions.create(config);
+
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ analyzeAnnotations(response);
+
+ } catch (Exception e) {
+ System.err.println("ERROR in " + testName + ":");
+ System.err.println(" Exception: " + e.getClass().getName());
+ System.err.println(" Message: " + e.getMessage());
+ e.printStackTrace();
+ }
+ }
+
+ /**
+ * Analyzes interaction outputs to find and display annotations.
+ */
+ private static void analyzeAnnotations(Interaction interaction) {
+ System.out.println("Results:");
+
+ if (!interaction.outputs().isPresent() || interaction.outputs().get().isEmpty()) {
+ System.out.println(" ❌ No outputs found in response");
+ return;
+ }
+
+ boolean foundAnnotations = false;
+ int textContentCount = 0;
+ int totalAnnotations = 0;
+
+ for (Content content : interaction.outputs().get()) {
+ if (content instanceof TextContent) {
+ textContentCount++;
+ TextContent textContent = (TextContent) content;
+
+ System.out.println("\n TextContent #" + textContentCount + ":");
+ System.out.println(" Text: " + textContent.text().orElse("(empty)"));
+
+ if (textContent.annotations().isPresent() && !textContent.annotations().get().isEmpty()) {
+ foundAnnotations = true;
+ List annotations = textContent.annotations().get();
+ totalAnnotations += annotations.size();
+
+ System.out.println(" ✅ ANNOTATIONS FOUND: " + annotations.size() + " annotation(s)");
+
+ for (int i = 0; i < annotations.size(); i++) {
+ Annotation ann = annotations.get(i);
+ System.out.println("\n Annotation " + (i + 1) + ":");
+ System.out.println(" Start Index: " + ann.startIndex().orElse(null));
+ System.out.println(" End Index: " + ann.endIndex().orElse(null));
+ System.out.println(" Source: " + ann.source().orElse("(none)"));
+
+ // Show the cited text segment if indices are present
+ if (ann.startIndex().isPresent()
+ && ann.endIndex().isPresent()
+ && textContent.text().isPresent()) {
+ String text = textContent.text().get();
+ int start = ann.startIndex().get();
+ int end = ann.endIndex().get();
+ if (start >= 0 && end <= text.length() && start < end) {
+ String citedText = text.substring(start, end);
+ System.out.println(" Cited Text: \"" + citedText + "\"");
+ }
+ }
+ }
+ } else {
+ System.out.println(" ❌ No annotations found in this TextContent");
+ }
+ }
+ }
+
+ System.out.println("\n SUMMARY:");
+ System.out.println(" Total TextContent blocks: " + textContentCount);
+ System.out.println(" Total annotations found: " + totalAnnotations);
+
+ if (foundAnnotations) {
+ System.out.println(" ✅ SUCCESS: The API returned annotations!");
+ } else {
+ System.out.println(" ⚠️ The API did not return annotations for this request.");
+ System.out.println(" This could mean:");
+ System.out.println(" - The model didn't use external sources");
+ System.out.println(" - The annotations feature may not be enabled yet");
+ System.out.println(" - This specific prompt didn't trigger citations");
+ }
+ }
+
+ private InteractionsTextAnnotations() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsThoughtContent.java b/examples/src/main/java/com/google/genai/examples/InteractionsThoughtContent.java
new file mode 100644
index 00000000000..3e25df03dff
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsThoughtContent.java
@@ -0,0 +1,295 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Usage:
+ *
+ *
Note: The Interactions API is currently only available via the Gemini Developer API (not
+ * Vertex AI).
+ *
+ *
1. Set an API key environment variable. You can find a list of available API keys here:
+ * https://aistudio.google.com/app/apikey
+ *
+ *
export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ *
2. Compile the java package and run the sample code.
+ *
+ *
This example tests the ThoughtContent functionality to understand how the model's internal
+ * reasoning is exposed through the Interactions API.
+ *
+ *
Structure: ThoughtContent contains:
+ * - signature: A cryptographic signature for the thought
+ * - summary: Optional list of Content (TextContent, ImageContent, etc.)
+ *
+ *
The summary field matches Python's structure: Optional[List[Union[TextContent, ImageContent]]]
+ * allowing the model to provide reasoning summaries with both text and visual elements.
+ *
+ *
Test Cases: 1. Simple Math Reasoning - Basic arithmetic with step-by-step thinking 2. Complex
+ * Logic Puzzle - Multi-step reasoning task 3. Reasoning with extended thinking mode
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsThoughtContent {
+
+ public static void main(String[] args) {
+ Client client = new Client();
+
+ System.out.println("=== ThoughtContent Testing Example ===\n");
+ System.out.println("Testing model's internal reasoning (ThoughtContent)\n");
+
+ // Test Case 1: Simple Math Reasoning
+ testSimpleMathReasoning(client);
+
+ // Test Case 2: Complex Logic Puzzle
+ testComplexLogicPuzzle(client);
+
+ // Test Case 3: Extended Thinking Mode
+ testExtendedThinking(client);
+
+ System.out.println("\n=== All tests completed ===");
+ }
+
+ /**
+ * Test Case 1: Simple Math Reasoning
+ *
+ *
Tests if ThoughtContent appears for basic arithmetic reasoning.
+ */
+ private static void testSimpleMathReasoning(Client client) {
+ System.out.println("\n--- Test Case 1: Simple Math Reasoning ---\n");
+
+ String prompt = "Think step by step: What is 15 * 24?";
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder().model("gemini-2.5-flash").input(prompt).build();
+
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ try {
+ Interaction response = client.interactions.create(config);
+
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ printResults(response);
+ analyzeContent(response);
+
+ } catch (Exception e) {
+ System.err.println("ERROR in Test Case 1:");
+ System.err.println(" Exception: " + e.getClass().getName());
+ System.err.println(" Message: " + e.getMessage());
+ e.printStackTrace();
+ }
+ }
+
+ /**
+ * Test Case 2: Complex Logic Puzzle
+ *
+ *
Tests ThoughtContent with a more complex reasoning task that requires multiple steps.
+ */
+ private static void testComplexLogicPuzzle(Client client) {
+ System.out.println("\n--- Test Case 2: Complex Logic Puzzle ---\n");
+
+ String prompt =
+ "Solve this logic puzzle step by step:\n"
+ + "Three friends - Alice, Bob, and Carol - each have a different favorite color (red,"
+ + " blue, or green).\n"
+ + "- Alice doesn't like blue\n"
+ + "- Bob's favorite color is not red\n"
+ + "- Carol likes green\n"
+ + "What is each person's favorite color? Show your reasoning.";
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder().model("gemini-2.5-flash").input(prompt).build();
+
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ try {
+ Interaction response = client.interactions.create(config);
+
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ printResults(response);
+ analyzeContent(response);
+
+ } catch (Exception e) {
+ System.err.println("ERROR in Test Case 2:");
+ System.err.println(" Exception: " + e.getClass().getName());
+ System.err.println(" Message: " + e.getMessage());
+ e.printStackTrace();
+ }
+ }
+
+ /**
+ * Test Case 3: Extended Thinking Mode
+ *
+ *
Tests ThoughtContent with a reasoning-heavy task.
+ */
+ private static void testExtendedThinking(Client client) {
+ System.out.println("\n--- Test Case 3: Extended Thinking Test ---\n");
+
+ String prompt =
+ "Calculate the following and explain your reasoning:\n"
+ + "If a train travels at 60 mph for 2.5 hours, then speeds up to 80 mph for another 1.5"
+ + " hours, how far does it travel in total?";
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(prompt)
+ .build();
+
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ try {
+ Interaction response = client.interactions.create(config);
+
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ printResults(response);
+ analyzeContent(response);
+
+ } catch (Exception e) {
+ System.err.println("ERROR in Test Case 3:");
+ System.err.println(" Exception: " + e.getClass().getName());
+ System.err.println(" Message: " + e.getMessage());
+ e.printStackTrace();
+ }
+ }
+
+ private static void printResults(Interaction interaction) {
+ System.out.println("Results:");
+ System.out.println(" Interaction ID: " + interaction.id());
+ System.out.println(" Status: " + interaction.status());
+ }
+
+ /**
+ * Analyzes interaction content to identify and display ThoughtContent.
+ *
+ *
This method: - Iterates through all outputs in the interaction - Identifies ThoughtContent
+ * instances - Displays thought signatures and summaries - Compares actual structure with expected
+ * structure
+ */
+ private static void analyzeContent(Interaction interaction) {
+ System.out.println("CONTENT ANALYSIS:");
+
+ if (!interaction.outputs().isPresent() || interaction.outputs().get().isEmpty()) {
+ System.out.println(" No outputs found in response");
+ return;
+ }
+
+ int thoughtCount = 0;
+ int textCount = 0;
+ int otherCount = 0;
+
+ System.out.println("\n Analyzing " + interaction.outputs().get().size() + " output(s):");
+
+ for (Content content : interaction.outputs().get()) {
+ System.out.println("\n Content Type: " + content.getClass().getSimpleName());
+
+ if (content instanceof ThoughtContent) {
+ thoughtCount++;
+ ThoughtContent thought = (ThoughtContent) content;
+
+ System.out.println(" >>> THOUGHT CONTENT FOUND <<<");
+ System.out.println(" Signature: " + thought.signature().orElse("(none)"));
+
+ if (thought.summary().isPresent()) {
+ List summaryContents = thought.summary().get();
+ System.out.println(" Summary: " + summaryContents.size() + " item(s)");
+
+ for (int i = 0; i < summaryContents.size(); i++) {
+ ThoughtSummaryContent summaryItem = summaryContents.get(i);
+ System.out.println(" Item " + (i + 1) + ": " + summaryItem.getClass().getSimpleName());
+
+ if (summaryItem instanceof TextContent) {
+ String text = ((TextContent) summaryItem).text().orElse("(empty)");
+ String preview = text.length() > 100 ? text.substring(0, 100) + "..." : text;
+ System.out.println(" Text: " + preview);
+ } else if (summaryItem instanceof ImageContent) {
+ System.out.println(" Image: " + ((ImageContent) summaryItem).uri().orElse("(no uri)"));
+ }
+ }
+ } else {
+ System.out.println(" Summary: (none)");
+ }
+
+ System.out.println(" Full ThoughtContent JSON:");
+ System.out.println(" " + thought.toJson());
+
+ } else if (content instanceof TextContent) {
+ textCount++;
+ TextContent text = (TextContent) content;
+ String textValue = text.text().orElse("(empty)");
+ String preview = textValue.length() > 100 ? textValue.substring(0, 100) + "..." : textValue;
+ System.out.println(" Text Preview: " + preview);
+ } else {
+ otherCount++;
+ System.out.println(" Content Class: " + content.getClass().getName());
+ }
+ }
+
+ System.out.println("\n SUMMARY:");
+ System.out.println(" ThoughtContent instances: " + thoughtCount);
+ System.out.println(" TextContent instances: " + textCount);
+ System.out.println(" Other content instances: " + otherCount);
+
+ if (thoughtCount == 0) {
+ System.out.println(
+ "\n NOTE: No ThoughtContent found. This may be expected if the model didn't use"
+ + " internal reasoning for this query.");
+ }
+
+ // Display final text output
+ if (interaction.outputs().isPresent() && !interaction.outputs().get().isEmpty()) {
+ System.out.println("\n FINAL TEXT OUTPUT:");
+ for (Content output : interaction.outputs().get()) {
+ if (output instanceof TextContent) {
+ System.out.println(" " + ((TextContent) output).text().orElse("(empty)"));
+ }
+ }
+ }
+ }
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsUrlContext.java b/examples/src/main/java/com/google/genai/examples/InteractionsUrlContext.java
new file mode 100644
index 00000000000..a9f397d5361
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsUrlContext.java
@@ -0,0 +1,143 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Usage:
+ *
+ *
Note: The Interactions API is currently only available via the Gemini Developer API (not
+ * Vertex AI).
+ *
+ *
1. Set an API key environment variable. You can find a list of available API keys here:
+ * https://aistudio.google.com/app/apikey
+ *
+ *
export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ *
2. Compile the java package and run the sample code.
+ *
+ *
Demonstrates how to use the UrlContext to enable the model to retrieve and use context
+ * from URLs. The model can fetch web pages and use their content to answer questions.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class InteractionsUrlContext {
+
+ public static void main(String[] args) {
+ // Instantiate the client. The client gets the API key from the environment variable
+ // `GOOGLE_API_KEY`.
+ //
+ Client client = new Client();
+
+ System.out.println("=== Interactions API: URL Context Tool Example ===\n");
+
+ // ===== STEP 1: Create UrlContext =====
+ System.out.println("STEP 1: Create UrlContext\n");
+
+ UrlContext urlTool = UrlContext.builder().build();
+
+ System.out.println("UrlContext created successfully\n");
+
+ // ===== STEP 2: Create interaction with URL Context enabled =====
+ System.out.println("---\n");
+ System.out.println("STEP 2: Create interaction with URL Context enabled\n");
+
+ String userQuestion =
+ "Please fetch and summarize the content from https://www.wikipedia.org/wiki/Artificial_intelligence";
+ System.out.println("User: " + userQuestion + "\n");
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .input(userQuestion)
+ .tools(urlTool)
+ .build();
+
+ // Print the request JSON
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ Interaction response = client.interactions.create(config);
+
+ // Print the response JSON
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ // ===== STEP 3: Extract and display the results =====
+ System.out.println("---\n");
+ System.out.println("STEP 3: Extract and display the results\n");
+
+ System.out.println("Response received. Interaction ID: " + response.id());
+ System.out.println();
+
+ if (response.outputs().isPresent()) {
+ for (Content content : response.outputs().get()) {
+ if (content instanceof TextContent) {
+ System.out.println("Text: " + ((TextContent) content).text().orElse("(empty)"));
+ System.out.println();
+ } else if (content instanceof UrlContextCallContent) {
+ UrlContextCallContent urlCall = (UrlContextCallContent) content;
+ System.out.println("URL Context Call:");
+ System.out.println(" ID: " + urlCall.id());
+ if (urlCall.arguments().isPresent()) {
+ System.out.println(" URLs: " + urlCall.arguments().get().urls().orElse(java.util.List.of()));
+ }
+ System.out.println();
+ } else if (content instanceof UrlContextResultContent) {
+ UrlContextResultContent urlResult = (UrlContextResultContent) content;
+ System.out.println("URL Context Result:");
+ System.out.println(" Call ID: " + urlResult.callId().orElse("N/A"));
+ System.out.println(" Is Error: " + urlResult.isError().orElse(false));
+
+ if (urlResult.result().isPresent()) {
+ List results = urlResult.result().get();
+ System.out.println(" Results: " + results.size() + " found");
+ for (int i = 0; i < results.size(); i++) {
+ UrlContextResult result = results.get(i);
+ System.out.println(" [" + (i + 1) + "] URL: " + result.url().orElse("N/A"));
+ System.out.println(" Status: " + result.status().map(Object::toString).orElse("N/A"));
+ }
+ }
+ System.out.println();
+ }
+ }
+ }
+
+ System.out.println("\n=== Example completed ===");
+ }
+
+ private InteractionsUrlContext() {}
+}
diff --git a/examples/src/main/java/com/google/genai/examples/InteractionsVideoContent.java b/examples/src/main/java/com/google/genai/examples/InteractionsVideoContent.java
new file mode 100644
index 00000000000..e4a5239f353
--- /dev/null
+++ b/examples/src/main/java/com/google/genai/examples/InteractionsVideoContent.java
@@ -0,0 +1,106 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import com.google.genai.types.interactions.content.Content;
+import com.google.genai.types.interactions.content.TextContent;
+import com.google.genai.types.interactions.content.VideoContent;
+
+/**
+ * Example demonstrating video analysis using VideoContent with the Interactions API.
+ *
+ *
This example shows:
+ *
+ *
Using VideoContent.fromUri() to analyze a video from a URL
+ *
+ *
+ *
Note: Inline base64-encoded video is not shown because video files are typically
+ * large and not suitable for inline embedding.
+ *
+ *
To run this example:
+ *
+ *
Set the GOOGLE_API_KEY environment variable: {@code export GOOGLE_API_KEY=YOUR_API_KEY}
+ *
Compile the examples: {@code mvn clean compile}
+ *
Note: The Interactions API is currently in beta.
+ */
+public final class InteractionsVideoContent {
+
+ public static void main(String[] args) {
+ Client client = new Client();
+
+ System.out.println("=== Interactions API: Video Content Example ===\n");
+
+ try {
+ // ===== Video from URI =====
+ System.out.println("--- Video from URI ---\n");
+
+ String videoUri = "https://storage.googleapis.com/cloud-samples-data/generative-ai/video/pixel8.mp4";
+ VideoContent videoContent = VideoContent.fromUri(videoUri, "video/mp4");
+ TextContent textPrompt = TextContent.builder()
+ .text("Describe what happens in this video.")
+ .build();
+
+ CreateInteractionConfig config =
+ CreateInteractionConfig.builder()
+ .model("gemini-2.5-flash")
+ .inputFromContents(textPrompt, videoContent)
+ .build();
+
+ System.out.println("=== REQUEST ===");
+ System.out.println(config.toJson());
+ System.out.println();
+
+ Interaction response = client.interactions.create(config);
+
+ System.out.println("=== RESPONSE ===");
+ System.out.println(response.toJson());
+ System.out.println();
+
+ printResults(response);
+
+ System.out.println("\n=== Example completed ===");
+
+ } catch (Exception e) {
+ System.err.println("Error: " + e.getMessage());
+ e.printStackTrace();
+ }
+ }
+
+ private static void printResults(Interaction interaction) {
+ System.out.println("Results:");
+ System.out.println(" Interaction ID: " + interaction.id());
+ System.out.println(" Status: " + interaction.status());
+
+ if (interaction.outputs().isPresent() && !interaction.outputs().get().isEmpty()) {
+ for (Content output : interaction.outputs().get()) {
+ if (output instanceof TextContent) {
+ System.out.println(" Text: " + ((TextContent) output).text().orElse("(empty)"));
+ } else {
+ System.out.println(" " + output.getClass().getSimpleName());
+ }
+ }
+ }
+ }
+
+ private InteractionsVideoContent() {}
+}
diff --git a/pom.xml b/pom.xml
index 90a90201ab4..082489f5a2d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -323,6 +323,7 @@
com/google/genai/types/AutoValue_*.class
+ com/google/genai/types/interactions/AutoValue_*.class
diff --git a/src/main/java/com/google/genai/AsyncInteractions.java b/src/main/java/com/google/genai/AsyncInteractions.java
new file mode 100644
index 00000000000..d8af33bb5ac
--- /dev/null
+++ b/src/main/java/com/google/genai/AsyncInteractions.java
@@ -0,0 +1,191 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Auto-generated code. Do not edit.
+
+package com.google.genai;
+
+import com.google.genai.Common.BuiltRequest;
+import com.google.genai.types.interactions.CancelInteractionConfig;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.DeleteInteractionConfig;
+import com.google.genai.types.interactions.DeleteInteractionResponse;
+import com.google.genai.types.interactions.GetInteractionConfig;
+import com.google.genai.types.interactions.Interaction;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Provides asynchronous methods for managing interactions. Instantiating this class is not
+ * required. After instantiating a {@link Client}, access methods through
+ * `client.async.interactions.methodName(...)` directly.
+ *
+ *
The Interactions API is available in both Vertex AI and Gemini API.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class AsyncInteractions {
+ Interactions interactions;
+ ApiClient apiClient;
+
+ public AsyncInteractions(ApiClient apiClient) {
+ this.apiClient = apiClient;
+ this.interactions = new Interactions(apiClient);
+ }
+
+ /**
+ * Asynchronously creates a new interaction with the specified configuration.
+ *
+ *
Either {@code model} or {@code agent} must be specified in the config, but not both.
+ *
+ *
Example usage for model-based interaction:
+ *
+ *
Example usage for agent-based interaction:
+ *
+ *
{@code
+ * CreateInteractionConfig config = CreateInteractionConfig.builder()
+ * .agent("deep-research-pro-preview-12-2025")
+ * .input("Research the history of quantum computing")
+ * .build();
+ * CompletableFuture future = client.async.interactions.create(config);
+ * }
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param config The configuration for creating the interaction
+ * @return A CompletableFuture containing the created Interaction with outputs
+ * @throws IllegalArgumentException if both model and agent are specified, or neither is specified
+ * @throws UnsupportedOperationException if using Vertex AI (not yet supported)
+ */
+ public CompletableFuture create(CreateInteractionConfig config) {
+ BuiltRequest builtRequest = interactions.buildRequestForCreate(config);
+
+ return this.apiClient
+ .asyncRequest("post", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())
+ .thenApplyAsync(
+ response -> {
+ try (ApiResponse res = response) {
+ return interactions.processResponseForCreate(res, config);
+ }
+ });
+ }
+
+ /**
+ * Asynchronously retrieves an interaction by its ID.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param id The ID of the interaction to retrieve
+ * @param config The configuration for the get request (can be null)
+ * @return A CompletableFuture containing the retrieved Interaction
+ */
+ public CompletableFuture get(String id, GetInteractionConfig config) {
+ BuiltRequest builtRequest = interactions.buildRequestForGet(id, config);
+
+ return this.apiClient
+ .asyncRequest("get", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())
+ .thenApplyAsync(
+ response -> {
+ try (ApiResponse res = response) {
+ return interactions.processResponseForGet(res, config);
+ }
+ });
+ }
+
+ /**
+ * Asynchronously cancels a background interaction that is still in progress.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param id The ID of the interaction to cancel
+ * @param config The configuration for the cancel request (can be null)
+ * @return A CompletableFuture containing the updated Interaction
+ */
+ public CompletableFuture cancel(String id, CancelInteractionConfig config) {
+ BuiltRequest builtRequest = interactions.buildRequestForCancel(id, config);
+
+ return this.apiClient
+ .asyncRequest("post", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())
+ .thenApplyAsync(
+ response -> {
+ try (ApiResponse res = response) {
+ return interactions.processResponseForCancel(res, config);
+ }
+ });
+ }
+
+ /**
+ * Asynchronously deletes an interaction by its ID.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param id The ID of the interaction to delete
+ * @param config The configuration for the delete request (can be null)
+ * @return A CompletableFuture containing the delete response
+ */
+ public CompletableFuture delete(
+ String id, DeleteInteractionConfig config) {
+ BuiltRequest builtRequest = interactions.buildRequestForDelete(id, config);
+
+ return this.apiClient
+ .asyncRequest(
+ "delete", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())
+ .thenApplyAsync(
+ response -> {
+ try (ApiResponse res = response) {
+ return interactions.processResponseForDelete(res, config);
+ }
+ });
+ }
+}
diff --git a/src/main/java/com/google/genai/Client.java b/src/main/java/com/google/genai/Client.java
index 0bc250b550b..22772ec2087 100644
--- a/src/main/java/com/google/genai/Client.java
+++ b/src/main/java/com/google/genai/Client.java
@@ -41,6 +41,7 @@ public final class Async {
public final AsyncTokens authTokens;
public final AsyncTunings tunings;
public final AsyncFileSearchStores fileSearchStores;
+ public final AsyncInteractions interactions;
public Async(ApiClient apiClient) {
this.models = new AsyncModels(apiClient);
@@ -53,6 +54,7 @@ public Async(ApiClient apiClient) {
this.authTokens = new AsyncTokens(apiClient);
this.tunings = new AsyncTunings(apiClient);
this.fileSearchStores = new AsyncFileSearchStores(apiClient);
+ this.interactions = new AsyncInteractions(apiClient);
}
}
@@ -68,6 +70,7 @@ public Async(ApiClient apiClient) {
public final Tokens authTokens;
public final Tunings tunings;
public final FileSearchStores fileSearchStores;
+ public final Interactions interactions;
/** Builder for {@link Client}. */
public static class Builder {
@@ -280,6 +283,7 @@ private Client(
authTokens = new Tokens(this.apiClient);
tunings = new Tunings(this.apiClient);
fileSearchStores = new FileSearchStores(this.apiClient);
+ interactions = new Interactions(this.apiClient);
}
/** Returns whether the client is using Vertex AI APIs. */
diff --git a/src/main/java/com/google/genai/DebugConfig.java b/src/main/java/com/google/genai/DebugConfig.java
index fcefa933332..292c2b839dc 100644
--- a/src/main/java/com/google/genai/DebugConfig.java
+++ b/src/main/java/com/google/genai/DebugConfig.java
@@ -16,6 +16,7 @@
package com.google.genai;
+
/** Data class configuration for debugging or testing the Client. */
@ExcludeFromGeneratedCoverageReport
final class DebugConfig {
diff --git a/src/main/java/com/google/genai/Interactions.java b/src/main/java/com/google/genai/Interactions.java
new file mode 100644
index 00000000000..0a1145dd419
--- /dev/null
+++ b/src/main/java/com/google/genai/Interactions.java
@@ -0,0 +1,632 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.genai;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.google.genai.Common.BuiltRequest;
+import com.google.genai.errors.GenAiIOException;
+import com.google.genai.types.HttpOptions;
+import com.google.genai.types.HttpResponse;
+import com.google.genai.types.interactions.CancelInteractionConfig;
+import com.google.genai.types.interactions.CancelInteractionParameters;
+import com.google.genai.types.interactions.CreateInteractionConfig;
+import com.google.genai.types.interactions.CreateInteractionParameters;
+import com.google.genai.types.interactions.DeleteInteractionConfig;
+import com.google.genai.types.interactions.DeleteInteractionParameters;
+import com.google.genai.types.interactions.DeleteInteractionResponse;
+import com.google.genai.types.interactions.GetInteractionConfig;
+import com.google.genai.types.interactions.GetInteractionParameters;
+import com.google.genai.types.interactions.Interaction;
+import java.io.IOException;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import okhttp3.Headers;
+import okhttp3.ResponseBody;
+
+/**
+ * Provides methods for managing interactions. Instantiating this class is not required. After
+ * instantiating a {@link Client}, access methods through `client.interactions.methodName(...)`
+ * directly.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ */
+public final class Interactions {
+
+ final ApiClient apiClient;
+
+ public Interactions(ApiClient apiClient) {
+ this.apiClient = apiClient;
+ }
+
+ /**
+ * Copies a field from source to target if it exists, without transformation.
+ *
+ * @param fromObject Source JSON node
+ * @param parentObject Target ObjectNode to populate
+ * @param fieldName Name of the field to copy
+ */
+ private void copyFieldIfPresent(JsonNode fromObject, ObjectNode parentObject, String fieldName) {
+ Object value = Common.getValueByPath(fromObject, new String[] {fieldName});
+ if (value != null) {
+ Common.setValueByPath(parentObject, new String[] {fieldName}, value);
+ }
+ }
+
+ /**
+ * Copies a field from source to target with a transformation function.
+ *
+ * @param fromObject Source JSON node
+ * @param parentObject Target ObjectNode to populate
+ * @param fieldName Name of the field to copy
+ * @param transformer Function to transform the value
+ */
+ private void copyFieldWithTransform(
+ JsonNode fromObject,
+ ObjectNode parentObject,
+ String fieldName,
+ java.util.function.Function transformer) {
+ Object value = Common.getValueByPath(fromObject, new String[] {fieldName});
+ if (value != null) {
+ Common.setValueByPath(parentObject, new String[] {fieldName}, transformer.apply(value));
+ }
+ }
+
+ /**
+ * Transforms CreateInteractionConfig to the request body format. This transformation is identical
+ * for both Vertex AI and MLDev platforms. Only the endpoint path differs (handled by
+ * ApiClient.buildMaybeVertexPath).
+ *
+ * @param fromObject Source JSON node containing the config
+ * @param parentObject Target ObjectNode to populate (modified in place)
+ */
+ @ExcludeFromGeneratedCoverageReport
+ void createInteractionConfig(JsonNode fromObject, ObjectNode parentObject) {
+ // Simple fields - no transformation
+ // Note: Field names must match @JsonProperty annotations (snake_case)
+ copyFieldIfPresent(fromObject, parentObject, "input");
+ copyFieldIfPresent(fromObject, parentObject, "agent");
+ copyFieldIfPresent(fromObject, parentObject, "background");
+ copyFieldIfPresent(fromObject, parentObject, "generation_config");
+ copyFieldIfPresent(fromObject, parentObject, "agent_config");
+ copyFieldIfPresent(fromObject, parentObject, "previous_interaction_id");
+ copyFieldIfPresent(fromObject, parentObject, "response_format");
+ copyFieldIfPresent(fromObject, parentObject, "response_mime_type");
+ copyFieldIfPresent(fromObject, parentObject, "response_modalities");
+ copyFieldIfPresent(fromObject, parentObject, "store");
+ // Tool types serialize directly with their type discriminator
+ copyFieldIfPresent(fromObject, parentObject, "tools");
+
+ // Fields with transformation
+ // Note: Interactions API expects raw model string, not transformed
+ copyFieldIfPresent(fromObject, parentObject, "model");
+ copyFieldWithTransform(
+ fromObject,
+ parentObject,
+ "system_instruction",
+ value -> JsonSerializable.toJsonNode(Transformers.tContent(value)));
+ }
+
+ /**
+ * Transforms CreateInteractionParameters to the request body. Platform-agnostic - works for both
+ * Vertex AI and MLDev.
+ *
+ * @param fromObject Source JSON node containing the parameters
+ * @return Transformed ObjectNode ready for the request body
+ */
+ @ExcludeFromGeneratedCoverageReport
+ ObjectNode createInteractionParameters(JsonNode fromObject) {
+ ObjectNode toObject = JsonSerializable.objectMapper().createObjectNode();
+
+ if (Common.getValueByPath(fromObject, new String[] {"config"}) != null) {
+ createInteractionConfig(
+ JsonSerializable.toJsonNode(Common.getValueByPath(fromObject, new String[] {"config"})),
+ toObject);
+ }
+
+ return toObject;
+ }
+
+ /** A shared buildRequest method for both sync and async methods. */
+ BuiltRequest buildRequestForCreate(CreateInteractionConfig config) {
+ // Validation: exactly one of model or agent must be specified
+ boolean hasModel = config.model().isPresent() && !config.model().get().isEmpty();
+ boolean hasAgent = config.agent().isPresent() && !config.agent().get().isEmpty();
+
+ if (hasModel && hasAgent) {
+ throw new IllegalArgumentException(
+ "Cannot specify both 'model' and 'agent'. Please provide only one.");
+ }
+
+ if (!hasModel && !hasAgent) {
+ throw new IllegalArgumentException(
+ "Must specify either 'model' or 'agent' in CreateInteractionConfig.");
+ }
+
+ // Validation: agentConfig only with agent, generationConfig only with model
+ if (hasAgent && config.generationConfig().isPresent()) {
+ throw new IllegalArgumentException(
+ "Cannot use 'generationConfig' with agent-based interactions. "
+ + "Use 'agentConfig' instead.");
+ }
+
+ if (hasModel && config.agentConfig().isPresent()) {
+ throw new IllegalArgumentException(
+ "Cannot use 'agentConfig' with model-based interactions. "
+ + "Use 'generationConfig' instead.");
+ }
+
+ CreateInteractionParameters.Builder parameterBuilder = CreateInteractionParameters.builder();
+
+ if (!Common.isZero(config)) {
+ parameterBuilder.config(config);
+ }
+ JsonNode parameterNode = JsonSerializable.toJsonNode(parameterBuilder.build());
+
+ ObjectNode body = createInteractionParameters(parameterNode);
+ String path = "interactions";
+
+ // The "_query" key is used internally to store query parameters
+ // that will be appended to the URL
+ JsonNode queryParams = body.get("_query");
+ if (queryParams != null) {
+ body.remove("_query");
+ path = String.format("%s?%s", path, Common.urlEncode((ObjectNode) queryParams));
+ }
+
+ Optional requestHttpOptions = Optional.empty();
+ if (config != null) {
+ requestHttpOptions = config.httpOptions();
+ }
+
+ String requestBody = JsonSerializable.toJsonString(body);
+ return new BuiltRequest(path, requestBody, requestHttpOptions);
+ }
+
+ /** A shared processResponse function for both sync and async methods. */
+ Interaction processResponseForCreate(ApiResponse response, CreateInteractionConfig config) {
+ ResponseBody responseBody = response.getBody();
+ String responseString;
+ try {
+ responseString = responseBody.string();
+ } catch (IOException e) {
+ throw new GenAiIOException("Failed to read HTTP response.", e);
+ }
+
+ JsonNode responseNode = JsonSerializable.stringToJsonNode(responseString);
+
+ Interaction sdkResponse = JsonSerializable.fromJsonNode(responseNode, Interaction.class);
+ Headers responseHeaders = response.getHeaders();
+ if (responseHeaders == null) {
+ return sdkResponse;
+ }
+ Map headers = new HashMap<>();
+ for (String headerName : responseHeaders.names()) {
+ headers.put(headerName, responseHeaders.get(headerName));
+ }
+ return sdkResponse.toBuilder().sdkHttpResponse(HttpResponse.builder().headers(headers)).build();
+ }
+
+ /** A shared buildRequest method for both sync and async methods. */
+ BuiltRequest buildRequestForGet(String id, GetInteractionConfig config) {
+
+ // Validation: id must be non-empty
+ if (id == null || id.isEmpty()) {
+ throw new IllegalArgumentException("Interaction ID must not be empty");
+ }
+
+ GetInteractionParameters.Builder parameterBuilder = GetInteractionParameters.builder();
+
+ if (!Common.isZero(id)) {
+ parameterBuilder.id(id);
+ }
+ if (!Common.isZero(config)) {
+ parameterBuilder.config(config);
+ }
+ JsonNode parameterNode = JsonSerializable.toJsonNode(parameterBuilder.build());
+
+ // Transform ID parameter into URL placeholder using special "_url" key
+ // The "_url" key is used internally to store URL path parameters
+ ObjectNode body = transformIdParameter(parameterNode);
+
+ String path = body.get("_url") != null ? Common.formatMap("{id}", body.get("_url")) : "{id}";
+ body.remove("_url");
+
+ // The "_query" key is used internally to store query parameters
+ // that will be appended to the URL
+ JsonNode queryParams = body.get("_query");
+ if (queryParams != null) {
+ body.remove("_query");
+ path = String.format("%s?%s", path, Common.urlEncode((ObjectNode) queryParams));
+ }
+
+ Optional requestHttpOptions = Optional.empty();
+ if (config != null) {
+ requestHttpOptions = config.httpOptions();
+ }
+
+ return new BuiltRequest(path, JsonSerializable.toJsonString(body), requestHttpOptions);
+ }
+
+ /** A shared processResponse function for both sync and async methods. */
+ Interaction processResponseForGet(ApiResponse response, GetInteractionConfig config) {
+ ResponseBody responseBody = response.getBody();
+ String responseString;
+ try {
+ responseString = responseBody.string();
+ } catch (IOException e) {
+ throw new GenAiIOException("Failed to read HTTP response.", e);
+ }
+
+ JsonNode responseNode = JsonSerializable.stringToJsonNode(responseString);
+
+ Interaction sdkResponse = JsonSerializable.fromJsonNode(responseNode, Interaction.class);
+ Headers responseHeaders = response.getHeaders();
+ if (responseHeaders == null) {
+ return sdkResponse;
+ }
+ Map headers = new HashMap<>();
+ for (String headerName : responseHeaders.names()) {
+ headers.put(headerName, responseHeaders.get(headerName));
+ }
+ return sdkResponse.toBuilder().sdkHttpResponse(HttpResponse.builder().headers(headers)).build();
+ }
+
+ /** A shared buildRequest method for both sync and async methods. */
+ BuiltRequest buildRequestForCancel(String id, CancelInteractionConfig config) {
+
+ // Validation: id must be non-empty
+ if (id == null || id.isEmpty()) {
+ throw new IllegalArgumentException("Interaction ID must not be empty");
+ }
+
+ CancelInteractionParameters.Builder parameterBuilder = CancelInteractionParameters.builder();
+
+ if (!Common.isZero(id)) {
+ parameterBuilder.id(id);
+ }
+ if (!Common.isZero(config)) {
+ parameterBuilder.config(config);
+ }
+ JsonNode parameterNode = JsonSerializable.toJsonNode(parameterBuilder.build());
+
+ // Transform ID parameter into URL placeholder using special "_url" key
+ // The "_url" key is used internally to store URL path parameters
+ ObjectNode body = transformIdParameter(parameterNode);
+
+ // Cancel uses POST to /interactions/{id}/cancel
+ String path =
+ body.get("_url") != null
+ ? Common.formatMap("{id}/cancel", body.get("_url"))
+ : "{id}/cancel";
+ body.remove("_url");
+
+ // The "_query" key is used internally to store query parameters
+ // that will be appended to the URL
+ JsonNode queryParams = body.get("_query");
+ if (queryParams != null) {
+ body.remove("_query");
+ path = String.format("%s?%s", path, Common.urlEncode((ObjectNode) queryParams));
+ }
+
+ Optional requestHttpOptions = Optional.empty();
+ if (config != null) {
+ requestHttpOptions = config.httpOptions();
+ }
+
+ return new BuiltRequest(path, JsonSerializable.toJsonString(body), requestHttpOptions);
+ }
+
+ /** A shared processResponse function for both sync and async methods. */
+ Interaction processResponseForCancel(ApiResponse response, CancelInteractionConfig config) {
+ ResponseBody responseBody = response.getBody();
+ String responseString;
+ try {
+ responseString = responseBody.string();
+ } catch (IOException e) {
+ throw new GenAiIOException("Failed to read HTTP response.", e);
+ }
+
+ JsonNode responseNode = JsonSerializable.stringToJsonNode(responseString);
+
+ Interaction sdkResponse = JsonSerializable.fromJsonNode(responseNode, Interaction.class);
+ Headers responseHeaders = response.getHeaders();
+ if (responseHeaders == null) {
+ return sdkResponse;
+ }
+ Map headers = new HashMap<>();
+ for (String headerName : responseHeaders.names()) {
+ headers.put(headerName, responseHeaders.get(headerName));
+ }
+ return sdkResponse.toBuilder().sdkHttpResponse(HttpResponse.builder().headers(headers)).build();
+ }
+
+ /**
+ * Shared transformer for interaction ID parameters (used by GET, CANCEL, DELETE operations).
+ * Transforms the "id" field from the input into a URL parameter.
+ *
+ * @param fromObject Source JSON node containing the ID
+ * @return Transformed ObjectNode with ID in _url.id path
+ */
+ @ExcludeFromGeneratedCoverageReport
+ private ObjectNode transformIdParameter(JsonNode fromObject) {
+ ObjectNode toObject = JsonSerializable.objectMapper().createObjectNode();
+
+ if (Common.getValueByPath(fromObject, new String[] {"id"}) != null) {
+ Common.setValueByPath(
+ toObject,
+ new String[] {"_url", "id"},
+ Transformers.tInteractionId(
+ this.apiClient, Common.getValueByPath(fromObject, new String[] {"id"})));
+ }
+
+ return toObject;
+ }
+
+ /**
+ * Shared transformer for delete interaction responses. Extracts sdkHttpResponse from the API
+ * response.
+ *
+ * @param fromObject Source JSON node from the API response
+ * @return Transformed ObjectNode with sdkHttpResponse field
+ */
+ @ExcludeFromGeneratedCoverageReport
+ private ObjectNode transformDeleteInteractionResponse(JsonNode fromObject) {
+ ObjectNode toObject = JsonSerializable.objectMapper().createObjectNode();
+
+ if (Common.getValueByPath(fromObject, new String[] {"sdkHttpResponse"}) != null) {
+ Common.setValueByPath(
+ toObject,
+ new String[] {"sdkHttpResponse"},
+ Common.getValueByPath(fromObject, new String[] {"sdkHttpResponse"}));
+ }
+
+ return toObject;
+ }
+
+ /** A shared buildRequest method for both sync and async methods. */
+ BuiltRequest buildRequestForDelete(String id, DeleteInteractionConfig config) {
+
+ // Validation: id must be non-empty
+ if (id == null || id.isEmpty()) {
+ throw new IllegalArgumentException("Interaction ID must not be empty");
+ }
+
+ DeleteInteractionParameters.Builder parameterBuilder = DeleteInteractionParameters.builder();
+
+ if (!Common.isZero(id)) {
+ parameterBuilder.id(id);
+ }
+ if (!Common.isZero(config)) {
+ parameterBuilder.config(config);
+ }
+ JsonNode parameterNode = JsonSerializable.toJsonNode(parameterBuilder.build());
+
+ // Transform ID parameter into URL placeholder using special "_url" key
+ // The "_url" key is used internally to store URL path parameters
+ ObjectNode body = transformIdParameter(parameterNode);
+
+ String path = body.get("_url") != null ? Common.formatMap("{id}", body.get("_url")) : "{id}";
+ body.remove("_url");
+
+ // The "_query" key is used internally to store query parameters
+ // that will be appended to the URL
+ JsonNode queryParams = body.get("_query");
+ if (queryParams != null) {
+ body.remove("_query");
+ path = String.format("%s?%s", path, Common.urlEncode((ObjectNode) queryParams));
+ }
+
+ Optional requestHttpOptions = Optional.empty();
+ if (config != null) {
+ requestHttpOptions = config.httpOptions();
+ }
+
+ return new BuiltRequest(path, JsonSerializable.toJsonString(body), requestHttpOptions);
+ }
+
+ /** A shared processResponse function for both sync and async methods. */
+ DeleteInteractionResponse processResponseForDelete(
+ ApiResponse response, DeleteInteractionConfig config) {
+ ResponseBody responseBody = response.getBody();
+ String responseString;
+ try {
+ responseString = responseBody.string();
+ } catch (IOException e) {
+ throw new GenAiIOException("Failed to read HTTP response.", e);
+ }
+
+ JsonNode responseNode = JsonSerializable.stringToJsonNode(responseString);
+
+ // Transform response - identical for both platforms
+ responseNode = transformDeleteInteractionResponse(responseNode);
+
+ DeleteInteractionResponse sdkResponse =
+ JsonSerializable.fromJsonNode(responseNode, DeleteInteractionResponse.class);
+ Headers responseHeaders = response.getHeaders();
+ if (responseHeaders == null) {
+ return sdkResponse;
+ }
+ Map headers = new HashMap<>();
+ for (String headerName : responseHeaders.names()) {
+ headers.put(headerName, responseHeaders.get(headerName));
+ }
+ return sdkResponse.toBuilder().sdkHttpResponse(HttpResponse.builder().headers(headers)).build();
+ }
+
+ /**
+ * Creates a new interaction with the specified configuration.
+ *
+ *
Either {@code model} or {@code agent} must be specified in the config, but not both.
+ *
+ *
When using function calling tools, the application must handle the function execution loop
+ * manually. If the interaction returns {@code status: "requires_action"}, extract the function
+ * calls from the outputs, execute them, and create a new interaction with the results using
+ * {@code previousInteractionId}.
+ *
+ *
Example usage for model-based interaction:
+ *
+ *
{@code
+ * CreateInteractionConfig config = CreateInteractionConfig.builder()
+ * .model("gemini-2.5-flash")
+ * .input("What is the capital of France?")
+ * .build();
+ * Interaction response = client.interactions.create(config);
+ * }
+ *
+ *
Example usage for agent-based interaction:
+ *
+ *
{@code
+ * CreateInteractionConfig config = CreateInteractionConfig.builder()
+ * .agent("deep-research-pro-preview-12-2025")
+ * .input("Research the history of quantum computing")
+ * .build();
+ * Interaction response = client.interactions.create(config);
+ * }
+ *
+ *
Example usage with manual function calling:
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param config The configuration for creating the interaction
+ * @return The created Interaction with outputs
+ * @throws IllegalArgumentException if both model and agent are specified, or neither is specified
+ * @throws GenAiIOException if the API request fails
+ */
+ public Interaction create(CreateInteractionConfig config) {
+ BuiltRequest builtRequest = buildRequestForCreate(config);
+
+ try (ApiResponse response =
+ this.apiClient.request(
+ "post", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())) {
+ return processResponseForCreate(response, config);
+ }
+ }
+
+ /**
+ * Retrieves an interaction by its ID.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param id The ID of the interaction to retrieve
+ * @param config The configuration for the get request (can be null)
+ * @return The retrieved Interaction
+ * @throws IllegalArgumentException if the ID is empty
+ * @throws GenAiIOException if the API request fails
+ */
+ public Interaction get(String id, GetInteractionConfig config) {
+ BuiltRequest builtRequest = buildRequestForGet(id, config);
+
+ try (ApiResponse response =
+ this.apiClient.request(
+ "get", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())) {
+ return processResponseForGet(response, config);
+ }
+ }
+
+ /**
+ * Cancels a background interaction that is still in progress.
+ *
+ *
Only applies to interactions created with background=true that are in IN_PROGRESS status.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param id The ID of the interaction to cancel
+ * @param config The configuration for the cancel request (can be null)
+ * @return The updated Interaction with CANCELLED status
+ * @throws IllegalArgumentException if the ID is empty
+ * @throws GenAiIOException if the API request fails
+ */
+ public Interaction cancel(String id, CancelInteractionConfig config) {
+ BuiltRequest builtRequest = buildRequestForCancel(id, config);
+
+ try (ApiResponse response =
+ this.apiClient.request(
+ "post", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())) {
+ return processResponseForCancel(response, config);
+ }
+ }
+
+ /**
+ * Deletes an interaction by its ID.
+ *
+ *
Note: The Interactions API is in beta and subject to change.
+ *
+ * @param id The ID of the interaction to delete
+ * @param config The configuration for the delete request (can be null)
+ * @return The delete response with HTTP headers
+ * @throws IllegalArgumentException if the ID is empty
+ * @throws GenAiIOException if the API request fails
+ */
+ public DeleteInteractionResponse delete(String id, DeleteInteractionConfig config) {
+ BuiltRequest builtRequest = buildRequestForDelete(id, config);
+
+ try (ApiResponse response =
+ this.apiClient.request(
+ "delete", builtRequest.path(), builtRequest.body(), builtRequest.httpOptions())) {
+ return processResponseForDelete(response, config);
+ }
+ }
+}
diff --git a/src/main/java/com/google/genai/Transformers.java b/src/main/java/com/google/genai/Transformers.java
index 65eab1ed837..8d1f10f03c7 100644
--- a/src/main/java/com/google/genai/Transformers.java
+++ b/src/main/java/com/google/genai/Transformers.java
@@ -409,6 +409,21 @@ public static String tCachedContentName(ApiClient apiClient, Object origin) {
"Unsupported cached content name type: " + origin.getClass());
}
+ /** Transforms an object to an interaction ID for the API. */
+ public static String tInteractionId(ApiClient apiClient, Object origin) {
+ if (origin == null) {
+ return null;
+ } else if (origin instanceof String) {
+ return getResourceName(apiClient, (String) origin, "interactions");
+ } else if (origin instanceof JsonNode) {
+ String interactionId = JsonSerializable.toJsonString((JsonNode) origin);
+ interactionId = interactionId.replace("\"", "");
+ return getResourceName(apiClient, interactionId, "interactions");
+ }
+ throw new IllegalArgumentException(
+ "Unsupported interaction ID type: " + origin.getClass());
+ }
+
/** Transforms an object to a list of Content for the embedding API. */
@SuppressWarnings("unchecked")
public static @Nullable List