網誌
代理原生後端

發佈日期 更新日期

Arag 及 Shouryamaan

如何建立 AI 程式開發代理可以自行操作的後端

以 Markdown 閱讀

當程式開發代理能夠透過結構化合約建立、檢查、使用、復原、移交和移除後端資源,這個後端才算可以由代理操作。能夠調用執行期 API 只是其中一步,項目設定、憑證、失敗處理、擁有權和清理也必須涵蓋。

最快的測試方式,是追蹤一個數據庫或一次部署的完整生命週期。只要缺少狀態或刪除合約,代理就仍然需要依賴人操作儀表板。

代理可以存取,不代表代理可以操作

在代理可存取的後端中,人先完成設定,應用程式才可以調用數據庫或 API。代理可操作的後端則更進一步,讓經過授權的代理也能執行建立和維持這個狀態所需的管理工作。

生命週期階段 可存取的後端 可操作的後端
建立 人使用管理介面 代理調用設有類型的建立操作
探索 人複製 ID 和 URL 代理取得結構化識別碼和端點
使用 應用程式調用服務 應用程式使用範圍受限的數據平面憑證
復原 人閱讀日誌並重試 代理讀取操作狀態並按照重試合約處理
輪替 人更換密鑰 代理要求輪替,而且不會看到上游憑證
移交 帳戶一開始就屬於某個人 人透過明確流程認領或接管擁有權
刪除 在管理介面操作 透過獲授權的刪除操作執行,並附有依賴關係和復原規則

代理原生基礎設施指南將同樣的區別套用到完整平台。

分開控制平面與數據平面

控制平面負責建立資源、變更設定、報告狀態、處理擁有權和執行計費規則;數據平面則回應應用程式請求。兩者應使用不同的憑證。

程式開發代理在建置時可能需要管理憑證,但部署後的應用程式只應取得所需的數據平面權限。瀏覽器套件不應拿到任何一種憑證,除非該憑證明確設計為公開資訊,或會被換成短效工作階段權杖。

NIST 的零信任指南主張按照主體、資源和政策作出存取決策,而不是按照網絡位置判斷。這項原則在此同樣適用:針對代理的身份、要求的資源和操作進行授權,再由服務執行決策。

讓資源建立過程可以觀察

建立調用應傳回資源 ID 和操作狀態。如果工作會非同步繼續執行,就要提供狀態查詢操作,並使用 ready、failed 或 deleted 等穩定的終止狀態。

不要讓代理從儀表板 URL 或 DNS 紀錄是否存在來推測資源是否就緒。平台應清楚說明哪些項目已就緒、哪些仍在等待。

定義安全的寫入行為

每一項寫入操作都應記載:

  • 操作是否具冪等性;
  • 用哪個操作識別碼或冪等鍵識別重試;
  • 伺服器會保留該鍵多久;
  • 逾時後,結果是已知還是未知;
  • 調用端如何取回原始結果;
  • 哪些失敗可以安全重試。

Stripe 的冪等性文件是一個清晰的公開例子:系統會儲存某個鍵第一次執行的結果,並在之後傳回同一結果。你的合約可以採用不同的保存期限和參數規則,但必須同樣明確。

傳回能夠決定下一步的錯誤

代理需要穩定的錯誤代碼、簡短訊息和結構化詳情。以下區別會直接影響之後的操作:

錯誤 下一步
invalid_request 修正指定欄位
not_authorized 停止操作,並要求權限更窄或不同的身份
approval_required 向人顯示待批准的確切操作
operation_in_progress 輪詢所提供的操作 ID
rate_limited 等到指定的重試時間
quota_exceeded 停止,或在變更方案或支出前先詢問
dependency_conflict 處理指定的依賴資源

HTML 錯誤頁或籠統的 500 錯誤會迫使代理猜測。資源配置期間的猜測,會造成重複建立資源,也會令清理工作出錯。

將擁有權與初始建立分開

用戶還不想建立帳戶時,代理可能已經需要建立隔離項目。這類項目仍須設定到期時間,並提供日後由人認領的流程。只有在用戶明確同意後,認領操作才能擴大擁有權,而且批准 URL 不應洩露代理的暫時密鑰。

Cohesivity 採用這種模式。npx @cohesivity/init 會建立或重用一個有效 72 小時的暫時租戶。資源文件位於 /offerings/<name>,資源透過管理平面配置,而應用程式則使用獨立的邊緣憑證。之後才由人透過同意流程認領。

使用程式開發代理配置後端資源的實作指南展示了完整流程。

依賴資源前先測試刪除

建立一個可隨時棄用的資源,中斷建立流程、再次執行、輪替存取權,最後將它刪除。確認依賴服務能夠繼續運作;如果不能,刪除操作也應以結構化說明指出阻擋原因。同時確認舊憑證已經失效。

下方提示會針對項目已使用的一項資源執行相同的生命週期檢查,而且不會改動供應商端的任何內容。