運作方式先決條件透過 WebSocket API 連線二進位影格通訊協定重新連線至 shell 常用案例安全考量錯誤處理最佳實務配額和限制相關主題

互動式 shell （終端機）

InvokeAgentRuntimeCommandShell 操作會透過 WebSocket 在執行中的 AgentCore 繫帶工作階段中開啟持久的互動式終端機。API 會使用執行期工作階段 ID 來識別此繫帶工作階段。與一次性命令執行不同，互動式 shell 會維護其環境變數、工作目錄、命令歷史記錄，以及跨輸入執行程序。

當您需要跨命令保留 shell 狀態時，請使用互動式 shell 進行偵錯、反覆開發或長時間執行的程序。

對於 SigV4 和 SigV4 預先簽署的請求，發起人需要集合的bedrock-agentcore:InvokeAgentRuntimeCommandShell許可。承載字符請求必須滿足繫帶傳入授權方。

重要

在啟動時，AgentCore CLI 命令和高階 AgentCore SDK shell 協助程式不支援繫帶目標。直接透過 InvokeAgentRuntimeCommandShell WebSocket API 連接到繫帶殼層，如本頁所示。

運作方式

InvokeAgentRuntimeCommandShell 在執行繫帶工作階段的 microVM 中，建立與互動式 shell 程序的 WebSocket 連線。連線使用二進位影格以雙向串流終端機輸入和輸出。

如果繫帶使用預設環境，殼層會在受管繫帶環境中執行。如果繫帶使用自訂容器，殼層會在該容器中執行。利用互動式終端機目前僅支援 Bash。

連線支援：

功能	說明
持久性狀態	環境變數、工作目錄、命令歷史記錄和執行中的程序會保留在相同的 shell 中。
重新連線	提供相同的執行期工作階段 ID 和 `shellId`，以重新連線至分離的 shell。服務會重播最多 256 KB 的緩衝輸出。
多個並行 shell	在一個繫帶工作階段上開啟最多 10 個作用中 Shell 工作階段。分離的殼層不會計入此限制。每個 shell 都有獨立的終端機程序，並共用工作階段檔案系統。

先決條件

處於 READY 狀態的繫帶
所選身分驗證方法的授權：SigV4 bedrock-agentcore:InvokeAgentRuntimeCommandShell 的 IAM 許可，或安全機制傳入授權方接受的承載字符
支援二進位影格和請求標頭或預先簽章 URLs WebSocket 用戶端
對於自訂容器，Bash 安裝在 /bin/bash。dash目前不支援其他 Shell，包括 sh和。

如需完整繫帶許可模型的詳細資訊，請參閱呼叫者所需的 IAM 許可。

透過 WebSocket API 連線

開啟下列 URL 的 WebSocket 連線：


wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells

使用繫帶 ARN，而不是其受管執行期的 ARN。將完整的繫帶 ARN 放入路徑之前，先進行 URL 編碼。繫帶 ARN 的格式如下：


arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<harnessId>

使用 WebSocket 升級請求傳送下列值：

Value	必要	說明
身分驗證	是	使用 Signature 第 4 版 (SigV4) 簽署請求、使用 SigV4 預先簽署的 URL，或傳送 `Authorization`標頭中繫帶傳入授權方設定的承載字符。SigV4 服務名稱為 `bedrock-agentcore`。
`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` 標頭或查詢參數	否	以現有的繫帶工作階段為目標，或使用提供的 ID 建立一個。值必須至少包含 33 個字元。如果您省略它，服務會建立執行期工作階段 ID，並在回應中傳回它。
`Sec-WebSocket-Protocol`	否	對於 SigV4 連線，選擇性提供 `v1.command.agentcore.aws.dev`來識別命令殼層二進位通訊協定。Bearer-token 連線會改用此表格後所述的身分驗證子通訊協定。
`shellId` 查詢參數	否	重新連線至現有的 shell。將其與建立 shell 的相同執行期工作階段 ID 搭配使用。

對於無法設定 Authorization 標頭的瀏覽器用戶端，Base64url 會編碼承載字符，並透過同時提供 base64UrlBearerAuthorization.<encoded-token>和 base64UrlBearerAuthorization sentinelSec-WebSocket-Protocol。請勿v1.command.agentcore.aws.dev同時提供承載字符連線。

101 Switching Protocols 回應會在和 X-Amzn-Bedrock-AgentCore-Shell-Id標頭中傳回執行階段工作階段 ID X-Amzn-Bedrock-AgentCore-Runtime-Session-Id和 Shell ID。無法讀取 WebSocket 升級回應標頭的用戶端可以從第一個STATUS影格讀取 Shell ID。框架不包含執行階段工作階段 ID，因此這些用戶端必須在連線之前產生並保留執行階段工作階段 ID。當您建立預先簽章的 URL 時，請在簽署 URL 之前將執行階段工作階段 ID 納入為查詢參數。

