跳到正文
AWS Machine Learning Blog· Sundar Raghavan·· 23 天前精選AI 評分60

如何透過 Amazon Bedrock AgentCore runtime 即時預覽編碼智能體建立的網站

Preview web apps live as your coding agent builds them with Amazon Bedrock AgentCore runtime

AI 導讀

AWS 示範以 Amazon Bedrock AgentCore runtime 的 Session endpoints,讓編碼智能體建立的 Vite 網站在瀏覽器中即時預覽,並在智能體儲存檔案時更新。

推薦理由

文章以 Vite 網站示範如何透過 Session endpoint 即時預覽編碼智能體的修改,並交代連接埠授權、本機憑證轉送與連線限制。

正文 · 繁體中文

如今,編碼代理已能建構可運作的網頁應用程式:儀錶板、產品頁面,或產品團隊想試用的原型。檢視這些成果最快的方法,是開啟應用程式、實際操作、要求修改,再檢查結果。只要應用程式在代理編輯時持續運行,這個流程就很順暢,因為每次修改都會在幾秒內顯示於瀏覽器。若必須先把應用程式複製到其他地方部署,每次修改都要等候部署,檢視速度也會因此受限。

Amazon Bedrock AgentCore 是一個平台,讓你使用自選的代理框架和基礎模型(FM),大規模建構、連接及最佳化代理。AgentCore runtime 是 Amazon Bedrock AgentCore 的一項功能,會在各自隔離的 microVM 中執行每個代理工作階段。透過 Session endpoints,你可以在自己的瀏覽器中開啟該工作階段內運行的應用程式。Session Endpoints 會為每個工作階段提供經驗證的 URL,並將每個請求的 HTTP 方法、路徑、查詢字串和本文,以及 WebSocket 連線,轉送至你允許的連接埠。你可以在代理儲存每個檔案時,即時查看頁面更新。

這篇文章會示範部署一個編碼代理,讓 Vite 網站在其工作階段中持續運行;接着在本機開啟一個頁面,左邊是聊天介面,右邊是即時網站。你會要求代理把網站切換成深色配色,跟着串流顯示的操作步驟,並觀看網站即時變更,毋須重新整理。最後,你會瞭解背後運作方式:同一工作階段內的第二個連接埠,以及 Session endpoint 會拒絕哪些請求。

14-remote-access 資料夾內有完整範例,包括本文所依循的 notebook;該資料夾位於 agentcore-samples GitHub 儲存庫中。

Session endpoint 的運作方式

每個工作階段都有自己的 Session endpoint,而使用方式受六項細節影響。

你可選擇它能連接哪些連接埠。 設定 allowedPorts 時,你可呼叫 CreateAgentRuntime,並指定 1–5 個項目;每項可為單一連接埠,或 8000–12000 範圍內的一段連接埠,且不得包含平台保留連接埠。允許連接埠並不會啟動伺服器,因此你的應用程式必須在該連接埠上監聽,並綁定至 0.0.0.0。

URL 會隨工作階段提供。 InvokeAgentRuntime 回應會在 X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url 標頭中帶上 URL;在有將此欄位建模的 SDK 中,該 URL 會以 sessionEndpointUrl 屬性提供。

每個請求都會經過身分驗證。 若 runtime 使用 AWS Identity and Access Management (IAM),每個 HTTP 請求、HTTP/2 串流及 WebSocket 握手都會帶有 Signature Version 4 (SigV4) 簽章。呼叫者亦須在 runtime 及其 runtime endpoint 上擁有 bedrock-agentcore:InvokeAgentRuntimeProxy 權限。若 runtime 使用 inbound JSON Web Token (JWT) authorizer,每個請求則會改為帶有 bearer token。知道 URL 並不代表已獲授權存取。

主機名稱會選擇連接埠。 不論目標連接埠為何,你的用戶端都會連接至 443 連接埠;主機名稱中的前綴則會選擇工作階段內的連接埠:

https://8090--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/index.html
https://8081--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/status

它會轉送伺服器支援的通訊協定。 HTTP/1.1 和 HTTP/2 請求(包括 server-sent events 和 gRPC),以及 WebSocket 連線都會通過。此操作示範使用 HTTP/1.1 和 WebSocket。

