仕組み前提条件 WebSocket API 経由で接続するバイナリフレームプロトコルシェルへの再接続一般的なユースケースセキュリティに関する考慮事項エラー処理ベストプラクティスクォータと制限関連トピック

インタラクティブシェル (ターミナル)

InvokeAgentRuntimeCommandShell オペレーションは、WebSocket 経由で実行中の AgentCore ハーネスセッション内で永続的なインタラクティブターミナルを開きます。API は、このハーネスセッションをランタイムセッション ID で識別します。ワンショットコマンドの実行とは異なり、インタラクティブシェルは、環境変数、作業ディレクトリ、コマンド履歴、および入力間での実行プロセスを維持します。

コマンド間でシェルの状態を保持する必要がある場合は、デバッグ、反復開発、または長時間実行されるプロセスにインタラクティブなシェルを使用します。

SigV4 および SigV4 の署名付きリクエストの場合、発信者にはハーネスに対するbedrock-agentcore:InvokeAgentRuntimeCommandShellアクセス許可が必要です。ベアラートークンリクエストは、代わりにハーネスインバウンドオーソライザーを満たす必要があります。

重要

起動時に、AgentCore CLI コマンドと高レベルの AgentCore SDK シェルヘルパーはハーネスターゲットをサポートしていません。このページに示すように、InvokeAgentRuntimeCommandShellWebSocket API を介してハーネスシェルに直接接続します。

仕組み

InvokeAgentRuntimeCommandShell は、ハーネスセッションを実行するmicroVM 内のインタラクティブなシェルプロセスへの WebSocket 接続を確立します。接続はバイナリフレームを使用して、ターミナルの入出力を両方向にストリーミングします。

ハーネスがデフォルト環境を使用している場合、シェルはマネージドハーネス環境で実行されます。ハーネスがカスタムコンテナを使用している場合、シェルはそのコンテナで実行されます。ハーネスインタラクティブターミナルは現在、Bash のみをサポートしています。

接続は以下をサポートします。

機能	説明
永続状態	環境変数、作業ディレクトリ、コマンド履歴、実行中のプロセスが同じシェル内に保持されます。
再接続	デタッチされたシェルに再接続`shellId`するには、同じランタイムセッション ID とを指定します。このサービスは、最大 256 KB のバッファされた出力を再生します。
複数の同時シェル	1 つのハーネスセッションで最大 10 のアクティブなシェルセッションを開きます。デタッチされたシェルはこの制限にはカウントされません。各シェルには独立したターミナルプロセスがあり、セッションファイルシステムを共有します。

前提条件

READY 状態のハーネス
選択した認証方法の承認: SigV4 bedrock-agentcore:InvokeAgentRuntimeCommandShell の IAM アクセス許可、またはハーネスインバウンドオーソライザーによって受け入れられるベアラートークン
バイナリフレームとリクエストヘッダーまたは署名付き URLs をサポートする WebSocket クライアント
カスタムコンテナの場合、Bash はにインストールされます/bin/bash。sh やなどの他のシェルdashは現在サポートされていません。

完全なハーネスアクセス許可モデルの詳細については、「」を参照してください発信者に必要な 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 アップグレードリクエストで次の値を送信します。

