本文覆盤一次企業內部辦公助手 Agent 的落地實踐。

這個項目最開始要驗證的問題不是“Agent 能不能聊天”，而是：

當 Agent 開始接工具、調系統、執行業務操作時，怎麼保證它是受控的。

如果只是問答，問題相對簡單。模型答錯了，最多是信息不準。

但一旦 Agent 進入內部業務系統，問題就變成了另一類工程問題：

• 誰能調用這個能力；
• 當前用戶有沒有權限；
• 這個動作只是查詢，還是會改變業務狀態；
• 寫操作執行前是否需要二次確認；
• 執行結果如何回傳；
• 失敗後如何解釋；
• 操作過程能不能被審計和追溯。

所以辦公助手不是把後臺搬進聊天框，而是把分散後臺能力、熟手經驗、權限校驗、二次確認和業務 workflow 組織成一條可控執行鏈路。

整體目標可以概括為：

1. 問題背景：能力不缺，缺的是可複用的處理鏈路

很多內部系統的問題，並不是“沒有能力”。

實際情況往往相反：後臺、數據平臺、配置系統、運營工具已經有很多能力，只是入口分散、字段分散、路徑分散。

熟手處理問題很快，不一定是因為點得快，而是因為他知道：

• 去哪個後臺查；
• 用哪個入口；
• 參數怎麼整理；
• 查完以後下一步看什麼；
• 哪些動作需要謹慎確認；
• 哪些結果可以繼續聯想追問。

新手慢，也不一定是不努力。他只是還沒有建立這張隱形地圖。

所以辦公助手第一階段要解決的，不是“模型能不能理解一句中文”，而是：

能不能把原來靠人記住的後臺路徑和操作經驗，沉澱成 Agent 可以理解、可以調用、可以確認、可以審計的流程。

這也是內部 Agent 和普通聊天機器人的核心差異。

聊天機器人解決的是信息表達問題。

企業內部 Agent 解決的是業務執行問題。

2. 場景收斂：先驗證查詢、寫操作和生成後執行

第一階段我們沒有追求覆蓋所有後臺，而是先選了三類場景：

場景	驗證問題	關鍵風險
對象查詢	能否沿著同一個對象連續追問	上下文是否穩定
批量操作	寫操作能否先確認再執行	是否誤執行、漏確認
運營提醒	內容生成後能否進入發送和結果回傳	是否停留在“生成文案”

2.1 對象查詢：從“找入口”變成“圍繞對象連續追問”

對象查詢類需求看起來簡單，但真實操作裡經常不是查一次就結束。

用戶可能先查基礎信息，再查關聯關係，再查狀態，再繼續判斷下一步看什麼。過去這些步驟通常分散在不同後臺和入口裡。

接入辦公助手後，用戶可以圍繞同一個對象連續追問，Agent 負責把背後的查詢鏈路串起來。

這個場景驗證的是：Agent 不只是把一次查詢包裝成自然語言，而是能把“當前對象”作為上下文繼續向下走。

2.2 批量操作：寫操作必須進入二次確認

批量操作的對比更明顯。

傳統後臺裡，一次批量操作可能要填寫對象、操作項、有效期、開關、備註等字段。它看起來只是一次提交，但實際是一條完整操作鏈路：

• 對象整理；
• 參數填寫；
• 操作項確認；
• 生效範圍確認；
• 執行；
• 結果彙總。

Agent 加持後的變化不是“少點幾個按鈕”，而是把這條鏈路拆成了“模型整理 + 人確認 + 系統執行”。

用戶先用一句話描述目標，Agent 整理操作對象、操作內容和執行參數，進入二次確認。用戶確認後再執行，並返回結果彙總。

這裡的關鍵點是：

模型可以幫助整理操作意圖，但不能把“用戶想做什麼”直接等同於“用戶已經確認執行”。

所以寫操作必須顯式進入 confirmation。