其範圍僅限單一工作階段。 每次請求都需要憑證,而且 URL 只在工作階段期間有效,因此應用它來建構、測試和檢視代理產生的成果。若要向用戶提供應用程式,請將它部署到 AWS Amplify Hosting 等託管服務。

瀏覽器本身無法為頁面發出的請求加入 SigV4 簽章或 bearer token,因此 bedrock-agentcore SDK 中的 Session endpoint 用戶端可在你的電腦上開啟本機 endpoint。瀏覽器會開啟 http://localhost:8088,而本機 endpoint 會在轉送請求及 WebSocket 握手之前,為每個請求及 WebSocket 握手加入你的憑證。

Session endpoint 與 runtime endpoint 不同,後者是 AgentCore runtime 已提供的。你可使用例如 DEFAULT 的 runtime endpoint 存取代理;該 endpoint 決定呼叫者會連到代理的哪個版本。InvokeAgentRuntime 呼叫會經由此 endpoint 解析,因此你可讓開發版和正式環境使用不同版本,並在不變更呼叫端的情況下發布新版本或回復舊版。使用 Session endpoint 則可查看代理在其工作階段內執行的內容,例如網頁預覽。它是經驗證的 URL,只會連到你允許的連接埠,不論工作階段使用哪個版本都可運作,且工作階段結束後便會失效。完整説明請參閲 透過 session endpoint 連接 runtime 工作階段。

解決方案概觀

此範例由四個部分組成。編碼代理在工作階段的 8080 連接埠上運行,並透過四個工具編輯網站檔案:list、read、write 和 edit。代理會在 8090 連接埠啟動 Vite 開發伺服器,該伺服器提供網站,並透過 hot-reload WebSocket 將每次儲存的變更推送至瀏覽器。在你的電腦上,PreviewApp 提供預覽頁面、將提示傳送至 InvokeAgentRuntime,並為網站開啟本機 endpoint。如圖 1 所示,預覽頁面會透過本機 endpoint 和 Session endpoint,從 8090 連接埠上的 Vite 開發伺服器載入網站;並透過 InvokeAgentRuntime 將提示傳送給 8080 連接埠上的代理。數字表示單一請求的步驟次序。

Architecture diagram: the preview page and local endpoint on your machine, the Session endpoint and InvokeAgentRuntime, and the agent and Vite development server in a runtime session, with Claude Haiku 5.5 in Amazon Bedrock.

圖 1:解決方案架構

PreviewApp 在步驟 1 之前已呼叫過一次 InvokeAgentRuntime 來啟動工作階段,這會同時啟動代理和 Vite 開發伺服器。PreviewApp 從該回應讀取 Session endpoint URL,並為 8090 連接埠開啟本機 endpoint。圖 1 中編號的步驟接着展示一項修改請求的流程:

  1. 預覽頁面的網站窗格會從 localhost:8088 上的本機 endpoint 載入網站。本機 endpoint 會為每個請求及 WebSocket 握手加上你的憑證,並將其轉送至 Session endpoint。 Session endpoint 會核驗簽章及連接埠是否符合 allowedPorts,然後將請求轉送至 8090 連接埠上的 Vite 開發伺服器。頁面會持續保持 Vite hot-reload WebSocket 連線開啟。
  2. PreviewApp 從聊天窗格傳送提示,並使用你的 AWS 憑證將提示作為標準 AWS API 請求簽署後傳給 InvokeAgentRuntime;runtime 再將提示傳送至 8080 連接埠上的代理。代理工作的步驟會在執行期間串流返回聊天窗格。
  3. 代理會在 Amazon Bedrock 中呼叫 Claude Haiku 5.5,以決定要修改甚麼。
  4. 代理會讀取網站檔案,並儲存它修改的檔案。Vite 開發伺服器提供這些檔案,並監察檔案變更。
  5. 檔案儲存後,Vite 會沿用步驟 1 開啟的 WebSocket,經 Session endpoint 及本機 endpoint 將變更推送回來,網站窗格隨即更新,毋須重新整理。
  6. 在 notebook 中,PreviewApp 會透過同一個 Session endpoint,讀取代理在 8081 連接埠上的 /status 路由。變更的只有連接埠。

