📌 本文重點
- 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_callhook，可以實作策略： - 檢查這次操作是否符合對應使用者的權限與當前工作流狀態。
-
做「dry-run 模式」，先記錄 Agent 意圖，再決定是否允許真正執行。
-
在
after_tool_call/errorhook，集中紀錄這一步的輸入、輸出與錯誤，替後續審計與調查提供完整 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 呼叫
continueAPI
# 使用者在 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：
- 把每個
hooksevent 打進集中式 log（如 GCP Logging + BigQuery），至少紀錄：session_id、step_id、tool_name、意圖摘要、結果。 -
若使用 OpenTelemetry，可以在
hooks裡附上trace_id，方便跨服務串接。 -
A/B 模型替換：
- 不要直接在生產環境把
model換成新版本，先透過hooks做 shadow traffic：- 真正回應使用者仍用舊模型
- 同時讓新的 Agent/模型在背景計算建議，記錄差異
- 用
hooksevent 製作評估報表：比較錯誤率、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 處理決策層，並導出hookslog 進入你的 observability stack
