作者: kerwin77106

📌 本文重點

• Managed Agents 提供內建任務分解與狀態管理
• hooks 讓治理、審計與風險控管更容易
• 透過 scope 與 proxy 控制 Agent blast radius

Gemini Managed Agents 解決的痛點很直接：你不必再自己拼一套 Agent orchestrator，卻仍然能拿到任務分解、長任務狀態管理、工具調用與可審計的事件流；同時把 blast radius、憑證外洩、錯誤恢復這些在 LangChain / 自建框架裡很容易踩到的雷收斂在一個可控的管理層裡。

重點說明

1. Managed Agents 的執行模型：從 session 到 hooks

以 Gemini API 的設計來看，一個 Managed Agent 核心會用到：

• Agent session + state 管理：官方幫你維護長任務的對話狀態、工具結果與任務進度，你只需要保存 session_id，不用自己設計 conversation store 或 workflow DAG。
• 任務分解與工具調用：你給一個高階任務描述（例如「關閉工單並同步到 Jira」），Agent 會自行拆解成子步驟並透過你註冊的 tools 呼叫外部系統。
• hooks 事件流：新版提供 hooks，在「工具呼叫前後」、「任務階段切換」、「錯誤發生」等時刻觸發事件，讓你可以做觀察、風險控管與自訂治理邏輯，而不必重寫整個 orchestrator。

💡 關鍵： Managed Agents 把你原本在 LangChain / 自建 orchestrator 中分散實作的 planner、tool router、memory 與 logging middleware，收斂成一層統一管理。

這整套等於把你平常在 LangChain / custom orchestrator 裡自己寫的：planner、tool router、memory、logging middleware，通通變成 Managed Agents 的內建能力。

2. 為什麼不再自己從零拼 Agent 架構？

自建 Agent 架構（LangChain 或自製 workflow engine）在 PoC 很爽，但一上生產通常會卡在幾件事：

• 長任務與錯誤恢復：
• 自建：要自己處理 multi-step 任務的 checkpoint、重試邏輯、worker crash 後如何恢復。常見結果是「任務一半死掉，使用者不知道發生什麼事」。

• Managed Agents：session/state、tool step 都在雲端管理，透過 hooks 你可以在每一步記錄 trace 或重試特定工具，不用自己實作 saga pattern。

• 審計與可觀測性：

• 自建：LLM prompt/response、tool 呼叫散在各 microservice，事後要還原「Agent 當時在想什麼」很困難。

• Managed Agents：事件流集中在 Agent 層，可以利用 hooks 把所有 decision log 打到你的 observability stack（如 BigQuery / Prometheus / OpenTelemetry）。

• blast radius 控制與憑證管理：

• 自建：如果把雲端 root token 或 GitHub PAT 直接塞進 tool config，一個「失控 Agent」就能亂改一堆東西（OpenAI rogue agent 事件就是警示）。
• Managed Agents：你註冊 tools 時就可限制作用域（只讀 / 特定資源）、憑證透過 secrets manager 管理，並用 hooks 做額外的風險檢查（例如禁止在非白名單 repo 寫入）。

💡 關鍵： Managed Agents 把長任務可靠性、審計與權限治理這些生產級問題，從應用程式層搬到共用的管理平面處理。

3. Hooks 對治理與風險控管的意義

近期業界對「Agentic Blast Radius」討論很熱：真正危險的不是單一錯誤，而是錯誤決策被當成正常狀態寫入企業系統，後面所有流程照規格運作，卻建立在錯誤前提上。

Managed Agents 的 hooks 剛好對應這問題：

• 在 before_tool_call hook，可以實作策略：
• 檢查這次操作是否符合對應使用者的權限與當前工作流狀態。

• 做「dry-run 模式」，先記錄 Agent 意圖，再決定是否允許真正執行。

• 在 after_tool_call / error hook，集中紀錄這一步的輸入、輸出與錯誤，替後續審計與調查提供完整 trace，而不是只看到最終 API error。

💡 關鍵： 透過 hooks，你可以在「執行前」與「錯誤當下」插入治理邏輯，而不是事後才從零碎 log 裡回推 Agent 發生了什麼事。

實作範例

