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:
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
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.enablepermission. 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.-
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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
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.enablepermission. 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.-
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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
-
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_IDnella 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
environmentdella 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 dell'API Managed Agents su Agent Platform
Scopri l'API Managed Agents su Agent Platform, un ambiente basato sulla configurazione e incentrato su REST per la creazione di agenti autonomi.
API Managed Agents nell'ambiente sandbox di Agent Platform
Scopri di più sul container della sandbox isolata, sulle autorizzazioni e sui pacchetti/strumenti preinstallati.