2.3 生成後執行：不要停在“AI 寫文案”

第三類場景是運營提醒類文案輔助。

這個場景很容易被誤解成“讓 AI 寫一段文案”。但真正進入業務系統後，問題不是生成文案，而是生成之後怎麼辦。

原流程需要在後臺表單裡填寫分類、對象、標題、內容、提醒等級等字段。

Agent 加持後，用戶先讓辦公助手基於對象狀態生成提醒文案。用戶確認文案後，Agent 再進入發送前確認。確認後才執行發送。發送完成後，還可以繼續追問這個對象的其他信息。

這類場景驗證的是：Agent 不能停留在“生成內容”，而要能把生成、確認、執行和結果回傳串起來。

3. 架構拆分：理解、編排和執行不要混在一起

為了避免辦公助手變成一個失控的萬能入口，我們在架構上把“理解、編排、執行”拆開。

整體鏈路可以簡化成：

各層職責大致如下：

層級	職責
用戶入口	承接消息、用戶身份和會話入口
通用 Agent 平臺	理解意圖、維護會話、加載 Skill、決定是否調用工具
Skill / Workflow	組織業務知識、任務流程、工具描述和確認邏輯
CLI / Tool	承接可執行的原子能力或流程入口
Gateway	鑑權、協議適配、二次確認、審計和下游調用
業務系統	提供被授權、可約束、可追蹤的業務能力

這裡最重要的一點，是不要讓 Agent 直接面對所有內部系統。

Agent 擅長理解自然語言、組織上下文、判斷下一步動作，但它不應該繞過權限系統，不應該直接拼內部接口，也不應該對高風險操作擁有默認執行權。

4. Gateway：不是轉發層，而是受控執行層

Gateway 在這個設計裡不是簡單的 HTTP 轉發層。

它更像 Agent 和業務系統之間的受控執行層，需要回答幾個問題：

• 當前用戶有沒有權限使用這個能力；
• 當前動作是否需要二次確認；
• 下游系統協議是否需要適配；
• 結果如何被標準化返回給 Agent；
• 操作過程是否需要記錄審計日誌；
• 權限失敗、業務失敗、參數錯誤分別如何解釋。

一個簡化後的執行流程大概是：

1. Agent 根據 Skill 判斷需要調用某個 Tool。
2. Tool 請求進入 Gateway。
3. Gateway 根據身份信息做用戶識別。
4. Gateway 根據 permission_scope 做權限校驗。
5. 如果是隻讀操作，校驗通過後直接調用下游。
6. 如果是寫操作，先生成 preview 或 confirmation。
7. 用戶確認後，Gateway 再執行真實寫操作。
8. Gateway 將執行結果、失敗原因或確認狀態標準化返回給 Agent。

這層的價值在於：能力可以繼續擴展，但擴展不是無邊界的。

每新增一個能力，都要先被描述、授權、接入、確認和審計，而不是臨時把一個後臺接口塞給模型。

5. Skill：不是說明文檔，而是業務能力的組織方式

辦公助手裡另一個關鍵點是 Skill。

很多人第一次聽到 Skill，容易把它理解成“給模型看的說明文檔”。但在這個項目裡，Skill 更像業務能力的組織方式。

如果把所有能力寫進一份大文檔，模型會遇到兩個問題：

• 上下文膨脹，能力越多，命中越不穩定；
• 業務邊界模糊，查詢、寫操作、流程任務混在一起，後續維護困難。

所以辦公助手沒有簡單按後臺系統拆能力，而是儘量按用戶問題和業務對象拆。

可以簡單理解成幾層：

• 根 Skill 做總分診，先判斷用戶問題的大方向；
• 領域文檔判斷具體業務域，縮小上下文範圍；
• Tool 承接單個原子能力；
• Workflow 承接多步任務閉環；
• 寫操作再走 confirmation。

5.1 根 Skill 先做路由，不要塞滿所有工具

