Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Guía para desarrolladores de la API de Interactions

La API de Interactions proporciona una interfaz unificada y con estado para compilar aplicaciones de IA generativa con modelos de Gemini y agentes autónomos en Gemini Enterprise Agent Platform. Usa la API de Interactions para administrar el almacenamiento de sesiones y las conversaciones de varios turnos, transmitir respuestas en tiempo real, aplicar resultados estructurados, invocar herramientas integradas y fundamentación, ejecutar llamadas a funciones y organizar tareas en segundo plano de larga duración.

En esta guía, se muestra cómo instalar el SDK de IA generativa de Google, autenticar tu cliente y, luego, implementar flujos de trabajo de interacción comunes. Para obtener detalles conceptuales sobre el ciclo de vida de las interacciones, consulta la descripción general de la API de Interactions.

Antes de comenzar

Antes de enviar solicitudes a la API de Interactions, configura tu proyecto de Google Cloud y el entorno de desarrollo:

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the API

Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user)
Check for the roles
1. In the Google Cloud console, go to the IAM page.
  Go to IAM
2. Select the project.
3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.
  Go to IAM
2. Select the project.
3. Click Grant access.
4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.
5. Click Select a role, then search for the role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

Conceptos clave

Revisa los siguientes conceptos para comprender cómo la API de Interactions administra el estado y las respuestas:

Interaction: La API de Interactions se centra en un recurso principal: un Interaction. Un Interaction representa un turno completo en una conversación o tarea, y hace un seguimiento de la cronología de los pensamientos del modelo, las llamadas a herramientas y los resultados finales. Proporciona un envoltorio unificado para las interacciones de instrucción y respuesta, y los flujos de trabajo de agentes complejos y de varios pasos.
Retención con estado: Las interacciones se almacenan del lado del servidor de forma predeterminada (store=True en Python o store: true en TypeScript/JavaScript). Las interacciones almacenadas persisten durante 7 días y se borran automáticamente después de ese tiempo. Si configuras store=False, se habilita el modo sin estado, que inhabilita la retención del servidor y cumple con la retención de datos cero (ZDR). El modo sin estado también inhabilita el encadenamiento de previous_interaction_id y la ejecución asíncrona (background=True).
Asistentes de respuesta: La versión 2.3.0 y posteriores del SDK de IA generativa de Google proporcionan propiedades de conveniencia en la respuesta de interacción, incluidas interaction.output_text, interaction.output_image y interaction.output_audio. Usa interaction.output_text para leer las respuestas de texto en lugar de indexar de forma manual en el array de pasos (como interaction.steps[-1].content[0].text).

Requisitos

Asegúrate de que tu entorno y tus solicitudes cumplan con los siguientes requisitos antes de integrarlos con la API de Interactions:

Compatibilidad con versiones del SDK: Usa una de las bibliotecas del SDK de IA generativa de Google compatibles.
Modelos compatibles: Usa modelos de Gemini 3 o versiones posteriores compatibles. Las familias de modelos anteriores no admiten esta API. Para obtener una lista completa de los modelos compatibles, consulta Modelos compatibles y Migra a las versiones más recientes de los modelos.
Parámetros con alcance de turno: Los parámetros de configuración, como tools, system_instruction y generation_config, se aplican solo al turno actual. Pasa estos parámetros en cada turno de interacción posterior si tu flujo de trabajo los requiere en una conversación de varios turnos.
Decodificaciones largas en Gemini 4 Argon: Para generar resultados de un solo turno que superen los 65,536 tokens (hasta 1,048,576 tokens menos los tokens de entrada) en gemini-4-argon o gemini-4-argon-cyber-permissive, usa la continuación automática del SDK de IA generativa de Google (google-genai >= 2.34.0 para Python, @google/genai >= 2.32.0 para TypeScript/JavaScript, Go >= 1.77.0, Java >= 1.80.0), background=True o continuation_token en el extremo v1beta1. Para ver muestras de código y reglas de continuación, consulta Decodificaciones largas en la guía para desarrolladores de Gemini 4 Argon.

Instala el SDK de IA generativa de Google

Instala o actualiza el SDK de IA generativa de Google para tu lenguaje preferido:

Python

pip install --upgrade "google-genai>=2.3.0"

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

Go

go get google.golang.org/genai

Java

<dependencies>
  <dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.78.0</version>
  </dependency>
</dependencies>

Autentica tu cliente

Puedes conectarte a la API de Interactions en Agent Platform con cualquiera de los siguientes métodos de autenticación:

Proyecto deGoogle Cloud con credenciales predeterminadas de la aplicación
Modo Exprés con una clave de API

Conéctate con un proyecto de Google Cloud con las credenciales predeterminadas de la aplicación (ADC)

Usa este método de autenticación para las cargas de trabajo empresariales y las implementaciones de producción en Google Cloud. Para autenticarte con las credenciales predeterminadas de la aplicación (ADC), inicializa el cliente con las siguientes propiedades:

enterprise=True
project="PROJECT_ID"
location="global"

Si aún no configuraste las credenciales locales, ejecuta gcloud auth application-default login.

En la siguiente muestra de código, reemplaza PROJECT_ID por el ID del proyecto deGoogle Cloud .

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Conéctate con el modo Exprés (clave de API)

Usa este método de autenticación para crear prototipos rápidos, secuencias de comandos ligeras o entornos que se autentiquen con una clave de API. Pasa tu clave de API cuando inicialices el cliente o en el encabezado HTTP x-goog-api-key.

En la siguiente muestra de código, reemplaza API_KEY por tu clave de API y PROJECT_ID por el ID del proyecto de Google Cloud .

Python

from google import genai

