跳到內容
Imbrace SDK

Vibe coding on iMBrace：動手建置

這是課程的第 2 級：動手建置。前面的級別會示範一個完整運作的使用案例；這一頁則換你自己動手建置一個。

完成後，你會在自己的測試組織中，擁有一個能運作的小型退貨櫃台：兩張數據表、一條任何人都能編輯的退款規則、一個計算步驟，以及一位能在對話中受理退貨的助理。它刻意做得很小，因為重點不在這個櫃台本身，而在於四個習慣——這些習慣能讓你在 iMBrace 上建置的任何東西都值得信任，第 3 級（建置得好）會深入介紹。下一課讓它等一個人做決定會以這個櫃台為基礎，加上第五個習慣：在向顧客承諾任何事之前，先由一個人做決定。

你將建置的內容

想像一家虛構公司 Harbor Bicycle Co.，在網路上銷售並維修自行車。你要為它建置退貨櫃台。當顧客寫信要求退貨時，這個櫃台應該要：

  1. 把這筆申請記錄成「數據表」（board）上的一列，而不是留在聊天紀錄裡。
  2. 依照 Harbor 任何人都能編輯的規則算出退款金額，而不是靠模型自己做運算。
  3. 讓一位助理在對話中受理退貨：它會記錄這筆退貨，不說出任何退款金額，也不做任何承諾——因為還沒有人做出決定。

櫃台刻意停在這裡。Decision、Decided by 和 Decided at 三個欄位會保持空白：它們是讓它等一個人做決定在有人答覆電子郵件時填入的紀錄——絕不是靠在儲存格裡打字。

這裡的一切都不是 Harbor Bicycle Co. 的真實系統——這家公司並不存在。在把成果展示給任何人看之前，記得把公司、商品和規則換成你自己的內容。

你需要準備的東西

  • 一個測試組織和一組 API 金鑰。如果你還沒有，API 金鑰指南 說明了如何從儀表板產生金鑰。這裡請使用測試組織的金鑰——絕不要使用正式環境的金鑰。

  • 一個透過 MCP 連接到該組織的 AI 程式碼工具，讓它能直接看到你的數據表和工作流，而不是用猜的。這一頁不指定特定工具；任何能建立 MCP 連線、又能讀取文字檔的程式碼助理都適用。MCP 指南 有你所用工具的確切連線步驟——請先完成連線，再開始下面的步驟 1。如果你的安裝環境未啟用 MCP，設定你的程式碼工具 說明了改用 SDK 的做法。

  • 如果你的工具偏好直接寫 SDK 程式碼，而不是直接呼叫平台，請安裝你所用語言的 SDK：

    Terminal window
    npm install @imbrace/sdk
    Terminal window
    pip install imbrace

    不論哪一種方式，你的工具最後都需要兩個環境變數：IMBRACE_API_KEY 和 IMBRACE_ORGANIZATION_ID。把它們放在本機的 .env 檔案中，絕不提交到任何地方；如果可以只把變數名稱交給程式碼工具，就不要把實際金鑰貼進與它的對話裡。

  • 大約一小時。大部分時間花在閱讀平台回傳給你的內容——這正是這一整頁想培養的習慣。

這一頁會用到幾個詞：「數據表」是你自己定義的結構化表格——由列與具型別的欄組成，就像一份輕量版的 CRM 表。「工作流」（也稱為 flow）是一經觸發就會自動依序執行的一連串步驟。「原生步驟」是平台內建的現成步驟——不必自己寫、不必自己架設，也沒有自己的金鑰要管理。「代理人」則是使用者或頻道會與之對話的介面；產品在畫面上把代理人列在「AI智能助手」（AgentIQ）選單之下。

操作步驟

1. 動手之前先看一看

先別急著打開編輯器，讓你的程式碼工具先確認目前已經有哪些東西存在。

你輸入的內容大致如下：

在我們動手之前：這個組織裡目前已經有哪些數據表？另外，請在平台的原生工作流步驟目錄中，搜尋任何與寄送和讀取電子郵件相關的步驟。

你應該會看到：在全新的測試組織中，數據表清單是空的——這是正常現象，不是失敗。如果這個組織原本就已經有其他工作內容，這次檢查看到的會是其他既有的數據表——這也沒關係；等你在步驟 2 建立好自己的數據表之後，依名稱到那裡尋找它就好。不論是哪一種情況，你也都會看到一小份電子郵件相關原生步驟的清單，旁邊可能還會列出你沒問到的其他頻道。把這份清單讀過一遍。這是第一個習慣：在考慮自己動手寫之前，先找出平台已經內建的步驟。工具從零寫出來的步驟，會讓你多一組要保管的憑證、多一段要維護的程式碼；原生步驟則兩者都不用。這份清單上的電子郵件步驟，正是讓它等一個人做決定會用到的。