根 Skill 不負責塞滿所有工具，而是先做路由，讓模型按任務選擇當前需要加載的領域能力。

一個簡化示意如下：

## Loading Order

1. Read this root file to understand runtime rules and domain routing.
2. Pick one domain according to the user's intent:
   - domains/object/DOMAIN.md: object query and related status.
   - domains/ops/DOMAIN.md: confirmation-based write operations.
   - domains/message/DOMAIN.md: message generation and sending flow.
3. Read the domain's referenced tools/*.yaml file.
4. If the matched tool has `requires_confirmation: true`,
   read common/confirmation.md.
5. If the gateway returns an auth error,
   read common/auth-errors.md.

這樣做的好處是，模型每次只讀當前任務需要的那條路徑，其他領域的 Tool 不進入上下文。

5.2 只讀 Tool：描述清楚輸入輸出和權限範圍

對於只讀查詢類能力，Tool 更像一個清晰的原子能力說明。

tools:
  - name: query_object_profile
    description: Query object profile through the gateway.
    permission_scope: object.profile.read
    gateway_route: object.profile.query
    requires_confirmation: false
    request:
      type: object
      required: [object_id]
      properties:
        object_id:
          type: string
          description: Business object id.
    response:
      data:
        type: object
        properties:
          object_id:
            type: string
          display_name:
            type: string
          status:
            type: string

這裡要明確幾件事：

• Tool 的職責要足夠窄；
• request / response 要結構化；
• permission_scope 要明確；
• 只讀操作不需要 confirmation；
• 返回結果要方便 Agent 繼續組織回答或進入下一步。

5.3 寫 Tool：必須顯式標記 confirmation

寫操作則必須顯式標記需要確認。

這個字段很小，但它決定了 Agent 能不能從“會調工具”走向“受控執行”。

tools:
  - name: execute_controlled_action
    description: Execute a controlled action after human confirmation.
    permission_scope: object.action.write
    gateway_route: object.action.execute
    requires_confirmation: true
    request:
      type: object
      required: [object_ids, action_type, params]
      properties:
        object_ids:
          type: array
          items:
            type: string
          description: Business object ids.
        action_type:
          type: string
          description: Controlled action type.
        params:
          type: object
          description: Action parameters.

讀寫 Tool 的差別，表面上只是 requires_confirmation 這個字段。

但工程上的意義很大：它把“模型決定做什麼”和“人確認是否執行”拆開了，也讓 Gateway 可以統一處理確認、審計和結果回傳。

5.4 confirmation 流程本身也要被寫清楚

確認流程不能只靠約定。

否則模型很容易跳過關鍵步驟，直接把“用戶想做什麼”誤當成“用戶已經確認執行”。

1. Call execute with --requires-confirmation.
2. Show the returned preview to the human operator.
3. If approved, call confirm with the returned confirm_id.
4. Return execution result and summary to the user.

這也是企業內部 Agent 和普通工具調用 Demo 的區別：Demo 裡調通接口就結束了，真實業務裡要考慮權限、確認、失敗、審計和追溯。

6. Tool 解決單步動作，Workflow 才解決一件事

辦公助手落地過程中，一個很重要的判斷是：Tool 和 Workflow 不能混在一起。

Tool 解決的是“能不能做一個動作”。

比如查一個對象、取一個狀態、生成一段內容、觸發一次通知。

但真實業務裡，用戶要的往往不是一個動作，而是“把這件事處理完”。

這就需要 Workflow。

類型	解決什麼	示例
Tool	一個原子動作	查詢對象、獲取狀態、生成內容、觸發通知
Workflow	一個多步任務閉環	批量操作、提醒發送、問題排查、上傳後校驗

以批量操作為例，它不是一個 execute 就能解釋清楚的動作。

一個相對完整的流程可能是：

parse intent
  -> resolve objects
  -> handle ambiguity
  -> build action preview
  -> ask human confirmation
  -> execute
  -> return summary