以下用兩個場景：客服流程自動化與企業工單處理，用 Python SDK 為例（結構接近實際 Gemini Managed Agents API，細節以官方文件為準）。

範例一：客服流程自動化 Agent

目標：收到客戶訊息後，Agent 會：

• 分類問題
• 查詢內部知識庫
• 若需要人工介入則建立工單
• 把整個過程記錄在 hooks 中，方便審計

定義 Agent 與工具

from google.ai.generativelanguage import AgentsClient

client = AgentsClient()

# 定義外部工具：查詢 FAQ 與建立 Zendesk 工單
faq_tool = {
  "name": "search_faq",
  "description": "從內部 FAQ 知識庫搜尋答案",
  "openapi_spec": "https://internal.example.com/tools/faq-openapi.json",
}

zendesk_tool = {
  "name": "create_ticket",
  "description": "在 Zendesk 建立客服工單",
  "openapi_spec": "https://internal.example.com/tools/zendesk-openapi.json",
}

# 建立 Managed Agent
agent = client.create_agent({
  "display_name": "customer-support-agent",
  "model": "models/gemini-3.6-flash",  # **Flash** 用於快速互動場景
  "tools": [faq_tool, zendesk_tool],
  "task_spec": {
    "goal": "根據客戶訊息自動回覆或建立工單",
    "constraints": [
      "不得修改客戶資料",
      "建立工單前必須有明確分類與摘要",
    ],
  },
})

session = client.create_session({
  "agent": agent.name,
  "user_id": "user-123",  # 方便後續權限與審計
})

設定 hooks 實作觀察與風險控管

# 假設 hooks 以 callback URL 或 Pub/Sub topic 形式註冊
client.register_hooks({
  "agent": agent.name,
  "hooks": [
    {
      "event": "before_tool_call",
      "endpoint": "https://ops.example.com/hooks/before_tool",
    },
    {
      "event": "after_tool_call",
      "endpoint": "https://ops.example.com/hooks/after_tool",
    },
    {
      "event": "error",
      "endpoint": "https://ops.example.com/hooks/error",
    },
  ],
})

在 before_tool_call 的 handler，你可以檢查：

# 伺服器端 hook handler 示意

@app.post("/hooks/before_tool")
def before_tool_hook(event: dict):
    tool_name = event["tool_name"]
    user_id = event["session_user_id"]
    payload = event["arguments"]

    # 權限邊界：只有 VIP 客戶可以建立高優先級工單
    if tool_name == "create_ticket" and payload.get("priority") == "high":
        if not is_vip(user_id):
            return {"allow": False, "reason": "non_vip_high_priority_blocked"}

    # 規則通過，允許執行
    return {"allow": True}

這樣工具呼叫前就有一層明確的治理邏輯，而不是讓 Agent 任意決定。

長任務與重試

客服場景可能會遇到：外部 Zendesk API 短暫掛掉。Managed Agents 幫你 keep session，你只需要在 hooks 裡做重試策略：

@app.post("/hooks/error")
def error_hook(event: dict):
    if event["tool_name"] == "create_ticket" and is_retryable(event["error"]):
        # 觸發外部重試流程，或要求 Agent 改用 fallback 策略
        schedule_retry(event["session_id"], step_id=event["step_id"])

    log_to_observability_stack(event)
    return {"ack": True}

範例二：企業內部工單處理工作流

目標：IT 服務台 Agent：

• 接收使用者問題
• 查詢 CMDB / 知識庫
• 規劃解決步驟
• 在 Jira 更新工單狀態

這裡重點在權限邊界與憑證管理。

工具註冊與憑證管理

你不應該讓 Agent 直接拿到 Jira 的 admin token，而是用受限憑證 + 後端 proxy：

jira_tool = {
  "name": "update_jira_issue",
  "description": "更新 Jira 工單狀態與評論",
  "openapi_spec": "https://proxy.example.com/tools/jira-openapi.json",
  "auth": {
    "type": "service_account",  # **不要**用個人 PAT
    "scopes": ["jira:issue:write"],
    "role": "it-helpdesk-agent",  # 僅能操作特定 project
  },
}

agent = client.create_agent({
  "display_name": "it-ticket-agent",
  "model": "models/gemini-3.6-pro",  # 較複雜決策可用 pro
  "tools": [jira_tool],
  "task_spec": {
    "goal": "協助處理 IT 工單並維護 Jira 狀態",
    "constraints": [
      "不得刪除工單",
      "不得變更工單 reporter",
    ],
  },
})

