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 gli ID ambiente (env_id) ed eseguire l'override dinamico delle configurazioni, ad esempio i server Model Context Protocol (MCP), durante le interazioni.

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

Prima di iniziare

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

  1. Accedi al tuo Google Cloud account. 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 l'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 all'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 al volo.

Per avviare un'interazione, specifica la destinazione dell'agente di base, ad esempio antigravity-preview-05-2026 (o la variante di anteprima più recente), e richiedi un ambiente remoto al volo:

REST

Variabili della richiesta

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

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: la località 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. L'interaction.id e l'environment_id, inclusi nei dati interaction.complete, possono essere utilizzati nelle chiamate successive per mantenere lo stato della sessione. L'interaction.id viene utilizzato per continuare la cronologia delle conversazioni, mentre l'environment_id consente di riutilizzare lo stesso ambiente sandbox. Per ulteriori informazioni, 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 ulteriori informazioni, 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 ulteriori informazioni, consulta Gestire lo stato della sessione.

Interagisci con un agente personalizzato creato utilizzando l'API Agents

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

Per ulteriori informazioni su come recuperare o elencare gli agenti personalizzati per trovare i relativi ID, consulta Elencare gli agenti.

Configurazione e inizializzazione dell'ambiente

Quando interagisci con un agente personalizzato:

  • Comportamento predefinito: se crei l'agente con un ambiente predefinito, specifica il 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 i requisiti di attività specifici. Ad esempio:

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

  • Allega le competenze utilizzando Skill Registry: fornisci un elenco di strumenti personalizzati, script o competenze dell'agente preconfigurati per fornire funzionalità specifiche o il flusso di lavoro di runtime. Consulta Skill Registry.

Per un elenco delle strutture di configurazione dell'ambiente ed esempi di come mantenere lo stato della conversazione multi-turno, 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 della richiesta

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

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: è supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato della risorsa agente registrata. Per ulteriori informazioni su come recuperare o elencare gli agenti personalizzati per trovare i relativi ID, consulta Elencare 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 di streaming. L'interaction.id e l'environment_id, inclusi nei dati interaction.complete, possono essere utilizzati nelle chiamate successive per mantenere lo stato della sessione. L'interaction.id viene utilizzato per continuare la cronologia delle conversazioni, mentre l'environment_id consente di riutilizzare lo stesso ambiente sandbox. Per ulteriori informazioni, 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 non hanno stato, a meno che non venga specificato un container di ambiente o una cronologia delle conversazioni. Nei flussi dell'assistente a più turni, puoi conservare i file locali, il contesto di esecuzione del codice, le modifiche del sistema, le librerie software open source installate in fase di runtime e la cronologia delle conversazioni tra le conversazioni:

  • Per continuare una conversazione: passa l'ID dell'interazione precedente a il 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 e nuovo. Utilizza questa opzione durante le interazioni iniziali.
"environment": "env_CAEQ..." Riutilizza il container sandbox esistente e persistente, 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 container sandbox e continua una conversazione, passa il environment_id restituito nel campo environment e specifica previous_interaction_id. Gli esempi seguenti mostrano come continuare una sessione con stato durante l'interazione con l'agente.

REST

Variabili della richiesta

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

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: è supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato della risorsa agente registrata (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 container sandbox esistente. Utilizza previous_interaction_id per continuare la cronologia delle conversazioni.

Eseguire 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 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 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 della richiesta

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

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: la località per l'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 delle credenziali (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 il container sandbox isolato, le autorizzazioni e i pacchetti/strumenti preinstallati.