如果沒有 Workflow，Agent 很容易變成“會調很多工具，但不會把事做完”。

這也是很多內部 AI 助手容易卡住的地方：單點能力看起來很多，真正處理問題時卻斷在中間。

辦公助手要補的，就是這條中間鏈路。

7. 哪些場景不適合第一階段接入 Agent

企業內部 Agent 很容易陷入一個誘惑：

既然能接工具，那是不是應該把所有接口都接進去？

我們的判斷是，不應該。

至少在第一階段，不應該。

不適合直接接入的場景包括：

場景	原因
強交互場景	過程依賴大量用戶即時反饋，不適合封裝成一次工具調用
長事務場景	需要完整狀態管理和恢復機制
複雜狀態機場景	狀態轉換必須由業務系統提供嚴格約束
重業務上下文授權場景	單靠通用 Gateway 難以表達完整授權語義
高風險不可逆寫操作	一旦誤執行，影響真實業務流程

原因不是技術做不到，而是風險收益比不合適。

普通問答答錯了，最多是信息不準；執行動作出錯，就可能影響真實業務流程。

所以更穩妥的路線是：

先接高頻、常用、可閉環、風險可控的場景，讓 Agent 穩定完成真實任務，再逐步擴大邊界。

8. 可複用清單：內部 Agent 接業務系統前先問這些問題

這次實踐沉澱下來，至少有一組檢查項可以複用。

8.1 能力接入前

• 這個能力是查詢還是寫操作；
• 是否高頻、常用、可閉環；
• 是否需要二次確認；
• 是否已有明確權限模型；
• 是否能提供結構化輸入輸出；
• 是否有可解釋的失敗原因；
• 是否能記錄審計日誌。

8.2 Skill 設計時

• 是否按用戶問題或業務對象拆分，而不是簡單按後臺系統堆工具；
• 根 Skill 是否只做路由；
• 領域 Skill 是否控制上下文範圍；
• Tool 是否足夠原子；
• Workflow 是否描述完整任務閉環；
• 寫操作是否顯式聲明 requires_confirmation；
• 權限失敗、參數缺失、下游失敗是否有獨立處理路徑。

8.3 Gateway 設計時

• 身份信息從哪裡來；
• 權限校驗在哪一層做；
• permission_scope 如何和業務權限模型映射；
• 寫操作 preview 如何生成；
• confirm_id 如何管理；
• 執行結果如何標準化；
• 審計信息記錄哪些字段；
• 下游協議差異在哪裡適配。

總結

辦公助手這個項目驗證的不是“又做了一個 AI 應用”。

它更像是自研 Agent 平臺進入真實業務系統的第一站。

這次實踐給我們的判斷是：

企業內部 Agent 的價值，不在於讓模型擁有更多後臺能力，而在於把後臺能力組織成更穩定、更安全、更可複用的業務流程。

Agent 從聊天走向執行，中間隔著的不是一句 prompt。

而是一整套工程機制：Skill 分層、Tool 描述、Workflow 編排、Gateway 鑑權、二次確認、審計記錄和邊界控制。

如果只把後臺接口塞給模型，能力越多，風險越大。

如果把能力放進受控流程裡，Agent 才有機會從“能回答”走向“能辦事”。

花椒技術交流群

還在孤軍研究 AI 工程化、AI 編程、Agent 落地，沒人同行交流、沒人拆解實戰？

這裡匯聚一線技術從業者，專注代碼評審、企業內部 AI 助手真實實戰落地。

想緊跟 AI 前沿動態、交流工程落地經驗、少走踩坑彎路，歡迎直接加入「花椒技術交流群」。

群內專屬福利拉滿：每日精選研發向 AI 行業日報、文章獨家延伸資料、文中未展開的技術細節，全部同步共享。

如果群過期關注公眾號 花椒技術，私信回覆「交流群」獲取最新入群二維碼。