Interagir com agentes

Este guia explica como interagir com agentes implantados na API Managed Agents na Agent Platform usando a API Interactions. Você vai aprender a interagir com agentes personalizados criados usando a API Agents e o agente base Antigravity pré-criado, incluindo a configuração dinâmica. Ele também explica como gerenciar e reutilizar ambientes de sandbox com IDs de ambiente (env_id) e substituir dinamicamente configurações, por exemplo, servidores do Protocolo de Contexto de Modelo (MCP), durante as interações.

Para mais informações sobre a API, consulte a documentação de referência da API Interaction.

Antes de começar

Antes de iniciar as interações com os agentes, configure seu ambiente:

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

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

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

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    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 email address for a Google Account.

    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.

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

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

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  9. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    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 email address for a Google Account.

    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.
  10. Se o agente usar ferramentas do Google Cloud Protocolo de Contexto de Modelo (MCP), conceda a função Usuário da ferramenta do MCP (roles/mcp.toolUser) à sua conta de usuário e à conta de serviço associada.

Interagir com agentes do Antigravity

A maneira mais simples de usar a API Managed Agents na Agent Platform é interagir diretamente com o agente base Antigravity próprio. Não é necessário criar um recurso de agente personalizado. Você pode invocar o agente na hora.

Para iniciar uma interação, especifique o destino do agente de base, como antigravity-preview-05-2026 (ou a variante de prévia mais recente), e solicite um ambiente remoto instantâneo:

REST

Variáveis de solicitação

Antes de chamar a API, substitua as seguintes variáveis:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional das suas interações. Somente a região global é compatível.

Método HTTP e URL

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

Corpo JSON da solicitação

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "antigravity-preview-05-2026",
  "environment": {
    "type": "remote"
  },
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Who are you, can you execute python code? Show me an example."
        }
      ]
    }
  ]
}

Comando curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "antigravity-preview-05-2026",
      "environment": {"type": "remote"},
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Who are you, can you execute python code? Show me an example."
                  }
              ]
          }
      ]
  }'

Exemplo de resposta

Após a interação inicial, o serviço retorna uma resposta de streaming. Os interaction.id e environment_id, incluídos nos dados de interaction.complete, podem ser usados em chamadas subsequentes para manter o estado da sessão. O interaction.id é usado para continuar o histórico de conversas, enquanto o environment_id permite reutilizar o mesmo ambiente de sandbox. Para mais informações, consulte Gerenciar o estado da sessão.

event: interaction.complete
data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 51132,
      "total_input_tokens": 48984,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 48984
        }
      ],
      "total_output_tokens": 769,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 769
        }
      ],
      "total_thought_tokens": 1379
    },
    "created": "2026-05-15T22:26:05Z",
    "updated": "2026-05-15T22:26:05Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

Python

Antes de executar esse código, defina as variáveis descritas na guia "REST".

from google import genai

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

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Who are you, can you execute python code? Show me an example.",
    environment={"type": "remote"},
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

A resposta de streaming gera objetos InteractionSSEEvent. O evento interaction.complete final contém o environment_id e a interação id, que podem ser reutilizados em chamadas subsequentes para manter o estado da sessão e o histórico de conversas. Para mais informações, consulte Gerenciar o estado da sessão.

JavaScript

Antes de executar esse código, defina as variáveis descritas na guia "REST".

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

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

const stream = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Who are you, can you execute python code? Show me an example.",
    environment: { type: "remote" },
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

A resposta de streaming gera objetos de evento. O evento interaction.complete final contém o environment_id e a interação id, que podem ser reutilizados em chamadas subsequentes para manter o estado da sessão e o histórico de conversas. Para mais informações, consulte Gerenciar o estado da sessão.

Interagir com um agente personalizado criado usando a API Agents

Para interagir com um agente personalizado criado conforme descrito em Criar e gerenciar agentes, especifique-o usando o ID dele.

Para mais informações sobre como recuperar ou listar agentes personalizados para encontrar os IDs deles, consulte Listar agentes.

Configuração e inicialização do ambiente

Ao interagir com um agente personalizado:

  • Comportamento padrão: se você criar o agente com um ambiente padrão, especifique o AGENT_ID na sua solicitação.

  • Defina explicitamente o ambiente: se você não definiu a configuração do ambiente ao criar o agente, é necessário definir explicitamente o ambiente no bloco environment da solicitação de interação inicial.

    Exemplo:

    "environment": {"type": "remote"}

