feat: [Experimental] Add interactions support.

README.md

@@ -3,6 +3,8 @@
 Java idiomatic SDK for the
 [Gemini Developer APIs][gemini-api-doc] and [Vertex AI][vertex-api-doc] APIs.
 
+**Note:** The SDK now has experimental support for the [Interactions API](#interactions-experimental).
+
 [![Maven][maven-version-image]][maven-version-link]
 [![Javadoc][javadoc-image]][javadoc-link]
 
@@ -972,6 +974,58 @@ public final class FileOperations {
 }
 ```
 
+### Interactions (Experimental)
+
+The `interactions` service provides access to experimental features.
+
+> [!WARNING]
+> This service is experimental and subject to change or removal in future releases.
+
+You can access it via the client:
+```java
+client.interactions
+```
+or asynchronously:
+```java
+client.async.interactions
+```
+
+### Example: Create Interaction
+
+This example demonstrates creating a simple model interaction.
+
+```java
+import com.google.genai.Client;
+import com.google.genai.interactions.models.interactions.Content;
+import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
+import com.google.genai.interactions.models.interactions.Interaction;
+import com.google.genai.interactions.models.interactions.Model;
+
+Client client = new Client();
+
+CreateModelInteractionParams params =
+    CreateModelInteractionParams.builder()
+        .input("Why is the sky blue?")
+        .model(Model.GEMINI_2_5_FLASH)
+        .build();
+
+Interaction interaction = client.interactions.create(params);
+
+System.out.println("Interaction ID: " + interaction.id());
+System.out.println("Status: " + interaction.status());
+
+// Print the text outputs from the interaction.
+interaction.outputs().ifPresent(outputs -> {
+  for (Content output : outputs) {
+    output.text().ifPresent(text -> System.out.println("Output: " + text.text()));
+  }
+});
+```
+
+For more examples, see `interactions*` in the [examples directory](https://github.com/googleapis/java-genai/tree/main/examples/).
+
+
+
 ## Versioning
 
 This library follows [Semantic Versioning](http://semver.org/).

examples/src/main/java/com/google/genai/examples/InteractionCreate.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2026 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:
+ *
+ * <p>1a. If you are using Vertex AI, setup ADC to get credentials:
+ * https://cloud.google.com/docs/authentication/provide-credentials-adc#google-idp
+ *
+ * <p>Then set Project, Location, and USE_VERTEXAI flag as environment variables:
+ *
+ * <p>export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT
+ *
+ * <p>export GOOGLE_CLOUD_LOCATION=YOUR_LOCATION
+ *
+ * <p>export GOOGLE_GENAI_USE_VERTEXAI=true
+ *
+ * <p>1b. If you are using Gemini Developer API, set an API key environment variable. You can find a
+ * list of available API keys here: https://aistudio.google.com/app/apikey
+ *
+ * <p>export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ * <p>2. Compile the java package and run the sample code.
+ *
+ * <p>mvn clean compile exec:java -Dexec.mainClass="com.google.genai.examples.InteractionCreate"
+ */
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.interactions.models.interactions.Content;
+import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
+import com.google.genai.interactions.models.interactions.Interaction;
+import com.google.genai.interactions.models.interactions.Model;
+
+/** An example of using the Unified Gen AI Java SDK to create an interaction. */
+public final class InteractionCreate {
+  public static void main(String[] args) {
+    // Instantiate the client. The client by default uses the Gemini Developer API. It gets the API
+    // key from the environment variable `GOOGLE_API_KEY`. Vertex AI API can be used by setting the
+    // environment variables `GOOGLE_CLOUD_LOCATION` and `GOOGLE_CLOUD_PROJECT`, as well as setting
+    // `GOOGLE_GENAI_USE_VERTEXAI` to "true".
+    //
+    // Note: Some services are only available in a specific API backend (Gemini or Vertex), you will
+    // get a `UnsupportedOperationException` if you try to use a service that is not available in
+    // the backend you are using.
+    Client client = new Client();
+
+    if (client.vertexAI()) {
+      System.out.println("Using Vertex AI");
+    } else {
+      System.out.println("Using Gemini Developer API");
+    }
+
+    CreateModelInteractionParams params =
+        CreateModelInteractionParams.builder()
+            .input("What is your name?")
+            .model(Model.GEMINI_2_5_FLASH)
+            .build();
+
+    Interaction interaction = client.interactions.create(params);
+
+    System.out.println("Interaction ID: " + interaction.id());
+    System.out.println("Status: " + interaction.status());
+
+    // Print the text outputs from the interaction.
+    interaction
+        .outputs()
+        .ifPresent(
+            outputs -> {
+              for (Content output : outputs) {
+                output.text().ifPresent(text -> System.out.println("Output: " + text.text()));
+              }
+            });
+  }
+
+  private InteractionCreate() {}
+}

examples/src/main/java/com/google/genai/examples/InteractionCreateAsync.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2026 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:
+ *
+ * <p>1a. If you are using Vertex AI, setup ADC to get credentials:
+ * https://cloud.google.com/docs/authentication/provide-credentials-adc#google-idp
+ *
+ * <p>Then set Project, Location, and USE_VERTEXAI flag as environment variables:
+ *
+ * <p>export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT
+ *
+ * <p>export GOOGLE_CLOUD_LOCATION=YOUR_LOCATION
+ *
+ * <p>export GOOGLE_GENAI_USE_VERTEXAI=true
+ *
+ * <p>1b. If you are using Gemini Developer API, set an API key environment variable. You can find a
+ * list of available API keys here: https://aistudio.google.com/app/apikey
+ *
+ * <p>export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ * <p>2. Compile the java package and run the sample code.
+ *
+ * <p>mvn clean compile exec:java
+ * -Dexec.mainClass="com.google.genai.examples.InteractionCreateAsync"
+ */
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.interactions.models.interactions.Content;
+import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
+import com.google.genai.interactions.models.interactions.Interaction;
+import com.google.genai.interactions.models.interactions.Model;
+import java.util.concurrent.CompletableFuture;
+
+/** An example of using the Unified Gen AI Java SDK to create an interaction asynchronously. */
+public final class InteractionCreateAsync {
+  public static void main(String[] args) {
+    // Instantiate the client. The client by default uses the Gemini Developer API. It gets the API
+    // key from the environment variable `GOOGLE_API_KEY`. Vertex AI API can be used by setting the
+    // environment variables `GOOGLE_CLOUD_LOCATION` and `GOOGLE_CLOUD_PROJECT`, as well as setting
+    // `GOOGLE_GENAI_USE_VERTEXAI` to "true".
+    //
+    // Note: Some services are only available in a specific API backend (Gemini or Vertex), you will
+    // get a `UnsupportedOperationException` if you try to use a service that is not available in
+    // the backend you are using.
+    Client client = new Client();
+
+    if (client.vertexAI()) {
+      System.out.println("Using Vertex AI");
+    } else {
+      System.out.println("Using Gemini Developer API");
+    }
+
+    CreateModelInteractionParams params =
+        CreateModelInteractionParams.builder()
+            .input("What is your name?")
+            .model(Model.GEMINI_2_5_FLASH)
+            .build();
+
+    CompletableFuture<Interaction> interactionFuture = client.async.interactions.create(params);
+
+    interactionFuture
+        .thenAccept(
+            interaction -> {
+              System.out.println("Interaction ID: " + interaction.id());
+              System.out.println("Status: " + interaction.status());
+
+              // Print the text outputs from the interaction.
+              interaction
+                  .outputs()
+                  .ifPresent(
+                      outputs -> {
+                        for (Content output : outputs) {
+                          output
+                              .text()
+                              .ifPresent(text -> System.out.println("Output: " + text.text()));
+                        }
+                      });
+            })
+        .join();
+  }
+
+  private InteractionCreateAsync() {}
+}

examples/src/main/java/com/google/genai/examples/InteractionCreateAsyncStreaming.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026 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:
+ *
+ * <p>1a. If you are using Vertex AI, setup ADC to get credentials:
+ * https://cloud.google.com/docs/authentication/provide-credentials-adc#google-idp
+ *
+ * <p>Then set Project, Location, and USE_VERTEXAI flag as environment variables:
+ *
+ * <p>export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT
+ *
+ * <p>export GOOGLE_CLOUD_LOCATION=YOUR_LOCATION
+ *
+ * <p>export GOOGLE_GENAI_USE_VERTEXAI=true
+ *
+ * <p>1b. If you are using Gemini Developer API, set an API key environment variable. You can find a
+ * list of available API keys here: https://aistudio.google.com/app/apikey
+ *
+ * <p>export GOOGLE_API_KEY=YOUR_API_KEY
+ *
+ * <p>2. Compile the java package and run the sample code.
+ *
+ * <p>mvn clean compile exec:java
+ * -Dexec.mainClass="com.google.genai.examples.InteractionCreateAsyncStreaming"
+ */
+package com.google.genai.examples;
+
+import com.google.genai.Client;
+import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
+import com.google.genai.interactions.models.interactions.Model;
+
+/**
+ * An example of using the Unified Gen AI Java SDK to create a streaming interaction asynchronously.
+ */
+public final class InteractionCreateAsyncStreaming {
+  public static void main(String[] args) {
+    // Instantiate the client. The client by default uses the Gemini Developer API. It gets the API
+    // key from the environment variable `GOOGLE_API_KEY`. Vertex AI API can be used by setting the
+    // environment variables `GOOGLE_CLOUD_LOCATION` and `GOOGLE_CLOUD_PROJECT`, as well as setting
+    // `GOOGLE_GENAI_USE_VERTEXAI` to "true".
+    //
+    // Note: Some services are only available in a specific API backend (Gemini or Vertex), you will
+    // get a `UnsupportedOperationException` if you try to use a service that is not available in
+    // the backend you are using.
+    Client client = new Client();
+
+    if (client.vertexAI()) {
+      System.out.println("Using Vertex AI");
+    } else {
+      System.out.println("Using Gemini Developer API");
+    }
+
+    CreateModelInteractionParams params =
+        CreateModelInteractionParams.builder()
+            .input("Tell me a story in 300 words.")
+            .model(Model.GEMINI_2_5_FLASH)
+            .build();
+
+    System.out.println("Streaming response:");
+    client
+        .async
+        .interactions
+        .createStreaming(params)
+        .subscribe(
+            event ->
+                event
+                    .contentDelta()
+                    .map(contentDelta -> contentDelta.delta())
+                    .flatMap(delta -> delta.text())
+                    .map(text -> text.text())
+                    .ifPresent(System.out::print))
+        // Wait for the stream to complete.
+        .onCompleteFuture()
+        .join();
+    System.out.println();
+
+    client.close();
+  }
+
+  private InteractionCreateAsyncStreaming() {}
+}