View a markdown version of this page

Shell execution - Amazon Bedrock AgentCore
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Shell execution

Amazon Bedrock AgentCore Runtime lets you run shell commands inside a running agent’s session. Two modes are available depending on your use case:

One-shot command execution - InvokeAgentRuntimeCommand

Runs a single command, streams stdout/stderr over HTTP/2, and returns the exit code. Each command starts a fresh shell process with no persistent state. Best for automated pipelines, CI/CD gates, and deterministic operations.

Interactive shells (terminals) - InvokeAgentRuntimeCommandShell

Opens a persistent terminal session over WebSocket with full shell state (environment variables, working directory, history). Supports reconnection via shellId. Best for debugging, environment inspection, and terminal UIs.

Feature comparison

Feature One-shot (InvokeAgentRuntimeCommand) Interactive (InvokeAgentRuntimeCommandShell)

Protocol

HTTP/2 (request-response stream)

WebSocket (persistent connection)

Shell state

Stateless — each command starts a fresh process

Persistent — environment, working directory, and history carry across commands

Output format

Structured events (contentStart, contentDelta, contentStop with exit code)

Binary frames (raw terminal I/O — supports colors, cursor control, full-screen apps)

Reconnection

No — each call is independent

Yes, via shellId

Duration

Configurable timeout (1–3,600 seconds)

1 hour max (reconnect with same shellId to continue)

Choosing the right mode

Use one-shot execution when…​ Use interactive shells when…​

The operation has a known command (npm test, git push)

You need persistent shell state across multiple commands

You want deterministic execution with a structured exit code

You want to explore the environment interactively

You’re automating a CI/CD pipeline step or validation gate

You’re building a terminal UI (Claude Code, Amazon Kiro, OpenAI Codex)

Each command is independent with no shared state

You need reconnection support for long-running work

You’re bootstrapping the environment before the agent starts

You’re debugging or inspecting a running agent
Topics