Guia para desenvolvedores da API Interactions

A API Interactions oferece uma interface unificada e com estado para criar aplicativos de IA generativa com modelos do Gemini e agentes autônomos na Gemini Enterprise Agent Platform. Use a API Interactions para gerenciar o armazenamento de sessões e conversas de vários turnos, transmitir respostas em tempo real, aplicar saídas estruturadas, invocar ferramentas e embasamento integrados, executar chamadas de função e orquestrar tarefas em segundo plano de longa duração.

Este guia mostra como instalar o SDK de IA generativa do Google, autenticar seu cliente e implementar fluxos de trabalho de interação comuns. Para detalhes conceituais sobre o ciclo de vida da interação, consulte a visão geral da API Interactions.

Antes de começar

Antes de enviar solicitações para a API Interactions, configure seu projeto do Google Cloud e o ambiente de desenvolvimento:

  1. 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.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. 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

  4. 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.

Principais conceitos

Confira os conceitos a seguir para entender como a API Interactions gerencia o estado e as respostas:

  • Interaction: a API Interactions se concentra em um recurso principal: uma Interaction. Um Interaction representa uma rodada completa em uma conversa ou tarefa, acompanhando a cronologia dos pensamentos do modelo, chamadas de ferramentas e saídas finais. Ele fornece um envelope unificado para interações de comando-resposta e Agentic Workflows complexos e de várias etapas.

  • Retenção com estado: as interações são armazenadas do lado do servidor por padrão (store=True em Python ou store: true em TypeScript/JavaScript). As interações armazenadas persistem por sete dias e são excluídas automaticamente após esse período. Definir store=False ativa o modo sem estado, que desativa a retenção de dados do lado do servidor e obedece à retenção zero de dados (ZDR). O modo sem estado também desativa o encadeamento de previous_interaction_id e a execução assíncrona (background=True).

  • Auxiliares de resposta: a versão 2.3.0 e mais recentes do SDK de IA Generativa do Google oferecem propriedades de conveniência na resposta de interação, incluindo interaction.output_text, interaction.output_image e interaction.output_audio. Use interaction.output_text para ler respostas de texto em vez de indexar manualmente na matriz de etapas (como interaction.steps[-1].content[0].text).

Requisitos

Verifique se o ambiente e as solicitações atendem aos seguintes requisitos antes de fazer a integração com a API Interactions:

  • Suporte à versão do SDK: use uma das bibliotecas do SDK de IA generativa do Google compatíveis.

  • Modelos compatíveis: use modelos compatíveis do Gemini 3 ou mais recentes. As famílias de modelos anteriores não são compatíveis com essa API. Para uma lista completa de modelos compatíveis, consulte Modelos compatíveis e Migrar para as versões mais recentes do modelo.

  • Parâmetros com escopo de turno: parâmetros de configuração como tools, system_instruction e generation_config se aplicam apenas ao turno atual. Transmita esses parâmetros em cada turno de interação subsequente se o fluxo de trabalho exigir isso em uma conversa com várias interações.

  • Decodificações longas no Gemini 4 Argon: para gerar saídas de turno único que excedam 65.536 tokens (até 1.048.576 tokens menos tokens de entrada) em gemini-4-argon ou gemini-4-argon-cyber-permissive, use a continuação automática do SDK de IA generativa do 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 ou continuation_token no endpoint v1beta1. Para exemplos de código e regras de continuação, consulte Decodificações longas no guia para desenvolvedores do Gemini 4 Argon.

Instalar o SDK de IA generativa do Google

Instale ou faça upgrade do SDK de IA generativa do Google para sua linguagem preferida:

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>

Autenticar o cliente

É possível se conectar à API Interactions na Agent Platform usando um dos seguintes métodos de autenticação:

Conectar-se usando um projeto do Google Cloud com o Application Default Credentials (ADC)

Use esse método de autenticação para cargas de trabalho corporativas e implantações de produção no Google Cloud. Para autenticar com o Application Default Credentials (ADC), inicialize o cliente com as seguintes propriedades:

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

Se você ainda não configurou as credenciais locais, execute gcloud auth application-default login.

No exemplo de código a seguir, substitua PROJECT_ID pelo ID do projeto doGoogle 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."
      }]
    }]
  }'

Conectar usando o modo expresso (chave de API)

