Build Hour：Agents SDK（第 3/4 段）

🧑‍🏫 Agents SDK 是 OpenAI 提供給開發者的工具包，用來打造 agent，也就是能自己動手完成任務的 AI 助手。這段示範把 agent 的工作環境搬到雲端，並且加上自訂工具、人工核准、多個 agent 接力，以及直接讀取外部資料。看完就會知道，一個能真正上線的 agent 背後要處理哪幾件事。

• 23:52 Step three 改用 Modal：回傳一個 sandbox provider，重點是 Agents SDK 需要的 client 和 options，這裡提供的是 modal sandbox client
  ↳ 第三步把 agent 的工作環境換到 Modal（一個雲端運算平台）。sandbox 是讓 agent 隔離作業的小電腦，sandbox provider 是提供它的來源，只要交出 SDK 需要的 client 和設定就能用。
• 23:52 modal sandbox client 和 Docker 版本一樣，都繼承自 base sandbox client
  ↳ 不管用 Docker（在自己電腦上開隔離環境的工具）還是 Modal，底層都照同一套規格寫。所以換平台時，其他程式碼幾乎不用動。
• 25:05 Demo：把任務指派給 program editor agent 後，Modal 上會出現一個啟動中的 sandbox，通常幾秒內、大約一秒就能啟動
  ↳ 把任務派給負責編輯的 agent 後，Modal 後台馬上出現一台正在開機的 sandbox。開機很快，大約一秒，幾乎不用等。
• 25:05 背後是 Agents SDK 負責把我們定義的所有檔案套用到 sandbox 上
  ↳ 機器開好後，SDK 會自動把你事先設定好的檔案放進 sandbox，不用自己一個一個搬。
• 25:36 Manifest 的概念：描述 agent 啟動時檔案系統應該長什麼樣子，也是把檔案附加到任務、並在多個任務或 agent 之間共用的方式
  ↳ manifest 像 agent 上工前的「桌面配置清單」，寫明開機時有哪些資料夾和檔案。它也是把檔案附到任務上的方法，讓不同任務或 agent 共用同一批資料。
• 25:36 Manifest 是一個簡單的 class，它的 entries 是一棵樹，用來定義目錄結構。範例只建立基本目錄結構，再把檔案直接上傳到 sandbox
  ↳ 寫法很單純：用樹狀結構列出有哪些資料夾、裡面放什麼，entries 就是這些項目。範例只建了基本資料夾，再把檔案直接傳進去。
• 26:06 Manifest 也能接入其他來源：從 harness 執行的位置複製檔案、R2 bucket、S3 bucket、Azure blob store 帳號、GitHub repo 都可以
  ↳ 檔案不一定要手動上傳，可以從很多地方抓：程式執行的所在位置（字幕稱 harness）、R2、亞馬遜的 S3、Azure 雲端儲存，或 GitHub 程式庫。
• 26:06 agent 啟動時，SDK 會把檔案樹 render 給模型看，讓它了解自己的工作空間，不必一直 grep 或 ls。也可以替這些項目加上說明
  ↳ agent 開工時，SDK 會把整個資料夾結構直接列給模型看。模型不必一直下 grep（搜尋）或 ls（列目錄）指令去摸索。你也能替每個項目加上說明。
• 26:36 到 Cloudflare 帳號重新整理，可以看到 snapshot 已經存在雲端。若 app 部署在正式環境，要恢復任務時，agent 可以直接從 R2 拉回 context 和 snapshot
  ↳ 打開 Cloudflare 後台，就能看到存檔已經在雲端。正式上線後，任務中斷要接著做時，agent 能直接從 R2 拿回之前的背景資料（context）和進度。
• 27:06 把自己的 context 和功能帶進 agent 相當關鍵，所以接著幫 agent 加入自訂工具
  ↳ agent 能不能真的幫上忙，關鍵在它能不能碰到你自己系統裡的資料和功能。所以下一步是幫它加上專屬工具。
• 27:37 預先寫好三個工具：更新任務狀態、更新任務的 assignee、搜尋所有 assignee
  ↳ 講者先寫好三個跟任務管理有關的工具：改任務狀態、改負責人（assignee），以及查詢有哪些人可以指派。
• 27:37 Function tool 的用法和以前一樣，本質上就是 Python（或 TypeScript）函式，再加上 function tool decorator
  ↳ function tool 是讓模型能呼叫的工具。做法跟以前一樣：寫一個普通的 Python 或 TypeScript 函式，在上面加一行 decorator 標記就好。
