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 gli agenti personalizzati creati utilizzando l'API Agents e l'agente di base predefinito Antigravity, inclusa la configurazione dinamica. Spiega anche come gestire e riutilizzare gli ambienti sandbox con ID ambiente (env_id) ed eseguire l'override dinamico delle configurazioni, ad esempio i server Model Context Protocol (MCP), durante le interazioni.

Per saperne di più 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 carichi di lavoro.

  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 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 Agent Platform API.

    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 il tuo agente utilizza gli strumenti Google Cloud Model Context Protocol (MCP), concedi il ruolo Utente strumento MCP (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 personalizzato; puoi richiamare l'agente al volo.

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 posizione regionale per le 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 di 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 Gestire 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 di streaming genera oggetti InteractionSSEEvent. L'evento finale interaction.complete 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 Gestire 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 di streaming genera oggetti evento. L'evento finale interaction.complete 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 Gestire lo stato della sessione.

Interagire con un agente personalizzato creato utilizzando l'API Agents

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

Per ulteriori informazioni su come recuperare o elencare gli agenti personalizzati per trovare i relativi ID, consulta Elenca 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 specifici dell'attività. Ad esempio:

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

  • Allegare competenze utilizzando il registro delle competenze: fornisci un elenco di strumenti, script o competenze dell'agente preconfigurati personalizzati per fornire funzionalità specifiche o il tuo flusso di lavoro di runtime. Vedi Skill Registry.

Per un elenco di strutture di configurazione dell'ambiente ed esempi di come mantenere lo stato della conversazione multiscambio, consulta Gestire lo stato della sessione con gli ID ambiente.

Invia un'interazione a un agente personalizzato

Invia un'interazione al tuo 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 maggiori informazioni su come recuperare o elencare gli agenti personalizzati per trovare i relativi ID, consulta Elenco degli 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 di 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 Gestire 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);
}

Gestire lo stato della sessione e le interazioni multi-turno

Per impostazione predefinita, le interazioni sono stateless, a meno che non scegli come target un contenitore o una cronologia delle conversazioni di un ambiente specifico. Nei flussi dell'assistente multi-turn, puoi conservare file locali, contesto di esecuzione del codice, modifiche al sistema, librerie software open source installate nel runtime e cronologia delle 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 ambiente sandbox standard nuovo. Utilizza questa opzione durante le interazioni iniziali.
"environment": "env_CAEQ..." Riutilizza il container sandbox persistente 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 dalle `sources` specificate, ad esempio quelli archiviati in Google Cloud Storage.

Per inviare una richiesta di interazione successiva che riutilizza lo stesso contenitore sandbox e continua una conversazione, passa il valore environment_id restituito nel campo environment e specifica previous_interaction_id. Gli esempi riportati di seguito mostrano come continuare una sessione con stato quando interagisci 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 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 contenitore sandbox esistente. Usa 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, trasmetti la stringa environment_id direttamente come parametro environment per riutilizzare un contenitore sandbox esistente. Usa previous_interaction_id per continuare la cronologia delle conversazioni.

Eseguire l'override delle configurazioni durante l'interazione

Sebbene le definizioni di 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. Gli strumenti o i server MCP specificati nel corpo della richiesta di interazione sostituiscono completamente gli strumenti preconfigurati dell'agente per la durata del turno di interazione.

Per eseguire l'override o definire un server MCP al momento dell'interazione, aggiungi uno strumento di tipo mcp_server all'interno dell'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 posizione 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 REST-first per la creazione di agenti autonomi.

Riferimento

Scopri di più sul contenitore sandbox isolato, sulle autorizzazioni e sui pacchetti/strumenti preinstallati.