後端 jira-openapi proxy 再做第二層防護：即使 Agent 誤用工具，也只能變更有限欄位。

處理長任務超時

工單處理有時會涉及人工確認，可能是跨多小時甚至多天的 session。Managed Agents 的好處是你可以：

• 把 session_id 存在工單系統欄位
• 每次使用者回覆時，用同一個 session 呼叫 continue API

# 使用者在 Jira 回覆時觸發

session_id = issue.fields.agent_session_id

response = client.continue_session({
  "session": session_id,
  "user_message": latest_comment,
})

# 若 session 已超時，可設計恢復策略，例如：
if response["status"] == "SESSION_EXPIRED":
    new_session = client.create_session({"agent": agent.name, "user_id": issue.reporter})
    # 把舊工單摘要作為新 session 的起始 context

你不需要自己處理 session token 過期與狀態重建邏輯，Agent 層會告訴你目前 session 狀態，再透過 hooks 或外部邏輯決定如何恢復。

建議與注意事項

1. 控 blast radius：先縮小可寫入面再放手給 Agent

• 在工具設計上，優先提供 read-only 工具，寫入工具要：
• 有明確 scope（特定 project/repo/表格）

• 綁定 service account，而不是廣泛的雲端管理員權限

• 搭配 hooks 實作：

• 白名單檢查（只能操作特定資源 ID 範圍）
• 寫入前的「二次確認模式」（例如需要人為核准才能執行某些寫操作）

2. 與既有工作流引擎的職責邊界

很多團隊已經有 Airflow / Temporal / Argo 做批處理或長流程編排，Managed Agents 不應該去取代它們，而是：

• 工作流引擎：負責確定性的步驟排程、重試、依賴關係管理。
• Managed Agents：負責「不確定性決策」：
• 推論要走哪種處理路徑
• 生成填寫資料或評論內容
• 以 hooks 形式把決策結果回傳給工作流引擎，再由後者執行關鍵性指令。

實務上可以讓 Airflow / Temporal 透過 Gemini API 啟動 Agent session，Agent 只負責決策與內容生成，真正的 API 呼叫仍由工作流引擎執行，降低 blast radius。

3. 可觀測性與 A/B 模型替換策略

• logging / trace：
• 把每個 hooks event 打進集中式 log（如 GCP Logging + BigQuery），至少紀錄：session_id、step_id、tool_name、意圖摘要、結果。

• 若使用 OpenTelemetry，可以在 hooks 裡附上 trace_id，方便跨服務串接。

• A/B 模型替換：

• 不要直接在生產環境把 model 換成新版本，先透過 hooks 做 shadow traffic：
  • 真正回應使用者仍用舊模型
  • 同時讓新的 Agent/模型在背景計算建議，記錄差異
• 用 hooks event 製作評估報表：比較錯誤率、tool 調用次數、平均成本，再決定是否切換正式模型。

4. 遷移既有 LangChain / 自建 Agent 的建議

• 先盤點現有架構中：
• 任務分解（planner）
• 工具 router
• 狀態存儲（conversation/memory store）

• logging / audit middleware

• 遷移策略：

• 優先把工具封裝成 Managed Agents 的 tools（API proxy + scope 控制）。
• 用 Gemini Managed Agents 取代 planner + router + state 部分，保留原本的資料存取與工作流引擎。
• 用 hooks 把事件打回你原有的 observability stack，避免多套 monitoring。

結論：如果你的專案已經開始碰到「長任務、錯誤恢復、權限治理、審計」這些生產級問題，Gemini Managed Agents + hooks 能讓你少維護一套自建 orchestrator，同時在 blast radius 控制與風險治理上有更明確的技術支點。

🚀 你現在可以做的事

• 盤點現有 LangChain / 自建 Agent 架構中的 planner、router、state 與 logging 元件
• 挑選一個實際場景，將現有工具封裝成 Managed Agents 的 tools 並接上 hooks
• 在現有工作流引擎（如 Airflow / Temporal）中試驗以 Managed Agents 處理決策層，並導出 hooks log 進入你的 observability stack