開始使用 WebSocket 進行雙向串流
Amazon Bedrock AgentCore 執行期可讓您部署支援 WebSocket 串流的代理程式,以進行即時雙向通訊。本指南會逐步解說如何使用 WebSocket 建立、測試和部署您的第一個雙向串流代理程式。
在本區段,您會學習:
-
AgentCore Runtime 如何支援 WebSocket 連線
-
如何使用雙向串流功能建立代理程式應用程式
-
如何在本機測試您的代理程式
-
如何將代理程式部署到 AWS
-
如何叫用已部署的代理程式
-
如何搭配 WebSocket 連線使用工作階段
如需 WebSocket 通訊協定的詳細資訊,請參閱 WebSocket RFC 6455
AgentCore Runtime 如何支援 WebSocket 連線
AgentCore Runtime 的 WebSocket 支援可在用戶端和代理程式之間啟用持久的雙向串流連線。AgentCore 執行期預期容器在/ws路徑8080的連接埠上實作 WebSocket 端點,這符合標準 WebSocket 伺服器實務。
AgentCore Runtime 的 WebSocket 支援提供與 相同的無伺服器、工作階段隔離、身分和可觀測功能InvokeAgentRuntime。此外,它使用 SigV4 或 OAuth 2.0 身分驗證透過 WebSocket 連線啟用低延遲、即時雙向訊息串流,因此非常適合即時對話語音代理程式等應用程式。
支援的 WebSocket 程式庫
AgentCore Runtime 上使用 WebSockets 的雙向串流支援使用任何 WebSocket 語言程式庫的應用程式。唯一的要求是用戶端使用 WebSocket 通訊協定連線連接到服務端點:
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<agentRuntimeArn>/ws
使用其中一種支援的身分驗證方法 (SigV4 標頭、SigV4 預先簽章的 URL 或 OAuth 2.0),且代理程式應用程式會實作 HTTP 通訊協定合約中指定的 WebSocket 服務合約。 HTTP 通訊協定合約
此彈性可讓您在不同程式設計語言和架構中使用偏好的 WebSocket 實作,以確保與現有程式碼庫和開發工作流程的相容性。
搭配 AgentCore 執行期使用 WebSocket
在此入門教學課程中,您將建立、測試和部署支援使用 bedrock-agentcore Python SDK 和 AgentCore CLI 部署雙向串流的代理程式應用程式。
主題
先決條件
開始之前,請確定您已:
-
AWS 已設定登入資料的帳戶。若要設定您的 AWS 登入資料,請參閱 CLI AWS 中的組態和登入資料檔案設定。
-
已安裝 Python 3.10+
-
AWS 許可 :若要使用 AgentCore CLI 建立和部署代理程式,您必須擁有適當的許可。如需詳細資訊,請參閱使用 AgentCore CLI。
步驟 1:設定專案並安裝相依性
建立專案資料夾並安裝必要的套件:
mkdir agentcore-runtime-quickstart-websocket cd agentcore-runtime-quickstart-websocket python3 -m venv .venv source .venv/bin/activate
將 pip 升級至最新版本:
pip install --upgrade pip
安裝下列必要套件:
-
bedrock-agentcore - 用於建置 AI 代理器的 Amazon Bedrock AgentCore 開發套件,包含 Python
websockets程式庫相依性
pip install bedrock-agentcore
步驟 2:建立雙向串流代理程式
為名為 的雙向串流代理程式程式碼建立來源檔案websocket_echo_agent.py。新增下列程式碼:
from bedrock_agentcore import BedrockAgentCoreApp app = BedrockAgentCoreApp() @app.websocket async def websocket_handler(websocket, context): """Simple echo WebSocket handler.""" await websocket.accept() try: data = await websocket.receive_json() # Echo back await websocket.send_json({"echo": data}) except Exception as e: print(f"Error: {e}") finally: await websocket.close() if __name__ == "__main__": app.run(log_level="info")
建立requirements.txt並新增下列項目:
bedrock-agentcore
包含 python websockets程式庫相依性
了解程式碼
-
BedrockAgentCoreApp:建立代理程式應用程式,擴展適用於 AI 代理程式部署的 Starlette,提供 WebSocket 支援、HTTP 路由、中介軟體和例外狀況處理功能
-
WebSocket 裝飾器 :
@app.websocket裝飾器會自動處理連接埠 8080 上/ws路徑的連線 -
Echo Logic :使用 傳回接收的資料
{"echo": data} -
錯誤處理 :使用 try/except/finally 結構,以確保適當的錯誤記錄和正常的連線關閉。
步驟 3:在本機測試雙向串流代理程式
啟動雙向串流代理程式
開啟終端機視窗,並使用下列命令啟動雙向串流代理程式:
python websocket_echo_agent.py
您應該會看到輸出,指出伺服器正在連接埠 8080 上執行。
測試 WebSocket 連線
建立名為 的本機 WebSocket websocket_agent_client.py 用戶端:
import asyncio import websockets import json async def local_websocket(): uri = "ws://localhost:8080/ws" try: async with websockets.connect(uri) as websocket: # Send a message await websocket.send(json.dumps({"inputText": "Hello WebSocket!"})) # Receive the echo response response = await websocket.recv() print(f"Received: {response}") except Exception as e: print(f"Connection failed: {e}") if __name__ == "__main__": asyncio.run(local_websocket())
開啟另一個終端機視窗並執行用戶端,在本機測試雙向串流代理程式:
python websocket_agent_client.py
成功:您應該會看到類似 Received: {"echo":{"inputText":"Hello WebSocket!"}} 的回應。在執行代理程式的終端機視窗中,輸入 Ctrl+C以停止代理程式。
步驟 4:將雙向串流代理程式部署至 AgentCore 執行期
安裝部署工具
安裝 AgentCore CLI:
npm install -g @aws/agentcore
驗證安裝:
agentcore --help
建立專案並部署至 AWS
為您的雙向串流代理程式建立新的專案:
agentcore create
部署您的代理程式:
agentcore deploy
注意
從代理程式檔案所在的專案目錄 () agentcore-runtime-quickstart-websocket 執行這些命令。
部署之後,您會收到客服人員執行期 ARN,如下所示:
arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/websocket_echo_agent-xyz123
儲存此 ARN,因為您需要它來叫用部署的代理程式。
步驟 5:叫用您部署的雙向串流代理程式
設定環境變數
設定必要的環境變數:
-
匯出您的客服人員 ARN:
export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/websocket_echo_agent-xyz123" -
如果使用 OAuth,請匯出承載字符:
export BEARER_TOKEN="your_oauth_token_here"
身分驗證方法
InvokeAgentRuntimeWithWebSocketStream API 動作會建立支援用戶端和代理程式之間雙向串流的 WebSocket 連線。您可以使用下列方法驗證 WebSocket 連線:
-
AWS Signature 第 4 版標頭 :使用您的 AWS 登入資料簽署 WebSocket 交握請求標頭
-
AWS Signature 第 4 版預先簽章的 URL:使用做為查詢參數提供的 SigV4 簽章建立預先簽章的 WebSocket URL
-
OAuth 承載字符 :在外部身分提供者整合的授權標頭中傳遞 OAuth 字符
提示
請確定您具有 bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream 許可。
使用 SigV4 簽章標頭進行連線
下列範例說明如何建立 WebSocket 連線,並使用 SigV4 簽章標頭與代理程式執行期通訊:
from bedrock_agentcore.runtime import AgentCoreRuntimeClient import websockets import asyncio import json import os async def main(): # Get runtime ARN from environment variable runtime_arn = os.getenv('AGENT_ARN') if not runtime_arn: raise ValueError("AGENT_ARN environment variable is required") # Initialize client client = AgentCoreRuntimeClient(region="us-west-2") # Generate WebSocket connection with authentication ws_url, headers = client.generate_ws_connection( runtime_arn=runtime_arn ) try: async with websockets.connect(ws_url, additional_headers=headers) as ws: # Send message await ws.send(json.dumps({"inputText": "Hello!"})) # Receive response response = await ws.recv() print(f"Received: {response}") except websockets.exceptions.InvalidStatus as e: print(f"WebSocket handshake failed with status code: {e.response.status_code}") print(f"Response headers: {e.response.headers}") print(f"Response body: {e.response.body.decode()}") except Exception as e: print(f"Connection failed: {e}") if __name__ == "__main__": asyncio.run(main())
執行 用戶端以測試您部署的代理程式:
python websocket_agent_client_sigv4_headers.py
成功:您應該會看到如下的回應:
Received: {"echo":{"inputText":"Hello!"}}
使用預先簽章的 URL 連線 (SigV4 透過查詢參數)
下列範例示範如何使用 SigV4 查詢參數建立 WebSocket URL 並建立連線:
from bedrock_agentcore.runtime import AgentCoreRuntimeClient import websockets import asyncio import json import os async def main(): runtime_arn = os.getenv('AGENT_ARN') if not runtime_arn: raise ValueError("AGENT_ARN environment variable is required") client = AgentCoreRuntimeClient(region="us-west-2") # Generate WebSocket pre-signed URL (with SigV4 via query parameters) # wss://...amazonaws.com/runtimes/.../ws?X-Amz-Algorithm=AWS4-HMAC-SHA256 # &X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Expires=300 # &X-Amz-SignedHeaders=...&X-Amz-Signature=... sigv4_url = client.generate_presigned_url( runtime_arn=runtime_arn, expires=300 # 5 minutes ) try: async with websockets.connect(sigv4_url) as ws: await ws.send(json.dumps({"inputText": "Hello!"})) response = await ws.recv() print(f"Received: {response}") except websockets.exceptions.InvalidStatus as e: print(f"WebSocket handshake failed with status code: {e.response.status_code}") print(f"Response headers: {e.response.headers}") print(f"Response body: {e.response.body.decode()}") except Exception as e: print(f"Connection failed: {e}") if __name__ == "__main__": asyncio.run(main())
執行 用戶端以測試您部署的代理程式:
python websocket_agent_client_sigv4_query_parameters.py
成功:您應該會看到如下的回應:
Received: {"echo":{"inputText":"Hello!"}}
使用 OAuth 連線
AgentCore 執行期支援 WebSocket 連線的 OAuth 承載字符身分驗證。若要使用 OAuth 身分驗證,您需要使用 JWT 授權來設定代理程式執行期,如驗證和使用傳入身分驗證和傳出身分驗證進行授權的 JWT 傳入授權和 OAuth 傳出存取範例一節中所述。
完成 OAuth 設定並依照步驟 4:使用承載權杖在 OAuth 指南中叫用代理程式後,您可以使用該權杖來建立 WebSocket 連線。 OAuth
具有 OAuth 的 Python 用戶端
下列範例示範如何使用 OAuth 從 Python 建立 WebSocket 連線:
from bedrock_agentcore.runtime import AgentCoreRuntimeClient import websockets import asyncio import json import os async def main(): # Get runtime ARN from environment variable runtime_arn = os.getenv('AGENT_ARN') if not runtime_arn: raise ValueError("AGENT_ARN environment variable is required") # Get OAuth bearer token from environment variable bearer_token = os.getenv('BEARER_TOKEN') if not bearer_token: raise ValueError("BEARER_TOKEN environment variable required for OAuth") # Initialize client client = AgentCoreRuntimeClient(region="us-west-2") # Generate WebSocket connection with OAuth ws_url, headers = client.generate_ws_connection_oauth( runtime_arn=runtime_arn, bearer_token=bearer_token ) try: async with websockets.connect(ws_url, additional_headers=headers) as ws: # Send message await ws.send(json.dumps({"inputText": "Hello!"})) # Receive response response = await ws.recv() print(f"Received: {response}") except websockets.exceptions.InvalidStatus as e: print(f"WebSocket handshake failed with status code: {e.response.status_code}") print(f"Response headers: {e.response.headers}") print(f"Response body: {e.response.body.decode()}") except Exception as e: print(f"Connection failed: {e}") if __name__ == "__main__": asyncio.run(main())
執行 用戶端以測試您部署的代理程式:
python websocket_agent_client_oauth.py
成功:您應該會看到如下的回應:
Received: {"echo":{"inputText":"Hello!"}}
使用 OAuth 的瀏覽器 JavaScript 用戶端
瀏覽器的原生 WebSocket API 不提供在交握期間設定自訂標頭的方法。為了支援瀏覽器的 OAuth 身分驗證,AgentCore 執行期接受 WebSocket 交握期間內嵌在 Sec-WebSocket-Protocol標頭中的承載字符。
字符必須是 base64url 編碼,字首為 base64UrlBearerAuthorization. ,後面接著 sentinel 子通訊協定 base64UrlBearerAuthorization。
下列範例示範如何使用 OAuth 從瀏覽器 JavaScript 建立 WebSocket 連線:
<!DOCTYPE html> <html> <body> <button onclick="connect()">Connect</button> <div id="output"></div> <script> function connect() { const bearerToken = "your_oauth_token_here"; const runtimeArn = "arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/agent-xyz123"; // Base64url encode token const base64url = btoa(bearerToken) .replace(/\+/g, '-') .replace(/\//g, '_') .replace(/=/g, ''); const ws = new WebSocket( `wss://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/${runtimeArn}/ws`, [`base64UrlBearerAuthorization.${base64url}`, "base64UrlBearerAuthorization"] ); ws.onopen = () => ws.send(JSON.stringify({ inputText: "Hello!" })); ws.onmessage = (e) => document.getElementById("output").innerText = e.data; } </script> </body> </html>
注意
此身分驗證方法適用於無法設定自訂標頭的瀏覽器型用戶端。對於非瀏覽器用戶端 (Python、Node.js 伺服器等),請使用 Python 用戶端中顯示的 OAuth 標頭身分驗證與 OAuth。 OAuth
注意
base64UrlBearerAuthorization 尚不支援 以外的子通訊協定。
重要
這是參考範例。不建議在生產程式碼中硬式編碼字符。
工作階段管理
在 WebSocket X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 連線上提供 session_id() (做為 URL 查詢參數或請求標頭) 會將連線路由至隔離的執行階段工作階段。客服人員可以存取存放在該工作階段中的對話內容,透過參考先前的互動來實作對話的持續性。不同的工作階段 IDs會存取個別的隔離內容,確保使用者或對話之間完全隔離。
如需完整的工作階段生命週期管理,包括追蹤、清除和錯誤處理,請參閱使用客服人員的隔離工作階段。
搭配 WebSocket 連線使用工作階段
若要搭配 WebSocket 連線使用工作階段,請為每個使用者或對話產生唯一的工作階段 ID,並在建立連線時傳遞它:
範例
提示
為了獲得最佳結果,請為您的工作階段 IDs 使用 UUID 或其他唯一識別符,以避免不同使用者或對話之間發生衝突。
透過將相同的工作階段 ID 用於相關的 WebSocket 連線,您可以確保在相同的對話中維護內容,讓您的客服人員能夠提供以先前互動為基礎的一致回應。
具有 WebSocket 連線的工作階段生命週期
對於 WebSocket 連線,每次用戶端和代理程式之間有訊息活動時,都會重設工作階段的閒置逾時。這包括任何 WebSocket 訊息交換,例如從用戶端傳送資料到代理程式、從代理程式接收回應到用戶端,或 WebSocket ping/pong 影格。這表示只要訊息繼續流動,作用中的 WebSocket 對話就會讓工作階段保持運作狀態,防止工作階段在持續互動期間提早終止。
如需設定生命週期設定的詳細資訊,請參閱設定 Amazon Bedrock AgentCore 生命週期設定。如需透過客服人員運作狀態更直接控制工作階段生命週期,請參閱執行期工作階段生命週期管理。
停止執行階段工作階段
若要在可設定之前停止執行中的工作階段 IdleRuntimeSessionTimeout(預設為 15 分鐘),請參閱停止執行中的工作階段。
可觀測性
Amazon Bedrock AgentCore 可觀測性可協助您追蹤、偵錯和監控您在 Amazon Bedrock AgentCore 執行期中託管的代理程式。首先,遵循啟用 Amazon Bedrock AgentCore 執行時間可觀測性 中的指示來啟用 CloudWatch 交易搜尋。若要觀察您的代理程式,請參閱檢視 Amazon Bedrock AgentCore 代理程式的可觀測性資料。
對於 WebSocket 連線,追蹤代表完整的連線工作階段,而不是個別訊息交換。
自訂標頭
自訂標頭可讓您將內容資訊從應用程式直接傳遞至初始 WebSocket 連線上的代理程式程式碼。如需自訂標頭支援、組態和限制的完整資訊,請參閱將自訂標頭傳遞至 Amazon Bedrock AgentCore 執行期。
此外,字首為 的標頭X-Amzn-Bedrock-AgentCore-Runtime-Custom-可以做為 WebSocket 連線中的 URL 查詢參數傳遞。
例如,您可以在 WebSocket URL 中將自訂標頭做為查詢參數傳遞:
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<agentRuntimeArn>/ws?X-Amzn-Bedrock-AgentCore-Runtime-Custom-TestHeader=query-param-test-value
代理程式應用程式容器將以標頭的形式接收這些內容:
"headers": { "x-amzn-bedrock-agentcore-runtime-custom-testheader": "query-param-test-value" }
附錄
安全考量
提示
如需所有執行期安全建議的合併檢視,請參閱 AgentCore 執行期的安全最佳實務。
- 身分驗證
-
所有 WebSocket 連線都需要透過 SigV4 或 OAuth 2.0 進行適當的 AWS 身分驗證
- 工作階段隔離
-
每個工作階段都會在具有專用資源的隔離執行環境中執行
- 傳輸安全性
-
所有連線都透過 HTTPS 使用 WSS (WebSocket Secure) 進行加密通訊
- 存取控制
-
IAM 政策控制 WebSocket 連線許可和對特定客服人員的存取
疑難排解
常見 WebSocket 特定問題
以下是您可能遇到的常見問題:
- 連線失敗
-
驗證您的代理程式應用程式在 處理連線請求
/ws - 身分驗證方法不符
-
確保您的用戶端使用與設定代理程式相同的身分驗證方法 (OAuth 或 SigV4)
- 連線因超過限制而關閉
-
如果超過限制,連線會自動關閉,例如訊息影格率或訊息影格大小限制。如需完整的限制資訊,請參閱 Amazon Bedrock AgentCore 的配額
- 超過訊息影格大小
-
設定訊息影格分割或實作區塊,以保持在 32KB 影格大小限制以下。在傳送之前,將大型訊息分割成較小的區塊
- 運作狀態檢查失敗
-
確保您的代理程式容器實作 HTTP 通訊協定合約 中指定的
/ping端點。此端點會驗證您的代理程式是否正常運作並準備好處理請求,進而啟用服務監控和自動化復原
錯誤處理
WebSocket 連線使用標準關閉碼進行錯誤通訊。常見的關閉代碼包括:
-
1000- 正常關閉 -
1001- 離開 -
1008- 違反政策 (超過限制) -
1009- 訊息太大 (超過訊息框架大小限制) -
1011- 伺服器錯誤
WebSocket 與其他通訊協定的比較
使用 WebSocket 的時機:
-
使用即時音訊串流進行即時語音對話,實現自然對話流程
-
雙向audio/text/binary資料流程 (將資料區塊從用戶端串流至客服人員,反之亦然)
-
中斷處理 (使用者可以在對話中中斷客服人員)
使用 HTTP 的時機:
-
HTTP 用於不需要雙向串流的請求回應模式
其他入門範例
如需使用 WebSocket 雙向串流搭配 AgentCore 執行期的其他範例,請參閱 WebSocket 雙向串流 GitHub 範例
-
Sonic 實作 (Python):具有即時音訊對話、語音選擇和中斷支援的原生 Amazon Nova Sonic WebSocket 實作
-
Strands 實作 (Python):使用 Strands BidiAgent 的架構型實作,透過自動工作階段管理和工具整合進行簡化的即時音訊對話
-
Echo 實作 (Python):用於測試 WebSocket 連線和身分驗證的簡易 echo 伺服器