Classmethod Bedrock Agentcore Shell API Web Terminal Poc
Amazon Bedrock AgentCoreのShell APIで、ブラウザーからKiro CLIを操作できるWebターミナルを作ってみた
- URL: https://dev.classmethod.jp/articles/bedrock-agentcore-shell-api-web-terminal-poc/
- 日付: 2026-06-07
- Tier: Tier 3
- 要旨: 2026/06/05に追加されたBedrock AgentCore RuntimeのShell API（InvokeAgentRuntimeCommandShell）を使い、xterm.js + Node.js中継サーバーでWebターミナルPoCを構築。WebSocketフレーム形式・SigV4署名・再接続設計を詳細に検証・解説。
詳細
Shell APIの概要
- AgentCore上のmicroVMにある対話シェルをWebSocket経由でリモート操作できる
- 接続エンドポイント:
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<arn>/ws/shells
フレーム形式（本検証で確認）
| チャネル | 方向 | 用途 |
|---|---|---|
| ch0 | Client→Agent | stdin（キー入力） |
| ch1 | Agent→Client | stdout |
| ch2 | Agent→Client | stderr |
| ch3 | Agent→Client | Shell確立通知（shellIdを含むJSON） |
| ch4 | Client→Agent | ターミナルリサイズ |
| ch5 | Client→Agent | ハートビート（30秒間隔） |
| ch255 | Client→Agent | Shell終了 |
制約値
- フレームサイズ: 64KB（超過でclose code 1009）
- フレームレート: 250 frames/sec（超過で1008）
- 接続TTL: 1時間
- 同時セッション上限: 10
再接続設計の発見
- ch255を送らずにWebSocket切断するとAgentCore側のShellセッションが維持される
- 同じsession_id + shellIdで再接続するとreplay bufferが再送される
- ブラウザー↔Node.jsは指数バックオフ（最大5回）で自動再接続
セキュリティ注意事項（本PoCは認証なしlocalhost専用）
0.0.0.0バインドのため-p 127.0.0.1:3000:3000でループバック限定公開が必須- Cross-Site WebSocket Hijacking対策のためOriginチェックが必要（本PoCでは省略）
- KIRO_API_KEYをstdin経由で渡すためPTYエコー・bash_history・replay bufferへの露出リスクあり