Use esse método de autenticação para prototipagem rápida, scripts leves ou ambientes que se autenticam com uma chave de API. Transmita sua chave de API ao inicializar o cliente ou no cabeçalho HTTP x-goog-api-key.

No exemplo de código a seguir, substitua API_KEY pela sua chave de API e PROJECT_ID pelo ID do projeto do 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."
      }]
    }]
  }'

Fluxos de trabalho de interação comuns

Depois de configurar o cliente, use o método interactions.create para gerenciar o armazenamento de sessões e as conversas de vários turnos, transmitir tokens de saída em tempo real, gerar JSON validado por esquema, invocar ferramentas e embasamento integrados, chamar funções externas e executar agentes autônomos.

Gerenciar o armazenamento da sessão e o estado da conversa

A API Interactions oferece suporte ao armazenamento com estado no servidor (store=True, padrão) e à execução sem estado gerenciada pelo cliente (store=False). A tabela a seguir compara os modos de interação com e sem estado:

Recurso Modo com estado (store=true, padrão) Modo sem estado (store=false)
Persistência do lado do servidor Armazena entradas, etapas intermediárias e saídas no servidor por sete dias. Desativa o armazenamento de interações do lado do servidor para oferecer suporte a fluxos de trabalho de retenção zero de dados (ZDR).
Contexto multiturno Encadeia as interações transmitindo a interação anterior id em previous_interaction_id. Requer a transmissão da matriz completa da conversa anterior steps em input em cada turno. Transmitir previous_interaction_id retorna um erro 400 Bad Request.
Execução em segundo plano (background=true) Compatível com interações de longa duração de modelos e agentes. Incompatível. A execução assíncrona em segundo plano requer persistência de estado do lado do servidor.
Métodos de ciclo de vida da sessão Oferece suporte à recuperação (get), listagem (list), cancelamento (cancel) e exclusão (delete) de interações. Não é possível recuperar após a conclusão da resposta síncrona ou de streaming.
Criptografia em repouso Criptografados por padrão com um Google-owned and Google-managed encryption keyou com chaves de criptografia gerenciadas pelo cliente (CMEK) nas multirregiões us e eu. Nenhum estado de interação é armazenado em repouso.

Executar conversas multiturno com estado

Por padrão, a API Interactions armazena o estado da conversa no servidor (store=True em Python ou store: true em TypeScript/JavaScript). Para continuar uma conversa, transmita o id da interação anterior para o parâmetro previous_interaction_id. A Agent Platform recupera o contexto de conversa armazenado, adiciona a nova rodada e reutiliza os tokens de prefixo armazenados em cache.

Ao encadear interações entre endpoints, observe as seguintes regras de local:

  • Mesmo local: é possível encadear interações no mesmo local (como global para global, us para us ou eu para eu).

  • Em locais diferentes: não é possível encadear em locais de endpoint diferentes (entre global e us ou eu, ou entre us e eu). Cada endpoint armazena o estado da interação em um armazenamento isolado. Portanto, referenciar um ID de interação criado em outro local retorna um erro 404 Not Found.

No exemplo a seguir, substitua PROJECT_ID pelo ID do projeto do 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?"
  }'

Executar conversas multiturno sem estado

Se a carga de trabalho exigir retenção de dados zero (ZDR), defina explicitamente store=False (store: false em TypeScript/JavaScript ou "store": false em REST) em cada solicitação.

No modo sem estado, você gerencia o histórico de conversas no cliente mantendo uma lista de objetos Step (user_input, thought, function_call, function_result e model_output) e enviando a matriz steps acumulada em input a 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?"}]
      }
    ]
  }'

Retenção e ciclo de vida da sessão

As interações armazenadas (store=True) seguem estas regras de retenção e ramificação:

  • Time to live (TTL) de 7 dias: cada interação armazenada persiste por 7 dias a partir do carimbo de data/hora created e é excluída automaticamente quando o TTL de 7 dias expira.

  • Armazenamento independente de pai e filho: quando você encadeia uma nova rodada usando previous_interaction_id, a plataforma de agentes copia o histórico de conversas do ancestral para o novo registro de interação. Como cada turno armazena a própria cópia do histórico da conversa, expirar ou excluir um turno anterior tem os seguintes efeitos:

    • A continuação de um turno posterior é bem-sucedida: se o turno 1 (interaction_1) expirar ou for excluído depois que o turno 2 (interaction_2) já tiver sido criado, você ainda poderá criar o turno 3 usando previous_interaction_id=interaction_2.id até que o próprio interaction_2 expire ou seja excluído.

    • A ramificação de uma rodada expirada ou excluída falha: tentar criar uma nova interação que faça referência direta a um ID de interação expirado ou excluído em previous_interaction_id retorna um erro 400 Bad Request (Previous Interaction ID not found).