• 28:07 Decorator 會把函式轉成 API 的 function tool 格式，並清楚定義參數，讓模型知道怎麼呼叫
  ↳ decorator 是加在函式上方的標記。它會把函式自動包裝成 API 看得懂的工具說明，寫清楚需要哪些參數，模型才知道怎麼正確使用。
• 28:07 SDK 收到 API 要求呼叫某個工具時，會自動導到對應函式、執行，再把結果回傳，不用自己實作 function calling 迴圈
  ↳ 模型說「我要用某個工具」時，SDK 會自動找到對應函式、執行它，再把結果交回模型。這段來回原本要自己寫程式處理，現在省掉了。
• 28:40 Demo：輸入「把這個任務指派給 Steve，並標記為 ready for review」
  ↳ 用一句日常的話下指令，一次要它做兩件事：換負責人、改狀態。重點是看 agent 會不會自己挑對工具來用。
• 28:40 Function tool 可以覆寫名稱，讓模型看到的名稱和函式本身的名稱不同
  ↳ 你可以另外取一個給模型看的工具名稱，跟程式裡的函式名稱分開。這樣能取一個模型比較容易理解的名字。
• 29:10 可以加 description 引導模型使用工具，也可以針對呼叫參數設 guardrails
  ↳ description 是寫給模型看的使用說明，告訴它什麼時候該用這個工具。guardrails 是護欄，限制模型呼叫工具時能帶哪些參數值，避免它亂填。
• 29:10 可以加 hooks 控制執行流程，也可以設定 timeout
  ↳ hooks 讓你在工具執行前後插入自己的處理步驟，用來控制流程。timeout 是時間上限，工具跑太久就停掉。
• 29:10 可以動態決定工具是否啟用（例如依 feature flag），不用手動註解來切換工具清單
  ↳ feature flag 是程式裡的開關。工具可以依開關自動決定這次要不要給模型用，不必每次手動把程式碼註解掉來增減工具。
• 29:40 Demo 結果：任務成功指派。這類工具適合把 app 的 context 或功能帶進 agent，例如讓它存取資料庫，或透過 MCP 使用 Slack
  ↳ 任務順利指派了。這類工具就是把你 app 的資料和功能接給 agent，例如查資料庫，或透過 MCP（讓 AI 連接外部服務的標準介面）使用 Slack。
• 30:14 Tool call approvals：有些工具需要 human in the loop 步驟，才能確定 agent 照指示做事、沒有失控
  ↳ tool call approval 是指某些工具要人同意才能執行。human in the loop 是在流程中留一個讓人確認的關卡，確保 agent 沒做出你沒要它做的事。
• 30:14 用過 Codex 的人應該很熟悉這種機制，它常會問「要不要執行這個 bash 指令」或「能不能連網」
  ↳ Codex（OpenAI 的寫程式 agent）常跳出來問「要執行這個指令嗎？」「可以連網嗎？」，這裡用的就是同一種機制。
• 30:14 在 Agents SDK 裡只要提供一個值即可：直接設 true，或提供依參數動態回傳 true/false 的函式
  ↳ 設定很簡單：設成 true，就是每次都要核准。或者寫一個小函式，依這次呼叫帶的參數內容，決定要不要先問你。
• 30:45 範例規則：要把狀態設為 done 就必須先經過本人核准，因為講者想在標記完成前先看一眼
  ↳ 範例的規則是：其他狀態可以自由改，但要標成「完成」就得先問講者，因為他想在結案前親自看一眼成果。
• 30:45 Demo：要求把任務標為 done 後，SDK 會啟動 sandbox、rehydrate 狀態、檢查目前狀態，再呼叫工具，接著跳出 tool call approval
  ↳ 要 agent 把任務標成完成後，SDK 會開機、rehydrate（還原上次存的狀態）、確認目前狀態，再呼叫工具。這時會跳出核准請求，等人決定。
• 31:16 Agent 之間可以 handoff。系統裡有兩個 agent：產出素材的 asset producer agent，以及 program editor agent
  ↳ handoff 是 agent 之間轉交工作。這裡有兩個角色：asset producer 負責產出素材，program editor 負責編輯內容，就像團隊分工。