client = genai.Client(
    enterprise=True,
    api_key="API_KEY",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "API_KEY",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Flujos de trabajo de interacción comunes

Después de configurar tu cliente, puedes usar el método interactions.create para administrar el almacenamiento de sesiones y las conversaciones de varios turnos, transmitir tokens de salida en tiempo real, generar JSON validado por esquemas, invocar herramientas integradas y fundamentación, llamar a funciones externas y ejecutar agentes autónomos.

Administra el almacenamiento de sesiones y el estado de las conversaciones

La API de Interactions admite el almacenamiento con estado del servidor (store=True, predeterminado) y la ejecución sin estado administrada por el cliente (store=False). En la siguiente tabla, se comparan los modos de interacción con estado y sin estado:

Función	Modo con estado (`store=true`, predeterminado)	Modo sin estado (`store=false`)
Persistencia del servidor	Almacena las entradas, los pasos intermedios y los resultados en el servidor durante 7 días.	Inhabilita el almacenamiento de interacciones del servidor para admitir flujos de trabajo de retención de datos cero (ZDR).
Contexto de varios turnos	Encadena turnos pasando la interacción anterior `id` en `previous_interaction_id`.	Requiere pasar el array completo de la conversación anterior `steps` en `input` en cada turno. Si pasas `previous_interaction_id`, se muestra un error `400 Bad Request`.
Ejecución en segundo plano (`background=true`)	Se admite para interacciones de larga duración con modelos y agentes.	No compatible. La ejecución asíncrona en segundo plano requiere la persistencia del estado del servidor.
Métodos del ciclo de vida de la sesión	Admite interacciones de recuperación (`get`), creación de listas (`list`), cancelación (`cancel`) y eliminación (`delete`).	No se puede recuperar después de que se completa la respuesta síncrona o de transmisión.
Encriptación en reposo	Se encriptan de forma predeterminada con una Google-owned and Google-managed encryption keyo con claves de encriptación administradas por el cliente (CMEK) en las multirregiones `us` y `eu`.	No se almacena ningún estado de interacción en reposo.

Ejecuta conversaciones de varios turnos con estado

De forma predeterminada, la API de Interactions almacena el estado de la conversación en el servidor (store=True en Python o store: true en TypeScript/JavaScript). Para continuar una conversación existente, pasa el id de la interacción anterior al parámetro previous_interaction_id. La plataforma del agente recupera el contexto de la conversación almacenado, agrega el nuevo turno y vuelve a usar los tokens de prefijo almacenados en caché.

Cuando encadenes interacciones entre extremos, observa las siguientes reglas de ubicación:

Misma ubicación: Puedes encadenar interacciones dentro de la misma ubicación (como global a global, us a us o eu a eu).
En diferentes ubicaciones: No se admite el encadenamiento en diferentes ubicaciones de extremos (entre global y us o eu, o entre us y eu). Cada extremo almacena el estado de la interacción en un almacenamiento aislado, por lo que hacer referencia a un ID de interacción creado en otra ubicación devuelve un error 404 Not Found.

En el siguiente ejemplo, reemplaza PROJECT_ID por el ID del proyecto de Google Cloud:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Turn 1: Start a stateful conversation (store=True by default)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi! My name is John. I am working on AI agents.",
    store=True,
)
print(f"Turn 1: {turn1.output_text}")

# Turn 2: Reference the stored conversation state using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

// Turn 1: Start a stateful conversation (store: true by default)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Turn 2: Reference the stored conversation state using previous_interaction_id
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: turn1.id,
});
console.log(`Turn 2: ${turn2.output_text}`);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

// Turn 1: Start a stateful conversation (store is true by default)
CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Hi! My name is John. I am working on AI agents."))
        .store(true)
        .build();

Interaction turn1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().orElseThrow();
System.out.println("Turn 1: " + turn1.outputText().orElse(""));

// Turn 2: Reference the stored conversation state using previousInteractionId
CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .previousInteractionId(turn1.id().orElseThrow())
        .input(InteractionsInput.of("What is my name?"))
        .build();

Interaction turn2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().orElseThrow();
System.out.println("Turn 2: " + turn2.outputText().orElse(""));

REST

# Turn 1: Start a stateful conversation
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": true,
    "input": "Hi! My name is John. I am working on AI agents."
  }'

# Turn 2: Pass the interaction ID from Turn 1 in previous_interaction_id
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": "What is my name?"
  }'

Ejecuta conversaciones de varios turnos sin estado

Si tu carga de trabajo requiere la retención de datos cero (ZDR), establece de forma explícita store=False (store: false en TypeScript/JavaScript o "store": false en REST) en cada solicitud.

En el modo sin estado, administras el historial de conversaciones en el cliente manteniendo una lista de objetos Step (user_input, thought, function_call, function_result y model_output) y enviando el array steps acumulado en input en cada turno:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "Hi! My name is John."}],
    }
]

# Turn 1: Stateless request (store=False)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input=history,
    store=False,
)
print(f"Turn 1: {turn1.output_text}")

# Append the model's generated steps and the next user turn to local history
history.extend(turn1.steps)
history.append(
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is my name?"}],
    }
)

# Turn 2: Send the full step history with store=False
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input=history,
    store=False,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

import { GoogleGenAI, Step } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const history: Step[] = [
    {
        type: "user_input",
        content: [{ type: "text", text: "Hi! My name is John." }],
    },
];

// Turn 1: Stateless request (store: false)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: history,
    store: false,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Append the model's generated steps and the next user turn to local history
if (turn1.steps) {
    history.push(...turn1.steps);
}
history.push({
    type: "user_input",
    content: [{ type: "text", text: "What is my name?" }],
});

// Turn 2: Send the full step history with store: false
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: history,
    store: false,
});
console.log(`Turn 2: ${turn2.output_text}`);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputContent;
import com.google.genai.gaos.models.interactions.UserInputStep;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

