此页面由 Cloud Translation API 翻译。

智能体开发套件快速入门

将 Agent Development Kit (ADK) 代理配置为使用 Vertex AI Agent Engine 会话和内存银行后，代理会自动为您读取和写入内存和会话。

如需快速入门使用 REST API，请参阅REST API 快速入门。

本教程演示了如何将 Vertex AI Agent Engine 会话和 Memory Bank 与 ADK 搭配使用，以创建和使用会话和长期记忆：

创建 Vertex AI Agent Engine 实例，以访问 Vertex AI Agent Engine 会话和内存银行。
创建本地 ADK 代理和运行程序。
与您的客服人员互动，动态生成可在多个会话中访问的长期记忆。
清理.

准备工作

如需完成本教程中演示的步骤，您必须先设置项目和环境。

设置项目

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.

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

Go to project selector

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

Enable the Vertex AI API.

Enable the API

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

Go to project selector

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

Enable the Vertex AI API.

Enable the API

如果您选择了项目，请确保您拥有该项目的 Vertex AI User (roles/aiplatform.user) IAM 角色。

向 Vertex AI 进行身份验证

如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
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.

Google Cloud

导入库

安装智能体开发套件：

pip install google-adk==1.2.0

设置环境变量

如需使用 ADK，请设置环境变量：

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

替换以下内容：

PROJECT_ID：您的项目 ID。
LOCATION：您的区域。 Vertex AI Agent Engine 内存银行和会话仅支持 us-central1。

创建 Vertex AI Agent Engine 实例

如需访问 Vertex AI Agent Engine 会话和 Vertex AI Agent Engine 内存银行，您首先需要创建 Vertex AI Agent Engine 实例。您无需部署任何代码即可开始使用会话和内存银行。如果不部署代码，创建 Vertex AI Agent Engine 实例应该需要几秒钟。

如果您希望 Vertex AI Agent Engine 内存银行使用大语言模型 (LLM) 为您生成回忆，请提供 memoryBankConfig.generationConfig，并添加您希望内存银行用于生成回忆的模型。您项目的 Vertex AI Reasoning Engine Service Agent 必须具有 aiplatform.endpoints.predict 权限才能使用该模型。

import requests

import google.auth
import google.auth.transport.requests

credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

response = requests.post(
    url=url,
    json={
        "contextSpec": {
            "memoryBankConfig": {
                "generationConfig": {
                    "model": f"projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_NAME"
                },
                "similaritySearchConfig": {
                    "embeddingModel": f"projects/PROJECT_ID/locations/LOCATION/publishers/google/models/EMBEDDING_MODEL_NAME"
                }
            }
        }
    },
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {credentials.token}"
    }

)

split_name = response.json()["name"].split("/")
agent_engine_name = "/".join(split_name[:-2])

替换以下内容：

PROJECT_ID：您的项目 ID。
LOCATION：您的区域。 Vertex AI Agent Engine 内存银行和会话仅支持 us-central1。
MODEL_NAME：用于生成回忆的 LLM 模型。您可以使用任何 Gemini 或 Model Garden 模型。
EMBEDDING_MODEL_NAME：（可选）用于查找特定范围内类似回忆的嵌入模型。您可以使用任何支持嵌入 API 的模型，只要该模型支持向量长度为 768 作为输出维度即可。

创建 ADK 代理

通过在 ADK BaseMemoryService 中封装内存银行，创建基于 Vertex AI Agent Engine 内存银行的内存服务。运行程序会调用 add_session_to_memory 以触发内存生成，并调用 search_memory 以检索当前作用域的内存。

from datetime import datetime
import json
import pprint
import requests

from google import adk
from google.adk.memory import BaseMemoryService
from google.adk.memory import base_memory_service
from google.adk.memory import memory_entry
import google.auth
import google.auth.transport.requests
from google.genai import types