allowedPorts 不包含 8080 連接埠,因為 InvokeAgentRuntime 無須經過 Session endpoint 就能連接代理。

先決條件

按照此操作示範進行前,你需要:

  • 一個位於支援 AgentCore runtime Session endpoint 的 AWS 區域的 AWS 帳戶,並已設定憑證。
  • 建立 AWS Identity and Access Management (IAM) role、上傳至 Amazon Simple Storage Service (Amazon S3) 及建立 runtime 的權限;此外,須為該 runtime 授予 bedrock-agentcore:InvokeAgentRuntime 及 bedrock-agentcore:InvokeAgentRuntimeProxy 權限,並在其 DEFAULT runtime endpoint 上授予相同權限。詳情請參閲 AgentCore runtime 的 IAM 權限。
  • Python 3.10 或更新版本,並安裝 bedrock-agentcore 1.25.2 或更新版本,以及 boto3 1.43.122 或更新版本。
  • 用來複製範例儲存庫的 Git,以及用來執行 notebook 的 Jupyter 環境,例如 JupyterLab,或安裝 Jupyter 擴充功能的 Visual Studio Code。
  • 可在 Amazon Bedrock 存取 Claude Haiku 5.5。如需按區域查閲模型可用情況,請參閲 各模型的區域可用性。
  • Node.js 22 或更新版本及 npm(部署指令碼會用它封裝代理和網站)。

此範例會使用 Node.js 直接程式碼部署,將代理部署為 Amazon S3 中的 zip 檔,因此無須使用 Docker 或 Amazon Elastic Container Registry (Amazon ECR) 儲存庫。Session endpoint 只適用於 microVM runtime,不適用於 Instances 運算類型;Session endpoint URL 可透過公開 HTTPS 存取。AWS PrivateLink 不支援輸入連線。

部署代理及其網站

首先部署 runtime;你在此選擇的設定會決定 Session endpoint 可連接哪些連接埠。部署指令碼會把代理封裝成單一檔案,為 runtime 的 Linux on Arm64 系統加入網站及其相依項目,把 zip 上傳至 Amazon S3,並建立 runtime。

以下是 deploy.py 中與本文相關的兩項設定。protocolConfiguration 指定代理在哪裏接收 InvokeAgentRuntime 請求;allowedPorts 則列出 Session endpoint 可連接的連接埠:網站使用 8090,代理狀態路由使用 8081。清單不包含 8080,因為 InvokeAgentRuntime 無須經 Session endpoint 就能連接代理。連接埠和路徑設定詳情請參閲 設定代理的服務連接埠和呼叫路徑。

agentRuntimeArtifact={"codeConfiguration": {
    "code": {"s3": {"bucket": code_bucket(), "prefix": S3_PREFIX}},
    "runtime": "NODE_22",
    "entryPoint": ["app.js"],
}},
protocolConfiguration={"serverProtocol": "HTTP", "port": 8080, "path": "/invocations"},
allowedPorts=[{"port": 8090}, {"port": 8081}],

網站的 Vite 設定會讓 Session endpoint 能連接開發伺服器。伺服器會在 0.0.0.0 上監聽 8090 連接埠,而且不會限制 Host 標頭(server.allowedHosts 為 true),因為請求會使用 runtime 指定的主機名稱,而非 localhost 抵達。Session endpoint 會在每個請求到達伺服器前進行身分驗證,因此伺服器本身毋須檢查主機名稱。

部署 runtime:

1. 複製範例儲存庫,並切換至範例資料夾:

git clone https://github.com/awslabs/agentcore-samples.git
cd agentcore-samples/01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints

2. 在範例資料夾中開啟 session_endpoints_preview.ipynb。

3. 執行安裝 cell,安裝 Python 相依套件。

4. 執行 %run deploy.py cell。部署需時幾分鐘,大部分時間都在等待 runtime 狀態變為 READY。

開啟預覽