WebSocket 升級逾時僅適用於直到服務傳回為止101 Switching Protocols。Shell 和自訂容器初始化可以在升級後繼續。等待初始STATUS影格，再將 shell 視為就緒、在等待時套用個別的應用程式逾時，並將關閉程式碼處理1011為 shell 初始化或伺服器故障。

下列 Python 範例使用一般 WebSocket 用戶端，且botocore僅用於簽署升級請求。它不使用 AgentCore SDK shell 協助程式。


pip install "boto3>=1.34" "websockets>=15"


import asyncio
import json
import urllib.parse
import uuid

import botocore.session
import websockets
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest


REGION = "us-west-2"
HARNESS_ARN = (
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:"
    "harness/MyHarness-a1b2c3d4e5"
)
SESSION_ID = str(uuid.uuid4())  # 36 characters
SUBPROTOCOL = "v1.command.agentcore.aws.dev"


def signed_headers(url):
    request = AWSRequest(
        method="GET",
        url=url,
        headers={
            "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": SESSION_ID,
        },
    )
    credentials = botocore.session.Session().get_credentials()
    SigV4Auth(credentials, "bedrock-agentcore", REGION).add_auth(request)
    return dict(request.headers)


async def main():
    encoded_arn = urllib.parse.quote(HARNESS_ARN, safe="")
    host = f"bedrock-agentcore.{REGION}.amazonaws.com"
    path = f"/runtimes/{encoded_arn}/ws/shells"
    https_url = f"https://{host}{path}"
    websocket_url = f"wss://{host}{path}"

    async with websockets.connect(
        websocket_url,
        additional_headers=signed_headers(https_url),
        subprotocols=[SUBPROTOCOL],
        open_timeout=330,
    ) as websocket:
        shell_id = websocket.response.headers.get(
            "X-Amzn-Bedrock-AgentCore-Shell-Id"
        )
        print(f"Connected to shell {shell_id}")

        # Channel 0x00 carries terminal input.
        await websocket.send(b"\x00echo 'Hello from my harness'\n")
        await websocket.send(b"\x00exit\n")

        async for frame in websocket:
            if isinstance(frame, str) or not frame:
                continue

            channel, payload = frame[0], frame[1:]
            if channel == 0x01:  # PTY output (command stdout and stderr)
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x02:  # Service or platform diagnostics
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x03:  # STATUS
                status = json.loads(payload)
                shell_id = status.get("metadata", {}).get("shellId", shell_id)
                print(f"\nStatus: {status}")


asyncio.run(main())

二進位影格通訊協定

每個應用程式層級訊息都是二進位 WebSocket 框架。第一個位元組識別頻道，其餘位元組則是承載。

Channel	Direction	酬載
`0x00` - STDIN	用戶端到服務	原始終端機輸入。
`0x01` - STDOUT	用戶端的服務	原始 PTY 輸出。PTY 在此頻道上結合命令 stdout 和 stderr。
`0x02` - STDERR	用戶端的服務	服務或平台診斷。Command stderr 是 `0x01` PTY 輸出的一部分。
`0x03` - 狀態	用戶端的服務	包含連線中繼資料或 Shell 結束狀態的 UTF-8 JSON。
`0x04` - RESIZE	用戶端到服務	UTF-8 JSON，格式為 `{"width":120,"height":40}`。每個維度必須介於 1 到 1，000 之間。
`0x05` - HEARTBEAT	兩個方向	選用的應用程式活動訊號。服務會回應承載。也支援 WebSocket ping 影格。
`0xFF` - 關閉	兩個方向	結束 shell 工作階段。

文字影格不屬於通訊協定。此服務會忽略隔離的文字影格，並在連續五個文字影格1003後關閉與程式碼的連線。

第一個STATUS影格會確認連線，並包含類似以下的中繼資料：


{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    "shellId": "my-shell",
    "reconnected": false
  },
  "status": "Success"
}

當 Shell 以非零狀態結束時，最終STATUS影格會在中包含ExitCode原因details.causes。

重新連線至 shell

同時存放執行階段工作階段 ID 和 shell ID。若要重新連線，請使用相同的執行階段工作階段 ID 標頭，並將 URL 編碼的 Shell ID 新增為查詢參數：


wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells?shellId=<shell-id>

shell 程序會在連線分離時繼續執行。重新連線時，服務會重播最多 256 KB 的緩衝輸出。如果分離metadata.bytesDropped的殼層產生的輸出超過重播緩衝區可以保留的輸出，則連線STATUS框架會metadata.reconnected設定為 true並包含。

使用相同的 Shell ID 開啟另一個連線會取代現有的連線。取代的用戶端會收到關閉碼 4000。

常用案例

