使用 LangGraph 代理程式

事前準備

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

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

取得代理程式的執行個體

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

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

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 執行個體。

支援的作業

LanggraphAgent 支援下列作業：

• query：用於同步取得查詢的回覆。
• stream_query：用於串流查詢的回覆。
• get_state：用於取得特定檢查點。
• get_state_history：列出執行緒的檢查點。
• update_state：建立對應不同情境的分支。

串流查詢的回覆

LangGraph 支援多種串流模式。主要有以下幾種：

• values：這個模式會在每個節點呼叫後，串流傳輸圖表的完整狀態。
• updates：在這個模式中，系統會在呼叫每個節點後，將圖表的狀態更新串流傳輸。

如要串流回 values (對應於圖表的完整狀態)：

for state_values in agent.stream_query(
    input=inputs,
    stream_mode="values",
    config={"configurable": {"thread_id": "streaming-thread-values"}},
):
    print(state_values)

如要回溯串流 updates (對應於圖表狀態的更新)：

for state_updates in agent.stream_query(
    input=inputs,
    stream_mode="updates",
    config={"configurable": {"thread_id": "streaming-thread-updates"}},
):
    print(state_updates)

人機迴圈

在 LangGraph 中，人為介入的常見做法是新增中斷點，中斷代理程式的動作序列，並讓人在稍後的時間點繼續流程。

注意： 這個步驟假設您使用的代理程式已設定為儲存檢查點。

查看

呼叫 .query 或 .stream_query 時，可以使用 interrupt_before= 或 interrupt_after= 引數設定中斷點：

from langchain.load import load as langchain_load

response = agent.query(
    input=inputs,
    interrupt_before=["tools"], # after generating the function call, before invoking the function
    interrupt_after=["tools"], # after getting a function response, before moving on
    config={"configurable": {"thread_id": "human-in-the-loop-deepdive"}},
)

langchain_load(response['messages'][-1]).pretty_print()

輸出內容會與下列內容類似：

================================== Ai Message ==================================
Tool Calls:
  get_exchange_rate (12610c50-4465-4296-b1f3-d751ec959fd5)
 Call ID: 12610c50-4465-4296-b1f3-d751ec959fd5
  Args:
    currency_from: USD
    currency_to: SEK

核准

如要核准產生的工具呼叫並繼續執行其餘作業，請將 None 傳遞至輸入內容，並在 config 中指定執行緒或檢查點：

from langchain.load import load as langchain_load

response = agent.query(
    input=None,  # Continue with the function call
    interrupt_before=["tools"], # after generating the function call, before invoking the function
    interrupt_after=["tools"], # after getting a function response, before moving on
    config={"configurable": {"thread_id": "human-in-the-loop-deepdive"}},
)

langchain_load(response['messages'][-1]).pretty_print()

輸出內容會與下列內容類似：

================================= Tool Message =================================
Name: get_exchange_rate

{"amount": 1.0, "base": "USD", "date": "2024-11-14", "rates": {"SEK": 11.0159}}

記錄

如要列出特定執行緒的所有檢查點，請使用 .get_state_history 方法：

for state_snapshot in agent.get_state_history(
    config={"configurable": {"thread_id": "human-in-the-loop-deepdive"}},
):
    if state_snapshot["metadata"]["step"] >= 0:
        print(f'step {state_snapshot["metadata"]["step"]}: {state_snapshot["config"]}')
        state_snapshot["values"]["messages"][-1].pretty_print()
        print("\n")

回應會類似於下列輸出內容序列：

step 3: {'configurable': {'thread_id': 'human-in-the-loop-deepdive', 'checkpoint_ns': '', 'checkpoint_id': '1efa2e95-ded5-67e0-8003-2d34e04507f5'}}
================================== Ai Message ==================================

The exchange rate from US dollars to Swedish krona is 1 USD to 11.0159 SEK.

step 2: {'configurable': {'thread_id': 'human-in-the-loop-deepdive', 'checkpoint_ns': '', 'checkpoint_id': '1efa2e95-d189-6a77-8002-5dbe79e2ce58'}}
================================= Tool Message =================================
Name: get_exchange_rate

{"amount": 1.0, "base": "USD", "date": "2024-11-14", "rates": {"SEK": 11.0159}}

step 1: {'configurable': {'thread_id': 'human-in-the-loop-deepdive', 'checkpoint_ns': '', 'checkpoint_id': '1efa2e95-cc7f-6d68-8001-1f6b5e57c456'}}
================================== Ai Message ==================================
Tool Calls:
  get_exchange_rate (12610c50-4465-4296-b1f3-d751ec959fd5)
 Call ID: 12610c50-4465-4296-b1f3-d751ec959fd5
  Args:
    currency_from: USD
    currency_to: SEK

step 0: {'configurable': {'thread_id': 'human-in-the-loop-deepdive', 'checkpoint_ns': '', 'checkpoint_id': '1efa2e95-c2e4-6f3c-8000-477fd654cb53'}}
================================ Human Message =================================

What is the exchange rate from US dollars to Swedish currency?

取得步驟的設定

如要取得較早的檢查點，請指定 checkpoint_id (和 checkpoint_ns)。首先，請倒轉至步驟 1，也就是產生工具呼叫時：