runtime 就緒後,便可啟動預覽。一次呼叫會完成三件事:啟動工作階段(並隨之啟動網站)、為 8090 連接埠開啟本機 endpoint,以及在 localhost:8087 提供預覽頁面。

from preview_app import PreviewApp

app = PreviewApp().start()
print("Open", app.url)

在 start() 中,使用 Session endpoint 的呼叫很精簡。第一次呼叫 InvokeAgentRuntime 會在回應標頭中傳回 URL;session_endpoint_url 會讀取該 URL,而 Session endpoint 用戶端則為 8090 連接埠開啟本機 endpoint:

answer = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn, runtimeSessionId=session_id,
    payload=json.dumps({"prompt": ""}).encode(), contentType="application/json",
)
endpoint = client.session_endpoint_client(session_endpoint_url(answer))
local = endpoint.open_local_endpoint(port=8090, local_port=8088).start()

開啟預覽:

  1. 執行啟動 PreviewApp 的 cell。
  2. 在瀏覽器開啟顯示的連結 http://localhost:8087。

頁面右方顯示由工作階段內 8090 連接埠提供的網站,左方則有簡短指南及建議提示。

要求代理作出修改

現在可要求代理作出修改,並觀看變更出現。每個提示都會透過 InvokeAgentRuntime 傳送給代理。代理會讀取所需檔案、寫入有修改的檔案,並逐步回報進度。檔案儲存後,Vite 開發伺服器會透過其 WebSocket,經 Session endpoint 和本機 endpoint 推送變更,網站隨即在原頁面更新。

要求修改:

  1. 在預覽頁面選取 將此網站切換為深色咖啡店配色主題。
  2. 代理在聊天窗格中讀取及儲存檔案時,跟隨它顯示的步驟。
  3. 觀看網站窗格。代理儲存樣式表時,網站便會更新;橫幅會指出變更來自哪個檔案。

以下影片展示代理處理多個請求時的預覽頁面。選取建議請求便會將它傳送給代理;聊天窗格會列出代理讀取及儲存的每個檔案,右方的網站窗格則毋須重新整理便會更新,從深色主題變成綠色的「Order ahead」(預先訂購)按鈕。

The preview page with a chat pane on the left and the live website on the right updating as the agent edits files

圖 2:代理工作時的預覽頁面

當你要求代理以 server-sent events 回覆時,操作步驟便會逐步串流顯示。你也可在 Python 中使用 app.ask 傳送相同提示,並用 iter_events 讀取由 bedrock-agentcore SDK 提供的串流。已開啟的頁面會以相同方式更新:

for event in app.ask("Make the Order ahead button green"):
    if "step" in event:
        print("  ", event["step"])
    elif "done" in event:
        print(event["done"]["reply"])

此 Python 指令碼的輸出應類似以下內容:

   Looking at the site's files
   Reading src/main.js
   Reading src/style.css
   Reading index.html
   Saved src/style.css
The Order ahead button is now green instead of brown, with white text kept for contrast. You can see it in the hero section, just below the "Small batch coffee, roasted every morning" heading at the top of the page.

在同一工作階段連接第二個連接埠

網站並非唯一可連接的伺服器。代理會在 8081 連接埠提供 /status,列出每個提示及其修改的檔案。相同的 Session endpoint 也可連接此路由,唯一不同之處是連接埠參數。

status = app.endpoint.request("GET", "/status", port=8081)
print("GET /status on port 8081: HTTP", status.status)
for edit in status.json()["edits"]:
    print("  ", edit["prompt"], "->", ", ".join(edit["files"]))

此 Python 指令碼的輸出應類似以下內容:

GET /status on port 8081: HTTP 200
   Make the Order ahead button green -> src/style.css

Session endpoint 會拒絕的內容

runtime 遇到拒絕的請求時,會傳回 HTTP 狀態、空白本文,並在回應標頭中附上錯誤代碼,讓你能分辨 runtime 拒絕的請求與應用程式傳回的錯誤。notebook 會分別傳送一個前往 allowedPorts 以外連接埠的請求,以及一個沒有憑證的請求;runtime 會以 403 AccessDenied 拒絕兩者。

以下表格列出你在使用 Session endpoints 建構應用程式時可能遇到的拒絕情況。

