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

InvokeAgentRuntimeCommandShell オペレーションは、WebSocket 経由で実行中の AgentCore ランタイムセッション内で永続的でインタラクティブなターミナルセッションを開きます。ワンショットコマンド実行とは異なり、シェルセッションは環境変数、作業ディレクトリ、コマンド履歴などの状態を維持します。これにより、アプリケーションのデバッグ、環境検査、ターミナルエクスペリエンスの構築が可能になります。

を呼び出すにはInvokeAgentRuntimeCommandShell、 アクセスbedrock-agentcore:InvokeAgentRuntimeCommandShell許可が必要です。

仕組み

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

同じエージェント、同じセッション

InvokeAgentRuntimeCommandShell は、 InvokeAgentRuntimeおよび と同じエージェントランタイムで動作しますInvokeAgentRuntimeCommand。個別のリソースは作成しません。でデプロイしたエージェントは、アクティブなセッションでシェル接続CreateAgentRuntimeを受け入れます。

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

前提条件

AgentCore CLI の使用

インストールとセットアップの手順については、「 CLI を使用した AgentCore ランタイムの開始方法」を参照してください。

CLI は、 の組み込みターミナルエクスペリエンスを提供しますagentcore exec。

agentcore exec --it

特定のランタイムに接続するには:

agentcore exec --it --runtime <runtime-arn> --region us-west-2

シェルを閉じることなくシェルからCtrl+]デタッチするには、 を押します。CLI は再接続コマンドを出力します。

agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

ワンショットコマンドの場合は、 を省略します--it。

agentcore exec "ls -la /tmp"

機械読み取り可能な出力の場合は、JSON モードを使用します。

agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

その他の CLI の例については、GitHub のAgentCore サンプル」を参照してください。

AgentCore SDK の使用

Python SDK をインストールします。

pip install bedrock-agentcore

再接続

一般的なパターンは、切断後に を使用してシェルに再接続shellIdし、すべてのセッション状態を維持することです。

import asyncio

from bedrock_agentcore.runtime import AgentCoreRuntimeClient

async def main():
    client = AgentCoreRuntimeClient(region="us-west-2")
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    session_id = "my-session-0000000000000000000000"
    shell_id = "my-shell"

    shell = await client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ).__aenter__()
    print(f"connected (reconnected={shell.reconnected})")
    await shell.send("export GREETING='hello'\n")
    await asyncio.sleep(1)

    async with client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ) as shell2:
        print(f"reconnected (reconnected={shell2.reconnected})")
        assert shell2.reconnected


if __name__ == "__main__":
    asyncio.run(main())

自動再接続

また、WebSocket 接続が切断されたときに SDK が自動的に再接続することもできます。これを有効にするReconnectConfigには、 を使用します。

import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {reconnected}")

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    shell_id = "my-persistent-shell"
    config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect)

    client = AgentCoreRuntimeClient(region="us-west-2")
    async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell:
        # If the connection drops, the SDK retries automatically
        await shell.send("long-running-command\n")
        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")

asyncio.run(main())

その他の SDK の例については、GitHub のAgentCore サンプル」を参照してください。

一般的なユースケース

主な設計選択肢

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

シェルセッション (ターミナル) のセキュリティ境界は microVM です。各 AgentCore ランタイムセッションは、独自のカーネル、メモリ、ファイルシステムを持つ分離されたmicroVM で実行されます。シェルセッションは、他の顧客のワークロードにアクセスしたり、VM の境界からエスケープしたりすることはできません。ただし、VM 内では、シェルコマンドはコンテナファイルシステム、および設定した認証情報またはシークレットにフルアクセスできます。

CloudWatch Logs を使用した監査

AgentCore Runtime は、リクエスト ID と接続メタデータをエージェントの Amazon CloudWatch Logs ロググループに送信します。これらのログを使用して、シェル接続アクティビティをモニタリングし、監査証跡を維持できます。ターミナル I/O コンテンツ (stdin/stdout) はクライアントにストリーミングされ、サービスによってログに記録されません。

CloudTrail を使用した監査

AWS CloudTrail は、アカウントに InvokeAgentRuntimeCommandShell API コールを記録します。各レコードには、発信者 ID、タイムスタンプ、送信元 IP アドレス、応答ステータスなどのメタデータが含まれます。CloudTrail はリクエストまたはレスポンスペイロードを記録しません。CloudTrail を使用して、シェルセッションを開いたユーザーとタイミングを監査し、接続の詳細のリクエスト ID を使用して CloudWatch Logs と関連付けます。

機密性の高いワークロードの場合は、次のような追加のコントロールを実装することを検討してください。

エラー処理

シェルセッション接続を確立すると、WebSocket のアップグレード中に次のエラーが発生することがあります。

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

ベストプラクティス

を使用する場合は、次のベストプラクティスに従ってくださいInvokeAgentRuntimeCommandShell。

クォータと制限

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