打造有界限的 LangGraph Agent，診斷 API 事件

決策：自動診斷，審慎修復

API 事件 Agent 可以透過蒐集記錄、健康檢查和近期部署中繼資料，節省調查時間。但它不應在未告知的情況下重新啟動服務、回復版本或變更設定。較安全的設計會將唯讀診斷與會產生副作用的修復操作分開、限制 Agent 的工作範圍，並讓操作人員看見失敗或缺漏的證據。

這是實務設計範例，不代表已測試的整合，也不是可直接用於正式環境的服務。以下工具本體僅供說明；請改用你自己的觀測系統用戶端，並設定驗證與最低必要權限。

先備條件與工作流程

你需要 Python、已在應用程式中設定且相容於 LangGraph 的聊天模型，以及現有診斷系統的用戶端函式。本範例假設這些用戶端函式會回傳資料或引發例外，不假設特定模型供應商、端點或工具整合方式。

實用的事件處理流程應採用受限迴圈：

1. 為受影響的服務與時間範圍，蒐集少量且預先定義的訊號。
2. 將每項結果標示為成功、失敗或無法取得。
3. 請模型摘要證據，並指出仍有哪些未知事項。
4. 在達到圖步驟上限後停止；任何會變更狀態的操作，都應先交由人工審核。

狀態欄位的用途在於維持營運上的清晰度：記錄查詢失敗，不應看起來像是成功搜尋但沒有符合條件的事件。

明確標示失敗狀態的診斷工具

工具契約應保持精簡。要求提供服務名稱與有限的時間範圍；若固定查詢已足夠，就不要讓模型任意查詢。回傳結構化結果，讓下游節點和事件報告能區分「沒有證據」與「工具失敗」。

from typing import Literal, TypedDict
from langchain.tools import tool

class Signal(TypedDict):
    status: Literal["ok", "error", "unavailable"]
    source: str
    data: str
    error: str | None


def query_logs(service: str, minutes: int) -> Signal:
    if not 1 <= minutes <= 60:
        return {
            "status": "error", "source": "logs", "data": "",
            "error": "minutes must be between 1 and 60",
        }
    try:
        # Replace with a read-only, scoped observability client call.
        rows = logs_client.search(service=service, minutes=minutes)
        return {
            "status": "ok", "source": "logs",
            "data": str(rows), "error": None,
        }
    except TimeoutError as exc:
        return {
            "status": "unavailable", "source": "logs", "data": "",
            "error": f"timeout: {exc}",
        }

@tool
def inspect_api(service: str, minutes: int = 15) -> dict:
    """Collect scoped, read-only API incident signals."""
    return query_logs(service, minutes)

如需健康檢查或部署中繼資料，請新增獨立工具並沿用相同的結果格式。不要攔截所有例外後只回傳空字串：應保留足夠的錯誤脈絡，以便診斷整合問題，同時避免在記錄或模型脈絡中暴露密鑰或敏感負載。

限制執行範圍，揭露未完成的執行

如果使用 LangGraph 的 create_agent 建立 Agent，請在呼叫時設定圖的遞迴上限。此上限限制圖步驟數量，但不保證能得到有用的答案，也不能取代工具層級的逾時設定。請在外層應用程式處理達到上限的情況，並清楚標示執行狀態為「未完成」，而不是將其視為已完成的診斷。

from langchain.agents import create_agent

agent = create_agent(
    model=your_configured_chat_model,
    tools=[inspect_api],
    system_prompt=(
        "Diagnose API incidents using available evidence. "
        "Report each source as ok, error, or unavailable. "
        "Do not claim a cause without supporting evidence. "
        "Do not perform remediation."
    ),
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content":
            "Investigate elevated errors for payments-api over the last 15 minutes."}]},
        config={"recursion_limit": 12},
    )
except Exception as exc:
    # Map known graph-limit and provider/tool failures to your app's
    # incident-run status; do not expose credentials or raw secrets.
    result = {"status": "incomplete", "reason": type(exc).__name__}

此上限值僅為範例，並非通用建議。請依允許使用的工具數量與模型回合數選擇適當值，並在工具層和應用程式層加入逾時與請求大小限制。記錄執行 ID、選定的服務與時間範圍、嘗試過的工具、工具狀態及終止原因。操作人員便能分辨「沒有發現錯誤」與「記錄後端逾時」。

在修復前加入人工審核

如果之後新增會改變正式環境狀態的工具，請使用 LangChain 的人在迴路中介軟體與 checkpointer，為這些工具加上審核關卡。文件所述的中介軟體可以暫停符合條件的工具呼叫，等待核准、編輯、拒絕或直接回覆。其狀態會先保存，待決策後即可恢復執行；正式環境應使用持久化 checkpointer，而非以下原型示範中的記憶體選項。請參閱 LangChain 人在迴路文件。

實務上的政策可以是：唯讀診斷不需中斷，而重新啟動、回復版本或變更設定的工具則必須取得核准。拒絕提議的操作時，應選擇拒絕；文件提醒，「respond」是代表工具採取行動，不是拒絕會產生副作用的呼叫。請在自己的工具實作中驗證編輯後的引數：文件指出，中介軟體不會依照畫面顯示的 schema 驗證編輯內容。

設計時應考量的失敗情況

• 結果為空： 回報「沒有收到符合條件的事件」，而不是「服務正常」。
• 工具逾時或授權失敗： 保留失敗來源與錯誤類別；不要無限期地悄悄重試。
• 重複呼叫工具： 限制圖的執行範圍並約束工具輸入。若加入重試，應設定明確且次數偏少的重試政策，並呈現嘗試次數。
• 中斷後無法恢復： 確認已設定 checkpointer，並在恢復時使用相同的 thread identifier。來源文件指出，人工審核需要 checkpointing。
• 容易誤導的最終摘要： 要求報告中的主張引用已蒐集的訊號，並列出無法取得的來源與尚未解決的問題。

事件執行檢查清單

部署前，請確認診斷工具為唯讀且範圍受限；時間範圍與查詢量受到限制；工具錯誤仍可被觀察；圖的執行設有上限；每項會產生副作用的操作都會暫停並等待人工決策。請測試逾時、空結果、拒絕操作和中斷後恢復等流程。優質的 Agent 不只是提出看似合理的根本原因，也會顯示實際取得了哪些證據，以及診斷範圍止於何處。

資料來源

• LangChain：人在迴路中介軟體 — 中斷後的決策、依條件審核工具、checkpointing，以及恢復暫停的執行。