• 31:16 內建的搜尋與更新 assignee 機制，讓多個 agent 能彼此協作
  ↳ 不用另做轉交機制。前面寫好的「查負責人、改負責人」工具，就能讓 agent 把任務改派給另一個 agent，彼此接力。
• 31:46 Demo：新增 issue 並放入檔案，指派給 program editor agent，指示它精修內容後改指派給 asset producer agent
  ↳ 開一張新工作單並附上檔案，交給編輯 agent，交代它「改完後轉給素材 agent」，測試兩個 agent 能不能自動接力。
• 32:20 Program editor agent 先接手處理，再把任務轉給 asset producer agent，由它產出素材並放回 sandbox
  ↳ 結果照計畫進行：編輯 agent 先做完自己的部分，再改派給素材 agent。素材 agent 產出素材後，放回同一個 sandbox 裡。
• 32:50 在 activity 頁面可以看到核准請求，按下核准後流程會繼續，任務最後被標為 done
  ↳ 最後在 activity（活動紀錄）頁面看到等待核准的請求。按下核准後，流程繼續跑完，任務變成完成。
• 32:50 最後示範：把外部 bucket 掛載（mount）到 manifest，以引入外部資料
  ↳ mount（掛載）是把外部儲存空間直接接到 sandbox 上，像插上外接硬碟，檔案留在原處不用複製。bucket 是雲端儲存裡裝檔案的容器。
• 33:20 原因一：檔案量很大（例如幾百份 PDF），每次啟動 sandbox 都要複製一遍很麻煩
  ↳ 第一個理由是檔案量大。如果有幾百份 PDF，每開一次 sandbox 就要整批複製一次，既慢又麻煩。
• 33:20 原因二：資料有很強的即時性需求，一直在變。從集中的 source of truth 掛載，比複製進去更好，因為複製的資料可能在 agent 開始工作前就過時了
  ↳ 第二個理由是資料常變。source of truth 是大家公認以它為準的那份資料。直接掛載才讀得到最新版，用複製的可能在 agent 開工前就過時了。
• 33:50 Agents SDK 原生支援掛載外部資料
  ↳ 這件事不用自己想辦法接，Agents SDK 本身就支援掛載外部資料。
• 33:50 範例的 R2 attachment store 會把上傳的檔案直接存到 R2，不再先放筆電再複製到容器。R2 成為應用層的 source of truth
  ↳ 範例改成讓使用者上傳的檔案直接存進 R2，不再先存在筆電、再複製進容器。R2 就成了整個 app 認定的那份正本。
• 34:21 使用 R2 attachment store 時會改用另一個 manifest，結構類似（task 加四個資料夾），但 input 不再是空目錄，而是 S3 mount 類型
  ↳ 這時改用另一份 manifest，資料夾結構差不多，一樣是任務加四個資料夾。差別在 input 資料夾不再是空的，而是掛載雲端儲存。
• 34:21 實際用的是 R2 bucket，卻選 S3 mount，因為 R2 和 S3 的 API 相容，所以兩者共用同一個物件
  ↳ 明明用的是 R2 卻選 S3 類型，是因為 R2 和亞馬遜 S3 的 API（程式之間溝通的介面）相容，所以用 S3 那套就能操作 R2。
• 34:52 參數包含 R2 bucket 名稱、access key、secret key，並使用 modal cloud bucket strategy
  ↳ 設定時要填 bucket 名稱、access key 和 secret key（類似帳號和密碼），並指定使用 Modal 的雲端 bucket 掛載方式。
• 34:52 許多 sandbox provider（包括 Modal）都有原生的外部 volume 掛載方式，這裡用的是 Modal 內建的
  ↳ 很多 sandbox 平台本身就有掛載外部儲存的功能，Modal 也有。這裡直接用 Modal 內建的方式，不另外處理。
• 34:52 若用 Docker 或一般容器，SDK 內建兩種現成方式（字幕中提到 fuse），兩者效果一樣好，哪個較適合要看你的系統
  ↳ 如果不用 Modal，改用 Docker 等一般容器，SDK 也備好兩種現成的掛載方式（字幕提到 fuse）。兩者效果一樣好，選哪個看你的系統。
• 35:23 Demo：再開一個新 issue，要求「再編輯一次這些素材」並附上檔案
  ↳ 再開一張新工作單並附上檔案，請 agent「再編輯一次這些素材」，示範改用掛載方式後的完整流程。

影片中實際用的是 R2 bucket，為什麼 manifest 裡選的是 S3 mount 類型？