Recuperar, listar, cancelar e excluir interações armazenadas

É possível inspecionar e gerenciar as interações armazenadas durante todo o ciclo de vida delas usando os seguintes métodos:

  • Recuperar uma interação (interactions.get): busca o recurso Interaction completo por id, incluindo as etapas de user_input, thought intermediárias e de ferramenta, além das etapas de model_output. Defina stream=True (e, opcionalmente, last_event_id) para transmitir ou retomar uma interação em andamento.

  • Listar interações (interactions.list): consulta os IDs de interação armazenados no projeto por REST usando page_size (padrão 10, máximo 500) e page_token. Retorna uma lista de recursos InteractionMetadata.

  • Cancelar uma interação em andamento (interactions.cancel): interrompe uma interação assíncrona em segundo plano (background=True) que está no estado in_progress ou requires_action e muda o status para cancelled. Você vai precisar pagar por todos os tokens gerados antes do cancelamento.

  • Excluir uma interação armazenada (interactions.delete): remove permanentemente uma interação armazenada antes que o TTL de sete dias expire. Somente interações em um estado terminal (completed, failed ou cancelled) podem ser excluídas. Se uma interação ainda estiver em execução em segundo plano, cancele-a antes de excluí-la.

No exemplo a seguir, substitua PROJECT_ID pelo ID do projeto do Google Cloud e INTERACTION_ID pelo ID da interação 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)"

Cotas e limites de armazenamento com estado

Além dos limites de token de modelo e taxa de solicitação, as interações com estado (store=True) estão sujeitas aos seguintes limites de armazenamento e simultaneidade para envolvidos no projeto:

Cota ou limite do sistema Limite padrão (por projeto) Descrição
Capacidade de criação de interações com estado por dia 240 GiB por dia Volume total máximo de dados de interação gravados no armazenamento do lado do servidor por dia em solicitações de interactions.create com store=true.
Capacidade de recuperação de interações com estado por dia 480 GiB por dia Volume total máximo de dados de interação armazenados lidos por dia em solicitações interactions.get e solicitações de várias interações que carregam interações anteriores usando previous_interaction_id.
Interações simultâneas com estado 500 interações simultâneas Número máximo de interações com estado ativas em execução simultânea em um projeto.

Para mais informações sobre como visualizar e gerenciar cotas na Plataforma de Agentes, consulte Cotas e limites do sistema.

Respostas de streaming em tempo real

Para reduzir a latência percebida em aplicativos interativos, é possível transmitir as respostas do modelo conforme elas são geradas. Defina stream=True (stream: true em TypeScript/JavaScript) ao chamar interactions.create para receber um stream iterável de eventos enviados pelo servidor. Filtre os eventos step.delta para renderizar blocos de texto incrementais conforme eles chegam:

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();

Gerar saída estruturada

Quando o aplicativo exige respostas em um formato previsível e legível por máquina, é possível restringir a saída do modelo para que ela corresponda a um esquema JSON específico. Transmita o esquema de destino, como um esquema JSON de modelo Pydantic em Python ou um objeto de esquema Type em TypeScript/JavaScript, diretamente para o 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);

Usar chamada de função (uso de ferramentas)

A chamada de função permite que um modelo solicite a execução de funções personalizadas ou APIs externas para coletar informações antes de formular uma resposta final. Em um fluxo de trabalho de interação com estado, a chamada de função segue um padrão de dois turnos:

  1. Declarar e transmitir ferramentas: forneça as declarações de função no parâmetro tools na solicitação inicial.

  2. Executar e retornar resultados: inspecione as etapas de resposta (interaction.steps) para as etapas function_call, execute a função local usando o arguments fornecido pelo modelo e envie uma interação de acompanhamento contendo um item function_result vinculado por call_id e 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);
    }
}

Usar ferramentas integradas

Além da chamada de função do lado do cliente, a API Interactions oferece suporte a ferramentas integradas do lado do servidor para modelos do Gemini 3. Quando você ativa uma ferramenta integrada no parâmetro tools, a Agent Platform executa a ferramenta no servidor durante uma única chamada interactions.create e registra as etapas de invocação (*_call) e saída (*_result) da ferramenta em interaction.steps.