É possível configurar recursos dinamicamente no ambiente sandbox durante a chamada inicial da API de interação para atender a requisitos específicos da tarefa. Exemplo:

  • Anexar habilidade usando o Cloud Storage: anexe buckets do Cloud Storage para carregar grandes volumes de dados ou diretórios de arquivos persistentes no sistema de arquivos do contêiner.

  • Anexe habilidades usando o Registro de habilidades: forneça uma lista de ferramentas, scripts ou habilidades de agente pré-empacotadas personalizados para oferecer recursos funcionais específicos ou seu fluxo de trabalho de tempo de execução. Consulte Registro de habilidades.

Para uma lista de estruturas de configuração de ambiente e exemplos de como manter o estado de conversas multiturno, consulte Gerenciar o estado da sessão com IDs de ambiente.

Enviar uma interação para um agente personalizado

Envie uma interação ao seu agente personalizado especificando o ID dele:

REST

Variáveis de solicitação

Antes de chamar a API, substitua as seguintes variáveis:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: somente a região global é compatível.
  • AGENT_ID: o identificador personalizado do recurso de agente registrado. Para mais informações sobre como recuperar ou listar agentes personalizados para encontrar os IDs deles, consulte Listar agentes.

Método HTTP e URL

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

Corpo JSON da solicitação

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Tell me the name of python packages used for data analysis."
        }
      ]
    }
  ]
}

Comando curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Tell me the name of python packages used for data analysis."
                  }
              ]
          }
      ]
  }'

Exemplo de resposta

Após a interação inicial, o serviço retorna uma resposta de streaming. Os interaction.id e environment_id, incluídos nos dados de interaction.complete, podem ser usados em chamadas subsequentes para manter o estado da sessão. O interaction.id é usado para continuar o histórico de conversas, enquanto o environment_id permite reutilizar o mesmo ambiente de sandbox. Para mais informações, consulte Gerenciar o estado da sessão.

data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 7558,
      "total_input_tokens": 6822,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 6822
        }
      ],
      "total_output_tokens": 278,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 278
        }
      ],
      "total_thought_tokens": 458
    },
    "created": "2026-05-15T22:38:56Z",
    "updated": "2026-05-15T22:38:56Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

Python

Antes de executar esse código, defina as variáveis descritas na guia "REST".

from google import genai

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Tell me the name of python packages used for data analysis.",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

JavaScript

Antes de executar esse código, defina as variáveis descritas na guia "REST".

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

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

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Tell me the name of python packages used for data analysis.",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Gerenciar o estado da sessão e interações de várias etapas

Por padrão, as interações não têm estado, a menos que você segmente um contêiner de ambiente ou histórico de conversas específico. Em fluxos de assistente com vários turnos, é possível manter arquivos locais, contexto de execução de código, modificações do sistema, bibliotecas de software de código aberto instaladas em tempo de execução e histórico de conversas:

  • Para continuar uma conversa: transmita o ID da interação anterior ao parâmetro previous_interaction_id.
  • Para continuar usando um ambiente criado: transmita o ID do ambiente retornado da interação anterior ao parâmetro environment.

É possível selecionar as principais configurações de ambiente usando os seguintes parâmetros no campo environment:

Estrutura JSON Descrição
"environment": {"type": "remote"} Provisiona um ambiente de sandbox padrão novo. Use essa opção durante as interações iniciais.
"environment": "env_CAEQ..." Reutiliza o contêiner de sandbox persistente atual, preservando todas as bibliotecas, scripts, arquivos e estados associados a esse ID de ambiente.
"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]} Provisiona uma nova sandbox remota e a pré-carrega com habilidades ou arquivos personalizados das `fontes` especificadas, como os armazenados no Google Cloud Storage.

Para enviar uma solicitação de interação subsequente que reutiliza o mesmo contêiner de sandbox e continua uma conversa, transmita o environment_id retornado no campo environment e especifique previous_interaction_id. Os exemplos a seguir demonstram como continuar uma sessão com estado ao interagir com o agente.

REST

Variáveis de solicitação

