Interactúa con agentes

En esta guía, se explica cómo interactuar con los agentes implementados en la API de Managed Agents en Agent Platform con la API de Interactions. Aprenderás a interactuar con agentes personalizados creados con la API de agentes y el agente base precompilado Antigravity, incluida su configuración dinámica. También se explica cómo administrar y reutilizar entornos de zona de pruebas con IDs de entorno (env_id) y anular de forma dinámica los parámetros de configuración, por ejemplo, los servidores de Protocolo de contexto del modelo (MCP), durante las interacciones.

Para obtener más información sobre la API, consulta la documentación de referencia de la API de Interaction.

Antes de comenzar

Antes de comenzar las interacciones con los agentes, configura tu entorno:

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  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. Si tu agente usa herramientas del Google Cloud Protocolo de contexto del modelo (MCP), otorga el rol de usuario de herramientas de MCP (roles/mcp.toolUser) a tu cuenta de usuario y a la cuenta de servicio asociada.

Interactuar con agentes de Antigravity

La forma más sencilla de usar la API de Managed Agents en Agent Platform es interactuar directamente con el agente base propio Antigravity. No necesitas crear un recurso de agente personalizado; puedes invocar al agente sobre la marcha.

Para iniciar una interacción, especifica el destino del agente base, como antigravity-preview-05-2026 (o la variante de versión preliminar más reciente), y solicita un entorno remoto sobre la marcha:

REST

Variables de solicitud

Antes de llamar a la API, reemplaza las siguientes variables:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de tus interacciones. Solo se admite la región global.

Método HTTP y URL

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

Cuerpo JSON de la solicitud

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

Respuesta de ejemplo

Después de la interacción inicial, el servicio devuelve una respuesta de transmisión. Los valores interaction.id y environment_id, incluidos en los datos de interaction.complete, se pueden usar en llamadas posteriores para mantener el estado de la sesión. El interaction.id se usa para continuar con el historial de conversaciones, mientras que el environment_id permite reutilizar el mismo entorno de zona de pruebas. Para obtener más información, consulta Administra el estado de la sesión.

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 ejecutar este código, configura las variables que se describen en la pestaña 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)

La respuesta de transmisión genera objetos InteractionSSEEvent. El evento interaction.complete final contiene el environment_id y la interacción id, que puedes volver a usar en llamadas posteriores para mantener el estado de la sesión y el historial de conversaciones. Para obtener más información, consulta Administra el estado de la sesión.

JavaScript

Antes de ejecutar este código, configura las variables que se describen en la pestaña 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);
}

La respuesta de transmisión genera objetos de evento. El evento interaction.complete final contiene el environment_id y la interacción id, que puedes volver a usar en llamadas posteriores para mantener el estado de la sesión y el historial de conversaciones. Para obtener más información, consulta Administra el estado de la sesión.

Interactuar con un agente personalizado creado con la API de Agents

Para interactuar con un agente personalizado creado como se describe en Crea y administra agentes, debes especificarlo con su ID de agente.

Para obtener más información sobre cómo recuperar o enumerar agentes personalizados para encontrar sus IDs, consulta Enumera agentes.

Configuración e inicialización del entorno

Cuando interactúas con un agente personalizado, ocurre lo siguiente:

  • Comportamiento predeterminado: Si creas el agente con un entorno predeterminado, especifica el AGENT_ID en tu solicitud.

  • Define el entorno de forma explícita: Si no definiste la configuración del entorno cuando creaste el agente, debes definirlo de forma explícita en el bloque environment de tu solicitud de interacción inicial.

    Por ejemplo:

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

Puedes configurar de forma dinámica las funciones en el entorno de zona de pruebas durante la llamada a la API de interacción inicial para cumplir con los requisitos específicos de la tarea. Por ejemplo:

  • Adjunta una habilidad con Cloud Storage: Adjunta buckets de Cloud Storage para cargar grandes volúmenes de datos o directorios de archivos persistentes en el sistema de archivos del contenedor.

  • Adjunta habilidades con el Registro de habilidades: Proporciona una lista de herramientas, secuencias de comandos o habilidades de agentes preempaquetadas personalizadas para proporcionar capacidades funcionales específicas o tu flujo de trabajo de entorno de ejecución. Consulta Registro de habilidades.

Para obtener una lista de las estructuras de configuración del entorno y ejemplos de cómo mantener el estado de la conversación de varios turnos, consulta Administra el estado de la sesión con IDs de entorno.

Envía una interacción a un agente personalizado

Envía una interacción a tu agente personalizado especificando el ID del agente:

REST

Variables de solicitud

Antes de llamar a la API, reemplaza las siguientes variables:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Solo se admite la región global.
  • AGENT_ID: Es el identificador personalizado de tu recurso de agente registrado. Para obtener más información sobre cómo recuperar o enumerar agentes personalizados para encontrar sus IDs, consulta Enumera agentes.

Método HTTP y URL

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

Cuerpo JSON de la solicitud

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

Ejemplo de respuesta

