本頁面由 Cloud Translation API 翻譯而成。

使用 LangChain 代理程式

事前準備

本教學課程假設您已詳閱並按照下列教學課程的指示操作：

開發 LangChain 代理程式：將 agent 開發為 LangchainAgent 的執行個體。
使用者驗證：以使用者身分進行驗證，以便查詢代理程式。
匯入並初始化 SDK，以便初始化用戶端來取得已部署的執行個體 (如有需要)。

取得代理程式的執行個體

如要查詢 LangchainAgent，請先建立新執行個體或取得現有執行個體。

如要取得特定資源 ID 對應的 LangchainAgent：

Vertex AI SDK for Python

請執行下列程式碼：

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

agent = client.agent_engines.get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

print(agent)

其中

PROJECT_ID 是您 Google Cloud 開發及部署代理程式的專案 ID，以及
LOCATION 是支援的區域。
RESOURCE_ID 是已部署代理程式的 ID，屬於 reasoningEngine 資源。

Python requests 程式庫

請執行下列程式碼：

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

使用 Python 適用的 Vertex AI SDK 時，agent 物件會對應至 AgentEngine 類別，其中包含下列項目：

包含已部署代理程式相關資訊的 agent.api_resource。您也可以呼叫 agent.operation_schemas()，傳回代理程式支援的作業清單。詳情請參閱「支援的作業」。
agent.api_client，可進行同步服務互動
agent.async_api_client，可進行非同步服務互動

本節其餘部分假設您有名為 agent 的 AgentEngine 執行個體。

支援的作業

支援的作業如下：

query：用於同步取得查詢的回覆。
stream_query：用於串流查詢的回覆。

query 和 stream_query 方法都支援相同類型的引數：

input：要傳送給服務專員的訊息。
config：查詢內容的設定 (如適用)。

查詢代理程式

指令：

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

等同於下列項目 (完整形式)：

agent.query(input={
    "input": [ # The input is represented as a list of messages (each message as a dict)
        {
            # The role (e.g. "system", "user", "assistant", "tool")
            "role": "user",
            # The type (e.g. "text", "tool_use", "image_url", "media")
            "type": "text",
            # The rest of the message (this varies based on the type)
            "text": "What is the exchange rate from US dollars to Swedish currency?",
        },
    ]
})

模型會根據角色區分不同類型的訊息，以便回覆。如果輸入內容中省略 role，系統會預設為 "user"。

角色	說明
`system`	用來告知聊天模型如何運作，並提供額外背景資訊。並非所有即時通訊模型供應商都支援這項功能。
`user`	代表使用者與模型互動時的輸入內容，通常是文字或其他互動式輸入內容。
`assistant`	代表模型的回覆，可能包含文字或呼叫工具的要求。
`tool`	用於在擷取外部資料或處理程序後，將工具呼叫結果傳回模型的訊息。

訊息的 type 也會決定如何解讀訊息的其餘部分 (請參閱「處理多模態內容」)。

使用多模態內容查詢代理程式

我們會使用下列代理程式 (將輸入內容轉送至模型，且不使用任何工具)，說明如何將多模態輸入內容傳遞至代理程式：

agent = agent_engines.LangchainAgent(
    model="gemini-2.0-flash",
    runnable_builder=lambda model, **kwargs: model,
)

多模態訊息會透過指定 type 和對應資料的內容區塊表示。一般來說，如果是多模態內容，您會將 type 指定為 "media"，將 file_uri 指向 Cloud Storage URI，並將 mime_type 用於解譯檔案。

映像檔

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "image/jpeg", "file_uri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg"},
]})

影片

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "video/mp4", "file_uri": "gs://cloud-samples-data/generative-ai/video/pixel8.mp4"},
]})

音訊

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "audio/mp3", "file_uri": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3"},
]})

如要查看 Gemini 支援的 MIME 類型清單，請參閱下列說明文件：

使用可執行的設定查詢代理程式

查詢代理程式時，您也可以指定代理程式的 config (遵循 RunnableConfig 的結構)。以下是兩種常見情境：

預設設定參數：
- run_id / run_name：執行作業的 ID。
- tags / metadata：使用 OpenTelemetry 追蹤時，用於分類執行的分類器。
自訂設定參數 (透過 configurable)：
- session_id：執行作業的工作階段 (請參閱「儲存對話記錄」)。
- thread_id：執行作業的執行緒 (請參閱「儲存檢查點」)。

舉例來說：

import uuid

run_id = uuid.uuid4()  # Generate an ID for tracking the run later.

response = agent.query(
    input="What is the exchange rate from US dollars to Swedish currency?",
    config={  # Specify the RunnableConfig here.
        "run_id": run_id                               # Optional.
        "tags": ["config-tag"],                        # Optional.
        "metadata": {"config-key": "config-value"},    # Optional.
        "configurable": {"session_id": "SESSION_ID"}   # Optional.
    },
)

print(response)