Questa pagina descrive come connettere un agente Agent Development Kit (ADK) con le sessioni della piattaforma degli agenti e utilizzare le sessioni gestite nell'ambiente locale e di produzione.
Prima di iniziare
Queste istruzioni utilizzano la seguente struttura di file di progetto di base per definire un agente ADK e il relativo codice di runner e deployment di supporto:
my_agent/
agent.py # main agent code
runner.py # code for interacting with the agent
deploy.py # code for deploying the agent to Google Cloud
Assicurati che l'ambiente sia configurato seguendo i passaggi Ottieni i ruoli richiesti e Autenticazione in Configura l'ambiente.
Imposta le variabili di ambiente
Per utilizzare l'ADK, imposta le variabili di ambiente:
import os
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
Sostituisci quanto segue:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la tua regione. Consulta le regioni supportate per le sessioni.
Crea un'istanza di Agent Runtime
Per accedere alle sessioni di Agent Platform, devi prima utilizzare un'istanza di Agent Runtime. Non è necessario eseguire il deployment di alcun codice per iniziare a utilizzare le sessioni. Se hai già utilizzato Agent Runtime, la creazione di un'istanza di Agent Runtime richiede solo pochi secondi senza il deployment del codice. Potrebbe essere necessario più tempo se è la prima volta che utilizzi Agent Runtime.
Progetto Google Cloud
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create(
config={
"display_name": "My Session Store",
}
)
# Print the runtime ID, you will need it in the later steps to initialize
# the ADK `VertexAiSessionService`.
print(remote_agent.api_resource.name.split("/")[-1])
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.
LOCATION: la tua regione. Consulta le regioni supportate per le sessioni.
Opzioni di sicurezza multiregionali, globali e aziendali
Le sessioni supportano endpoint regionali, multiregionali (us e eu) e globali (global). Tieni presente i seguenti requisiti di sicurezza e crittografia quando scegli una località e crei l'istanza:
- Chiavi di crittografia gestite dal cliente (CMEK):
non puoi utilizzare CMEK se la tua istanza di Sessions
è configurata per utilizzare l'endpoint
global(location="global"), perché Cloud Key Management Service (Cloud KMS) richiede che le chiavi di crittografia risiedano all'interno di un confine geografico di residenza dei dati. Per criptare i dati della sessione con una chiave Cloud KMS, crea un'istanza padre autonoma (senza eseguire il deployment del codice di runtime dell'agente) in una località regionale o multiregionale supportata (uscon una chiaveusoeucon una chiaveeurope) e includiencryption_specinconfigquando chiamiclient.runtimes.create(). Le istanze che eseguono anche il deployment di un agente su Agent Runtime supportano CMEK solo in località a regione singola. Per saperne di più, consulta CMEK per le sessioni. - Controlli di servizio VPC (Controlli di servizio VPC): per proteggere le risorse delle sessioni all'interno di un perimetro di servizio o instradare il traffico delle sessioni tramite Agent Gateway, consulta Controlli di servizio VPC per le sessioni.
Sviluppa il tuo agente ADK
Per creare l'agente ADK, segui le istruzioni riportate in ADK o utilizza il codice seguente per creare un agente che saluta un utente con saluti fissi. Salva questo codice in un file denominato agent.py.
# file: my_agent/agent.py
from google import adk
def greetings(query: str):
"""Tool to greet user."""
if 'hello' in query.lower():
return {"greeting": "Hello, world"}
else:
return {"greeting": "Goodbye, world"}
# Define an ADK agent
root_agent = adk.Agent(
model="gemini-2.0-flash",
name='my_agent',
instruction="You are an Agent that greet users, always use greetings tool to respond.",
tools=[greetings]
)
Configura l'esecutore ADK
ADK Runtime orchestra l'esecuzione di agenti, strumenti e callback, nonché le chiamate alle sessioni di lettura e scrittura. Inizializza il runner con VertexAiSessionService, che si connette alle sessioni di Agent Platform. Salva questo codice in un file denominato runner.py.
Google Cloud Project
# file: my_agent/runner.py
import agent # Import from your agent.py
from google.adk import Runner
from google.adk.sessions import VertexAiSessionService
from google.genai import types
app_name="APP_NAME"
user_id="USER_ID"
# Create the ADK runner with VertexAiSessionService
session_service = VertexAiSessionService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="AGENT_ENGINE_ID"
)
runner = Runner(
agent=agent.root_agent,
app_name=app_name,
session_service=session_service)
# Helper method to send query to the runner
async def call_agent(query, session_id, user_id):
content = types.Content(role='user', parts=[types.Part(text=query)])
async for event in runner.run_async(
user_id=user_id, session_id=session_id, new_message=content):
if event.is_final_response():
final_response = event.content.parts[0].text
print("Agent Response: ", final_response)
Sostituisci quanto segue:
APP_NAME: il nome dell'applicazione dell'agente.
USER_ID: scegli il tuo ID utente con un limite di caratteri di 128. Ad esempio,
user-123.AGENT_ENGINE_ID: l'ID risorsa di un'istanza di Agent Runtime.
Per gli agenti di cui è stato eseguito il deployment, l'ID risorsa è elencato come variabile di ambiente
GOOGLE_CLOUD_AGENT_ENGINE_IDPer gli agenti locali, puoi recuperare l'ID risorsa utilizzando
remote_agent.api_resource.name.split("/")[-1].
Interagisci con l'agente
Dopo aver definito l'agente e configurato le sessioni di Agent Platform, puoi interagire con l'agente per verificare che la cronologia e gli stati della sessione vengano mantenuti.
UI ADK
Per testare l'agente con l'interfaccia utente dell'ADK e connetterti ad Agent Platform Sessions, esegui il comando adk web nel terminale.
Sebbene adk web in genere legga le variabili di ambiente da un file .env, ignora questo file quando utilizzi il flag --session_service_uri. Devi invece impostare le variabili di ambiente GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_LOCATION nella sessione del terminale prima di eseguire il comando.
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"export GOOGLE_CLOUD_LOCATION="LOCATION"adk web --session_service_uri=agentengine://AGENT_ENGINE_ID
# Sample output
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Python
Utilizza il codice Python dell'ADK per gestire sessioni e stati. Aggiungi il seguente codice alla fine del file runner.py per interagire con l'agente.
Per brevità, i seguenti snippet contengono chiamate await di primo livello. Per eseguire questo codice come script Python, inserisci gli snippet all'interno di una funzione async e utilizza asyncio.run() per eseguirlo, come mostrato in questo esempio:
import asyncio
async def main():
# Place one or more snippets here.
# For example:
session = await session_service.create_session(
app_name=app_name,
user_id=user_id)
await call_agent("Hello!", session.id, user_id)
asyncio.run(main())
Crea una sessione ed esegui una query sull'agente
Utilizza il seguente codice per creare una sessione e inviare una query all'agente. Specifica un ID sessione personalizzato per organizzare le sessioni utilizzando il tuo schema di denominazione o per eseguire rapidamente la transizione da altri servizi. Se non specifichi un ID sessione, Agent Platform ne genera uno automaticamente.
# file: my_agent/runner.py
# Create a session
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
session_id=session_id)
await call_agent("Hello!", session.id, user_id)
# Agent response: "Hello, world"
await call_agent("Thanks!", session.id, user_id)
# Agent response: "Goodbye, world"
Per gli ID sessione personalizzati, tieni presente le seguenti limitazioni per evitare collisioni con gli ID generati dal sistema:
- Se il primo carattere è una lettera, l'ID può contenere fino a 63 caratteri. I caratteri validi sono lettere minuscole, numeri e trattini (
[a-z0-9-]). L'ultimo carattere deve essere una lettera o un numero. - Se il primo carattere è un numero, l'ID può contenere fino a 9 caratteri. I caratteri validi sono i numeri (
[0-9]) senza zeri iniziali.
Dopo che la sessione è stata creata e passata all'esecutore, ADK la utilizza per archiviare gli eventi dell'interazione corrente. Puoi anche riprendere una sessione precedente fornendo l'ID della sessione.
Configura la durata (TTL) della sessione
Tutte le sessioni devono avere una scadenza. Puoi definire questa scadenza durante la creazione o l'aggiornamento di una sessione. La sessione e i relativi eventi figlio vengono eliminati automaticamente al termine del periodo di scadenza. Puoi impostare direttamente la data e l'ora di scadenza (expire_time) o impostare la durata (ttl) in secondi. Se non viene specificato nessuno dei due, il sistema applica un TTL predefinito di 365 giorni.
Durata
Se imposti la durata, il server calcola la data e l'ora di scadenza come create_time + ttl per le sessioni appena create o update_time + ttl per le sessioni aggiornate.
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
# Session will be deleted 10 days after creation time.
ttl=f"{24 * 60 * 60 * 10}s"
)
```
Scadenza
import datetime
expire_time = datetime.datetime.now(
tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10)
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
# Session will be deleted at the provided time (10 days after current time).
expire_time=expire_time.isoformat()
)
Elenca le sessioni esistenti
Elenca tutte le sessioni esistenti associate a un determinato ID utente.
# List sessions
sessions = await session_service.list_sessions(app_name=app_name,user_id=user_id)
print(sessions)
# ListSessionsResponse(session_ids=['1122334455', '9988776655'])
Gestisci gli stati della sessione
Gli stati contengono le informazioni di cui l'agente ha bisogno per una conversazione. Puoi fornire uno stato iniziale come dizionario quando crei una sessione:
# Create a session with state
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
state={'key': 'value'})
print(session.state['key'])
# value
Per aggiornare lo stato della sessione al di fuori del runner, aggiungi un nuovo evento alla sessione utilizzando state_delta:
# file: my_agent/runner.py
from google.adk.events import Event, EventActions
import time
# Define state changes
state_changes = {'key': 'new_value'}
# Create event with actions
actions_with_update = EventActions(state_delta=state_changes)
system_event = Event(
invocation_id="invocation_id",
author="system", # Or 'agent', 'tool' etc.
actions=actions_with_update,
timestamp=time.time()
)
# Append the event
await session_service.append_event(session, system_event)
# Check updated state
updated_session = await session_service.get_session(
app_name=app_name,
user_id=user_id,
session_id=session.id)
# State is updated to new value
print(updated_session.state['key'])
# new_value
Campi personalizzati per gli eventi
L'ADK supporta uno schema di eventi flessibile, in modo da poter includere dati arbitrari negli eventi di sessione. Questo è utile per l'interoperabilità con altri framework di agenti o per l'archiviazione di dati sugli eventi personalizzati.
Quando aggiungi un evento con campi personalizzati, l'ADK serializza i dati sugli eventi nel campo raw_event dell'evento di sessione archiviato.
# Create an event with custom fields
custom_event = Event(
invocation_id="invocation_id",
author="user",
timestamp=time.time(),
custom_field="custom_value",
another_field={"nested_key": "nested_value"}
)
# Append the event
await session_service.append_event(session, custom_event)
Quando recuperi la sessione, gli eventi recuperati conservano questi campi personalizzati.
Elimina una sessione
Elimina una sessione specifica associata a un ID utente:
await session_service.delete_session(app_name=app_name, user_id=user_id, session_id=session.id)
Esegui il deployment dell'agente su Agent Platform
Dopo aver testato l'agente localmente, puoi eseguirne il deployment in produzione aggiornando l'istanza di Agent Platform con i parametri:
Google Cloud Project
client.runtimes.update(
resource_name=remote_agent.api_resource.name,
agent=AGENT,
config={
"display_name": DISPLAY_NAME, # Optional.
"requirements": REQUIREMENTS, # Optional.
"staging_bucket": STAGING_BUCKET, # Required.
},
)
Sostituisci quanto segue:
AGENT: l'applicazione che implementa il metodo
query / stream_query(ad esempio,AdkAppper un agente ADK).DISPLAY_NAME: un nome facile da ricordare per l'agente.
REQUIREMENTS: un elenco di pacchetti pip richiesti dall'agente. Ad esempio,
["google-cloud-storage", "google-cloud-agentplatform[runtimes,adk]"].STAGING_BUCKET: un bucket Cloud Storage con prefisso
gs://.
Esegui la pulizia
Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare l'istanza di runtime dell'agente insieme alle relative risorse secondarie:
remote_agent.delete(force=True)