What's New

Amazon Bedrock AgentCore Runtime now supports interactive shell sessions via a new InvokeAgentRuntimeCommandShell API, enabling developers to open a persistent, PTY-backed terminal directly inside a running agent's microVM over WebSocket. This complements the existing one-shot InvokeAgentRuntimeCommand API by providing a full terminal experience with persistent state, colors, tab completion, and reconnect support. The feature is especially targeted at developers hosting coding agents such as Claude Code, OpenAI Codex, and Amazon Kiro, who need to inspect, debug, and interact with live agent environments in real time.

How It Works

• InvokeAgentRuntimeCommandShell establishes a persistent WebSocket connection to an interactive shell process (PTY-backed) running inside the agent's isolated microVM, streaming terminal I/O as binary frames in both directions.
• Shell sessions maintain full state across commands within the same session — environment variables, working directory, and command history all persist, behaving exactly like a local terminal.
• Each session is identified by a session_id and a shell_id; providing both on reconnect lands the developer back in the exact same shell, with up to 256 KB of buffered output replayed.
• Brief network interruptions trigger automatic reconnection; longer disconnects can be resumed manually by supplying the stored session_id and shell_id.
• A single agent runtime supports up to 10 concurrent shell sessions, enabling parallel terminal windows against the same or different microVMs.
• The AgentCore CLI exposes this capability via agentcore exec --it --runtime <runtime-arn>, with Ctrl+] to detach without closing the shell and a printed reconnect command for later resumption.
• The operation requires the bedrock-agentcore:InvokeAgentRuntimeCommandShell IAM permission and a runtime in READY state; agents deployed before June 5, 2026 must be redeployed to gain support.

Why It's Important

• Coding agents like Claude Code and Amazon Kiro inherently require interactive terminal access to inspect files, run ad-hoc commands, and react to dynamic environment state — capabilities that one-shot execution cannot provide.
• Persistent shell state eliminates the need to re-establish environment context on every command, dramatically reducing latency and complexity for multi-step debugging workflows.
• The reconnect mechanism with buffered output replay makes the feature viable for long-running agent sessions over unreliable networks, a critical requirement for production developer tooling.
• Up to 10 concurrent shells per runtime allows teams to observe multiple agent branches executing in parallel, accelerating debugging and experimentation cycles.
• By providing a native terminal UX inside an isolated microVM, AWS removes the need for developers to build custom tunneling or SSH infrastructure to introspect agent environments.

How It's Different

• Unlike the existing InvokeAgentRuntimeCommand (HTTP/2, stateless, one-shot), InvokeAgentRuntimeCommandShell uses WebSocket for a persistent, bidirectional connection that preserves full shell state across inputs.
• Output is raw binary terminal I/O supporting ANSI colors, cursor control, and full-screen applications, whereas one-shot execution returns structured events (contentStart, contentDelta, contentStop) with an exit code.
• Interactive shells support reconnection via shellId with output buffering; one-shot commands have no reconnection concept since each call is fully independent.
• Interactive sessions have a 1-hour maximum duration but can be extended by reconnecting with the same IDs, while one-shot commands have a configurable timeout of 1–3,600 seconds per call.
• The CLI --it flag mirrors the familiar docker exec -it pattern, lowering the learning curve for developers already accustomed to container-based development workflows.

When to Prefer It

• Use interactive shells when you need to explore or debug a live agent environment interactively — inspecting files, checking process state, or running exploratory commands whose output informs the next step.
• Prefer interactive shells when building terminal UI experiences for coding agents (Claude Code, Amazon Kiro, OpenAI Codex) that require a real PTY with colors, tab completion, and cursor control.
• Choose interactive shells when a sequence of commands must share environment variables, working directory, or shell history — for example, activating a virtual environment and then running tests within it.
• Use interactive shells when working over potentially unstable network connections where automatic reconnect and output buffering are needed to avoid losing session context.
• Prefer interactive shells when you want to watch multiple agent branches work in parallel by opening several concurrent terminal windows against the same runtime.
• Stick with one-shot InvokeAgentRuntimeCommand for automated CI/CD pipelines, deterministic validation gates, or any scenario where a single known command runs independently and a structured exit code is required.

Availability

• Generally available as of June 5, 2026, with no preview or beta qualifier indicated in the announcement.
• Agents deployed before June 5, 2026 must be redeployed to enable interactive shell support; agents created on or after this date support the feature automatically.
• Region availability is not explicitly stated in the announcement; availability is expected to follow the existing AgentCore Runtime regional footprint.
• Pricing details are not specified in the announcement; costs are expected to align with existing AgentCore Runtime session pricing, but developers should consult the AWS pricing page for confirmation.
• A hard limit of 10 concurrent active shell sessions per agent runtime applies; new connection attempts are rejected when at capacity.
• The bedrock-agentcore:InvokeAgentRuntimeCommandShell IAM permission must be explicitly granted; it is not inherited from existing AgentCore Runtime permissions.

Related Resources

• https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-command-shell.html
• https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-shell-execution.html