全部產品
Search

搜尋本產品

    AgentCore：高代碼 Agent 部署與使用指南

    文件中心

    AgentCore：高代碼 Agent 部署與使用指南

    更新時間：Sep 18, 2026

    高代碼 Agent 支援將自行開發的 Agent 應用以容器鏡像部署到 AgentCore。您可以保留已有的開發架構和 HTTP 服務，在控制台配置運行環境、調試對話並擷取調用地址。

    本文介紹控制台操作。應用開發、SDK 安裝及架構接入，請參見開發參考；首次體驗可參見使用 Python SDK 快速建立高代碼 Agent。

    前提條件

    • 已開通 AgentCore，並建立 Workspace。具體操作，請參見管理 Workspace。

    • 已準備可啟動並執行 Agent 容器鏡像，並推送至企業版Container Registry ACR。

    • 已明確應用的啟動命令、監聽連接埠、健全狀態檢查路徑及對話協議。

    • 如應用使用平台模型、MCP、Skill 等資源，已在目標 Workspace 中完成相應資源配置，並準備具備要求的權限的執行角色。

    說明：本文介紹將自建代碼部署到 AgentCore 託管運行，不是將本地啟動並執行 Agent 納管到平台。自建 HTTP 服務無需替換為 AgentCoreServer，但其實際介面必須與控制台填寫的協議和路徑一致。

    步驟一：檢查鏡像與應用配置

    建立前，確認鏡像滿足以下要求。

    檢查項

    要求

    鏡像架構

    支援 linux/amd64（x86_64），不能僅支援 ARM64。

    Shell 環境

    鏡像中同時提供可執行檔 /bin/bash 和 /bin/sh。

    鏡像倉庫

    當前僅支援企業版 ACR。按當前建立頁要求，執行個體需開啟公開匿名拉取，鏡像倉庫需設為公開。不要將密鑰或業務資料打入公開鏡像。

    服務監聽

    應用監聽 0.0.0.0，服務連接埠與控制台配置一致。僅監聽 127.0.0.1 的服務無法正常接收平台轉寄的請求。

    健全狀態檢查

    應用提供可訪問的健全狀態檢查介面。路徑和連接埠以應用實際實現為準。

    依賴與配置

    鏡像包含啟動所需的程式、依賴和檔案；業務環境變數在部署時按需填寫。

    鏡像倉庫還需從 Agent 運行環境網路可達。本地能夠推送或拉取鏡像，不代表雲端可以拉取。網路設定見後文"配置網路和日誌"。鏡像構建樣本，請參見使用 Python SDK 快速建立高代碼 Agent。

    步驟二：建立高代碼 Agent

    1. 進入建立頁面

    1. 登入 AgentCore 控制台。

    2. 在頂部選擇目標地區，並切換至目標 Workspace。

    3. 在左側導覽列單擊 Agent，單擊 建立 Agent。

    4. 在 選擇建立方式 中選擇 自訂代碼 / 鏡像。

    2. 配置基本資料和容器鏡像

    在 基本資料 地區填寫以下內容。

    參數

    操作說明

    Agent 名稱

    設定便於識別的名稱，例如 my-code-agent。

    描述

    可選。填寫應用用途或職責。

    容器鏡像執行個體

    選擇已準備的企業版 ACR 執行個體。建立執行個體後可單擊重新整理按鈕重新載入。

    鏡像倉庫

    選擇鏡像所在的倉庫。

    鏡像版本

    在版本列表中選擇要部署的版本，可通過 Digest、鏡像大小和最近推送時間核對。

    建議為每次發布使用明確的版本標籤，便於後續確認部署內容和定位問題。

    3. 配置啟動方式和執行角色

    參數

    操作說明

    啟動命令

    填寫鏡像內可執行檔應用啟動命令。不要直接照抄與自身目錄、入口檔案不一致的樣本。

    服務連接埠

    填寫應用實際監聽連接埠。建立頁預設顯示 8080；若應用監聽 9000，需改為 9000。

    執行角色

    選擇授予 Agent 運行時所需雲資源存取權限的角色。可通過 查看策略 核對許可權，通過重新整理按鈕更新角色列表。

    環境變數

    按應用要求添加名稱和值，支援表單模式和 JSON 模式。應用無需額外環境變數時可不填。

    執行角色用於 Agent 訪問雲資源，不是外部調用 Agent 的 API Key。角色要求請參見頁面上的 授權說明。

    所選角色的狀態決定頁面上可用的授權入口：

    • 角色顯示 未建立 時，單擊 一鍵建立並授權，由平台建立角色並附加所需策略。

    • 角色已存在但缺少要求的權限時，頁面會列出缺失的許可權，可單擊 一鍵授權 補齊，或單擊 前往 RAM 控制台授權 自行處理。

    • 授權完成後提示 授權成功，許可權已生效。若提示授權未完成或許可權尚未生效，請重試。

    說明：授權視窗被瀏覽器攔截時，需允許快顯視窗後重試。當前帳號缺少相應許可權時，頁面無法列出角色，需聯絡主帳號或許可權管理員授權。

    使用平台模型、MCP 或 Skill 時，由代碼引用相應資源。高代碼建立頁不會像託管 Harness 一樣替應用產生提示詞、選擇模型或註冊工具，具體接入方法請參見對應語言的 SDK 使用指南。

    4. 聲明對話協議

    在 協議配置 中單擊 配置，勾選應用實際支援的協議，填寫 Path，並按需添加 Header。可同時聲明兩種協議。

    頁面選項

    適用情境

    頁面預填 Path

    Chat Completions

    使用 OpenAI Chat Completions 格式調用 Agent。

    /openai/v1/chat/completions

    AGUI

    使用 AG-UI 格式進行流式對話，展示應用返回的執行過程和工具事件。

    /ag-ui/agent

    • Path：填寫應用的實際介面路徑，以 / 開頭，不填寫完整網域名稱。例如自建服務使用 /v1/chat/completions，應修改為該路徑。

    • Header：填寫調用該協議介面時需要攜帶的固定要求標頭。沒有其他需求時留空；不要將下遊模型的 API Key 誤填為 Agent 介面的鑒權資訊。

    填寫後單擊彈窗內的 儲存。

    說明：協議聲明不會為應用自動產生對應介面，也不會自動增加工具事件。未聲明協議時，控制台調試面板無法按協議發起對話；如果聲明與實際介面不一致，可能出現 404 或響應解析失敗。

    5. 配置運行資源和健全狀態檢查

    在 進階配置 中按需調整以下參數。

    配置項

    操作說明

    規格

    選擇應用所需的 CPU 和記憶體。

    執行個體數

    設定運行執行個體數量。

    執行個體最大 Session 數

    設定單個執行個體承載的 Session 數量上限，並結合應用並發能力調整。

    Session TTL（秒）

    設定平台 Session 的存活時間參數；這不是模型單次產生的逾時時間。

    會話隔離方式

    根據業務選擇 不啟用、會話親和 或 Header 隔離，並完成所選方式要求的配置。

    健全狀態檢查

    填寫檢查路徑、檢查連接埠、檢查間隔、逾時時間和不健康閾值。

    平台會按配置進行健全狀態檢查。連續檢查失敗會影響執行個體接收流量，並可能觸發執行個體重啟。因此，不能只修改服務連接埠而保留不匹配的檢查連接埠。

    以下為官網 Python 快速入門樣本的部署值，僅適用於該樣本，其他應用按實際實現填寫。

    配置項

    樣本值

    啟動命令

    uvicorn app:server --host 0.0.0.0 --port 9000

    服務連接埠

    9000

    對話協議與路徑

    AGUI，/ag-ui/agent

    健全狀態檢查路徑

    /readyz

    健全狀態檢查連接埠

    9000

    說明：當前建立頁的健全狀態檢查預設路徑為 /healthz。使用 /readyz 或其他路徑的應用，需要手動修改，不應直接保留頁面預設值。

    6. 配置網路和日誌

    網路設定

    • 應用需要訪問公網模型服務或其他公網介面時，按需開啟 允許預設網卡訪問公網。

    • 應用需要訪問 Workspace 的 VPC 資源時，按需開啟 允許訪問 VPC。開啟後使用當前 Workspace 的 VPC 配置。

    • 未開啟 VPC 訪問時，鏡像通過公網拉取。如 ACR 配置了公網訪問白名單，將頁面顯示的 當前 Workspace 公網出口 IP 加入白名單；開啟 VPC 訪問後，平台會嘗試經 VPC 拉取鏡像，需同時確認 ACR 允許對應 VPC 訪問。

    日誌配置

    建議開啟 啟用日誌，選擇 記錄項目 和 日誌庫，以便在部署或調用異常時查看作業記錄。應用也需要輸出有助於排障的啟動資訊和錯誤記錄檔，避免列印密鑰及敏感業務內容。

    7. 提交建立

    核對鏡像版本、啟動命令、服務連接埠、協議路徑和健全狀態檢查配置，單擊頁面右上方的 立即建立。

    建立後返回 Agent 列表，等待狀態變為 運行中。將滑鼠移至對應卡片，單擊 詳情，可在 概覽與配置 中查看已儲存的鏡像版本、啟動配置和協議聲明。

    步驟三：在控制台調試

    1. 開啟 Agent 詳情，單擊 調試。

    2. 在協議下拉框中選擇已聲明的協議，確認 調試端點 顯示就緒。

    3. 輸入一條簡單訊息，例如"你好，請用一句話介紹你能做什麼"，單擊發送。

    4. 檢查 Agent 是否返回預期回答。隨後再測試需要調用工具或訪問業務資源的請求。

    需要重新開始對話時，單擊 建立會話。排障時可複製頁面上的會話 ID，並通過 作業記錄 查看對應時間段的記錄。

    說明：能否展示執行過程和工具調用，取決於應用返回的協議事件。僅在控制台勾選 AGUI，不會自動補齊代碼未輸出的事件。

    步驟四：從業務應用調用

    1. 在 Agent 詳情中單擊 外部渠道配置。

    2. 單擊 直接存取，查看 Endpoint 狀態和調用地址。

    3. 在 鑒權方式 中單擊 擷取鑒權資訊，按頁面顯示的 Header 名稱和 API Key 配置調用方。

    4. 參考頁面的 API 呼叫說明 和調用樣本發起請求，使用與協議聲明一致的路徑及請求格式。

    Endpoint 是 Agent 應用的訪問地址，不是下遊模型供應商地址。API Key 應儲存在可信的服務端配置中，不要寫入公開前端代碼或文檔。

    請求體和流式響應的開發樣本，請參見 Python SDK 使用指南或 Node.js SDK 使用指南中的"調用 Agent 服務"。自建 Server 使用其實際實現的協議。

    更新 Agent

    1. 將新版本鏡像推送到 ACR。

    2. 開啟 Agent 詳情，在 概覽與配置 中單擊 編輯配置；也可從列表卡片進入 編輯。

    3. 重新整理鏡像版本列表並選擇新版本。若應用入口、連接埠或協議發生變化，同步修改啟動命令、服務連接埠、健全狀態檢查和協議配置。

    4. 單擊 儲存，等待更新完成，並重新進行控制台調試和業務調用驗證。

    更新可能影響正在處理的請求，建議在合適的業務時間視窗操作。不要僅根據 ACR 中出現新鏡像，就判斷 Agent 已使用新版本，應在 Agent 配置中核對。

    查看運行狀態和排查異常

    入口

    用途

    概覽與配置

    核對當前鏡像版本、啟動命令、連接埠、環境變數和協議聲明。

    執行個體與 Session

    查看執行個體狀態、Session 數量，並按執行個體 ID 或 Session ID 定位。

    可觀測 → 基礎監控

    查看所選時間範圍的運行資料。

    可觀測 → 作業記錄

    查看已配置採集的應用日誌。

    現象

    優先檢查

    找不到鏡像或拉取失敗

    地區、ACR 執行個體及倉庫、鏡像版本、公開匿名拉取配置，以及公網白名單或 VPC 訪問配置。

    執行個體未就緒或反覆重啟

    鏡像架構、Shell、啟動命令、依賴、資源規格；核對應用監聽地址、服務連接埠和健全狀態檢查路徑、連接埠。

    調試頁沒有可選協議

    在 編輯配置 → 協議配置 中聲明應用支援的協議並儲存。

    調用返回 404

    協議 Path 是否與應用路由一致，是否誤把樣本路徑用於自建服務。

    調用返回鑒權錯誤

    區分外部調用的 Endpoint API Key 與應用訪問雲資源的執行角色；按失敗環節核對。

    普通對話正常，但模型或工具調用失敗

    代碼引用的資源名稱、所屬 Workspace、執行角色許可權，以及下遊服務是否可達。

    看不到作業記錄

    是否已啟用日誌並選擇正確的記錄項目、日誌庫；應用是否輸出日誌，查詢時間是否覆蓋失敗時刻。

    向支援人員反饋時，提供地區、Workspace ID、Agent ID、失敗時間和錯誤資訊；如有會話 ID 或請求 ID，一併提供。不要附帶 API Key 或完整敏感要求標頭。

    開發參考