Interactive Shells (Terminals)

The InvokeAgentRuntimeCommandShell operation opens a persistent, interactive terminal session inside a running AgentCore Runtime session over WebSocket. Unlike one-shot command execution, shell sessions maintain state — environment variables, working directory, and command history carry across inputs. This enables debugging, environment inspection, and building terminal experiences in your application.

To call InvokeAgentRuntimeCommandShell, you need bedrock-agentcore:InvokeAgentRuntimeCommandShell permissions.

How it works

InvokeAgentRuntimeCommandShell establishes a WebSocket connection to an interactive shell process running inside your agent’s session. The connection uses binary frames to stream terminal input and output in both directions.

Same agent, same session

InvokeAgentRuntimeCommandShell operates on the same agent runtime as InvokeAgentRuntime and InvokeAgentRuntimeCommand. You don’t create separate resources. The agent you deployed with CreateAgentRuntime accepts shell connections on any active session.

The connection supports:

Prerequisites

Using the AgentCore CLI

For installation and setup instructions, see Get started with AgentCore Runtime using the CLI.

The CLI provides a built-in terminal experience with agentcore exec.

agentcore exec --it

To connect to a specific runtime:

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

Press Ctrl+] to detach from a shell without closing it. The CLI prints a reconnect command:

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

For one-shot commands, omit --it:

agentcore exec "ls -la /tmp"

For machine-readable output, use JSON mode:

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

For additional CLI examples, see AgentCore samples on GitHub.

Using the AgentCore SDK

Install the Python SDK:

pip install bedrock-agentcore

Reconnection

A common pattern is to use shellId to reconnect to a shell after a disconnect, preserving all session state.

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())

Auto-reconnect

The SDK can also automatically reconnect when the WebSocket connection drops. Use ReconnectConfig to enable this:

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())

For additional SDK examples, see AgentCore samples on GitHub.

Common use cases

Key design choices

Security considerations

The security boundary for shell sessions (terminals) is the microVM. Each AgentCore Runtime session runs in an isolated microVM with its own kernel, memory, and filesystem. Shell sessions cannot access other customers' workloads or escape the VM boundary. However, within your VM, shell commands have full access to the container filesystem and any credentials or secrets you have configured.

Auditing with CloudWatch Logs

AgentCore Runtime sends the request ID and connection metadata to your agent’s Amazon CloudWatch Logs log group. You can use these logs to monitor shell connection activity and maintain an audit trail. Terminal I/O content (stdin/stdout) is streamed to your client and is not logged by the service.

Auditing with CloudTrail

AWS CloudTrail records InvokeAgentRuntimeCommandShell API calls in your account. Each record includes metadata such as the caller identity, timestamp, source IP address, and response status. CloudTrail does not log the request or response payload. Use CloudTrail to audit who opened shell sessions and when, then correlate with CloudWatch Logs using the request ID for connection details.

For sensitive workloads, consider implementing additional controls such as:

Error handling

When establishing a shell session connection, you might encounter the following errors during the WebSocket upgrade:

Once connected, the following close codes indicate why a connection was terminated:

Best practices

Follow these best practices when using InvokeAgentRuntimeCommandShell:

Quotas and limits

For complete service limits, see Quotas for Amazon Bedrock AgentCore.