A API Interactions é compatível com as seguintes ferramentas integradas:

  • Execução de código ({"type": "code_execution"}): gera e executa código Python em um ambiente de sandbox para realizar cálculos, análise de dados e raciocínio baseado em código. Para saber mais sobre bibliotecas, faturamento e limitações, consulte Execução de código.

  • Contexto de URL ({"type": "url_context"}): recupera e analisa o conteúdo de URLs públicos da Web incluídos no comando. Para detalhes sobre armazenamento em cache de índice, buscas em tempo real e combinação de contexto de URL com pesquisa, consulte Contexto de URL.

  • Embasamento com a Pesquisa Google ({"type": "google_search"}): embasa as respostas do modelo em informações da Web em tempo real e retorna citações inline. Consulte Embasar respostas com a Pesquisa Google.

  • Uso do computador ({"type": "computer_use"}): permite fluxos de trabalho de automação do navegador e da interface do usuário. Para controles de configuração e segurança, consulte Uso do computador.

Executar código Python

Para ativar a execução de código, inclua {"type": "code_execution"} na lista tools. A matriz interaction.steps retornada contém etapas code_execution_call (com arguments.code e arguments.language), etapas code_execution_result (com result e is_error) e a etapa final model_output.

No exemplo a seguir, substitua PROJECT_ID pelo ID do projeto do 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"}]
  }'

Recuperar conteúdo de páginas da Web com contexto de URL

Para permitir que o modelo busque e analise páginas da Web referenciadas no comando, inclua {"type": "url_context"} na lista tools. A API registra os URLs buscados nas etapas url_context_call e url_context_result e anexa anotações url_citation ao texto gerado em model_output.

No exemplo a seguir, substitua PROJECT_ID pelo ID do projeto do Google Cloud e YOUR_URL_1 e YOUR_URL_2 pelos URLs públicos a serem comparados:

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"}]
  }'

Embasar respostas com a Pesquisa Google

O embasamento conecta os modelos do Gemini a fontes externas verificáveis para reduzir as alucinações e fornecer respostas atualizadas com citações. Para uma visão geral das opções de embasamento na Agent Platform, consulte a Visão geral do embasamento, Embasamento com a Pesquisa Google e Embasamento na Web para empresas.

Quando você ativa o embasamento com a Pesquisa Google transmitindo {"type": "google_search"} na lista tools, a API Interactions retorna dados de pesquisa e atribuição diretamente na linha do tempo interaction.steps:

  • google_search_call: contém as consultas de pesquisa emitidas pelo modelo (step.arguments.queries).

  • google_search_result: contém sugestões de pesquisa (result[].search_suggestions), um snippet HTML/CSS usado para renderizar sugestões de pesquisa em interfaces do usuário. Os recursos da Web com URLs de origem e títulos são fornecidos como anotações inline url_citation em blocos de texto model_output.

  • Anotações inline url_citation: cada bloco de conteúdo text (TextContent) em uma etapa model_output pode incluir uma matriz annotations. Cada anotação url_citation identifica o intervalo de caracteres ou bytes (start_index e end_index) no texto de resposta, junto com a origem title e url.

No exemplo a seguir, substitua PROJECT_ID pelo ID do projeto do 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"}]
  }'

A resposta inclui as etapas google_search_call, google_search_result e model_output com anotações url_citation inline:

{
  "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"
            }
          ]
        }
      ]
    }
  ]
}

Executar agentes e tarefas em segundo plano de longa duração

Além dos modelos de fundação, a API Interactions permite invocar agentes autônomos especializados usando o parâmetro agent:

  • antigravity-preview-05-2026: agente gerenciado de uso geral com execução de código, gerenciamento de arquivos e navegação na Web em um ambiente Linux seguro em sandbox. Para mais informações, consulte Interagir com agentes.
  • deep-research-preview-04-2026: agente Deep Research do Gemini, que planeja e executa tarefas de pesquisa na Web em várias etapas e sintetiza descobertas de várias fontes em relatórios abrangentes. Para mais informações, consulte Usar o agente do Deep Research do Gemini.
  • Agentes personalizados: recursos de agentes personalizados configurados e provisionados com client.agents.create().