List<Step> history = new ArrayList<>();
history.add(
    Step.of(
        UserInputStep.builder()
            .content(
                List.of(
                    UserInputContent.of(
                        TextContent.builder().text("Hi! My name is John.").build())))
            .build()));

// Turn 1: Stateless request (store(false))
CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofSteps(history))
        .store(false)
        .build();

Interaction turn1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().orElseThrow();
System.out.println("Turn 1: " + turn1.outputText().orElse(""));

// Append the model's generated steps and the next user turn to local history
turn1.steps().ifPresent(history::addAll);
history.add(
    Step.of(
        UserInputStep.builder()
            .content(
                List.of(
                    UserInputContent.of(
                        TextContent.builder().text("What is my name?").build())))
            .build()));

// Turn 2: Send the full step history with store(false)
CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofSteps(history))
        .store(false)
        .build();

Interaction turn2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().orElseThrow();
System.out.println("Turn 2: " + turn2.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "Hi! My name is John."}]
      },
      {
        "type": "model_output",
        "content": [{"type": "text", "text": "Hello John! How can I help you today?"}]
      },
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is my name?"}]
      }
    ]
  }'

Retención y ciclo de vida de la sesión

Las interacciones almacenadas (store=True) siguen estas reglas de retención y ramificación:

Tiempo de actividad (TTL) de 7 días: Cada interacción almacenada persiste durante 7 días desde su marca de tiempo created y se borra automáticamente cuando vence el TTL de 7 días.
Almacenamiento independiente de elementos superiores y secundarios: Cuando encadenas un turno nuevo con previous_interaction_id, Agent Platform copia el historial de conversaciones del ancestro en el registro de interacción nuevo. Debido a que cada turno almacena su propia copia del historial de conversaciones, el vencimiento o la eliminación de un turno anterior tiene los siguientes efectos:
- La continuación desde un turno posterior se realiza correctamente: Si el turno 1 (interaction_1) vence o se borra después de que ya se creó el turno 2 (interaction_2), puedes crear el turno 3 con previous_interaction_id=interaction_2.id hasta que interaction_2 venza o se borre.
- La ramificación desde un turno vencido o borrado falla: Si intentas crear una interacción nueva que haga referencia directamente a un ID de interacción vencido o borrado en previous_interaction_id, se devuelve un error 400 Bad Request (Previous Interaction ID not found).

Recuperar, enumerar, cancelar y borrar interacciones almacenadas

Puedes inspeccionar y administrar las interacciones almacenadas durante todo su ciclo de vida con los siguientes métodos:

Recupera una interacción (interactions.get): Recupera el recurso Interaction completo por id, incluidos los pasos de user_input, los pasos intermedios de thought y de herramientas, y los pasos de model_output. Establece stream=True (y, de forma opcional, last_event_id) para transmitir o reanudar una interacción en curso.
Enumera interacciones (interactions.list): Consulta los IDs de interacción almacenados en tu proyecto a través de REST con page_size (10 predeterminado, 500 máximo) y page_token. Muestra una lista de recursos InteractionMetadata.
Cancela una interacción en curso (interactions.cancel): Detiene una interacción asíncrona en segundo plano (background=True) que se encuentra en el estado in_progress o requires_action, y cambia su estado a cancelled. Se te facturarán los tokens generados antes de la cancelación.
Borra una interacción almacenada (interactions.delete): Quita de forma permanente una interacción almacenada antes de que venza su TTL de 7 días. Solo se pueden borrar las interacciones en un estado terminal (completed, failed o cancelled). Si una interacción aún se está ejecutando en segundo plano, cancélala antes de borrarla.

En el siguiente ejemplo, reemplaza PROJECT_ID por el ID del proyecto de Google Cloud y INTERACTION_ID por el ID de interacción de destino:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Retrieve a stored interaction by ID
interaction = client.interactions.get(id="INTERACTION_ID")
print(f"Status: {interaction.status}")

# Cancel an in-progress background interaction
cancelled = client.interactions.cancel(id="INTERACTION_ID")
print(f"After cancel: {cancelled.status}")

# Delete a completed, failed, or cancelled interaction before its 7-day TTL
client.interactions.delete(id="INTERACTION_ID")
print("Interaction deleted.")

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

// Retrieve a stored interaction by ID
const interaction = await ai.interactions.get("INTERACTION_ID");
console.log(`Status: ${interaction.status}`);

// Cancel an in-progress background interaction
const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`After cancel: ${cancelled.status}`);

// Delete a completed, failed, or cancelled interaction before its 7-day TTL
await ai.interactions.delete("INTERACTION_ID");
console.log("Interaction deleted.");

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.operations.CancelInteractionByIdResponse;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.models.operations.GetInteractionByIdResponse;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

String interactionId = "INTERACTION_ID";

// Retrieve a stored interaction by ID
GetInteractionByIdResponse getResponse =
    client.interactions.get(new GetInteractionByIdRequest(interactionId));
Interaction interaction = getResponse.interaction().orElseThrow();
System.out.println("Status: " + interaction.status().map(InteractionStatus::value).orElse(""));

// Cancel an in-progress background interaction
CancelInteractionByIdResponse cancelResponse = client.interactions.cancel(interactionId);
Interaction cancelled = cancelResponse.interaction().orElseThrow();
System.out.println("After cancel: " + cancelled.status().map(InteractionStatus::value).orElse(""));

// Delete a completed, failed, or cancelled interaction before its 7-day TTL
client.interactions.delete(interactionId);
System.out.println("Interaction deleted.");

REST

# Retrieve a stored interaction by ID
curl -X GET "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# List stored interactions (up to 500 per page)
curl -X GET "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions?page_size=10" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# Cancel an in-progress background interaction
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# Delete a completed, failed, or cancelled interaction
curl -X DELETE "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

