O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Guia para desenvolvedores da API Interactions

Visualizar

Este recurso está sujeito aos "Termos da Pré-GA" nos Termos Gerais de Serviço dos Termos Específicos de Serviço e aos Termos Adicionais para Produtos Pré-lançamento de IA Generativa. Você pode processar dados pessoais para esse recurso conforme descrito no Aditivo sobre tratamento de dados do Cloud, sujeito às obrigações e restrições descritas no contrato que rege seu acesso ao Google Cloud. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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 executar conversas multiturno, transmitir respostas em tempo real, aplicar saídas estruturadas, 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 à API Interactions, configure seu projeto Google Cloud e ambiente de desenvolvimento:

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access.
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role, then search for the role.
To grant additional roles, click Add another role and add each additional role.
Click Save.

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

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

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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access.
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role, then search for the role.
To grant additional roles, click Add another role and add each additional role.
Click Save.

Principais conceitos

Confira os conceitos a seguir para entender como a API Interactions gerencia estados e respostas:

Interaction: a API Interactions se concentra em um recurso principal: um Interaction. Um Interaction representa um turno completo em uma conversa ou tarefa, rastreando a cronologia de ideias do modelo, chamadas de ferramentas e saídas finais. Ele oferece um envelope unificado para interações de solicitação-resposta e fluxos de trabalho de agentes complexos e com várias etapas.
Retenção com estado: as interações são armazenadas no lado do servidor por padrão (store=True em Python ou store: true em TypeScript/JavaScript). As interações armazenadas ficam disponíveis 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 do lado do servidor e está em conformidade com a 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).
Helpers de resposta: o SDK de IA generativa do Google versão 2.3.0 e mais recente fornece propriedades convenientes 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 a matriz de etapas (como interaction.steps[-1].content[0].text).

Requisitos

Antes de integrar com a API Interactions, verifique se seu ambiente e suas solicitações atendem aos seguintes requisitos:

Suporte a versões do SDK: use o SDK de IA Generativa do Google unificado (>= 2.3.0 para Python ou @google/genai >= 2.3.0 para TypeScript e JavaScript).
- A versão 2.3.0 ou mais recente é necessária para propriedades de assistente de resposta e recursos do agente, enquanto a versão 2.0.0 é compatível com o esquema básico steps.
- Os SDKs legados (google-cloud-aiplatform, @google-cloud/vertexai e google-generativeai) não são compatíveis com a API Interactions.
Modelos compatíveis: use os modelos do Gemini 3 ou mais recentes. As famílias de modelos anteriores não oferecem suporte a 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 no escopo da rodada: parâmetros de configuração como tools, system_instruction e generation_config se aplicam apenas à rodada atual. Transmita esses parâmetros em cada turno de interação subsequente se o fluxo de trabalho exigir isso em uma conversa multiturno.

Instalar o SDK de IA generativa do Google

Instale ou faça upgrade do SDK de IA generativa do Google (>= 2.3.0) para sua linguagem de programação preferida:

Python

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

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

Autenticar seu cliente

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

Conectar usando um projeto Google Cloud com Application Default Credentials (ADC)

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

enterprise=True
project= Google Cloud project ID
location="global"

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

No exemplo de código a seguir, substitua PROJECT_ID pelo ID do projetoGoogle 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/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Conectar usando o modo expresso (chave de API)

Recomendamos usar esse método de autenticação para prototipagem rápida, scripts leves ou ambientes que 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.

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/v1beta1/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "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 criar conversas multiturno, transmitir tokens de saída em tempo real, gerar JSON validado por esquema, chamar funções externas e executar agentes autônomos.

Gerenciar conversas multiturno com estado

Ao contrário das APIs de chat sem estado, que exigem o reenvio do histórico de mensagens completo a cada solicitação, a API Interactions gerencia o estado da conversa no servidor por padrão (store=True em Python ou store: true em TypeScript/JavaScript).

Para continuar uma conversa, transmita o id da interação anterior ao parâmetro previous_interaction_id. A Agent Platform recupera automaticamente o contexto da conversa armazenada e anexa a nova interação. Se você definir store=False (store: false em TypeScript/JavaScript), a persistência do lado do servidor será desativada e não será possível encadear turnos subsequentes com previous_interaction_id.

Python

# Turn 1: Start a 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

// Turn 1: Start a 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}`);

Transmita respostas em tempo real