Antes de chamar a API, substitua as seguintes variáveis:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: somente a região global é compatível.
  • AGENT_ID: o identificador personalizado do recurso de agente registrado (ou antigravity-preview-05-2026).
  • PREVIOUS_INTERACTION_ID: o ID da interação retornado da interação anterior.
  • ENV_ID: o ID do ambiente retornado da interação anterior.

Método HTTP e URL

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

Corpo JSON da solicitação

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "environment": "ENV_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "What did I ask you before and what did you do?"
        }
      ]
    }
  ]
}

Comando curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
      "environment": "ENV_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "What did I ask you before and what did you do?"
                  }
              ]
          }
      ]
  }'

Python

Antes de executar esse código, defina as variáveis descritas na guia "REST".

from google import genai

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="What did I ask you before and what did you do?",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    environment="ENV_ID",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

No SDK do Python, transmita a string environment_id diretamente como o parâmetro environment para reutilizar um contêiner de sandbox existente. Use previous_interaction_id para continuar o histórico da conversa.

JavaScript

Antes de executar esse código, defina as variáveis descritas na guia "REST".

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

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

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "What did I ask you before and what did you do?",
    previous_interaction_id: "PREVIOUS_INTERACTION_ID",
    environment: "ENV_ID",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

No SDK para JavaScript, transmita a string environment_id diretamente como o parâmetro environment para reutilizar um contêiner de sandbox existente. Use previous_interaction_id para continuar o histórico da conversa.

Substituir configurações durante a interação

Embora as definições de agentes personalizados geralmente incluam configurações padrão para ferramentas, habilidades e conexões de terceiros, é possível ajustar essas definições de forma dinâmica por interação sem modificar a configuração do recurso do agente subjacente.

Um caso de uso comum é substituir dinamicamente as conexões com servidores do Protocolo de Contexto de Modelo (MCP) durante a execução. Todas as ferramentas ou servidores MCP especificados no corpo da solicitação de interação substituem completamente as ferramentas pré-configuradas do agente durante essa interação.

Para substituir ou definir um servidor MCP no momento da interação, adicione uma ferramenta do tipo mcp_server na lista tools da solicitação de interação:

REST

Variáveis de solicitação

Antes de chamar a API, substitua as seguintes variáveis:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local da sua interação. Somente a região global é compatível.
  • AGENT_ID: o identificador personalizado do recurso do agente.
  • MCP_SERVER_URL: o URL do gateway HTTP remoto do novo servidor MCP.
  • MCP_SERVER_NAME: um rótulo descritivo para o domínio do host do MCP de destino.
  • MCP_HEADER_KEY: opcional. O nome da chave do cabeçalho (por exemplo, Authorization).
  • MCP_HEADER_VALUE: opcional. O valor da credencial (por exemplo, Bearer <token>).

Método HTTP e URL

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

Corpo JSON da solicitação

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "agents/AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Analyze our database and summarize recent purchase events."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp_server",
      "url": "MCP_SERVER_URL",
      "name": "MCP_SERVER_NAME",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

Comando curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
     "stream": true,
     "background": true,
     "store": true,
     "agent": "agents/AGENT_ID",
     "input": [
         {
             "type": "user_input",
             "content": [
                 {
                     "type": "text",
                     "text": "Analyze our database and summarize recent purchase events."
                 }
             ]
         }
     ],
     "tools": [
         {
             "type": "mcp_server",
             "url": "MCP_SERVER_URL",
             "name": "MCP_SERVER_NAME",
             "headers": {
                 "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
             }
         }
     ]
  }'

Python

Antes de executar esse código, defina as variáveis descritas na guia "REST".

from google import genai

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Analyze our database and summarize recent purchase events.",
    tools=[
        {
            "type": "mcp_server",
            "url": "MCP_SERVER_URL",
            "name": "MCP_SERVER_NAME",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

JavaScript

Antes de executar esse código, defina as variáveis descritas na guia "REST".

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

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

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Analyze our database and summarize recent purchase events.",
    tools: [
        {
            type: "mcp_server",
            url: "MCP_SERVER_URL",
            name: "MCP_SERVER_NAME",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

A seguir

Visão geral

Saiba mais sobre a API Managed Agents na Agent Platform, um ambiente orientado por configuração e REST para criar agentes autônomos.

Referência

Saiba mais sobre o contêiner isolado do sandbox, as permissões e os pacotes/ferramentas pré-instalados.