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 Agents y el agente base prediseñado 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 cómo anular de forma dinámica las configuraciones, por ejemplo, los servidores del 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 a interactuar 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 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. Si tu agente usa herramientas del Protocolo de contexto del modelo (MCP) Google Cloud , otorga el rol de usuario de la herramienta MCP (roles/mcp.toolUser) a tu cuenta de usuario y a la cuenta de servicio asociada.

Interactúa 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 Antigravity de origen. No necesitas crear un recurso de agente personalizado; puedes invocar el agente sobre la marcha.

Para iniciar una interacción, especifica el destino del agente base, como antigravity-preview-05-2026 (o la variante de vista previa 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 parámetros 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 el historial de conversación, mientras que el environment_id permite reutilizar el mismo entorno 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 reutilizar 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 eventos. El evento interaction.complete final contiene el environment_id y la interacción id, que puedes reutilizar 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.

Interactúa 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 Cómo enumerar agentes.

Configuración e inicialización del entorno

Cuando interactúes con un agente personalizado, haz lo siguiente:

  • Comportamiento predeterminado: Si crea el agente con un entorno predeterminado, especifique AGENT_ID en su solicitud.

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

    Por ejemplo:

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

Puedes configurar funciones de forma dinámica en el entorno de pruebas durante tu primera llamada a la API de interacción para cumplir con los requisitos de tareas específicas. Por ejemplo:

  • Adjuntar 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 prediseñadas personalizadas para proporcionar capacidades funcionales específicas o tu flujo de trabajo de tiempo de ejecución. Consulta Skill Registry.

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 Cómo enumerar 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 parámetros 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 el historial de conversación, mientras que el environment_id permite reutilizar el mismo entorno 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);
}

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

De forma predeterminada, las interacciones no tienen estado, a menos que segmentes un contenedor de entorno o un historial de conversación específicos. En los flujos de asistentes de varios turnos, puedes conservar archivos locales, contexto de ejecución de código, modificaciones del sistema, bibliotecas de software de código abierto instaladas en el tiempo 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ó en la interacción anterior al parámetro environment.

Puedes seleccionar configuraciones clave del entorno con los siguientes parámetros en el campo environment:

Estructura JSON Descripción
"environment": {"type": "remote"} Aprovisiona un entorno de zona de pruebas estándar nuevo. Usa esta opción durante las interacciones iniciales.
"environment": "env_CAEQ..." Reutiliza el contenedor de zona de pruebas persistente existente y conserva todas las bibliotecas, los archivos, los estados y las secuencias de comandos asociados con este ID de entorno.
"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]} Aprovisiona un nuevo entorno de pruebas remoto y lo precarga con archivos o habilidades personalizadas de las "fuentes" especificadas, como las almacenadas en Google Cloud Storage.

Para enviar una solicitud de interacción posterior que reutilice el mismo contenedor de zona de pruebas y continúe una conversación, pasa el environment_id devuelto 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 de tu recurso de agente registrado (o antigravity-preview-05-2026).
  • PREVIOUS_INTERACTION_ID: Es el ID de interacción que se devolvió en la interacción anterior.
  • ENV_ID: Es el ID del entorno que se devolvió en 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 la configuración durante la interacción

Si bien las definiciones de agentes personalizadas suelen incluir configuraciones predeterminadas para herramientas, habilidades y conexiones de terceros, puedes ajustar estas definiciones de forma dinámica en función de cada 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) durante el tiempo 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 el 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 de tu recurso de 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 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 zona de pruebas aislado, los permisos y los paquetes o herramientas instalados previamente.