2. 建立用來存放退貨申請的數據表

你輸入的內容：

建立一個名為 Return Requests 的數據表，包含以下欄位：Customer name、Order reference、Item、Condition、Price、Refund amount、Decision、Decided by、Decided at。

你應該會看到：組織中出現一個新的數據表，有這九個欄位，但還沒有任何列。請到平台裡打開它，親眼確認欄位名稱與型別——不要只相信工具對自己做了什麼的摘要說明。最後三個欄位 Decision、Decided by 和 Decided at，是一個人的答覆所留下的紀錄：這一課不會填入它們，讓它等一個人做決定才會。

如果你的工具說它無法建立任何東西，代表它的 MCP 連線是唯讀的——這是預設值。請依照 MCP 頁面的說明加入寫入權限（在連線位址上加一個旗標），而且務必只在測試組織上這麼做。

3. 新增兩筆測試資料列

請使用合成資料。就算是在測試組織中，也絕不使用真實的顧客或訂單資訊。

你輸入的內容：

在 Return Requests 新增兩列資料，顧客姓名和訂單編號請用明顯是假的內容。第一列：一頂未拆封的安全帽，價格 45。第二列：一個用過的自行車鎖，價格 28。Refund amount、Decision、Decided by 和 Decided at 欄位先留空。

你應該會看到：兩列資料，Condition 分別是「unopened」和「used」，Price 已經填好，最後四個欄位是空的。

Return Requests 數據表已開啟，顯示欄位與兩筆資料列 1「知識模組」（Knowledge）>「數據表」（DataIQ）。2 Return Requests 數據表的欄位與資料列。

4. 把退款規則放在有人能修改的地方，而不是寫進一句話裡

這是第二個習慣，也是這一頁最重要的一個。直接在代理人的指示裡寫「未拆封全額退款，用過的退一半」會更快，但請不要這麼做。寫進代理人指示裡的規則，除非有人去編輯這個代理人，否則無法修改，也無法向顧客引述，事後更無法稽核。而以資料列形式存在的規則，這三件事都做得到。

你輸入的內容：

建立第二個數據表，名為 Refund Rules，包含兩個欄位：Condition 和 Refund percent。新增兩列資料：unopened、100；used、50。

你應該會看到：一個兩列兩欄的數據表。Harbor Bicycle Co. 的任何人都能打開它，把 50 改成 60，完全不必動到工作流或代理人。

Refund Rules 數據表，任何人都能編輯的兩筆規則 1「知識模組」（Knowledge）>「數據表」（DataIQ）。2 Refund Rules 數據表的兩筆資料列。

5. 建立工作流，把運算交給一個小步驟處理

你輸入的內容：

在 Return Requests 這個數據表上建立一個名為 Calculate refund amount 的工作流，只要有一列被新增或修改就會執行。它應該：讀取該列的 Condition，到 Refund Rules 上查出對應的那一列，用一個單純的計算步驟把 Price 乘上 Refund percent，再把結果寫進 Refund amount。數據表的讀取和寫入請使用原生步驟。只有乘法運算本身需要你自己寫一個步驟，而且要保持單純——它只接收兩個數字、回傳一個數字，不碰其他任何東西。這個步驟裡不能有網路呼叫，也不能有憑證。

你應該會看到：一個可以在平台自己的編輯器裡從頭讀到尾、完全不必打開任何程式碼的工作流。裡面大部分步驟都是原生步驟，只有一個是你的工具寫的簡短計算步驟，而且短到十秒內就能讀完。如果你的工具有提供測試執行選項，就手動執行一次，確認未拆封安全帽的 Refund amount 是 45，用過的自行車鎖是 14。

Calculate refund amount 工作流：讀取資料表、計算步驟與寫回資料表，從上到下 1「Find the matching…」查找 Refund Rules 上符合的資料列（原生步驟）。2「Calculate refund (…)」唯一一行手寫的計算步驟。3「Write Refund amo…」把結果寫回資料列（原生步驟）。

這是第三個習慣：模型很擅長判斷該套用哪一條規則，但不適合被信任在無人監督、每一次都要在壓力下默默算對乘法。把運算交給一個計算步驟去做。讓模型負責判斷，讓程式碼負責計算。

6. 建立代理人

