在 Vertex AI Agent Engine 開發及部署代理

在 Vertex AI Agent Engine 開發及部署代理

本頁說明如何使用下列代理框架建立及部署代理，以便在 Vertex AI Agent Engine Runtime 中執行：

• LangGraph

• LangChain

• AG2

• LlamaIndex 查詢管道 (預先發布版)

本快速入門導覽課程會逐步引導您完成下列步驟：

• 設定您的 Google Cloud 專案。

• 安裝 Vertex AI SDK for Python 和所選架構。

• 開發貨幣兌換代理程式。

• 將代理部署至 Vertex AI Agent Engine 執行階段。

• 測試已部署的代理程式。

如要瞭解如何使用 Agent Development Kit 快速入門，請參閱「使用 Agent Development Kit 在 Vertex AI Agent Engine 上開發及部署代理」。

事前準備

注意： 如要啟用 API，您需要 serviceusage.services.enable 權限。如果沒有這項權限，請要求管理員授予服務用量管理員 (roles/serviceusage.serviceUsageAdmin) 角色。

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

如要取得使用 Vertex AI Agent Engine 所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• Vertex AI 使用者 (roles/aiplatform.user)
• 儲存空間管理員 (roles/storage.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

安裝並初始化 Vertex AI SDK for Python

1. 執行下列指令，安裝 Vertex AI SDK for Python 和其他必要套件：

   LangGraph

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,langchain]>=1.112

   LangChain

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,langchain]>=1.112

   AG2

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,ag2]>=1.112

   LlamaIndex

   預先發布版

   這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,llama_index]>=1.112

2. 以使用者身分進行驗證

   Colab

   請執行下列程式碼：

   from google.colab import auth
   
   auth.authenticate_user(project_id="PROJECT_ID")
   

   Cloud Shell

   您無需採取任何動作。

   本機殼層

   執行下列指令：

   gcloud auth application-default login

   快速模式

   如果您使用 Vertex AI 的快速模式，則無須採取任何行動。

3. 執行下列程式碼，匯入 Vertex AI Agent Engine 並初始化 SDK：

   1. (選用) 測試您開發的代理前，請先匯入 Vertex AI Agent Engine 並初始化 SDK，如下所示：

      Google Cloud 專案

      import vertexai
      
      vertexai.init(
          project="PROJECT_ID",               # Your project ID.
          location="LOCATION",                # Your cloud region.
      )
      

      其中：

      • PROJECT_ID 是您 Google Cloud 開發及部署代理程式時所用的專案 ID

      • LOCATION 是支援的區域之一。

      快速模式

      如果您在快捷模式下使用 Vertex AI，請執行下列程式碼：

      import vertexai
      
      vertexai.init(
          api_key="API_KEY"
      )
      

      其中 API_KEY 是用來驗證代理程式的 API 金鑰。

   2. 部署代理程式前，您需要匯入 Vertex AI Agent Engine 並初始化 SDK，如下所示：

      Google Cloud 專案

      import vertexai
      
      client = vertexai.Client(
          project="PROJECT_ID",               # Your project ID.
          location="LOCATION",                # Your cloud region.
      )
      

      其中：

      • PROJECT_ID 是您 Google Cloud 開發及部署代理程式時所用的專案 ID

      • LOCATION 是支援的區域之一。

      快速模式

      如果您在快捷模式下使用 Vertex AI，請執行下列程式碼：

      import vertexai
      
      client = vertexai.Client(
          api_key="API_KEY"
      )
      

      其中 API_KEY 是用來驗證代理程式的 API 金鑰。

開發代理

1. 為代理開發貨幣匯率工具：

   def get_exchange_rate(
       currency_from: str = "USD",
       currency_to: str = "EUR",
       currency_date: str = "latest",
   ):
       """Retrieves the exchange rate between two currencies on a specified date."""
       import requests
   
       response = requests.get(
           f"https://api.frankfurter.app/{currency_date}",
           params={"from": currency_from, "to": currency_to},
       )
       return response.json()
   

2. 例項化代理程式：

   LangGraph

   from vertexai import agent_engines
   
   agent = agent_engines.LanggraphAgent(
       model="gemini-2.0-flash",
       tools=[get_exchange_rate],
       model_kwargs={
           "temperature": 0.28,
           "max_output_tokens": 1000,
           "top_p": 0.95,
       },
   )
   

   LangChain

   from vertexai import agent_engines
   
   agent = agent_engines.LangchainAgent(
       model="gemini-2.0-flash",
       tools=[get_exchange_rate],
       model_kwargs={
           "temperature": 0.28,
           "max_output_tokens": 1000,
           "top_p": 0.95,
       },
   )
   

   AG2

   from vertexai import agent_engines
   
   agent = agent_engines.AG2Agent(
       model="gemini-2.0-flash",
       runnable_name="Get Exchange Rate Agent",
       tools=[get_exchange_rate],
   )
   

   LlamaIndex

   預先發布版

   這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

   from vertexai.preview import reasoning_engines
   
   def runnable_with_tools_builder(model, runnable_kwargs=None, **kwargs):
       from llama_index.core.query_pipeline import QueryPipeline
       from llama_index.core.tools import FunctionTool
       from llama_index.core.agent import ReActAgent
   
       llama_index_tools = []
       for tool in runnable_kwargs.get("tools"):
           llama_index_tools.append(FunctionTool.from_defaults(tool))
       agent = ReActAgent.from_tools(llama_index_tools, llm=model, verbose=True)
       return QueryPipeline(modules = {"agent": agent})
   
   agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
       model="gemini-2.0-flash",
       runnable_kwargs={"tools": [get_exchange_rate]},
       runnable_builder=runnable_with_tools_builder,
   )
   

3. 在本機測試代理：

   LangGraph

   agent.query(input={"messages": [
       ("user", "What is the exchange rate from US dollars to SEK today?"),
   ]})
   

   LangChain

   agent.query(
       input="What is the exchange rate from US dollars to SEK today?"
   )
   

   AG2

   agent.query(
       input="What is the exchange rate from US dollars to SEK today?"
   )
   

   LlamaIndex

   預先發布版

   這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

   agent.query(
       input="What is the exchange rate from US dollars to SEK today?"
   )
   

部署代理程式

在 Vertex AI 中建立 reasoningEngine 資源，部署代理：

LangGraph

remote_agent = client.agent_engines.create(
    agent,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

LangChain

remote_agent = client.agent_engines.create(
    agent,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

AG2

remote_agent = client.agent_engines.create(
    agent,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,ag2]"],
    },
)

LlamaIndex

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

remote_agent = client.agent_engines.create(
    agent,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,llama_index]"],
    },
)

使用代理

傳送查詢內容，測試已部署的代理：

LangGraph

remote_agent.query(input={"messages": [
    ("user", "What is the exchange rate from US dollars to SEK today?"),
]})

LangChain

remote_agent.query(
    input="What is the exchange rate from US dollars to SEK today?"
)

AG2

remote_agent.query(
    input="What is the exchange rate from US dollars to SEK today?"
)

LlamaIndex

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

remote_agent.query(
    input="What is the exchange rate from US dollars to SEK today?"
)

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。

remote_agent.delete(force=True)

後續步驟

• 探索筆記本。
• 設定環境。
• 開發代理。
• 部署代理程式。
• 使用代理程式。
• 管理代理程式。
• 取得支援。