Interagire con gli agenti

Questa guida spiega come interagire con gli agenti di cui è stato eseguito il deployment nell'API Managed Agents su Agent Platform utilizzando l'API Interactions. Scoprirai come interagire con agenti personalizzati creati utilizzando l'API Agents e l'agente di base predefinito Antigravity, inclusa la sua configurazione dinamica. Spiega inoltre come gestire e riutilizzare gli ambienti sandbox con gli ID ambiente (env_id) e come eseguire l'override dinamico delle configurazioni, ad esempio dei server Model Context Protocol (MCP), durante le interazioni.

Per ulteriori informazioni sull'API, consulta la documentazione di riferimento dell'API Interaction.

Prima di iniziare

Prima di iniziare le interazioni con gli agenti, configura l'ambiente:

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
  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 l'agente utilizza gli strumenti Google Cloud Model Context Protocol (MCP), concedi il ruolo MCP Tool User (roles/mcp.toolUser) sia al tuo account utente sia al account di servizio associato.

Interagisci con gli agenti Antigravity

Il modo più semplice per utilizzare l'API Managed Agents su Agent Platform è interagire direttamente con l'agente di base proprietario Antigravity. Non è necessario creare una risorsa agente personalizzata; puoi richiamare l'agente on the fly.

Per avviare un'interazione, specifica il target dell'agente di base, ad esempio antigravity-preview-05-2026 (o l'ultima variante di anteprima), e richiedi un ambiente remoto on the fly:

REST

Variabili di richiesta

Prima di chiamare l'API, sostituisci le seguenti variabili:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la località regionale per le tue interazioni. È supportata solo la regione global.

Metodo HTTP e URL

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

Corpo JSON della richiesta

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

Esempio di risposta

Dopo l'interazione iniziale, il servizio restituisce una risposta in streaming. interaction.id e environment_id, inclusi nei dati interaction.complete, possono essere utilizzati nelle chiamate successive per mantenere lo stato della sessione. interaction.id viene utilizzato per continuare la cronologia delle conversazioni, mentre environment_id consente di riutilizzare lo stesso ambiente sandbox. Per saperne di più, consulta Gestisci lo stato della sessione.

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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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 risposta in streaming genera oggetti InteractionSSEEvent. L'evento interaction.complete finale contiene environment_id e l'interazione id, che puoi riutilizzare nelle chiamate successive per mantenere lo stato della sessione e la cronologia delle conversazioni. Per saperne di più, consulta Gestisci lo stato della sessione.

JavaScript

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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 risposta in streaming genera oggetti evento. L'evento interaction.complete finale contiene environment_id e l'interazione id, che puoi riutilizzare nelle chiamate successive per mantenere lo stato della sessione e la cronologia delle conversazioni. Per saperne di più, consulta Gestisci lo stato della sessione.

Interagisci con un agente personalizzato creato utilizzando l'API Agents

Per interagire con un agente personalizzato creato come descritto in Crea e gestisci gli agenti, devi specificarlo utilizzando il relativo ID agente.

Per saperne di più su come recuperare o elencare gli agenti personalizzati per trovare i loro ID, consulta Elenca gli agenti.

Configurazione e inizializzazione dell'ambiente

Quando interagisci con un agente personalizzato:

  • Comportamento predefinito: se crei l'agente con un ambiente predefinito, specifica AGENT_ID nella richiesta.

  • Definisci esplicitamente l'ambiente: se non hai definito la configurazione dell'ambiente durante la creazione dell'agente, devi definire esplicitamente l'ambiente nel blocco environment della richiesta di interazione iniziale.

    Ad esempio:

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

Puoi configurare dinamicamente le funzionalità nell'ambiente sandbox durante la chiamata API di interazione iniziale per soddisfare requisiti di attività specifici. Ad esempio:

  • Collega skill utilizzando Cloud Storage: collega i bucket Cloud Storage per caricare volumi di dati di grandi dimensioni o directory di file persistenti nel file system del container.

  • Collega le skill utilizzando il registro delle skill: fornisci un elenco di strumenti personalizzati, script o skill dell'agente predefinite per fornire funzionalità specifiche o il tuo workflow di runtime. Consulta Skill Registry.

Per un elenco delle strutture di configurazione dell'ambiente ed esempi di come mantenere lo stato della conversazione a più turni, consulta Gestisci lo stato della sessione con gli ID ambiente.

Invia un'interazione a un agente personalizzato

Invia un'interazione all'agente personalizzato specificando l'ID agente:

REST

Variabili di richiesta

Prima di chiamare l'API, sostituisci le seguenti variabili:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: è supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato della risorsa dell'agente registrato. Per ulteriori informazioni su come recuperare o elencare gli agenti personalizzati per trovare i loro ID, consulta Elenca gli agenti.

Metodo HTTP e URL

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

Corpo JSON della richiesta

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

Esempio di risposta

Dopo l'interazione iniziale, il servizio restituisce una risposta in streaming. interaction.id e environment_id, inclusi nei dati interaction.complete, possono essere utilizzati nelle chiamate successive per mantenere lo stato della sessione. interaction.id viene utilizzato per continuare la cronologia delle conversazioni, mentre environment_id consente di riutilizzare lo stesso ambiente sandbox. Per saperne di più, consulta Gestisci lo stato della sessione.

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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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);
}