互動式偵錯: 檢查已安裝的套件、檔案、程序和環境組態，這些套件、檔案、程序和環境組態都位於與 harness 代理程式相同的環境中。
自訂環境驗證: 對於具有自訂容器的繫帶，請從該容器內部驗證已安裝的相依性和檔案系統掛載。
編碼代理程式終端機存取: 提供持久性執行環境，用於編碼需要建立檔案、執行測試、檢查輸出和反覆運算的代理程式。
長時間執行的程序: 啟動程序、從 WebSocket 分離，然後稍後重新連線以檢查進度或提供輸入。

安全考量

重要

可以開啟 Harness shell 的委託人具有繫帶工作階段的互動式命令存取權。僅限於bedrock-agentcore:InvokeAgentRuntimeCommandShell信任的委託人和特定的集合 ARNs。

shell 可以在選取的環境或掛載的檔案系統上存取客戶提供的資料、檔案和秘密。它也可以連接到工作階段可以到達的網路目的地。shell 環境使用允許清單，不會插入 AgentCore 平台或工作負載登入資料。shell 會保留在工作階段隔離的 microVM 中，且無法存取其他客戶的工作負載。

AgentCore 會將請求 ID 和連線中繼資料傳送至 Amazon CloudWatch Logs 中的 harness Runtime 日誌群組。服務不會記錄終端機輸入或輸出。

AWS CloudTrail 會記錄 InvokeAgentRuntimeCommandShell API 呼叫，包括呼叫者身分、時間戳記、來源 IP 地址、已解析的執行時間資源和回應狀態。CloudTrail 不會記錄終端機輸入或輸出。

如需更多利用安全指引，請參閱安全性和存取控制。

錯誤處理

WebSocket 升級可能會傳回下列錯誤：

ValidationException: 請求參數無效。確認執行階段工作階段 ID 至少包含 33 個字元、殼層 ID 有效，且功能可在目標區域中使用。在請求路徑中使用 URL 編碼的繫帶 ARN；直接使用受管執行期 ARN 會遭到拒絕。
AccessDeniedException: 發起人沒有集合的bedrock-agentcore:InvokeAgentRuntimeCommandShell許可。
ResourceNotFoundException: 指定的繫帶不存在。確認 URL 包含 URL 編碼的繫帶 ARN。
ServiceQuotaExceededException (429): 最多 10 個作用中 Shell 已開啟。結束作用中 shell 或將其分離，然後重試。
RuntimeClientError (424): 無法達到執行時間。
ThrottlingException: 請求超過 API 速率限制。以指數退避重試。
RetryableConflictException (409): 服務正在佈建或銷毀目標工作階段。以短指數退避重試。

連線後，以下關閉代碼會指出連線結束的原因：

Code	意義	用戶端動作
`1000`	shell 已順利退出。	視為正常終止。
`1003`	用戶端將五個連續的文字影格傳送至僅限二進位的通訊協定。	切換到二進位影格。不要自動重新連線相同的行為。
`1006`	由於網路故障或服務中斷，連線在沒有關閉影格的情況下結束。	使用儲存的 Shell ID 重新連線。
`1008`	一小時連線持續時間已過期、影格率超過每秒 250 個影格，或寫入緩衝區溢位。	重新連線持續時間到期。對於速率或緩衝區違規，請在重新連線之前關閉。
`1009`	框架承載超過 64 KB。	將承載分割為小於 64 KB 的影格，然後重新連線。
`1011`	發生非預期的伺服器故障。	以指數退避重試。
`4000`	使用相同 shell ID 連線的另一個用戶端。	不要自動重新連線。通知使用者另一個用戶端連接到 shell。

最佳實務

為每個邏輯終端機產生並保留唯一的 Shell ID。
使用 Shell ID 保留執行階段工作階段 ID。需要這兩個值才能重新連線。
立即讀取輸出，讓連線寫入緩衝區不會填滿。
將大型輸入分割為小於 64 KB 的二進位影格。
如果 shell 必須保留更長的可用時間，請在一小時連線限制之前或之後重新連線。
不再需要 shell 時，明確結束 shell。分離的殼層不會計入 10-active-shell 限制。此服務會保留最多 20 個作用中和分離的 shell 項目，並在必要時移出最舊的分離 shell。
當連線可以啟動冷繫帶工作階段時，請使用至少 330 秒的升級逾時。在升級後等待初始STATUS影格時套用個別的逾時。

配額和限制

限制	Value	說明
影格承載上限	64 KB	較大的影格會導致關閉程式碼 `1009`。
影格播放速率	每秒 250 個影格	超過限制會導致關閉程式碼 `1008`。
連線持續時間上限	1 小時	使用相同的執行階段工作階段 ID 和 Shell ID 重新連線以繼續。
每個集合工作階段的並行作用中 Shell	10	當 10 個 Shell 處於作用中狀態時，會拒絕新的連線。分離的殼層不會計入此限制。
保留的作用中和分離的 shell 項目	20	達到限制時，服務會先移出最舊的分離殼層，再建立另一個殼層。
重新連線緩衝區	256 KB	重新連線後重新播放的最大輸出。

如需完整的服務限制，請參閱 Amazon Bedrock AgentCore 的配額。