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 com a API Agents e o agente de base pré-criado Antigravity, incluindo como configurá-lo dinamicamente. Ele também explica como gerenciar e reutilizar ambientes de sandbox com IDs de ambiente (env_id) e substituir dinamicamente configurações, como 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 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 sem custos financeiros.
  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 Gemini Enterprise 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

  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 Gemini Enterprise 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

  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 o papel de Usuário da ferramenta 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 próprio Antigravity. Não é necessário criar um recurso de agente personalizado. É possível invocar o agente em tempo real.

Para iniciar uma interação, especifique o destino do agente base, como antigravity-preview-05-2026 (ou a variante de pré-lançamento mais recente), e solicite um ambiente remoto em tempo real:

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. O interaction.id e o environment_id, incluídos nos dados 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 do agente.

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 solicitação.

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

    Exemplo:

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

É possível configurar dinamicamente os recursos no ambiente de sandbox durante a chamada de API Interactions inicial para atender aos 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.

  • Anexar habilidades usando o registro de habilidades: forneça uma lista de ferramentas personalizadas, scripts ou habilidades de agente pré-empacotadas para fornecer recursos funcionais específicos ou seu fluxo de trabalho de ambiente 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 para o 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 é aceita.
  • 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. O interaction.id e o environment_id, incluídos nos dados 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 as interações em vários turnos

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 reter arquivos locais, contexto de execução de código, modificações do sistema, bibliotecas de software de código aberto instaladas no ambiente de execução e histórico de conversas:

  • Para continuar uma conversa: transmita o ID da interação anterior para o parâmetro previous_interaction_id.
  • Para continuar usando um ambiente criado: transmita o ID do ambiente retornado da interação anterior para o 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 permanente, 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 um novo sandbox remoto e o pré-carrega com habilidades ou arquivos personalizados das fontes especificadas, como os armazenados no Cloud Storage.

Para enviar uma solicitação de interação subsequente que reutilize o mesmo contêiner de sandbox e continue 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 é aceita.
  • 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 para Python, transmita a string environment_id diretamente como o parâmetro environment para reutilizar um contêiner de sandbox. 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. 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 dinamicamente essas definições por interação sem modificar a configuração do recurso de agente subjacente.

Um caso de uso comum é substituir dinamicamente as conexões com servidores do Protocolo de Contexto de Modelo (MCP) no ambiente de 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 à lista tools da sua 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 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

Aprenda mais sobre a API Agentes Gerenciados na Agent Platform, um ambiente orientado por configuração e com foco em REST para criar agentes autônomos.

Referência

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