Gestisci lo stato della sessione e le interazioni multi-turno

Per impostazione predefinita, le interazioni sono stateless, a meno che non scegli come target un container di ambiente specifico o la cronologia delle conversazioni. Nei flussi dell'assistente multi-turno, puoi conservare file locali, contesto di esecuzione di codice, modifiche di sistema, librerie software open source installate in fase di runtime e cronologia delle conversazioni tra le conversazioni:

  • Per continuare una conversazione: passa l'ID dell'interazione precedente al parametro previous_interaction_id.
  • Per continuare a utilizzare un ambiente creato: passa l'ID ambiente restituito dall'interazione precedente al parametro environment.

Puoi selezionare le configurazioni chiave dell'ambiente utilizzando i seguenti parametri nel campo environment:

Struttura JSON Descrizione
"environment": {"type": "remote"} Esegue il provisioning di un nuovo ambiente sandbox standard. Utilizza questa opzione durante le interazioni iniziali.
"environment": "env_CAEQ..." Riutilizza il container sandbox permanente esistente, conservando tutte le librerie, gli script, i file e lo stato associati a questo ID ambiente.
"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]} Esegue il provisioning di una nuova sandbox remota e la precarica con competenze o file personalizzati provenienti dalle "origini" specificate, ad esempio quelle archiviate in Cloud Storage.

Per inviare una richiesta di interazione successiva che riutilizzi lo stesso container sandbox e continui una conversazione, passa il valore environment_id restituito nel campo environment e specifica previous_interaction_id. I seguenti esempi mostrano come continuare una sessione stateful durante l'interazione con l'agente.

REST

Variabili di richiesta

Prima di chiamare l'API, sostituisci le seguenti variabili:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: è supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato della risorsa dell'agente registrato (o antigravity-preview-05-2026).
  • PREVIOUS_INTERACTION_ID: l'ID interazione restituito dall'interazione precedente.
  • ENV_ID: l'ID ambiente restituito dall'interazione precedente.

Metodo HTTP e URL

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

Corpo JSON della richiesta

{
  "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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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)

Nell'SDK Python, passa la stringa environment_id direttamente come parametro environment per riutilizzare un container sandbox esistente. Utilizza previous_interaction_id per continuare la cronologia delle conversazioni.

JavaScript

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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);
}

Nell'SDK JavaScript, passa la stringa environment_id direttamente come parametro environment per riutilizzare un contenitore sandbox esistente. Utilizza previous_interaction_id per continuare la cronologia delle conversazioni.

Esegui l'override delle configurazioni durante l'interazione

Sebbene le definizioni degli agenti personalizzati includano in genere configurazioni predefinite per strumenti, competenze e connessioni di terze parti, puoi modificare dinamicamente queste definizioni in base all'interazione senza modificare la configurazione della risorsa dell'agente sottostante.

Un caso d'uso comune è l'override dinamico delle connessioni ai server Model Context Protocol (MCP) in fase di runtime. Tutti gli strumenti o i server MCP specificati nel corpo della richiesta di interazione sostituiscono completamente gli strumenti preconfigurati dell'agente per la durata di quel turno di interazione.

Per eseguire l'override o definire un server MCP al momento dell'interazione, aggiungi uno strumento di tipo mcp_server all'elenco tools della richiesta di interazione:

REST

Variabili di richiesta

Prima di chiamare l'API, sostituisci le seguenti variabili:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la località dell'interazione. È supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato della risorsa agente.
  • MCP_SERVER_URL: l'URL del gateway HTTP remoto del nuovo server MCP.
  • MCP_SERVER_NAME: un'etichetta descrittiva per il dominio host MCP di destinazione.
  • MCP_HEADER_KEY: (Facoltativo) Il nome della chiave dell'intestazione (ad esempio, Authorization).
  • MCP_HEADER_VALUE: (Facoltativo) Il valore della credenziale (ad esempio, Bearer <token>).

Metodo HTTP e URL

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

Corpo JSON della richiesta

{
  "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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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);
}

Passaggi successivi

Panoramica

Scopri l'API Managed Agents su Agent Platform, un ambiente basato sulla configurazione e incentrato su REST per la creazione di agenti autonomi.

Riferimento

Scopri di più sul container della sandbox isolata, sulle autorizzazioni e sui pacchetti/strumenti preinstallati.