快速開始使用 REST API

本教學課程將示範如何直接對 Vertex AI Agent Engine 工作階段和記憶庫發出 REST API 呼叫，以建立及使用工作階段和長期記憶。如果您不希望代理程式架構為您協調呼叫，或是想將 Sessions 和 Memory Bank 與 Agent Development Kit (ADK) 以外的代理程式架構整合，請使用 REST API。

如需使用 ADK 的快速入門導覽課程，請參閱「使用 Agent Development Kit 快速入門」。

本教學課程會使用下列步驟：

  1. 使用下列選項建立回憶集錦：
  2. 擷取記憶體。
  3. 清除所用資源。

事前準備

如要完成本教學課程中示範的步驟，請先按照「設定 Memory Bank」一文中的步驟操作。

從 Vertex AI Agent Engine 會話生成記憶內容

設定 Vertex AI Agent Engine 工作階段和 Memory Bank 後，即可建立工作階段並附加事件。記憶內容是根據使用者與代理程式的對話生成的事實，可供日後的使用者互動。詳情請參閱「產生回憶集錦」和「擷取回憶集錦」。

  1. 使用不透明的使用者 ID 建立工作階段。除非您在生成記憶體時明確提供範圍，否則系統會自動以範圍 {"user_id": "USER_ID"} 為這個工作階段生成的任何記憶體加上索引鍵。

    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])

    更改下列內容：

    • LOCATION：您的區域。Vertex AI Agent Engine Memory Bank 僅支援 us-central1。

    • AGENT_ENGINE_NAME：您建立的 Vertex AI Agent Engine 執行個體名稱，或是現有的 Vertex AI Agent Engine 執行個體。名稱的格式應為 projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}。

    • USER_ID：使用者的 ID。除非您在生成記憶體時明確提供範圍，否則系統會自動以範圍 {"user_id": "USER_ID"} 為這個工作階段生成的任何記憶體加上索引鍵。

  2. 將活動以疊代方式上傳至工作階段。事件可以包含使用者、代理程式和工具之間的任何互動。事件的排序清單代表工作階段的對話記錄。系統會使用這項對話記錄做為來源資料，為該使用者生成記憶內容。

    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. 如要根據對話記錄生成回憶集錦，請為工作階段觸發回憶集錦生成要求：

    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
)

更改下列內容：

  • (選用) SCOPE：代表生成回憶範圍的字典，最多 5 個鍵/值配對，且不得包含 * 字元。例如 {"session_id": "MY_SESSION"}。系統只會合併範圍相同的記憶體。如果未提供，則使用 {"user_id": session.user_id}。

上傳回憶

除了使用原始對話產生記憶內容，您也可以上傳記憶內容，或讓代理程式使用 CreateMemory 直接新增記憶內容。您可直接提供應儲存的使用者相關事實，而非讓記憶庫從內容中擷取資訊。我們建議您以第一人稱撰寫有關使用者的事實 (例如 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))
  )
)
"""

擷取及使用回憶集錦

您可以擷取使用者的記憶內容，並納入系統指令，讓 LLM 存取個人化情境。

如要進一步瞭解如何使用範圍型方法擷取回憶集錦，請參閱「擷取回憶集錦」。

# 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"}
    )
)

您可以使用 jinja 將結構化記憶轉換為提示：


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>
"""

清除所用資源

如要清除此專案中使用的所有資源，您可以刪除用於本快速入門導覽課程的 Google Cloud 專案。

或者，您也可以按照下列步驟，刪除在本教學課程中建立的個別資源：

  1. 使用下列程式碼範例刪除 Vertex AI Agent Engine 執行個體，這也會刪除與 Vertex AI Agent Engine 執行個體相關聯的所有工作階段或記憶體。

    agent_engine.delete(force=True)

  2. 刪除所有在本機建立的檔案。

後續步驟