請求 runtime 的回應
不在 allowedPorts 清單中的連接埠 403 AccessDenied
沒有有效憑證的請求 403 AccessDenied 或 401 AuthenticationRequired
已允許但沒有伺服器監聽的連接埠 502 PortNotReachable
工作階段已不存在的 URL 404 SessionNotFound

如何保障工作階段存取權

runtime 轉送請求前會移除本身的身分驗證標頭,因此網站不會收到你的簽章。請求會在 AWS CloudTrail 中記錄為 InvokeAgentRuntimeProxy 事件,事件來源為 bedrock-agentcore.amazonaws.com。本機 endpoint 會使用你的憑證執行操作,因此會限制可使用它的人。它只會監聽 127.0.0.1,只回應發往其本機位址的請求,並拒絕由其他來源網頁開啟的 WebSocket 連線。只在使用預覽時啟動本機 endpoint。詳情請參閲 在 CloudTrail 記錄 Session endpoint 請求。

這些存取控制不會將網站與代理隔離。兩者在同一工作階段中運行,因此執行角色只應獲授予代理所需的權限。若 runtime 更換工作階段的運算資源,已開啟的連線會中斷;除非工作階段使用持續性儲存空間,否則代理所作的修改可能無法保留。如需讓檔案在運算資源更換後仍保留,請參閲 AgentCore runtime 的檔案系統設定。

代理的檔案工具會確保每個路徑都位於網站資料夾內,並拒絕資料夾以外的路徑,因此提示無法令代理修改工作階段中的其他檔案。若其他人也能向你的編碼代理傳送提示,可考慮使用 Amazon Bedrock Guardrails 篩選有害提示及回應,並在發布前檢視代理作出的修改。

清理資源

為避免持續產生費用,請停止預覽並刪除範例建立的資源。代理修改的網站存放在工作階段中,因此工作階段結束時,網站也會一併消失。

清理步驟:

1. 執行停止 cell,並在 notebook 提示時按 Enter。這會停止預覽頁面、本機 endpoint 及工作階段。

2. 執行 %run cleanup.py cell,刪除 runtime、已上傳的程式碼及 IAM role。

總結

Session endpoints 讓你可從自己的工具透過 HTTP/1.1、HTTP/2 及 WebSocket,經身分驗證後存取 AgentCore runtime 工作階段中的應用程式,並只連接你允許的連接埠。本文示範在工作階段內部署一個編碼代理和 Vite 網站,透過本機 endpoint 在瀏覽器開啟即時網站,要求代理套用深色主題,並觀看代理儲存檔案時出現的變更。你亦連接了同一工作階段中的第二個連接埠,並確認 Session endpoint 會拒絕哪些請求。

若要進一步探索,可在 notebook 中將你自己的網站放進 site 資料夾並執行,或調整代理工具以配合你的編碼代理運作方式。如需完整選項(包括連接埠範圍、OAuth、HTTP/2 及 gRPC),請參閲 透過 session endpoint 連接 runtime 工作階段。

若要更改自己的代理供 InvokeAgentRuntime 使用的連接埠或路徑,請參閲 設定代理的服務連接埠和呼叫路徑。若代理亦需要在同一工作階段執行建置或測試指令,請參閲 在 AgentCore runtime 工作階段中執行 shell 指令。如要像此範例一樣,從 zip 檔部署自己的 Node.js 代理,請參閲 Node.js 直接程式碼部署。如需瞭解服務提供的其他功能,可先參閲 使用 Amazon Bedrock AgentCore runtime 託管代理或工具,並到 agentcore-samples GitHub 儲存庫查閲更多範例。


關於作者

Sundar Raghavan

Sundar Raghavan

Sundar 是 AWS Agentic AI Foundations 團隊的資深解決方案架構師。他負責 Bedrock AgentCore 的開發者體驗,包括 SDK 和 CLI,並主導框架及生態系整合策略。他專注於協助開發者在 AWS 上建構、部署及擴展正式環境用 AI 代理。他亦透過 Strands Robots,將同一套代理開發者體驗延伸至 Physical AI。

來源:AWS Machine Learning Blog · aws.amazon.com