標籤: Gemini API

  • 用 Gemini Managed Agents 落地可控生產級 Agent

    用 Gemini Managed Agents 落地可控生產級 Agent

    📌 本文重點

    • 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_idstep_idtool_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
  • 用 Gemini Managed Agents 搭建可控多代理系統

    用 Gemini Managed Agents 搭建可控多代理系統

    📌 本文重點

    • Managed Agents 讓多代理 workflow 更可控可審計
    • 背景任務與長流程能安全持續運行
    • remote MCP + 沙盒工具提升協作與安全
    • 憑證輪替支援零信任長連線場景

    Gemini Managed Agents 的最新更新,直接解決了多代理系統在實務上的四個痛點:長流程容易中斷、背景任務難管理、多代理協作缺乏控制平面、工具執行缺乏安全邊界、長連線憑證管理容易出事。如果你目前只是在做「單模型聊天 + 幾個工具」,這批能力讓你可以往「有審計、有重試、有觀測性」的多代理 workflow 進化,而且不需要自己再搭一層任務編排框架。


    重點說明

    1. 背景任務與長流程編排:從同步聊天到任務隊列

    新的 Managed Agents 支援在代理內啟動 背景任務(background tasks),並維持任務狀態。

    關鍵好處:

    • 可以把耗時操作(例如 ETL、長時間 API 輪詢、批次報表)移到背景,不阻塞前端對話。
    • 每個背景任務都有 狀態與 ID,便於你實作自家任務隊列、重試策略與恢復機制。
    • 代理本身幫你維護「對話上下文 + 任務上下文」,你只需在外層規劃任務生命週期。

    💡 關鍵: 把長流程變成有狀態、可重試的背景任務,是從「聊天玩具」升級成「可靠工作流系統」的關鍵一步。

    典型設計:

    • 前端對話 → 由主 Agent 判斷是否需要啟動背景任務。
    • 使用 Agents API 建立 task,狀態儲存在 Managed Agents 內部或你自己的 DB
    • 外部有一個「任務監控 worker」定期查詢任務狀態、做重試或告警。

    2. remote MCP / 多代理協作:控制平面 vs 應用層 SDK

    Managed Agents 現在可以直接連到 remote MCP。實務上有兩種典型 architecture:

    • 控制平面導向(Control Plane first)
    • 多個工具 / 子代理掛在 MCP server(例如一個 operations MCP、一個 data MCP)。
    • Managed Agent 只要知道 MCP endpoint,就能呼叫裡面的工具。
    • 適合大型企業,把權限、審計、資源配額集中放在 MCP 層。

    • 應用層 SDK 導向(SDK first)

    • 你在應用程式碼中透過 SDK 把工具包成 Gemini Tool / Functions,再掛到 Managed Agents。
    • 權限管理偏向 app side,例如每個 tenant 對應一組工具設定。

    關鍵差異在 權限與隔離

    • 控制平面模式:透過 MCP 做 RBAC、租戶隔離、審計;Managed Agent 像「智慧前端」。
    • SDK 模式:更靈活,適合快速迭代,但要自己補一套完整審計與 resource control

    3. 安全沙盒內整合自定義工具與函式

    更新後的 Managed Agents 允許在 安全沙盒(sandbox) 同時使用:

    • 官方 sandbox 工具(如瀏覽器、code executor)。
    • 你自定義的 functions / tools

    好處:

    • 你可以在受控環境內執行「可能有副作用」的操作,例如 DB query、檔案處理,而不直接暴露到外部系統。
    • 工具執行與 LLM 推理同樣有 超時與資源配額 控制,避免單一任務吃光整個 pod

    設計重點:

    • 每個工具要有明確的 作用範圍(只讀 / 可寫),把「刪除、修改」操作拆成獨立工具並 預設關閉
    • 在工具層做 輸入驗證與錯誤處理,避免 LLM 亂塞參數導致意外副作用。

    4. 憑證刷新與長連線安全:token 旋轉 + 零信任

    Managed Agents 支援在 不丟失 state 的情況下刷新憑證

    • 代理可以維持長流程(幾小時到幾天)的狀態,同時你的服務端可以定期輪替 API tokenOIDC access token
    • 這讓零信任架構更好落地:
    • 不再有「因為流程長,只好給超長效 token」的妥協。
    • 可以要求所有外部呼叫都透過短效憑證 + 中央驗證服務。

    💡 關鍵: 「長流程 + 短效憑證」的組合,讓零信任不再與實務需求衝突。


    實作範例

    以下用一個從「單模型聊天」升級成「有背景任務 + 多代理協作 + 審計」的簡化範例示意(以 Node.js 伺服器 + Gemini API 為例,為示意用虛擬碼)。

    1. 建立核心 Managed Agent

    import { AgentsClient } from "@google-ai/gemini";
    
    const agents = new AgentsClient({
      projectId: process.env.GCP_PROJECT_ID,
      location: "global",
    });
    
    // 建立主 Agent:負責對話 + 任務編排
    async function createMainAgent() {
      const [agent] = await agents.createAgent({
        parent: "projects/xxx/locations/global",
        agent: {
          displayName: "orchestrator-agent",
          model: "gemini-2.0-pro",
          // 掛上 MCP 與工具
          tools: [
            { mcpServer: { endpoint: process.env.MCP_OPS_URL } },
            { mcpServer: { endpoint: process.env.MCP_DATA_URL } },
            { functionDeclarations: [
              {
                name: "schedule_background_job",
                description: "Create a background task for long-running workflow",
                parameters: {
                  type: "object",
                  properties: {
                    jobType: { type: "string" },
                    payload: { type: "object" },
                  },
                  required: ["jobType", "payload"],
                },
              },
            ]},
          ],
          // 安全設定:限制可寫操作
          safetySettings: {
            allowWriteOps: false,
          },
        },
      });
    
      return agent.name; // 用來後續呼叫
    }
    

    重點:

    • AgentsClient.createAgent 建立主 Agent,掛上多個 MCP 伺服器 與自定義 function
    • safetySettings 示意限制寫入操作,實務上可自訂更細。

    2. 前端對話:從「單次聊天」變成可啟動背景任務

    // 使用者傳入訊息,主 Agent 可能決定啟動背景任務
    async function handleUserMessage(agentName: string, sessionId: string, text: string) {
      const [response] = await agents.generateMessage({
        name: agentName,
        // sessionId 用你自己的,方便日後審計與追蹤
        session: { id: sessionId },
        prompt: { text },
      });
    
      // 若 LLM 觸發工具呼叫,可能是 schedule_background_job
      if (response.toolCall) {
        const call = response.toolCall;
        if (call.name === "schedule_background_job") {
          const taskId = await createBackgroundTask(call.args);
          // 把 taskId 回寫到對話,讓使用者可以查詢
          return { reply: `已建立背景任務,ID: ${taskId}` };
        }
      }
    
      return { reply: response.outputText };
    }
    

    這裡用 generateMessage(或官方實際命名類似方法)示意:

    • 你自己維護 sessionId,不要依賴傳輸層的 session 概念,以免遇到像 MCP 無狀態 變更就斷鏈。
    • 工具呼叫觸發後,交給應用層建立背景任務。

    3. 背景任務隊列與重試設計

    // 簡化版任務建立
    async function createBackgroundTask({ jobType, payload }) {
      const taskId = crypto.randomUUID();
    
      await db.tasks.insert({
        id: taskId,
        type: jobType,
        payload,
        status: "pending",
        retryCount: 0,
      });
    
      return taskId;
    }
    
    // 任務 worker:定期跑
    async function taskWorkerLoop() {
      const tasks = await db.tasks.find({
        status: { $in: ["pending", "retry"] },
      }).limit(50);
    
      for (const task of tasks) {
        try {
          await runTask(task); // 實際呼叫 MCP 或其他工具
          await db.tasks.update(task.id, { status: "done" });
        } catch (err) {
          const nextRetry = task.retryCount + 1;
          if (nextRetry > 3) {
            await db.tasks.update(task.id, { status: "failed" });
          } else {
            await db.tasks.update(task.id, {
              status: "retry",
              retryCount: nextRetry,
            });
          }
        }
      }
    }
    

    重點:

    • 背景任務管理放在你的應用層,但任務內容可以是對 Managed Agents / MCP 工具 的呼叫。
    • 任務狀態與重試策略明確放在 DB,避免「背景任務孤兒進程」沒人管。

    4. 憑證刷新與零信任示意

    // 透過中介層取得短效 token,供 AgentsClient 使用
    async function getAgentsClient() {
      const token = await authService.getRotatingToken(); // 有效期 15 分鐘
      return new AgentsClient({
        authToken: token,
        projectId: process.env.GCP_PROJECT_ID,
      });
    }
    
    // 每次呼叫都用最新 token
    async function safeGenerateMessage(agentName, sessionId, text) {
      const client = await getAgentsClient();
      const [response] = await client.generateMessage({
        name: agentName,
        session: { id: sessionId },
        prompt: { text },
      });
      return response;
    }
    

    這種做法搭配 Managed Agents 的「不丟 state 憑證刷新」能力,可以在維持長流程的同時,讓底層 token 持續輪替。


    建議與注意事項

    1. 防止 Agent 自動刪庫型事故

    • 所有「修改 / 刪除」類工具:
    • 預設不掛到主 Agent,改掛到專門的「ops Agent」,再用人工或嚴格策略觸發。
    • 在工具層做 白名單 / 黑名單 檢查,例如禁止 DROP TABLE、限制影響範圍。
    • 所有高風險操作應要求:
    • 二次確認(LLM 生成計畫 → 使用者或守門服務審核 → 才執行)。

    2. 審計與回溯:不要把責任丟給 MCP

    MCP 轉為 stateless 之後,如果你沒自己建立 trace id,就會遇到:

    • 同一條資金轉帳流程,log 看起來是四個不相干的事件,無法證明「誰觸發了什麼」。

    建議:

    • 在應用層產生 correlationId / traceId,寫入:
    • 所有 Agents API 呼叫
    • MCP 請求的 metadata
    • DB 任務表與 log 系統
    • 在出事時可以把「對話 → Agent 決策 → MCP 工具呼叫 → DB 操作」串回一條 timeline

    3. 背景任務治理:避免孤兒進程與資源爆炸

    • 每個任務必須有:
    • 明確 statuspending / running / retry / failed / done)。
    • 最大重試次數與 退避策略exponential backoff)。
    • 超時與最大執行時間限制。
    • 週期性 job 清理:
    • 清掉超過 SLApending 任務,標記為 timeout_failed
    • 對高失敗率任務發告警,不要無限重試打爆外部 API

    4. 多代理協作架構選型

    • 團隊偏「平台 / SRE」:建議 控制平面模式,用 MCP 集中治理,Managed Agents 做業務邏輯。
    • 團隊偏「產品 /快速迭代」:先用 SDK 模式,在 app 層掛工具,後續再逐步抽到 MCP。

    5. Observability:為多代理 workflow 補上眼睛

    • 最低限度:
    • 每次 Agent 呼叫記錄:agentNamesessionIdtraceId、使用工具列表、執行結果。
    • 建議導入:
    • 分散追蹤(如 OpenTelemetry),把 Agents / MCP / DB 統一進 tracing system。
    • 守門 dashboard:顯示背景任務隊列狀態、失敗率、平均耗時。

    結論:Gemini Managed Agents 的背景任務、remote MCP、安全沙盒工具與憑證刷新能力,讓你可以在現有專案裡自然從「單模型聊天」過渡到「可控、可審計的多代理 workflow」。核心心法是:把任務編排與審計留在應用層,讓 Managed Agents 專心做協作與自動化,並以零信任與資源治理觀點設計整體架構。

    🚀 你現在可以做的事

    • 在現有聊天應用中加入 sessionIdtraceId 與簡單任務表,開始嘗試背景任務編排
    • 盤點現有工具,決定哪些適合掛在 MCP、哪些用 SDK 模式直接掛到 Managed Agents
    • 規劃短效 token 取得流程,實作一個中介層 authService.getRotatingToken() 來配合 Managed Agents 使用