Vercel Agent 如何安全存取生產環境

在生產系統上執行的代理程式需要授權才能行動。像「fix this deployment」這樣的請求並不會一開始就告訴你它會採取哪些操作或需要什麼存取權。若授予代理程式廣泛存取權，錯誤可能會影響到無關的資源。每一步都要求批准，使用者必須在知道代理程式打算如何解決問題之前，先批准每一項個別動作。重複的提示會使這種審查變成點選批准的習慣。

Vercel Agent 首先調查問題，然後提出一個計畫，說明它將做什麼以及需要哪些存取權。批准該計畫會授予執行所需的額外許可權，讓使用者能在授權任何變更前審閱建議的修復方案。

計畫決定許可權

對於失效的生產部署，Vercel Agent 可能會檢查最近的部署和 build logs，然後將失敗的部署與最後一次正常部署進行比較。唯讀存取權允許此調查自動進行。若此調查導致建議重新部署，Vercel Agent 會在一個計畫中請求額外的存取權，使用者可在一次決策中審閱並批准。

存取權由範圍（scopes）定義，這些範圍是 Vercel 授權系統所認可的命名能力。任何超出唯讀基準的存取請求都必須整體審批，包括其內部包含的唯讀任務。在此範例中，調查在 Vercel Agent 提出重新部署之前，先以獨立的唯讀計畫執行：

計畫	工作	請求的範圍
調查失敗	檢查最近的部署和 build logs，然後將失敗的部署與最後一次成功的部署進行比較	`read:deployment`
重新部署最後一次已知良好的建置	建立部署	`read-write:deployment`

簡短的唯讀查詢可以在沒有計畫的情況下執行。對於較長的調查，Vercel Agent 會建立一個唯讀計畫，讓使用者在其自動執行時可追蹤任務與進度。

計畫將使用者想完成的事與 Vercel Agent 允許執行的事連結起來：

意圖：使用者所要求的結果。
工作：Vercel Agent 為達成此目標所建議的任務。
存取權：這些任務所需的範圍。
執行：執行存取限制的憑證與 API 檢查。

每個儲存的計畫都會記錄其任務與進度，並將請求的範圍附加到每項任務。任務說明會說明為何需要存取權，範圍則在整個計畫中合併。

唯讀基準目前包含所有以 read: 開頭的已註冊範圍。當計畫請求超出此基準的存取權或包含支援的外部動作（如開啟 GitHub pull request）時，需要審批。唯讀操作仍可能暴露敏感資訊，因此自動審批並不代表工作無害。

Vercel Agent 只能使用使用者已擁有的許可權

Vercel Agent 以 Vercel App 形式執行，使用者授權其在團隊內代表自己行事。此授權受到 user’s existing permissions 的限制，因此批准計畫無法授予使用者不存在的存取權。

Vercel OAuth 服務將該授權換成具有特定範圍的短期存取權杖。這些範圍定義了令牌允許的功能，例如閱讀部署或變更專案設定。Vercel API 在每一次請求時檢查令牌，以執行這些限制。

使用者可以為擁有數十個專案的團隊授權 Vercel Agent。重新部署計畫需要部署寫入許可權。編輯環境變數、變更網域以及管理團隊成員各自都需要各自的許可權。

部署寫入許可權比單一重新部署更廣泛。在計畫中命名部署 X 本身並不會將 token 限制於該部署。執行時期，協調 Vercel Agent 執行的軟體，會在選擇已批准的憑證前先確認計畫是否仍有效。Vercel API 會對每一次請求檢查其憑證的許可權。

批准決定 Vercel Agent 可以使用哪些許可權

當使用者批准需要額外 Vercel 存取的計畫時，其所請求的範圍會再次被檢查，並準備一個包含唯讀基礎範圍加上已批准許可權的 token。執行時期，協調 Vercel Agent 執行的軟體，會在選擇已批准的憑證前先確認計畫仍有效。該憑證仍受其範圍、團隊、使用者許可權以及到期時間的限制。

所使用的憑證取決於工作內容：

工作	憑證
唯讀調查	一個包含唯讀範圍的基礎 token
已批准的 Vercel 變更	一個包含基礎範圍加上已批准額外範圍的 token
外部操作	該提供者特定的憑證與許可權

模型的指示告訴它何時提出計畫並請求批准。如果它嘗試執行超出令牌許可權的操作，Vercel API 會拒絕該請求，即使模型認為此行動對完成任務是必要的。

單一計畫可包含 Vercel 變更與 GitHub 拉取請求。使用者在同一計畫中審核兩者，且每個提供者使用獨立的許可權與憑證。GitHub 拉取請求存取許可權與擁有者及儲存庫繫結，因此在 acme/storefront 開啟拉取請求的批准適用於該儲存庫，即使使用者同時擁有 acme/payments 的存取許可權。於那裡開啟拉取請求仍須另行批准。

