Guida rapida all'SDK Vertex AI Agent Engine

Questo tutorial mostra come effettuare chiamate API direttamente a Sessioni e Banca della memoria di Vertex AI Agent Engine utilizzando l'SDK Vertex AI Agent Engine. Utilizza l'SDK Vertex AI Agent Engine 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: utilizzo di Agent Development Kit.

Questo tutorial utilizza i seguenti passaggi:

  1. Crea ricordi utilizzando le seguenti opzioni:
  2. Recuperare i ricordi.
  3. Pulizia.

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima seguire i passaggi descritti in Configurazione di Memory Bank.

Genera ricordi con le sessioni di Vertex AI Agent Engine

Dopo aver configurato le sessioni e Memory Bank 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. Per ulteriori informazioni, vedi Generare ricordi 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.

    import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# For Express Mode users, initialize the Vertex AI Client as follows:
# client = vertexai.Client(
#   api_key="API_KEY",
# )

# This assumes that you already have an Agent Engine instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
  # The name can be fetched using `agent_engine.api_resource.name`.
  name="AGENT_ENGINE_NAME",
  user_id="USER_ID"
)

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.

    • LOCATION: La tua regione. Consulta le regioni supportate per Memory Bank.

    • AGENT_ENGINE_NAME: il nome dell'istanza Vertex AI Agent Engine che hai creato o di un'istanza 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 degli 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.

    import datetime

client.agent_engines.sessions.events.append(
  name=session.response.name,
  author="user",  # Required by Sessions.
  invocation_id="1",  # Required by Sessions.
  timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
  config={
    "content": {
      "role": "user",
      "parts": [{"text": "hello"}]
    }
  }
)

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

    client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
    "session": session.response.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 viene fornito, viene utilizzato {"user_id": session.user_id}.

Caricare i ricordi

In alternativa alla generazione di ricordi utilizzando dialoghi grezzi, puoi caricare ricordi o chiedere ai tuoi agenti di aggiungerli direttamente utilizzando GenerateMemories con fatti preestratti. 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).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Sostituisci quanto segue:

  • FACT: Il fatto preestratto che deve essere consolidato con i ricordi esistenti. Puoi fornire fino a 5 fatti preestratti in un elenco come il seguente:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio, {"session_id": "MY_SESSION"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito.

In alternativa, puoi utilizzare CreateMemory per caricare i ricordi senza utilizzare Memory Bank per l'estrazione o il consolidamento.

memory = client.agent_engines.memories.create(
    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 al 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.memories.retrieve(
        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>
"""

Eliminare i ricordi

Puoi eliminare un ricordo specifico utilizzando il nome della risorsa:

client.agent_engines.memories.delete(name=MEMORY_NAME)

Sostituisci quanto segue:

  • MEMORY_NAME: il nome del ricordo da eliminare. Il nome deve essere nel seguente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Puoi trovare il nome del ricordo recuperando i ricordi.

Esegui la pulizia

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

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