為避免在代碼或工具中寫入程式碼密鑰、令牌等敏感資訊，AgentRun 提供了集中的憑證管理功能。您可以安全地儲存認證資訊，並在多個智能體中引用。這不僅提升了安全性，也極大地簡化了憑證的維護工作：只需修改一次，所有引用該憑證的地方即可同步生效。
AgentRun 中的憑證主要分為兩大類：
-
訪問 AgentRun 服務的憑證：用於訪問和使用 AgentRun 平台內部的各項資源，包括智能體（Agent）、沙箱（BrowserTool、 CodeInterpreter）、模型治理（模型代理與負載平衡）和工具服務。
-
訪問第三方服務的憑證：用於 AgentRun 平台內部的智能體或工具在執行任務時，訪問外部的第三方服務（如大語言模型、雲端服務 API 等）。
本文將指導您如何建立、管理和使用不同類型的憑證。
快速入門：為大語言模型配置憑證
為智能體使用的第三方大語言模型（如 OpenAI）建立一個安全的訪問憑證，並將其應用於模型配置中。
步驟一：建立模型服務憑證
-
在 AgentRun 平台頂部導覽列選擇其他，然後在左側菜單中選擇憑證管理。
-
在憑證管理頁面，選擇憑證類別為訪問第三方服務憑證，點擊添加服務憑證。
-
配置以下參數：
-
服務類型：選擇模型服務。
-
服務提供者：選擇您的大模型服務商，例如
OpenAI。 -
憑證名稱：輸入一個易於識別的名稱，例如
my-llm-key。 -
API Key：填入您從供應商處擷取的
API Key原始內容。
-
-
點擊添加憑證完成建立。
步驟二：在模型配置中引用憑證
-
在模型管理頁面點擊添加模型。
-
在憑證配置部分，選擇使用已有憑證，從下拉式清單中選擇您剛剛建立的憑證，例如
my-llm-key。 -
點擊建立模型。
完成以上步驟後，當智能體通過此模型與大語言模型互動時，AgentRun 將自動使用您配置的憑證進行安全認證。
憑證類型詳解
訪問 AgentRun 服務的憑證
此類憑證用於調用 AgentRun 平台內部的服務介面（如智能體管理、沙箱執行、模型治理等）。您可以在憑證詳情頁查看其綁定的所有資源。
API Key
適用情境：最通用和簡單的鑒權方式，適用於大多數支援固定令牌認證的 API 呼叫用戶端。
核心配置
-
要求標頭名稱：存放 API Key 的要求標頭欄位名。常見值為
Authorization或X-Api-Key。 -
API Key：API Key 的具體值。
注意
請僅填寫原始密鑰（例如sk-xxxxxxxxxxxx），請勿包含Bearer等任何首碼。
JWT(JSON Web Token)
適用情境：適用於與使用 JWT 進行身分識別驗證的系統整合。AgentRun 需要驗證傳入請求中 JWT 的簽名有效性。這通常通過配置 JSON Web Key Set (JWKS) 來實現，AgentRun 支援靜態配置 JWKS 內容或通過 URL 動態擷取 JWKS
1. JWKS JSON
適用於公開金鑰不常變更的情境，您可以直接將公開金鑰集合（JWKS）的 JSON 內容靜態配置在 AgentRun 中。
核心配置：在文字框中填入完整的 JWKS JSON 資料。這通常是一個包含 keys 數組的 JSON 對象。
2. JWKS URL
適用於遵循標準協議（如 OIDC Discovery），且公開金鑰可能會定期輪轉的情境。AgentRun 將自動訪問您提供的 URL 以擷取最新的公開金鑰集合。
核心配置
-
JWKS端點URL：提供標準 JWKS 資料的遠程服務地址（通常以
/.well-known/jwks.json結尾）。AgentRun 將定期從該地址重新整理公開金鑰用於驗證 JWT 簽名。為確保安全，必須使用 HTTPS 協議。
Basic 認證
適用情境：用於快速適配僅支援 Basic 認證的舊系統或自我裝載環境。
核心配置：
-
使用者名稱：Basic 認證所需的使用者名稱。
-
密碼：Basic 認證所需的密碼。
安全警告
Basic 認證在傳輸過程中僅使用 Base 64 編碼，若未使用 HTTPS，使用者名稱和密碼極易泄露。因其安全性較低，不推薦在生產環境中使用。
配置完成後，請在調用遠程服務時使用如下格式的要求標頭進行鑒權：Authorization: Basic <base64(username:password)>。
訪問第三方服務的憑證
此類憑證用於 AgentRun 平台內部的組件（如智能體或工具）在執行任務時，訪問外部的第三方服務。
適用情境：當智能體需要調用第三方大語言模型（LLM）服務（如 OpenAI、Anthropic 等）或通過 FunModel 平台部署的開源模型時使用。
核心配置：
-
服務提供者：選擇對應的大模型供應商。
-
API Key：該供應商提供的存取金鑰。
適用情境：用於工具調用通用的第三方 API。
核心配置：配置 API Key 的具體值。該密鑰將被加密儲存，僅在 Agent 調用時解密使用。
適用情境：用於調用主流雲端服務商（如阿里雲、AWS、騰訊雲等）的 API。引用此憑證後，AgentRun 將根據云服務商的規範自動處理複雜的請求籤名，您無需關心簽名細節。
核心配置
-
雲端服務商：選擇對應的雲端服務商。
-
Access Key ID (AK)：雲端服務商提供的存取金鑰 ID。
-
Secret Access Key (SK)：雲端服務商提供的存取金鑰。
-
賬戶ID：（可選）部分雲端服務商需要的額外身份標識。
核心優勢：自動簽名
您只需提供 AK/SK，AgentRun 將根據目標雲端服務商的規範，在後台自動處理複雜的請求籤名演算法。為確保安全，建議為 AK/SK 憑證綁定具有最小許可權的子帳號（如 RAM 使用者）。
適用情境：適配需要通過非標準或多個自訂要求標頭進行認證的第三方 API。
適用情境：您可以配置一組或多組索引值對，它們將作為要求標頭附加到發往第三方服務的請求中。
管理憑證
在憑證管理列表頁，可以對已建立的憑證進行以下操作：
-
啟用/禁用：通過修改啟用狀態 開關快速控制憑證的有效性。禁用後，任何使用該憑證的調用請求都將失敗（通常返回 401 錯誤）。此功能適用於臨時吊銷存取權限或響應安全事件。
-
編輯：更新憑證的配置資訊，如更換新的 API Key。
-
刪除：永久移除憑證。此操作無法復原，請謹慎操作，並確保沒有正在啟動並執行服務依賴此憑證。
故障排查與FAQ
Q: 更新 FunModel 憑證後，為什麼 AgentRun 調用失敗？
A: 當前 AgentRun 與 FunModel 平台的憑證資訊尚未實現自動同步。當您在 FunModel 更新憑證後，必須手動在 AgentRun 的憑證管理頁面找到對應的大模型 Key憑證並進行更新。建議您在計劃內進行憑證變更，並預留時間完成雙邊同步。
Q: 遠程擷取 JWT 失敗，如何排查？
A: 請按以下步驟檢查您的遠程擷取配置：
-
檢查 JWKS URL：確保 URL 可通過公網正常訪問，且為 HTTPS 協議。
-
類比請求：使用 Postman 等工具，根據您配置的要求方法、要求標頭、請求體，手動調用 JWKS URL，確認介面能正常返回 JWKS 格式的 JSON 資料。
-
查看服務日誌：如果問題仍然存在，請聯絡平台管理員查看 AgentRun 後台日誌，擷取從遠程服務擷取 Token 失敗的具體原因。
Q: API 呼叫返回 401 Unauthorized 或 403 Forbidden 錯誤是什麼原因？
A: 這通常意味著鑒權失敗，請檢查：
-
您使用的憑證是否已在 AgentRun 中被禁用。
-
您發送的 API 請求中，攜帶的憑證資訊（如 Header 名稱、Header 值）是否與在 AgentRun 中配置的完全一致，注意檢查空格、首碼等細節。
-
如果憑證是動態（如 JWT），確認其是否已到期。