snapshot_config = {}
for state_snapshot in agent.get_state_history(
    config={"configurable": {"thread_id": "human-in-the-loop-deepdive"}},
):
    if state_snapshot["metadata"]["step"] == 1:
        snapshot_config = state_snapshot["config"]
        break

print(snapshot_config)

輸出內容會與下列內容類似：

{'configurable': {'thread_id': 'human-in-the-loop-deepdive',
  'checkpoint_ns': '',
  'checkpoint_id': '1efa2e95-cc7f-6d68-8001-1f6b5e57c456'}}

時間回溯

如要取得檢查點，可以使用 .get_state 方法：

# By default, it gets the latest state [unless (checkpoint_ns, checkpoint_id) is specified]
state = agent.get_state(config={"configurable": {
    "thread_id": "human-in-the-loop-deepdive",
}})

print(f'step {state["metadata"]["step"]}: {state["config"]}')
state["values"]["messages"][-1].pretty_print()

根據預設，系統會取得最新的檢查點 (依時間戳記)。輸出內容應如下所示：

step 3: {'configurable': {'thread_id': 'human-in-the-loop-deepdive', 'checkpoint_ns': '', 'checkpoint_id': '1efa2e95-ded5-67e0-8003-2d34e04507f5'}}
================================== Ai Message ==================================

The exchange rate from US dollars to Swedish krona is 1 USD to 11.0159 SEK.

取得設定的檢查點

針對特定設定 (例如步驟設定中的 snapshot_config)，您可以取得對應的檢查點：

state = agent.get_state(config=snapshot_config)
print(f'step {state["metadata"]["step"]}: {state["config"]}')
state["values"]["messages"][-1].pretty_print()

輸出內容會與下列內容類似：

step 1: {'configurable': {'thread_id': 'human-in-the-loop-deepdive', 'checkpoint_ns': '', 'checkpoint_id': '1efa2e95-cc7f-6d68-8001-1f6b5e57c456'}}
================================== Ai Message ==================================
Tool Calls:
  get_exchange_rate (12610c50-4465-4296-b1f3-d751ec959fd5)
 Call ID: 12610c50-4465-4296-b1f3-d751ec959fd5
  Args:
    currency_from: USD
    currency_to: SEK

重播

如要從特定狀態重播，請將狀態設定 (即 state["config"]) 傳遞至代理程式。狀態設定是類似下列內容的字典：

{'configurable': {'thread_id': 'human-in-the-loop-deepdive',
  'checkpoint_ns': '',
  'checkpoint_id': '1efa2e95-cc7f-6d68-8001-1f6b5e57c456'}}

如要從 state["config"] (產生工具呼叫的位置) 重新播放，請在輸入內容中指定 None：

from langchain.load import load as langchain_load

for state_values in agent.stream_query(
    input=None, # resume
    stream_mode="values",
    config=state["config"],
):
    langchain_load(state_values["messages"][-1]).pretty_print()

結果會類似下列輸出序列：

================================== Ai Message ==================================
Tool Calls:
  get_exchange_rate (12610c50-4465-4296-b1f3-d751ec959fd5)
 Call ID: 12610c50-4465-4296-b1f3-d751ec959fd5
  Args:
    currency_from: USD
    currency_to: SEK

================================= Tool Message =================================
Name: get_exchange_rate

{"amount": 1.0, "base": "USD", "date": "2024-11-14", "rates": {"SEK": 11.0159}}

================================== Ai Message ==================================

The exchange rate from US dollars to Swedish krona is 1 USD to 11.0159 SEK.

分支

您可以使用 .update_state 方法，從先前的檢查點分支，嘗試其他情境：

branch_config = agent.update_state(
    config=state["config"],
    values={"messages": [last_message]}, # the update we want to make
)

print(branch_config)

輸出內容會與下列內容類似：

{'configurable': {'thread_id': 'human-in-the-loop-deepdive',
  'checkpoint_ns': '',
  'checkpoint_id': '1efa2e96-0560-62ce-8002-d1bb48a337bc'}}

注意： branch_config 的 checkpoint_id 與 state["config"] 不同，這是因為 .update_state

我們可以透過 branch_config 查詢代理程式，從更新狀態的檢查點繼續：

from langchain.load import load as langchain_load

for state_values in agent.stream_query(
    input=None, # resume
    stream_mode="values",
    config=branch_config,
):
    langchain_load(state_values["messages"][-1]).pretty_print()

結果會類似下列輸出序列：

================================== Ai Message ==================================
Tool Calls:
  get_exchange_rate (12610c50-4465-4296-b1f3-d751ec959fd5)
 Call ID: 12610c50-4465-4296-b1f3-d751ec959fd5
  Args:
    currency_date: 2024-09-01
    currency_from: USD
    currency_to: SEK

================================= Tool Message =================================
Name: get_exchange_rate

{"amount": 1.0, "base": "USD", "date": "2024-08-30", "rates": {"SEK": 10.2241}}

================================== Ai Message ==================================

The exchange rate from US dollars to Swedish krona on 2024-08-30 was 1 USD to 10.2241 SEK.

後續步驟

• 使用代理人。
• 評估代理程式。
• 管理已部署的代理程式。
• 取得支援。