Como os Agentic Workflows geralmente levam vários minutos para serem concluídos, execute-os de maneira assíncrona em segundo plano definindo background=True. A API retorna imediatamente um objeto Interaction com um id que pode ser consultado usando client.interactions.get() até que interaction.status faça a transição para completed:

Antes de testar este exemplo, substitua PROJECT_ID pelo ID do projeto doGoogle 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)

Acessar arquivos enviados do Cloud Storage

É possível usar a API Interactions para acessar arquivos do Cloud Storage enviados. No exemplo a seguir, substitua PROJECT_ID pelo ID do projeto doGoogle 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)

Ao transmitir URIs do Cloud Storage (por exemplo, gs://bucket-name/path/to/file) para a API Interactions, as solicitações verificam o acesso de leitura usando as credenciais do autor da chamada antes que o agente de serviço da plataforma de agentes (service-PROJECT_NUMBER@gcp-sa-aiplatform.) do projeto de chamada busque o objeto no Cloud Storage.

Para transmitir arquivos do Cloud Storage em uma solicitação de interação, o principal chamador (conta de usuário, conta de serviço ou identidade federada) precisa ter a permissão storage.objects.get para todos os objetos referenciados. Para buckets do Cloud Storage entre projetos ou buckets do Cloud Storage com políticas de IAM personalizadas, conceda acesso de leitura ao principal de chamada e ao agente de serviço do projeto de chamada.

Cada solicitação de interação do modelo padrão do Gemini aceita até 100 URIs distintos do Cloud Storage (gs://) (até 2 GiB menos 500 KiB por arquivo). Quando você encadeia turnos com estado usando previous_interaction_id, a Agent Platform conta os URIs gs:// distintos de forma cumulativa no histórico de conversas e no turno atual. As interações de agentes gerenciados (solicitações que definem agent em vez de model), os modelos Gemini Omni e os modelos Lyria 3 estão excluídos desse limite de 100 URIs.

Configurar papéis do IAM para acessar arquivos do Cloud Storage

Conceda um dos papéis predefinidos padrão que incluem a permissão storage.objects.get:

  • Leitor de objetos do Storage (roles/storage.objectViewer): acesso de leitura a objetos (recomendado).

  • Usuário de objetos do Storage (roles/storage.objectUser): acesso de leitura e gravação a objetos.

Para conceder acesso a uma conta de usuário usando a Google Cloud CLI, use o seguinte comando:

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

Para conceder acesso a uma conta de serviço de chamada específica, use o seguinte comando:

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

Resolver problemas de acesso a arquivos do Cloud Storage

Se o principal que faz a chamada não tiver permissões suficientes, a API Interactions vai retornar um erro 403 Forbidden semelhante ao seguinte:

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

Para resolver esse problema, conceda o papel de Leitor de objetos do Storage (roles/storage.objectViewer) no bucket ou objeto do Cloud Storage ao autor da chamada autenticado (e ao agente de serviço da plataforma de agentes do projeto de chamada para buckets do Cloud Storage entre projetos ou personalizados do IAM).

Se o objeto especificado não existir ou se as permissões do bucket impedirem que o autor da chamada veja se o objeto existe, a API Interactions vai retornar um erro 404 Not Found semelhante ao seguinte:

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

Para resolver esse problema, verifique se o URI do Cloud Storage está correto e confirme se o autor da chamada autenticado tem acesso de leitura ao bucket.

Se uma solicitação de interação do modelo fizer referência a mais de 100 URIs distintos do Cloud Storage na rodada atual e em qualquer histórico de previous_interaction_id vinculado, a API Interactions vai retornar um erro 400 Bad Request semelhante ao seguinte:

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

Para resolver o problema, siga um destes procedimentos:

  • Inicie uma nova interação sem previous_interaction_id quando os arquivos de interações anteriores não forem mais necessários.
  • Combine documentos menores ou transmita outros arquivos inline dentro do limite de payload da solicitação (256 MiB compactados para solicitações síncronas ou de streaming, ou 9,75 MiB descompactados quando service_tier estiver definido como deferred com background e store definidos como true).
  • Use generateContent para solicitações que referenciam URIs do gs:// até os limites de itens do modelo por modalidade (3.000 imagens e PDFs combinados, 1.000 arquivos de áudio e 10 vídeos ou até 6.500 arquivos, incluindo arquivos de texto simples).

Criptografar dados de interação com CMEK

As interações com estado (store=True em Python ou store: true em TypeScript/JavaScript) armazenam dados de interação em repouso por até 7 dias. Para proteger esses dados com sua própria chave de criptografia em vez de uma Google-owned and Google-managed encryption key, use um perfil de exibição. Um perfil de exibição vincula uma chave do Cloud Key Management Service a um projeto, local e escopo de API. Enquanto um perfil de veiculação existir, a Agent Platform vai criptografar automaticamente os dados de interação armazenados. O formato da solicitação de interação não muda.

A CMEK do perfil de veiculação para a API Interactions é compatível com as multirregiões us e eu. A região global não é compatível.

Para configurar a CMEK para a API Interactions, faça o seguinte:

  1. Ative a API Cloud KMS e a API Agent Platform no seu projeto. Consulte Antes de começar.
  2. Crie uma chave do Cloud KMS na multirregião us ou eu. Consulte Criar um keyring e uma chave.
  3. Conceda ao agente de serviço da Gemini Enterprise Agent Platform o papel roles/cloudkms.cryptoKeyEncrypterDecrypter na chave. Consulte Conceder permissões da Agent Platform.

  4. Crie um perfil de exibição na mesma multirregião (us ou eu) que define scope como INTERACTIONS_API e cmekConfig.encryptionSpec.kmsKeyName como sua chave:

    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"
      }
    }
  }'

    Aguarde a conclusão da operação de criação de longa duração ("done": true). Para mais detalhes sobre como gerenciar, atualizar ou excluir perfis de veiculação, consulte Criar um perfil de veiculação.

  5. Envie suas solicitações de interação para a mesma multirregião us ou eu do seu perfil de veiculação. A CMEK do perfil de veiculação não está disponível no endpoint global.

    • SDK de IA generativa do Google: inicialize o cliente com location="us" ou location="eu" (location: "us" ou location: "eu" em TypeScript/JavaScript).
    • REST: envie solicitações para o endpoint multirregional https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions, em que LOCATION é us ou eu.

    Se você desativar a chave ou revogar o acesso do agente de serviço, as solicitações que criam ou leem interações armazenadas vão falhar com um erro FAILED_PRECONDITION.