値	必要	説明
Authentication	あり	署名バージョン 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`でコマンドシェルバイナリプロトコルを識別するを提供します。ベアラートークン接続は、代わりにこの表の後に説明されている認証サブプロトコルを使用します。
`shellId` クエリパラメータ	いいえ	既存のシェルに再接続します。シェルを作成したのと同じランタイムセッション ID で使用します。

Authorization ヘッダーを設定できないブラウザクライアントの場合、base64url はベアラートークンをエンコードし、 base64UrlBearerAuthorization.<encoded-token> と base64UrlBearerAuthorization の両方を経由で提供しますSec-WebSocket-Protocol。ベアラートークン接続v1.command.agentcore.aws.devでも提供しないでください。

101 Switching Protocols レスポンスは、および X-Amzn-Bedrock-AgentCore-Shell-Idヘッダーでランタイムセッション ID X-Amzn-Bedrock-AgentCore-Runtime-Session-Idとシェル ID を返します。WebSocket アップグレードレスポンスヘッダーを読み取れないクライアントは、最初のSTATUSフレームからシェル ID を読み取ることができます。フレームにはランタイムセッション ID が含まれていないため、これらのクライアントは接続する前にランタイムセッション ID を生成して保持する必要があります。署名付き URL を作成するときは、URL に署名する前にランタイムセッション ID をクエリパラメータとして含めます。

WebSocket のアップグレードタイムアウトは、サービスがを返すまで適用されます101 Switching Protocols。シェルとカスタムコンテナの初期化は、アップグレード後も続行できます。シェルを準備済みとして扱う前に最初のSTATUSフレームを待ち、待機中に別のアプリケーションタイムアウトを適用し、クローズコードをシェルの初期化またはサーバー障害1011として処理します。

次の Python の例では、一般的な WebSocket クライアントと botocoreを使用してアップグレードリクエストに署名します。AgentCore SDK シェルヘルパーを使用しません。


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 フレームです。最初のバイトはチャネルを識別し、残りのバイトはペイロードです。

チャネル	Direction	ペイロード
`0x00` - STDIN	クライアントからサービスへ	Raw ターミナル入力。
`0x01` - STDOUT	クライアントへのサービス	Raw PTY 出力。PTY は、このチャネルでコマンド stdout と stderr を組み合わせます。
`0x02` - STDERR	クライアントへのサービス	サービスまたはプラットフォームの診断。コマンド stderr は `0x01` PTY 出力の一部です。
`0x03` - ステータス	クライアントへのサービス	接続メタデータまたはシェルの終了ステータスを含む UTF-8 JSON。
`0x04` - サイズ変更	クライアントからサービスへ	形式の UTF-8 JSON`{"width":120,"height":40}`。各ディメンションは 1～1,000 である必要があります。
`0x05` - ハートベアト	両方向	オプションのアプリケーションハートビート。サービスはペイロードをエコーします。WebSocket ping フレームもサポートされています。
`0xFF` - 閉じる	両方向	シェルセッションを終了します。

テキストフレームはプロトコルの一部ではありません。このサービスは、分離されたテキストフレームを無視し、5 つの連続したテキストフレーム1003の後にコードとの接続を閉じます。

最初のSTATUSフレームは接続を確認し、次のようなメタデータを含めます。


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

シェルがゼロ以外のステータスで終了すると、最終STATUSフレームに ExitCodeの原因が含まれますdetails.causes。

シェルへの再接続

ランタイムセッション ID とシェル ID の両方を保存します。再接続するには、同じランタイムセッション ID ヘッダーを使用し、URL エンコードされたシェル ID をクエリパラメータとして追加します。


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

接続がデタッチされている間、シェルプロセスは引き続き実行されます。再接続時に、サービスは最大 256 KB のバッファ出力を再生します。接続STATUSフレームは metadata.reconnectedに設定trueされ、デタッチされたシェルが再生バッファが保持できるよりも多くの出力を生成metadata.bytesDroppedしたかどうかが含まれます。

同じシェル ID で別の接続を開くと、既存の接続が置き換えられます。置き換えられたクライアントはクローズコードを受け取ります4000。

一般的なユースケース

インタラクティブデバッグ: ハーネスエージェントと同じ環境で、インストールされているパッケージ、ファイル、プロセス、環境設定を検査します。
カスタム環境検証: カスタムコンテナを持つハーネスの場合は、そのコンテナ内からインストールされた依存関係とファイルシステムのマウントを確認します。
コーディングエージェントのターミナルアクセス: ファイルの作成、テストの実行、出力の検査、反復を行う必要があるエージェントをコーディングするための永続的な実行環境を提供します。
長時間実行中のプロセス: プロセスを開始し、WebSocket からデタッチし、後で再接続して進行状況を確認したり、入力を提供したりできます。

セキュリティに関する考慮事項

重要

Harness シェルを開くことができるプリンシパルには、ハーネスセッションへのインタラクティブなコマンドアクセスがあります。信頼できるプリンシパルと特定のハーネス ARN bedrock-agentcore:InvokeAgentRuntimeCommandShellに制限します。 ARNs

シェルは、選択した環境またはマウントされたファイルシステムで、お客様が提供したデータ、ファイル、シークレットにアクセスできます。また、セッションが到達できるネットワーク送信先に接続することもできます。シェル環境は許可リストを使用し、AgentCore プラットフォームまたはワークロード認証情報を挿入しません。シェルはセッションの分離されたmicroVM 内にとどまり、別の顧客のワークロードにアクセスすることはできません。

AgentCore は、Amazon CloudWatch Logs のハーネスランタイムロググループにリクエスト ID と接続メタデータを送信します。サービスはターミナルの入力または出力を記録しません。

AWS CloudTrail は、発信者 ID、タイムスタンプ、ソース IP アドレス、解決されたランタイムリソース、レスポンスステータスなどの InvokeAgentRuntimeCommandShell API コールを記録します。CloudTrail はターミナルの入力または出力を記録しません。

Harness セキュリティガイダンスの詳細については、「」を参照してくださいセキュリティとアクセス制御について。

エラー処理

WebSocket のアップグレードでは、次のエラーが発生する可能性があります。

ValidationException: リクエストパラメータが無効です。ランタイムセッション ID に 33 文字以上が含まれ、シェル ID が有効で、この機能がターゲットリージョンで使用可能であることを確認します。リクエストパスで URL エンコードされたハーネス ARN を使用します。マネージドランタイム ARN の直接使用は拒否されます。
AccessDeniedException: 発信者にはハーネスに対するbedrock-agentcore:InvokeAgentRuntimeCommandShellアクセス許可がありません。
ResourceNotFoundException: 指定されたハーネスは存在しません。URL に URL エンコードされたハーネス ARN が含まれていることを確認します。
ServiceQuotaExceededException (429): 最大 10 個のアクティブなシェルがすでに開いています。アクティブなシェルを終了するか、デタッチしてから再試行します。
RuntimeClientError (424): ランタイムに到達できませんでした。
ThrottlingException: リクエストが API レート制限を超えました。エクスポネンシャルバックオフを使用して再試行してください。
RetryableConflictException (409): サービスはターゲットセッションをプロビジョニングまたは破棄しています。短いエクスポネンシャルバックオフで再試行します。

接続すると、次のクローズコードは接続が終了した理由を示します。

コード	意味	クライアントアクション
`1000`	シェルは正常に終了しました。	通常の終了として扱います。
`1003`	クライアントは、バイナリのみのプロトコルに 5 つの連続したテキストフレームを送信しました。	バイナリフレームに切り替えます。同じ動作で自動的に再接続しないでください。
`1006`	ネットワーク障害またはサービスの中断により、接続はクローズフレームなしで終了しました。	保存されたシェル ID で再接続します。
`1008`	接続時間が 1 時間経過した場合、フレームレートが 1 秒あたり 250 フレームを超えた場合、または書き込みバッファがオーバーフローした場合。	有効期限が切れるまで再接続します。レートまたはバッファ違反の場合は、再接続する前にバックオフします。
`1009`	フレームペイロードが 64 KB を超えました。	ペイロードを 64 KB 未満のフレームに分割し、再接続します。
`1011`	予期しないサーバー障害が発生しました。	エクスポネンシャルバックオフを使用して再試行してください。
`4000`	同じシェル ID で接続された別のクライアント。	自動的に再接続しないでください。別のクライアントがシェルにアタッチしたことをユーザーに通知します。

ベストプラクティス

論理ターミナルごとに一意のシェル ID を生成して保持します。
ランタイムセッション ID をシェル ID で保持します。再接続には両方の値が必要です。
接続書き込みバッファがいっぱいにならないように、出力をすぐに読み取ります。
大きな入力を 64 KB 未満のバイナリフレームに分割します。
シェルをより長く使用する必要がある場合は、1 時間の接続制限の前後に再接続します。
不要になったシェルは明示的に終了します。デタッチされたシェルは、10-active-shell の制限にはカウントされません。このサービスは、最大 20 個のアクティブシェルエントリとデタッチシェルエントリを保持し、必要に応じて最も古いデタッチシェルを削除します。
接続がコールドハーネスセッションを開始できる場合は、少なくとも 330 秒のアップグレードタイムアウトを使用します。アップグレード後の最初のSTATUSフレームを待っている間に、別のタイムアウトを適用します。

クォータと制限

制限	値	説明
最大フレームペイロード	64 KB	フレームが大きいほど、クローズコードになります`1009`。
フレームレート	250 フレーム/秒	制限を超えると、クローズコードになります`1008`。
最大接続時間	1 時間	続行するには、同じランタイムセッション ID とシェル ID で再接続します。
ハーネスセッションあたりの同時アクティブシェル	10	10 個のシェルがアクティブな場合、新しい接続は拒否されます。デタッチされたシェルはこの制限にはカウントされません。
保持されたアクティブなシェルエントリとデタッチされたシェルエントリ	20	制限に達すると、サービスは別のシェルを作成する前に、最も古いデタッチされたシェルを削除します。
再接続バッファ	256 KB	再接続後に再生される最大出力。

完全なサービス制限については、「Amazon Bedrock AgentCore のクォータ」を参照してください。