Guida rapida all'API REST

Questo tutorial mostra come effettuare chiamate API REST direttamente a Sessioni e Memory Bank di Vertex AI Agent Engine per creare e utilizzare sessioni e ricordi a lungo termine. Utilizza l'API REST se non vuoi che un framework di agenti orchestri le chiamate per te o se vuoi integrare Sessioni e Banca della memoria con framework di agenti diversi da Agent Development Kit (ADK).

Per la guida rapida all'utilizzo di ADK, consulta Guida rapida all'utilizzo di Agent Development Kit.

Questo tutorial utilizza i seguenti passaggi:

  1. Crea l'istanza di Vertex AI Agent Engine per accedere a Sessioni e Banca della memoria di Vertex AI Agent Engine.
  2. Crea ricordi utilizzando le seguenti opzioni:
  3. Recuperare i ricordi.
  4. Pulisci.

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima configurare il progetto e l'ambiente.

Configura il progetto

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.
  8. Se hai selezionato un progetto, assicurati di disporre del ruolo IAM Vertex AI User (roles/aiplatform.user) sul progetto.

    9. Autenticarsi in Vertex AI

    Per utilizzare gli esempi di Python questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command: 

      gcloud init

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione Google Cloud .

    Importare librerie

    Installa l'SDK Vertex AI:

    pip install google-cloud-aiplatform>=1.100.0

    Crea l'istanza di Vertex AI Agent Engine

    Per accedere a Vertex AI Agent Engine Sessions e Vertex AI Agent Engine Memory Bank, devi prima creare un'istanza di Vertex AI Agent Engine. Non è necessario eseguire il deployment di un agente per iniziare a utilizzare Sessioni e Banca della memoria. Senza il deployment dell'agente, la creazione di un'istanza di Vertex AI Agent Engine dovrebbe richiedere pochi secondi.

    import vertexai

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

agent_engine = client.agent_engines.create()

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • LOCATION: La tua regione. Per il Memory Bank di Vertex AI Agent Engine è supportato solo us-central1.

    Genera ricordi dalle sessioni di Vertex AI Agent Engine

    Dopo aver configurato le sessioni e la banca di memoria di Vertex AI Agent Engine, puoi creare sessioni e aggiungere eventi. I ricordi vengono generati come fatti dalla conversazione dell'utente con l'agente, in modo che siano disponibili per le interazioni future dell'utente. Per ulteriori informazioni, vedi Generare e recuperare ricordi.

    1. Crea una sessione con un ID utente opaco. Tutti i ricordi generati da questa sessione vengono automaticamente associati all'ambito {"user_id": "USER_ID"}, a meno che tu non fornisca esplicitamente un ambito durante la generazione dei ricordi.

      from google.cloud import aiplatform_v1beta1

sessions_client = aiplatform_v1beta1.SessionServiceClient(
  client_options={
    "api_endpoint": "https://LOCATION-aiplatform.googleapis.com"
  },
  transport="rest"
)

session_lro = sessions_client.create_session(
  parent=AGENT_ENGINE_NAME,
  session={"user_id": "USER_ID"}
)
session_name = "/".join(session_lro.operation.name.split("/")[0:-2])

      Sostituisci quanto segue:

      • LOCATION: La tua regione. Per il Memory Bank di Vertex AI Agent Engine è supportato solo us-central1.

      • AGENT_ENGINE_NAME: il nome dell'istanza di Vertex AI Agent Engine che hai creato o di un'istanza di Vertex AI Agent Engine esistente. Il nome deve essere nel seguente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

      • USER_ID: un identificatore per l'utente. Tutti i ricordi generati da questa sessione vengono automaticamente associati all'ambito {"user_id": "USER_ID"}, a meno che tu non fornisca esplicitamente un ambito durante la generazione dei ricordi.

    2. Carica gli eventi in modo iterativo nella sessione. Gli eventi possono includere qualsiasi interazione tra l'utente, l'agente e gli strumenti. L'elenco ordinato di eventi rappresenta la cronologia delle conversazioni della sessione. Questa cronologia delle conversazioni viene utilizzata come materiale di origine per generare ricordi per quell'utente specifico.

      event = aiplatform_v1beta1.SessionEvent(
    author="user",  # Required by Sessions.
    invocation_id="1",  # Required by Sessions.
    timestamp=datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ'),  # Required by Sessions.
    content = aiplatform_v1beta1.Content(
        role="user",
        parts=[aiplatform_v1beta1.Part(text="Hello")]
    )
)

sessions_client.append_event(name=session_name, event=event)

    3. Per generare ricordi dalla cronologia delle conversazioni, attiva una richiesta di generazione di ricordi per la sessione:

      client.agent_engines.generate_memories(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": session_name
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE
)

    Sostituisci quanto segue:

    • (Facoltativo) SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati, con un massimo di 5 coppie chiave-valore e nessun carattere *. Ad esempio: {"session_id": "MY_SESSION"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito. Se non fornito, viene utilizzato {"user_id": session.user_id}.

    Caricare ricordi

    In alternativa alla generazione di ricordi utilizzando dialoghi grezzi, puoi caricare i ricordi o chiedere ai tuoi agenti di aggiungerli direttamente utilizzando CreateMemory. Anziché estrarre informazioni dai tuoi contenuti, Memory Bank ti consente di fornire direttamente i fatti da memorizzare sull'utente. Ti abbiamo consigliato di scrivere i fatti sugli utenti in prima persona (ad esempio, I am a software engineer).

    memory = client.agent_engines.create_memory(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope= {"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

    Recuperare e utilizzare i ricordi

    Puoi recuperare i ricordi per il tuo utente e includerli nelle istruzioni di sistema per dare all'LLM l'accesso al tuo contesto personalizzato.

    Per ulteriori informazioni sul recupero dei ricordi utilizzando un metodo basato sull'ambito, vedi Recuperare i ricordi.

    # Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.retrieve_memories(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

    Puoi utilizzare jinja per convertire i tuoi ricordi strutturati in un prompt:

    
from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

    Esegui la pulizia

    Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare il Google Cloud progetto utilizzato per la guida introduttiva.

    In alternativa, puoi eliminare le singole risorse che hai creato in questo tutorial nel seguente modo:

    1. Utilizza il seguente esempio di codice per eliminare l'istanza di Vertex AI Agent Engine, che elimina anche eventuali sessioni o ricordi associati all'istanza di Vertex AI Agent Engine.

      agent_engine.delete(force=True)

    2. Elimina tutti i file creati localmente.

    Passaggi successivi