class AgentEngineMemoryBankService(BaseMemoryService):
  """Memory service for Agent Engine Memory Bank."""

  def __init__(self, agent_engine_name):
    self.agent_engine_name = agent_engine_name
    self.url = f"https://us-central1-aiplatform.googleapis.com/v1beta1/{self.agent_engine_name}"
    self.credentials, _ = google.auth.default()

  async def add_session_to_memory(self, session: adk.sessions.Session):
    """Adds a session to Agent Engine Memory Bank.

    A session can be added multiple times during its lifetime.

    Args:
        session: The session to add.
    """
    auth_req = google.auth.transport.requests.Request()
    self.credentials.refresh(auth_req)

    response = requests.post(
        url=f"{self.url}/memories:generate",
        headers={
            "Content-Type": "application/json; charset=utf-8",
            "Authorization": f"Bearer {self.credentials.token}",
        },
        json={
            "vertex_session_source": {
                "session": f"{self.agent_engine_name}/sessions/{session.id}"
            }
        }
    )
    return response.json()

  async def search_memory(
      self, app_name: str, user_id: str, query: str
  ) -> adk.memory.base_memory_service.SearchMemoryResponse:
    """Searches for memories that match the query."""
    auth_req = google.auth.transport.requests.Request()
    self.credentials.refresh(auth_req)

    filter = json.dumps(json.dumps({"user_id": user_id}))

    response = requests.get(
        url=f"{self.url}/memories?filter=scope={filter}",
        headers={
            "Content-Type": "application/json; charset=utf-8",
            "Authorization": f"Bearer {self.credentials.token}",
        },
    )

    memory_events = []
    for memory in response.json().get("memories", []):
        memory_events.append(
            memory_entry.MemoryEntry(
                author="user",
                content=types.Content(
                  parts=[types.Part(text=memory.get("fact"))],
                  role="user"),
                timestamp=memory.get("updateTime")
            )
        )

    return base_memory_service.SearchMemoryResponse(memories=memory_events)

开发 ADK 代理时，请添加 Memory 工具，用于控制何时使用内存服务以及如何将内存包含在提示中。示例代理使用 PreloadMemoryTool，该代理始终会在每回合开始时检索记忆，并在系统指令中包含这些记忆：

from google import adk

agent = adk.Agent(
    model="gemini-2.0-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)

创建 ADK 运行程序，用于协调代理、工具和回调的执行。将 VertexAiSessionService 与 AgentEngineMemoryBankService 类搭配使用时，运行程序会协调调用以读取和写入会话和内存。

from google.adk.sessions import VertexAiSessionService

session_service = VertexAiSessionService(
  "PROJECT_ID", "LOCATION")

memory_service = AgentEngineMemoryBankService(
  agent_engine_name="AGENT_ENGINE_NAME")

runner = adk.Runner(
    agent=agent,
    app_name="AGENT_ENGINE_NAME",
    session_service=session_service,
    memory_service=memory_service)

def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(user_id=user_id, session_id=session, new_message=content)

  for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

替换以下内容：

AGENT_ENGINE_NAME：您创建的 Vertex AI Agent Engine 实例或现有 Vertex AI Agent Engine 实例的名称。该名称应采用以下格式：projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID。

与您的代理互动

定义代理并设置会话和记忆库后，您就可以与代理互动了。

创建您的第一个会话。由于在与用户的首次会话期间没有可用回忆，因此代理不知道任何用户偏好设置，例如用户的首选温度：

注意：客服人员和 Memory Bank 的回答可能会因所使用的模型而异。
```
session = await session_service.create_session(
  app_name="AGENT_ENGINE_NAME",
  user_id="USER_ID"
)

call_agent(
  "Can you update the temperature to my preferred temperature?",
  session.id,
  "USER_ID")

# Agent response: "What is your preferred temperature?"
call_agent("I like it at 71 degrees", session.id, "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.
```
替换以下内容：
- USER_ID：用户的标识符。在此会话中生成的回忆以此不透明标识符作为键。生成的回忆的范围以 {"user_id": "USER_ID"} 的形式存储。
如需使用会话生成回忆，请调用 add_session_to_memory：
```
await memory_service.add_session_to_memory(session)
```
注意：如需手动检查生成的内存，请参阅获取生成的内存。

创建第二个会话。如果您使用了 PreloadMemoryTool，代理会在每轮对话开始时检索记忆，以访问用户之前向代理传达的偏好设置。

session = await session_service.create_session(
  app_name="AGENT_ENGINE_NAME",
  user_id="USER_ID")

call_agent("Fix the temperature!", session.id, "USER_ID")
# Agent Response:  Setting temperature to 71 degrees.  Is that correct?

清理

如需清理此项目中使用的所有资源，您可以删除用于本快速入门的 Google Cloud 项目。

否则，您可以逐个删除在本教程中创建的资源，如下所示：

使用以下代码示例删除 Vertex AI Agent Engine 实例，这也会删除属于该 Vertex AI Agent Engine 的所有会话或回忆。

credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/AGENT_ENGINE_NAME"

response = requests.delete(
    url=url,
    json={"force": True},
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {credentials.token}"
    }

)

删除本地创建的所有文件。

后续步骤

REST API 快速入门。

智能体开发套件快速入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

设置项目

向 Vertex AI 进行身份验证

导入库

设置环境变量

创建 Vertex AI Agent Engine 实例

创建 ADK 代理

与您的代理互动

清理

后续步骤

智能体开发套件快速入门