Cuotas y límites de almacenamiento con estado

Además de los límites de tokens de modelos y de porcentaje de solicitudes, las interacciones con estado (store=True) están sujetas a los siguientes límites de almacenamiento y simultaneidad a nivel del proyecto:

Cuota o límite del sistema	Límite predeterminado (por proyecto)	Descripción
Capacidad de procesamiento de creación de interacciones con estado por día	`240 GiB` por día	Volumen total máximo de datos de interacción escritos en el almacenamiento del servidor por día en `interactions.create` solicitudes con `store=true`.
Capacidad de procesamiento de recuperación de interacciones con estado por día	`480 GiB` por día	Volumen total máximo de datos de interacción almacenados que se leen por día en las solicitudes de `interactions.get` y las solicitudes de varios turnos que cargan turnos anteriores con `previous_interaction_id`.
Interacciones con estado simultáneas	`500` interacciones simultáneas	Cantidad máxima de interacciones con estado activas que se ejecutan de forma simultánea en un proyecto.

Para obtener más información sobre cómo ver y administrar cuotas en Agent Platform, consulta Cuotas y límites del sistema.

Transmite respuestas en tiempo real

Para reducir la latencia percibida en las aplicaciones interactivas, puedes transmitir las respuestas del modelo a medida que se generan. Establece stream=True (stream: true en TypeScript/JavaScript) cuando llames a interactions.create para recibir un flujo iterable de eventos enviados por el servidor. Filtra los eventos step.delta para renderizar fragmentos de texto incrementales a medida que llegan:

Python

response = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a short poem about debugging.",
    stream=True,
)

for event in response:
    if event.event_type == "step.delta" and hasattr(event.delta, "text"):
        print(event.delta.text, end="", flush=True)
print()

TypeScript / JavaScript

const responseStream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a short poem about debugging.",
    stream: true,
});

for await (const event of responseStream) {
    if (event.event_type === "step.delta" && event.delta && "text" in event.delta) {
        process.stdout.write(event.delta.text);
    }
}
console.log();

Genera un resultado estructurado

Cuando tu aplicación requiere respuestas en un formato predecible y legible por máquinas, puedes restringir el resultado del modelo para que coincida con un esquema JSON específico. Pasa tu esquema de destino, como un esquema JSON de modelo de Pydantic en Python o un objeto de esquema Type en TypeScript/JavaScript, directamente al parámetro polimórfico response_format:

Python

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recommend one famous sci-fi book.",
    response_format=Book.model_json_schema(),
)

# The output text is valid JSON matching the Book schema
print(interaction.output_text)

TypeScript / JavaScript

import { Type } from "@google/genai";

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER },
    },
    required: ["title", "author", "yearPublished"],
};

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Recommend one famous sci-fi book.",
    response_format: BookSchema,
});

console.log(interaction.output_text);

Usa la llamada a funciones (uso de herramientas)

La llamada a funciones permite que un modelo solicite la ejecución de funciones personalizadas o APIs externas para recopilar información antes de formular una respuesta final. En un flujo de trabajo de interacción con estado, la llamada a función sigue un patrón de dos turnos:

Declara y pasa herramientas: Proporciona tus declaraciones de funciones en el parámetro tools en la solicitud inicial.
Ejecuta y devuelve resultados: Inspecciona los pasos de respuesta (interaction.steps) para los pasos de function_call, ejecuta tu función local con el arguments proporcionado por el modelo y envía una interacción de seguimiento que contenga un elemento function_result vinculado por call_id y previous_interaction_id.

Python

# Define a declarative function tool schema
stock_tool = {
    "type": "function",
    "name": "get_stock_price",
    "description": "Gets the stock price for a given ticker symbol.",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "The stock ticker symbol"}
        },
        "required": ["ticker"],
    },
}