Después de la interacción inicial, el servicio devuelve una respuesta de transmisión. Los valores interaction.id y environment_id, incluidos en los datos de interaction.complete, se pueden usar en llamadas posteriores para mantener el estado de la sesión. El interaction.id se usa para continuar con el historial de conversaciones, mientras que el environment_id permite reutilizar el mismo entorno de zona de pruebas. Para obtener más información, consulta Administra el estado de la sesión.

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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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);
}

Administrar el estado de la sesión y las interacciones de varios turnos

De forma predeterminada, las interacciones no tienen estado, a menos que se orienten a un contenedor de entorno o un historial de conversaciones específicos. En los flujos de asistente de varios turnos, puedes conservar los archivos locales, el contexto de ejecución de código, las modificaciones del sistema, las bibliotecas de software de código abierto instaladas en el entorno de ejecución y el historial de conversaciones en todas las conversaciones:

  • Para continuar una conversación, pasa el ID de la interacción anterior al parámetro previous_interaction_id.
  • Para seguir usando un entorno creado, pasa el ID del entorno que se devolvió de la interacción anterior al parámetro environment.

Puedes seleccionar parámetros de configuración clave del entorno con los siguientes parámetros en el campo environment:

Estructura de JSON Descripción
"environment": {"type": "remote"} Aprovisiona un entorno de zona de pruebas estándar y nuevo. Usa esta opción durante las interacciones iniciales.
"environment": "env_CAEQ..." Vuelve a usar el contenedor de zona de pruebas persistente existente y conserva todas las bibliotecas, las secuencias de comandos, los archivos y el estado asociados con este ID de entorno.
"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]} Aprovisiona una nueva zona de pruebas remota y la carga previamente con habilidades o archivos personalizados de las `sources` especificadas, como los almacenados en Cloud Storage.

Para enviar una solicitud de interacción posterior que reutilice el mismo contenedor de la zona de pruebas y continúe una conversación, pasa el environment_id que se muestra en el campo environment y especifica previous_interaction_id. En los siguientes ejemplos, se muestra cómo continuar una sesión con estado cuando se interactúa con el agente.

REST

Variables de solicitud

Antes de llamar a la API, reemplaza las siguientes variables:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Solo se admite la región global.
  • AGENT_ID: Es el identificador personalizado del recurso de agente registrado (o antigravity-preview-05-2026).
  • PREVIOUS_INTERACTION_ID: Es el ID de interacción que se muestra en la interacción anterior.
  • ENV_ID: Es el ID del entorno que se devolvió de la interacción anterior.

Método HTTP y URL

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

Cuerpo JSON de la solicitud

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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)

En el SDK de Python, pasa la cadena environment_id directamente como el parámetro environment para reutilizar un contenedor de zona de pruebas existente. Usa previous_interaction_id para continuar el historial de conversaciones.

JavaScript

Antes de ejecutar este código, configura las variables que se describen en la pestaña 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);
}

En el SDK de JavaScript, pasa la cadena environment_id directamente como el parámetro environment para reutilizar un contenedor de zona de pruebas existente. Usa previous_interaction_id para continuar el historial de conversaciones.

Anula los parámetros de configuración durante la interacción

Si bien las definiciones de agentes personalizados suelen incluir parámetros de configuración predeterminados para herramientas, habilidades y conexiones de terceros, puedes ajustar de forma dinámica estas definiciones por interacción sin modificar la configuración del recurso del agente subyacente.

Un caso de uso común es anular de forma dinámica las conexiones a los servidores del Protocolo de contexto del modelo (MCP) en el entorno de ejecución. Cualquier herramienta o servidor de MCP especificado en el cuerpo de la solicitud de interacción anula por completo las herramientas preconfiguradas del agente durante ese turno de interacción.

Para anular o definir un servidor de MCP en el momento de la interacción, agrega una herramienta de tipo mcp_server dentro de la lista tools de tu solicitud de interacción:

REST

Variables de solicitud

Antes de llamar a la API, reemplaza las siguientes variables:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación de tu interacción. Solo se admite la región global.
  • AGENT_ID: Es el identificador personalizado del recurso de tu agente.
  • MCP_SERVER_URL: Es la URL de la puerta de enlace HTTP remota del nuevo servidor de MCP.
  • MCP_SERVER_NAME: Es una etiqueta descriptiva para el dominio del host de MCP de destino.
  • MCP_HEADER_KEY: Opcional Es el nombre de la clave del encabezado (por ejemplo, Authorization).
  • MCP_HEADER_VALUE: Opcional Es el valor de la credencial (por ejemplo, Bearer <token>).

Método HTTP y URL

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

Cuerpo JSON de la solicitud

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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);
}

¿Qué sigue?

Descripción general

Obtén información sobre la API de Managed Agents en Agent Platform, un entorno basado en la configuración y centrado en REST para crear agentes autónomos.

Referencia

Obtén información sobre el contenedor de la zona de pruebas aislada, los permisos y los paquetes o las herramientas preinstalados.