代理人可以透過 SDK 的 AI Agent 方法建立（網站上有相關說明），也可以在平台的 AI智能助手畫面中建立，這個步驟會用到其中一種方式。不論哪一種，你的工具都可以幫你寫好代理人的指示。

你輸入的內容：

首先建立一個名為 Log return request 的工作流，讓代理人可以把它當成工具呼叫。這個工作流接收 Customer name、Order reference、Item、Condition 和 Price，在 Return Requests 上建立一列只包含這五個值的資料，不寫入其他任何內容。接著建立一個名為 Return Desk Assistant 的代理人，只給它這一個工具——而不是整個數據表本身。它的工作是：當顧客描述想退貨的商品時，用這個工具記錄下來，並回覆對方申請正在審核中。它絕不能說出退款金額，也絕不能做出任何承諾——因為人還沒有做出決定。

AI智能助手的代理清單，Return Desk Assistant 卡片 1「行動模組」（Actions）>「AI智能助手」（AgentIQ）。2 Return Desk Assistant 代理卡片。

為什麼給工具而不是給整個數據表：如果代理人拿到整個數據表的存取權，它就能寫入任何欄位，包括 Decision——等於能自己核准自己的申請。工具則只能寫入顧客提供的那五個欄位，所以決定權留在人的手上（下一課會建置一個人如何做決定）。這是第四個習慣：只給代理人一個範圍很窄的工具，對應它必須做的那一件事。

還有一點值得寫進代理人自己的指示裡：Refund Rules 是以精確比對的方式查找，所以要告訴代理人在填寫 Condition 時，使用規則本身的那兩個詞——「unopened」或「used」——絕不要用顧客自己的說法，也不要翻譯它。凡是工作流會以精確比對方式查找資料列的數據表，只要是由能理解自然語言的代理人負責寫入，都需要同樣的細心。

你應該會看到：對新建立的代理人說類似「我想退貨，訂單 HB-2044，一頂還沒拆封的安全帽。我叫 Morgan Ellery，訂單金額是 39」，就會在 Return Requests 上產生一列填好這些細節的資料，並得到類似「你的退貨申請已經記錄，正由團隊審核中」的回覆——沒有金額、沒有承諾。幾秒鐘之後，那一列的 Refund amount 會自動填入：未拆封安全帽是 39。目前還沒有人審核這筆申請；讓它等一個人做決定會加上負責審核的人。如果你的工具草擬的指示讓代理人自己猜一個退款數字，這裡就該抓出來：把指示退回去，要求把金額從代理人能說的內容裡拿掉。接著請它自己核准這筆申請：它應該做不到，因為它的工具裡沒有任何東西能寫入 Decision。

Return Desk Assistant 的回覆：已記錄並交由審核，沒有金額也沒有承諾 1「分析模組」（InsightsIQ）。2 AI智能助手的回覆沒有提到金額，也沒有任何承諾。

如何確認它真的可行

不要把程式碼工具對自己做了什麼的摘要說明當成證據。一段聽起來合理、描述建置成功的說法很容易寫出來，也很容易被誤認為真的成功——請親自去看。

  • 打開 Return Requests。兩列資料的 Refund amount 都應該正確：45 和 14。兩列的 Decision、Decided by 和 Decided at 都是空的。
  • 打開 Calculate refund amount 的執行紀錄，讀取每次執行的實際狀態，而不是摘要說明：每次執行都顯示為已完成。
  • 用一筆新編的退貨案例去跟 Return Desk Assistant 對話。確認出現了一列新資料，它的 Refund amount 幾秒鐘後會自動填入，而且代理人的回覆沒有任何金額、也沒有任何承諾。
  • 請這個助理核准一筆申請。確認 Decision 仍然是空的：代理人沒有辦法寫入這個欄位。

如果上面任何一項不成立，這其實比一個看起來沒問題、實際上卻不行的建置更有價值。修好失敗的那一項，然後再檢查一次。

接下來可以做的事

  • 接著進行讓它等一個人做決定，這是第二次實作。它從這個櫃台開始，讓它在向顧客承諾任何事之前，先以電子郵件詢問一個人。
  • 試著加入第二種 Condition——例如商品退回時少了包裝盒——並新增第二列規則。確認你不需要動到工作流或代理人，就能改變退款比例。
  • 閱讀第 3 級「建置得好」，了解這些習慣背後更完整的方法——它會說明是什麼讓像這樣的建置，在交給真實顧客而不只是測試組織時，依然禁得起考驗。
  • 關於 SDK、CLI 或 MCP 連線本身的任何內容，engineer.imbrace.co 是保持最新的權威來源——這一頁會比那裡更快過時。設定你的程式碼工具 有完整的設定說明。