def get_stock_price(ticker: str) -> float:
    """Executes the local tool function."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass the tool declaration to the model
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the stock price of GOOG?",
    tools=[stock_tool],
)

# Inspect the interaction steps for function call requests
for step in interaction.steps:
    if step.type == "function_call" and step.name == "get_stock_price":
        ticker_arg = step.arguments.get("ticker")
        price = get_stock_price(ticker_arg)

        # Turn 2: Submit the function execution result to the conversation
        final_turn = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "call_id": step.id,
                "result": {"price": price},
            }],
            previous_interaction_id=interaction.id,
        )
        print(final_turn.output_text)

TypeScript / JavaScript

// Define a declarative function tool schema
const stockTool = {
    type: "function",
    name: "getStockPrice",
    description: "Gets the stock price for a given ticker symbol.",
    parameters: {
        type: "object",
        properties: {
            ticker: { type: "string", description: "The stock ticker symbol" },
        },
        required: ["ticker"],
    },
};

function getStockPrice({ ticker }: { ticker: string }): number {
    if (ticker.toUpperCase() === "GOOG") return 175.50;
    return 100.00;
}

// Turn 1: Pass the tool declaration to the model
const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the stock price of GOOG?",
    tools: [stockTool],
});

// Inspect the interaction steps for function call requests
for (const step of interaction.steps ?? []) {
    if (step.type === "function_call" && step.name === "getStockPrice") {
        const tickerArg = step.arguments.ticker as string;
        const price = getStockPrice({ ticker: tickerArg });

        // Turn 2: Submit the function execution result to the conversation
        const finalTurn = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [{
                type: "function_result",
                call_id: step.id,
                result: { price },
            }],
            previous_interaction_id: interaction.id,
        });
        console.log(finalTurn.output_text);
    }
}

Usa herramientas integradas

Además de la llamada a funciones del cliente, la API de Interactions admite herramientas integradas del servidor para los modelos de Gemini 3. Cuando habilitas una herramienta integrada en el parámetro tools, Agent Platform la ejecuta en el servidor durante una sola llamada a interactions.create y registra los pasos de invocación (*_call) y resultado (*_result) de la herramienta en interaction.steps.

La API de Interactions admite las siguientes herramientas integradas:

Ejecución de código ({"type": "code_execution"}): Genera y ejecuta código de Python en un entorno de zona de pruebas para realizar cálculos, análisis de datos y razonamiento basado en código. Para obtener información sobre las bibliotecas compatibles, la facturación y las limitaciones, consulta Ejecución de código.
Contexto de URL ({"type": "url_context"}): Recupera y analiza el contenido de las URL web públicas incluidas en su solicitud. Para obtener detalles sobre el almacenamiento en caché de índices, las recuperaciones en vivo y la combinación del contexto de URL con la búsqueda, consulta Contexto de URL.
Fundamentación con la Búsqueda de Google ({"type": "google_search"}): Fundamenta las respuestas del modelo en información web en tiempo real y devuelve citas intercaladas. Consulta Fundamenta las respuestas con la Búsqueda de Google.
Uso de la computadora ({"type": "computer_use"}): Habilita los flujos de trabajo de automatización del navegador y de la interfaz de usuario. Para conocer los controles de configuración y seguridad, consulta Uso de la computadora.

Ejecutar código de Python

Para habilitar la ejecución de código, incluye {"type": "code_execution"} en la lista tools. El array interaction.steps que se devuelve contiene pasos code_execution_call (con arguments.code y arguments.language), pasos code_execution_result (con result y is_error) y el paso final model_output.

En el siguiente ejemplo, reemplaza PROJECT_ID por el ID del proyecto de Google Cloud:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Calculate the 50th Fibonacci number and find its closest prime.",
    tools=[{"type": "code_execution"}],
)

for step in interaction.steps:
    if step.type == "code_execution_call":
        print(f"Generated code:\n{step.arguments.code}")
    elif step.type == "code_execution_result":
        print(f"Execution result:\n{step.result}")
    elif step.type == "model_output":
        for content in step.content:
            if content.type == "text":
                print(content.text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Calculate the 50th Fibonacci number and find its closest prime.",
    tools: [{ type: "code_execution" }],
});

for (const step of interaction.steps ?? []) {
    if (step.type === "code_execution_call") {
        console.log(`Generated code:\n${step.arguments?.code}`);
    } else if (step.type === "code_execution_result") {
        console.log(`Execution result:\n${step.result}`);
    } else if (step.type === "model_output") {
        for (const content of step.content ?? []) {
            if (content.type === "text") {
                console.log(content.text);
            }
        }
    }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Calculate the 50th Fibonacci number and find its closest prime."))
        .tools(List.of(CodeExecution.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

for (Step step : interaction.steps().orElse(List.of())) {
    if (step instanceof CodeExecutionCallStep callStep) {
        callStep
            .arguments()
            .flatMap(args -> args.code())
            .ifPresent(code -> System.out.println("Generated code:\n" + code));
    } else if (step instanceof CodeExecutionResultStep resultStep) {
        resultStep
            .result()
            .ifPresent(res -> System.out.println("Execution result:\n" + res));
    }
}
System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Calculate the 50th Fibonacci number and find its closest prime.",
    "tools": [{"type": "code_execution"}]
  }'

Recupera el contenido de una página web con el contexto de URL

Para permitir que el modelo recupere y analice las páginas web a las que se hace referencia en tu instrucción, incluye {"type": "url_context"} en la lista tools. La API registra las URLs recuperadas en los pasos url_context_call y url_context_result, y adjunta anotaciones de url_citation al texto generado en model_output.

En el siguiente ejemplo, reemplaza PROJECT_ID por el ID del proyecto de Google Cloud, y YOUR_URL_1 y YOUR_URL_2 por las URLs públicas que se compararán:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    tools=[{"type": "url_context"}],
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    tools: [{ type: "url_context" }],
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Compare the key findings from YOUR_URL_1 and YOUR_URL_2."))
        .tools(List.of(URLContext.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    "tools": [{"type": "url_context"}]
  }'

Fundamenta las respuestas con la Búsqueda de Google

La fundamentación conecta los modelos de Gemini con fuentes externas verificables para reducir las alucinaciones y proporcionar respuestas actualizadas con citas. Para obtener una descripción general de las opciones de fundamentación en Agent Platform, consulta la descripción general de la fundamentación, Fundamentación con la Búsqueda de Google y Fundamentación web para empresas.

Cuando habilitas la Fundamentación con la Búsqueda de Google pasando {"type": "google_search"} en la lista tools, la API de Interactions devuelve datos de búsqueda y atribución directamente en la línea de tiempo de interaction.steps:

google_search_call: Contiene las búsquedas que emite el modelo (step.arguments.queries).
google_search_result: Contiene sugerencias de búsqueda (result[].search_suggestions), un fragmento de HTML/CSS que se usa para renderizar sugerencias de búsqueda en las interfaces de usuario. Los recursos web con URLs de origen y títulos se proporcionan como anotaciones url_citation intercaladas en los bloques de texto de model_output.
Anotaciones url_citation intercaladas: Cada bloque de contenido text (TextContent) dentro de un paso model_output puede incluir un array annotations. Cada anotación url_citation identifica el intervalo de caracteres o bytes (start_index y end_index) en el texto de respuesta junto con la fuente title y url.

En el siguiente ejemplo, reemplaza PROJECT_ID por el ID del proyecto de Google Cloud:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the 2026 Super Bowl?",
    tools=[{"type": "google_search"}],
)

print(interaction.output_text)

# Parse inline url_citation annotations from model_output steps
print("\nSources:")
for step in interaction.steps:
    if step.type == "model_output" and step.content:
        for content in step.content:
            if content.type == "text" and getattr(content, "annotations", None):
                for annotation in content.annotations:
                    if annotation.type == "url_citation":
                        span = content.text[annotation.start_index:annotation.end_index]
                        print(f"- [{annotation.title}]({annotation.url}) (cited text: {span!r})")

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Who won the 2026 Super Bowl?",
    tools: [{ type: "google_search" }],
});

console.log(interaction.output_text);

// Parse inline url_citation annotations from model_output steps
console.log("\nSources:");
for (const step of interaction.steps ?? []) {
    if (step.type === "model_output") {
        for (const content of step.content ?? []) {
            if (content.type === "text" && content.annotations) {
                for (const annotation of content.annotations) {
                    if (annotation.type === "url_citation") {
                        const span = content.text.slice(
                            annotation.start_index,
                            annotation.end_index,
                        );
                        console.log(
                            `- [${annotation.title}](${annotation.url}) (cited text: "${span}")`,
                        );
                    }
                }
            }
        }
    }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the 2026 Super Bowl?"))
        .tools(List.of(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

System.out.println(interaction.outputText().orElse(""));

// Parse inline URLCitation annotations from ModelOutputStep blocks
System.out.println("\nSources:");
for (Step step : interaction.steps().orElse(List.of())) {
    if (step instanceof ModelOutputStep outputStep) {
        for (Content content : outputStep.content().orElse(List.of())) {
            if (content instanceof TextContent textContent) {
                for (Annotation annotation : textContent.annotations().orElse(List.of())) {
                    if (annotation instanceof URLCitation citation) {
                        System.out.printf(
                            "- %s: %s (span: %d..%d)%n",
                            citation.title().orElse(""),
                            citation.url().orElse(""),
                            citation.startIndex().orElse(0L),
                            citation.endIndex().orElse(0L));
                    }
                }
            }
        }
    }
}

REST

# Request
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the 2026 Super Bowl?",
    "tools": [{"type": "google_search"}]
  }'

La respuesta incluye los pasos google_search_call, google_search_result y model_output con anotaciones url_citation intercaladas:

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROA",
  "model": "gemini-3.8-flash",
  "status": "completed",
  "steps": [
    {
      "type": "google_search_call",
      "id": "search_call_1",
      "arguments": {
        "queries": ["2026 Super Bowl winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_call_1",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for search suggestions -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The Seattle Seahawks won Super Bowl LX on February 8, 2026.",
          "annotations": [
            {
              "type": "url_citation",
              "start_index": 0,
              "end_index": 59,
              "title": "Super Bowl LX",
              "url": "https://example.com/super-bowl-lx"
            }
          ]
        }
      ]
    }
  ]
}

Ejecutar agentes y tareas en segundo plano de larga duración

Además de los modelos de base, la API de Interactions te permite invocar agentes autónomos especializados con el parámetro agent:

antigravity-preview-05-2026: Agente administrado de uso general con ejecución de código, administración de archivos y navegación web en un entorno de Linux seguro con zona de pruebas. Para obtener más información, consulta Interactúa con agentes.
deep-research-preview-04-2026: Es el agente de Deep Research de Gemini, que planifica y ejecuta tareas de investigación web de varios pasos y sintetiza los hallazgos de varias fuentes en informes completos. Para obtener más información, consulta Usa Gemini Deep Research.
Agentes personalizados: Son recursos de agentes personalizados que se configuran y aprovisionan con client.agents.create().

Debido a que los flujos de trabajo de los agentes suelen tardar varios minutos en completarse, ejecútalos de forma asíncrona en segundo plano configurando background=True. La API devuelve de inmediato un objeto Interaction con un id que puedes sondear con client.interactions.get() hasta que interaction.status cambie a completed:

Antes de probar este ejemplo, reemplaza PROJECT_ID por el ID del proyecto deGoogle Cloud .

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    input="Analyze competitive positioning for solar energy providers.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status in ("failed", "cancelled"):
        print(f"Research ended with status: {interaction.status}")
        break
    time.sleep(10)

Accede a los archivos de Cloud Storage subidos

Puedes usar la API de Interactions para acceder a los archivos de Cloud Storage subidos. En el siguiente ejemplo, reemplaza PROJECT_ID por el ID del proyecto deGoogle Cloud :

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "user_input",
            "content": [
                {"type": "text", "text": "Summarize the attached document:"},
                {
                    "type": "document",
                    "uri": "gs://my-secure-bucket/quarterly_report.pdf",
                    "mime_type": "application/pdf",
                },
            ],
        }
    ],
)

print(interaction.output_text)

Cuando se pasan URIs de Cloud Storage (por ejemplo, gs://bucket-name/path/to/file) a la API de Interactions, las solicitudes verifican el acceso de lectura con las credenciales del emisor antes de que el agente de servicio de Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.) del proyecto que realiza la llamada recupere el objeto de Cloud Storage.

Para pasar archivos de Cloud Storage en una solicitud de interacción, la principal que realiza la llamada (cuenta de usuario, cuenta de servicio o identidad federada) debe tener el permiso storage.objects.get para todos los objetos a los que se hace referencia. Para los buckets de Cloud Storage entre proyectos o los buckets de Cloud Storage con políticas de IAM personalizadas, otorga acceso de lectura a la principal que realiza la llamada y al agente de servicio del proyecto que realiza la llamada.

Cada solicitud de interacción estándar del modelo de Gemini admite hasta 100 URIs de Cloud Storage (gs://) distintos (hasta 2 GiB menos 500 KiB por archivo). Cuando encadenas turnos con estado usando previous_interaction_id, Agent Platform cuenta los URIs de gs:// distintos de forma acumulativa en el historial de conversaciones y el turno actual. Las interacciones de agentes administrados (solicitudes que establecen agent en lugar de model), los modelos de Gemini Omni y los modelos de Lyria 3 se excluyen de este límite de 100 URIs.

Configura roles de IAM para acceder a los archivos de Cloud Storage

Otorga uno de los roles predefinidos estándar que incluyen el permiso storage.objects.get:

Visualizador de objetos de Storage (roles/storage.objectViewer): Acceso de lectura a los objetos (recomendado).
Usuario de objetos de almacenamiento (roles/storage.objectUser): Acceso de lectura y escritura a los objetos.

Para otorgar acceso a una cuenta de usuario con Google Cloud CLI, usa el siguiente comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:user-email@example.com" \
    --role="roles/storage.objectViewer"

Para otorgar acceso a una cuenta de servicio de llamada específica, usa el siguiente comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="serviceAccount:sa-name@PROJECT_ID." \
    --role="roles/storage.objectViewer"

Soluciona problemas de acceso a archivos de Cloud Storage

Si la principal que realiza la llamada no tiene permisos suficientes, la API de Interactions devuelve un error 403 Forbidden similar al siguiente:

Access error:
PERMISSION_DENIED - 403 Forbidden: Calling principal lacks
storage.objects.get on one or more Cloud Storage URIs.

Para resolver este problema, otorga el rol de visualizador de objetos de Storage (roles/storage.objectViewer) en el bucket o el objeto de Cloud Storage al emisor autenticado (y al agente de servicio de la plataforma de agentes del proyecto que realiza la llamada para los buckets de Cloud Storage entre proyectos o de IAM personalizada).

Si el objeto especificado no existe o si los permisos del bucket impiden que el emisor vea si el objeto existe, la API de Interactions devuelve un error 404 Not Found similar al siguiente:

Access error:
NOT_FOUND - 404 Not Found: The object does not exist, or bucket
permissions prevent revealing object existence.

Para resolver este problema, verifica que el URI de Cloud Storage sea correcto y confirma que el emisor autenticado tenga acceso de lectura al bucket.

Si una solicitud de interacción del modelo hace referencia a más de 100 URIs de Cloud Storage distintos en el turno actual y en cualquier historial de previous_interaction_id vinculado, la API de Interactions devuelve un error 400 Bad Request similar al siguiente:

INVALID_ARGUMENT - 400 Bad Request: Request references 101 distinct gs:// URIs, which exceeds the maximum of 100.

Para solucionar este problema, realiza una de las siguientes acciones:

Inicia una interacción nueva sin previous_interaction_id cuando ya no se necesiten los archivos de turnos anteriores.
Combina documentos más pequeños o pasa archivos adicionales intercalados dentro del límite de carga útil de la solicitud (256 MiB comprimidos para solicitudes síncronas o de transmisión, o 9.75 MiB sin comprimir cuando service_tier se establece en deferred con background y store establecidos en true).
Usa generateContent para las solicitudes que hacen referencia a URIs de gs:// hasta los límites de elementos del modelo por modalidad (3,000 imágenes y archivos PDF combinados, 1,000 archivos de audio y 10 videos, o hasta 6,500 archivos cuando se incluyen archivos de texto sin formato).

Encripta los datos de interacción con CMEK

Las interacciones con estado (store=True en Python o store: true en TypeScript/JavaScript) almacenan datos de interacción en reposo durante un máximo de 7 días. Para proteger esos datos con tu propia clave de encriptación en lugar de una Google-owned and Google-managed encryption key, usa un perfil de entrega. Un perfil de entrega vincula una clave de Cloud Key Management Service a un proyecto, una ubicación y un permiso de API. Mientras exista un perfil de entrega, Agent Platform encriptará automáticamente los datos de interacción almacenados; el formato de tu solicitud de interacción no cambiará.

La CMEK del perfil de entrega para la API de Interactions es compatible con las multirregiones us y eu. La región global no es compatible.

Para configurar CMEK para la API de Interactions, haz lo siguiente:

Habilita la API de Cloud KMS y la API de Agent Platform en tu proyecto. Consulta Antes de comenzar.
Crea una clave de Cloud KMS en la multirregión us o eu. Consulta Crea un llavero de claves y una clave.
Otorga al agente de servicio de Gemini Enterprise Agent Platform el rol roles/cloudkms.cryptoKeyEncrypterDecrypter en la clave. Consulta Otorga permisos de Agent Platform.

Crea un perfil de entrega en la misma multirregión (us o eu) que establezca scope en INTERACTIONS_API y cmekConfig.encryptionSpec.kmsKeyName en tu clave:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/servingProfiles?servingProfileId=SERVING_PROFILE_ID" \
  -d '{
    "displayName": "Interactions API CMEK profile",
    "description": "CMEK for Interactions API",
    "scope": "INTERACTIONS_API",
    "cmekConfig": {
      "encryptionSpec": {
        "kmsKeyName": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME"
      }
    }
  }'

Espera a que se complete la operación de creación de larga duración ("done": true). Para obtener más detalles sobre cómo administrar, actualizar o borrar perfiles de entrega, consulta Crea un perfil de entrega.

Envía tus solicitudes de interacción a la misma multirregión us o eu que tu perfil de entrega. La CMEK del perfil de entrega no está disponible en el extremo global.
- SDK de IA generativa de Google: Inicializa el cliente con location="us" o location="eu" (location: "us" o location: "eu" en TypeScript/JavaScript).
- REST: Envía solicitudes al extremo multirregional https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions, en el que LOCATION es us o eu.
Si inhabilitas la clave o revocas el acceso del agente de servicio, las solicitudes que crean o leen interacciones almacenadas fallan con un error FAILED_PRECONDITION.

Flujos de trabajo de REST avanzados

Para la automatización basada en shell, las canalizaciones de CI/CD o los entornos sin un entorno de ejecución de Python o TypeScript/JavaScript, puedes llamar a la API de Interactions directamente a través de HTTP con curl.

Extremo de REST

Envía solicitudes POST al siguiente extremo de API de Interactions:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions

Reemplaza las siguientes variables en tus solicitudes:

PROJECT_ID: Es el ID del proyecto de Google Cloud .
LOCATION: Se establece en global (o us o eu con el host multirregional https://aiplatform.LOCATION.rep.googleapis.com para la residencia de datos o la CMEK).

Configura las variables de entorno y la autenticación

Antes de ejecutar los ejemplos de curl en las siguientes secciones, exporta tu ID del proyecto, el modelo de destino o el ID del agente, y un token de acceso de OAuth 2.0 generado a partir de las credenciales predeterminadas de la aplicación:

PROJECT_ID="PROJECT_ID"
MODEL_ID="gemini-3.8-flash"
AGENT_ID="deep-research-preview-04-2026"
ACCESS_TOKEN=$(gcloud auth print-access-token)

Formato de respuesta síncrona

Una solicitud POST síncrona devuelve un objeto JSON interaction que incluye los metadatos únicos de interacción id, ejecución status, conversación steps y token usage:

{
  "id": "your-interaction-id",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Serverless computing is a cloud execution model where the cloud provider dynamically manages the allocation and provisioning of servers, charging customers based on actual usage rather than pre-purchased capacity."
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 24751,
    "total_input_tokens": 23894,
    "total_output_tokens": 857
  },
  "created": "2026-05-08T10:44:43Z",
  "updated": "2026-05-08T10:44:43Z",
  "environment_id": "your-environment-id",
  "object": "interaction"
}

Continúa una interacción con estado de varios turnos

Para continuar una conversación almacenada a través de REST, pasa el id de una respuesta anterior en el campo previous_interaction_id del cuerpo de la solicitud JSON.

Antes de probar esta muestra, reemplaza PREVIOUS_INTERACTION_ID por el id que se devolvió en una interacción anterior.

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "store": true,
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

Transmite resultados con eventos enviados por el servidor

Para transmitir actualizaciones incrementales a través de REST, incluye "stream": true en el cuerpo de la solicitud JSON:

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Write a long story about space travel."
      }]
    }]
  }'

Cuando se establece "stream": true, el servidor responde con Transfer-Encoding: chunked y Content-Type: text/event-stream (eventos enviados por el servidor). Cada evento de la transmisión incluye un prefijo data: que contiene una carga útil de JSON con el event_type y el contenido delta del paso. curl mantiene abierta automáticamente la conexión HTTP y escribe fragmentos entrantes en stdout en tiempo real hasta que se completa la interacción.

Ejecuta un agente administrado en segundo plano

Para iniciar una tarea de agente administrado de larga duración de forma asíncrona a través de REST, especifica el agent de destino, establece "background": true y configura "environment": "remote":

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"${AGENT_ID}"'",
    "environment": "remote",
    "background": true,
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

¿Qué sigue?

Explora los siguientes recursos para obtener más información sobre la API de Interactions, las herramientas integradas y la fundamentación:

Obtén más información sobre los conceptos clave en la descripción general de la API de Interactions.
Explora los esquemas de solicitud y respuesta en la referencia de la API de Interactions.
Obtén más información sobre la ejecución de código, el contexto de URL y la Fundamentación con la Búsqueda de Google.
Aprende a interactuar con agentes administrados y usar el agente de Gemini Deep Research.

Guía para desarrolladores de la API de Interactions Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Check for the roles

Grant the roles

Conceptos clave

Requisitos

Instala el SDK de IA generativa de Google

Python

TypeScript / JavaScript

Go

Java

Autentica tu cliente

Conéctate con un proyecto de Google Cloud con las credenciales predeterminadas de la aplicación (ADC)

Python

TypeScript / JavaScript

REST

Conéctate con el modo Exprés (clave de API)

Python

TypeScript / JavaScript

REST

Flujos de trabajo de interacción comunes

Administra el almacenamiento de sesiones y el estado de las conversaciones

Ejecuta conversaciones de varios turnos con estado

Python

TypeScript / JavaScript

Java

REST

Ejecuta conversaciones de varios turnos sin estado

Python

TypeScript / JavaScript

Java

REST

Retención y ciclo de vida de la sesión

Recuperar, enumerar, cancelar y borrar interacciones almacenadas

Python

TypeScript / JavaScript

Java

REST

Cuotas y límites de almacenamiento con estado

Transmite respuestas en tiempo real

Python

TypeScript / JavaScript

Genera un resultado estructurado

Python

TypeScript / JavaScript

Usa la llamada a funciones (uso de herramientas)

Python

TypeScript / JavaScript

Usa herramientas integradas

Ejecutar código de Python

Python

TypeScript / JavaScript

Java

REST

Recupera el contenido de una página web con el contexto de URL

Python

TypeScript / JavaScript

Java

REST

Fundamenta las respuestas con la Búsqueda de Google

Python

TypeScript / JavaScript

Java

REST

Ejecutar agentes y tareas en segundo plano de larga duración

Accede a los archivos de Cloud Storage subidos

Configura roles de IAM para acceder a los archivos de Cloud Storage

Soluciona problemas de acceso a archivos de Cloud Storage

Encripta los datos de interacción con CMEK

Flujos de trabajo de REST avanzados

Extremo de REST

Configura las variables de entorno y la autenticación

Formato de respuesta síncrona

Continúa una interacción con estado de varios turnos

Transmite resultados con eventos enviados por el servidor

Ejecuta un agente administrado en segundo plano

¿Qué sigue?

Guía para desarrolladores de la API de Interactions