計畫與令牌使用相同的許可權定義

提出的計畫可能會要求已被重新命名或移除的許可權。我們最初為 Vercel Agent 維護獨立的許可權清單，可能與發行其令牌的 OAuth 服務不同步。後來我們改用相同的範圍定義，以便在規劃階段捕捉這些不匹配。

在會話設定時，Vercel Agent 會將這些定義從 Vercel 範圍登錄檔載入到記憶體目錄。取得登錄檔需要團隊授權，而範圍定義本身則在團隊間共用。目錄提供在三個階段使用的定義：

計畫驗證：請求的範圍會被標準化，未知或格式錯誤的名稱在計畫儲存或提交審批前會被拒絕。
審批：請求的範圍決定計畫是否符合唯讀基準或需要額外存取許可權。
令牌準備：有效範圍定義已批准工作所需的憑證。

例如，更新防火牆規則的任務可能會請求過時的範圍。系統會拒絕該計畫並回傳有效範圍，讓 Vercel Agent 在請求批准前進行修正。這樣可在規劃階段捕捉不匹配，並要求明確修正，而非退回至更廣泛的存取許可權。

抓取 registry 會增加延遲與服務依賴，於是 Vercel Agent 會快取目錄並使用該快取來檢查載入時的已儲存方案。這些檢查會反映快取中的定義，直到目錄以 registry 的變更重新整理。

恢復工作需具備一個啟用且已獲批准的方案

Vercel Agent 可能在原始聊天請求結束後才收到批准，或在執行已批准的重新部署前失去連線。儲存的方案包含其狀態、批准者與時間，以及其任務與所請求的許可權。該紀錄將提議的工作與使用者授權的存取權連結，並允許在恢復工作時檢查批准。

在恢復前，執行時期會重新載入方案並確認其為啟用狀態，再選取擁有已批准許可權的憑證。即使其憑證仍有剩餘有效時間，已停止的方案也會通過該檢查失敗。

若批准與停止請求同時到達，方案只能在停止尚未改變其狀態時，從等待批准移至啟用。執行時期接著再次確認方案為啟用，才會使用已批准的憑證。

若調查顯示目前方案需被取代，Vercel Agent 可提出另一方案。要求提升存取權的替代方案需再次獲批准，讓使用者有機會一次檢視修訂後的工作與許可權。

當許可權需要更精確時

隨著 Vercel Agent 進入平臺更多區域，我們必須修正涉及多個資源或有不同後果的操作的存取規則。連結域名可能同時需要域名與專案許可權，而先行設定防火牆規則並發布則需要不同層級的存取權。範圍需捕捉這些差異，同時保持每個方案的存取請求易於管理。

在整個規劃過程中，將這些範圍對應到建議的修復需要謹慎：

選擇範圍：Vercel Agent 在資訊不完整時選擇範圍，可能會請求不足的存取權而使任務被阻塞，或請求過多而授予超出工作需求的許可權。任務層級指導能幫助它…
描述工作：『重新部署最後一次成功的建置』為使用者提供可評估的具體行動，而僅以範圍名稱則需自行推斷後果。方案必須說明預期變更，並明確指出憑證實際施行的限制。
理解拒絕：被拒絕的操作可能表示缺少範圍、資源不正確，或本應保持阻止的操作。Vercel Agent 必須在請求額外許可權前區分這些情況。

即使具備正確許可權，重新部署仍需判斷所選提交是否安全上線。這取決於應用程式、失敗原因與建議修復。使用者需要足夠資訊來評估選擇，而 Vercel Agent 仍需正確執行。

唯讀調查同樣需要對其檢索的資訊進行控制，包括敏感的專案設定與作業細節。我們選擇了唯讀基準，讓 Vercel Agent 能在請求授權前先進行調查，且這個選擇須隨著範圍與所暴露資訊的變化而持續審查。其他系統可能需要更窄的基準。必須有獨立的控制機制來管理檢索資訊的處理方式與可送往之處。

Vercel Agent 可能會做出錯誤決策或在閱讀內容（例如建置日誌）時遇到惡意指令。範圍限制的憑證會限制其在任何情況下能執行的操作，但允許的操作仍可能造成損害。因此，計畫必須與沙盒隔離、網路政策、秘密處理、速率限制、審計日誌及服務授權同步運作。我們關於代理架構中的安全邊界的研究說明瞭代理、其憑證與執行程式碼之間的分離。

從調查到批准的行動

授權仍與所需執行的工作相連。執行階段會為正在執行的計畫選擇已批准的憑證，並以其範圍定義 Vercel Agent 可執行的操作。調查完成後，使用者可以同時評估建議的修正與所需的存取許可權。

嘗試 Vercel Agent 以調查專案中的問題。審閱其發現，若提出變更建議，請先評估計畫與所請求的存取許可權再行批准。