Para reduzir a latência percebida em aplicativos interativos, é possível transmitir as respostas do modelo à medida que elas são geradas. Defina stream=True (stream: true em TypeScript/JavaScript) ao chamar interactions.create para receber um fluxo iterável de eventos enviados pelo servidor. Filtre eventos step.delta para renderizar partes de texto incrementais à medida que 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 corresponder a um esquema JSON específico. Transmita seu 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 a chamada de função (uso de ferramentas)

Com a chamada de função, um modelo pode solicitar 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 duas rodadas:

Declarar e transmitir ferramentas: forneça as declarações de função no parâmetro tools na solicitação inicial.
Executar e retornar resultados: inspecione as etapas de resposta (interaction.steps) para etapas function_call, execute sua 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);
    }
}

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

Além dos modelos de base, 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: o agente Deep Research do Gemini, que planeja e executa tarefas de pesquisa na Web de várias etapas e sintetiza descobertas de várias fontes em relatórios abrangentes. Para mais informações, consulte Usar o agente Deep Research do Gemini.
Agentes personalizados: recursos de agentes personalizados configurados e provisionados com client.agents.create().

Como os fluxos de trabalho do agente geralmente levam vários minutos para serem concluídos, execute-os de forma assíncrona em segundo plano definindo background=True. A API retorna imediatamente um objeto Interaction com um id que pode ser pesquisado 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 projetoGoogle 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 os arquivos enviados do Cloud Storage. Veja o exemplo a seguir:

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"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 são avaliadas usando credenciais do usuário final (EUC). A API busca objetos do Cloud Storage usando a identidade do autor da chamada autenticado, em vez de um agente de serviço do projeto em segundo plano.

Para transmitir arquivos do Cloud Storage em uma solicitação de interação, o principal de chamada (conta de usuário, conta de serviço ou identidade federada) precisa ter a permissão storage.objects.get para todos os objetos referenciados.

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.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Resolver problemas de acesso a arquivos do Cloud Storage

Se o principal de chamada não tiver permissões suficientes, a API Interactions vai retornar um erro 403 Forbidden semelhante a este:

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

Para resolver esse problema, conceda o papel Leitor de objetos do Storage (roles/storage.objectViewer) no bucket ou objeto ao autor da chamada autenticado.

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

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 caller autenticado tem acesso de leitura ao bucket.

Fluxos de trabalho REST avançados

Para automação baseada em shell, pipelines de CI/CD ou ambientes sem um tempo de execução de 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/v1beta1/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 uma região personalizada compatível, se necessário para sua configuração.

Definir variáveis de ambiente e autenticação

Antes de executar os exemplos de curl nas seções a seguir, exporte seu ID do projeto, modelo de destino ou ID do agente e um token de acesso OAuth 2.0 gerado com as 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 POST síncrona 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 esta amostra, substitua PREVIOUS_INTERACTION_ID pelo id retornado por uma interação anterior.

curl -X POST "https://aiplatform.googleapis.com/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

Transmitir saída 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/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "role": "user",
      "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 fluxo inclui um prefixo data: que contém uma carga JSON com o conteúdo de event_type e delta de 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 usando REST, especifique o agent de destino, defina "background": true e configure "environment": "remote":

curl -X POST "https://aiplatform.googleapis.com/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

A seguir

Saiba mais sobre os principais conceitos na visão geral da API Interactions.
Confira os esquemas de solicitação e resposta na referência da API Interactions.
Aprenda a interagir com agentes gerenciados e usar o agente Deep Research do Gemini.

Guia para desenvolvedores da API Interactions Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Check for the roles

Grant the roles

Check for the roles

Grant the roles

Principais conceitos

Requisitos

Instalar o SDK de IA generativa do Google

Python

TypeScript / JavaScript

Autenticar seu cliente

Conectar usando um projeto Google Cloud com Application Default Credentials (ADC)

Python

TypeScript / JavaScript

REST

Conectar usando o modo expresso (chave de API)

Python

TypeScript / JavaScript

REST

Fluxos de trabalho de interação comuns

Gerenciar conversas multiturno com estado

Python

TypeScript / JavaScript

Transmita respostas em tempo real

Python

TypeScript / JavaScript

Gerar saída estruturada

Python

TypeScript / JavaScript

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

Python

TypeScript / JavaScript

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

Acessar arquivos enviados do Cloud Storage

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

Resolver problemas de acesso a arquivos do Cloud Storage

Fluxos de trabalho REST avançados

Endpoint REST

Definir variáveis de ambiente e autenticação

Formato de resposta síncrona

Continuar uma interação multiturno com estado

Transmitir saída com eventos enviados pelo servidor

Executar um agente gerenciado em segundo plano

A seguir

Guia para desenvolvedores da API Interactions