Fluxos de trabalho REST avançados

Para automação baseada em shell, pipelines de CI/CD ou ambientes sem um ambiente de execução do Python ou TypeScript/JavaScript, é possível chamar a API Interactions diretamente por HTTP usando curl.

Endpoint REST

Envie solicitações POST para o seguinte endpoint de API Interactions:

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

Substitua as seguintes variáveis nas suas solicitações:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: defina como global (ou us ou eu com o host multirregional https://aiplatform.LOCATION.rep.googleapis.com para residência de dados ou CMEK).

Definir variáveis de ambiente e autenticação

Antes de executar os exemplos de curl nas seções a seguir, exporte o ID do projeto, o modelo de destino ou o ID do agente e um token de acesso do OAuth 2.0 gerado pelo Application Default Credentials:

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 resposta síncrona

Uma solicitação síncrona POST retorna um objeto JSON interaction que inclui os metadados exclusivos de interação id, execução status, conversa steps e 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"
}

Continuar uma interação multiturno com estado

Para continuar uma conversa armazenada por REST, transmita o id de uma resposta anterior no campo previous_interaction_id do corpo da solicitação JSON.

Antes de testar este exemplo, substitua PREVIOUS_INTERACTION_ID pelo id retornado por uma interação 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?"
      }]
    }]
  }'

Saída de stream com eventos enviados pelo servidor

Para transmitir atualizações incrementais por REST, inclua "stream": true no corpo da solicitação 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."
      }]
    }]
  }'

Quando "stream": true é definido, o servidor responde com Transfer-Encoding: chunked e Content-Type: text/event-stream (eventos enviados pelo servidor). Cada evento no stream inclui um prefixo data: que contém um payload JSON com o conteúdo de event_type e o delta da etapa. O curl mantém automaticamente a conexão HTTP aberta e grava os blocos recebidos em stdout em tempo real até que a interação seja concluída.

Executar um agente gerenciado em segundo plano

Para iniciar uma tarefa de agente gerenciado de longa duração de forma assíncrona por REST, especifique o agent de destino, defina "background": true e configure "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."
      }]
    }]
  }'

A seguir

Confira os recursos a seguir para saber mais sobre a API Interactions, as ferramentas integradas e o embasamento: