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

Interactive shells (terminals)

The InvokeAgentRuntimeCommandShell operation opens a persistent, interactive terminal inside a running AgentCore harness session over WebSocket. The API identifies this harness session with a runtime session ID. Unlike one-shot command execution, an interactive shell maintains its environment variables, working directory, command history, and running processes across inputs.

Use an interactive shell for debugging, iterative development, or long-running processes when you need to preserve shell state across commands.

For SigV4 and SigV4 pre-signed requests, the caller needs bedrock-agentcore:InvokeAgentRuntimeCommandShell permission on the harness. Bearer-token requests must satisfy the harness inbound authorizer instead.

How it works

InvokeAgentRuntimeCommandShell establishes a WebSocket connection to an interactive shell process in the microVM that runs your harness session. The connection uses binary frames to stream terminal input and output in both directions.

If the harness uses the default environment, the shell runs in the managed harness environment. If the harness uses a custom container, the shell runs in that container. Harness interactive terminals currently support Bash only.

The connection supports:

Prerequisites

For more information about the complete harness permissions model, see Required IAM permissions for callers.

Connect through the WebSocket API

Open a WebSocket connection to the following URL:

wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells

Use the harness ARN, not the ARN of its managed Runtime. URL-encode the complete harness ARN before putting it in the path. A harness ARN has the following format:

arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<harnessId>

Send the following values with the WebSocket upgrade request:

For a browser client that cannot set an Authorization header, base64url-encode the bearer token and offer both base64UrlBearerAuthorization.<encoded-token> and the base64UrlBearerAuthorization sentinel through Sec-WebSocket-Protocol. Do not also offer v1.command.agentcore.aws.dev on a bearer-token connection.

The 101 Switching Protocols response returns the runtime session ID and shell ID in the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id and X-Amzn-Bedrock-AgentCore-Shell-Id headers. Clients that cannot read WebSocket upgrade response headers can read the shell ID from the first STATUS frame. The frame doesn’t contain the runtime session ID, so these clients must generate and retain a runtime session ID before connecting. When you create a pre-signed URL, include the runtime session ID as a query parameter before signing the URL.

The WebSocket upgrade timeout applies only until the service returns 101 Switching Protocols. Shell and custom-container initialization can continue after the upgrade. Wait for the initial STATUS frame before treating the shell as ready, apply a separate application timeout while waiting, and handle close code 1011 as a shell initialization or server failure.

The following Python example uses a generic WebSocket client and botocore only to sign the upgrade request. It doesn’t use an AgentCore SDK shell helper.

pip install "boto3>=1.34" "websockets>=15"

import asyncio
import json
import urllib.parse
import uuid

import botocore.session
import websockets
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest


REGION = "us-west-2"
HARNESS_ARN = (
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:"
    "harness/MyHarness-a1b2c3d4e5"
)
SESSION_ID = str(uuid.uuid4())  # 36 characters
SUBPROTOCOL = "v1.command.agentcore.aws.dev"


def signed_headers(url):
    request = AWSRequest(
        method="GET",
        url=url,
        headers={
            "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": SESSION_ID,
        },
    )
    credentials = botocore.session.Session().get_credentials()
    SigV4Auth(credentials, "bedrock-agentcore", REGION).add_auth(request)
    return dict(request.headers)


async def main():
    encoded_arn = urllib.parse.quote(HARNESS_ARN, safe="")
    host = f"bedrock-agentcore.{REGION}.amazonaws.com"
    path = f"/runtimes/{encoded_arn}/ws/shells"
    https_url = f"https://{host}{path}"
    websocket_url = f"wss://{host}{path}"

    async with websockets.connect(
        websocket_url,
        additional_headers=signed_headers(https_url),
        subprotocols=[SUBPROTOCOL],
        open_timeout=330,
    ) as websocket:
        shell_id = websocket.response.headers.get(
            "X-Amzn-Bedrock-AgentCore-Shell-Id"
        )
        print(f"Connected to shell {shell_id}")

        # Channel 0x00 carries terminal input.
        await websocket.send(b"\x00echo 'Hello from my harness'\n")
        await websocket.send(b"\x00exit\n")

        async for frame in websocket:
            if isinstance(frame, str) or not frame:
                continue

            channel, payload = frame[0], frame[1:]
            if channel == 0x01:  # PTY output (command stdout and stderr)
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x02:  # Service or platform diagnostics
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x03:  # STATUS
                status = json.loads(payload)
                shell_id = status.get("metadata", {}).get("shellId", shell_id)
                print(f"\nStatus: {status}")


asyncio.run(main())

Binary frame protocol

Every application-level message is a binary WebSocket frame. The first byte identifies the channel, and the remaining bytes are the payload.

Text frames aren’t part of the protocol. The service ignores isolated text frames and closes the connection with code 1003 after five consecutive text frames.

The first STATUS frame confirms the connection and includes metadata similar to the following:

{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    "shellId": "my-shell",
    "reconnected": false
  },
  "status": "Success"
}

When the shell exits with a nonzero status, the final STATUS frame includes an ExitCode cause in details.causes.

Reconnect to a shell

Store both the runtime session ID and the shell ID. To reconnect, use the same runtime session ID header and add the URL-encoded shell ID as a query parameter:

wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells?shellId=<shell-id>

The shell process continues running while the connection is detached. On reconnection, the service replays up to 256 KB of buffered output. The connection STATUS frame sets metadata.reconnected to true and includes metadata.bytesDropped if the detached shell produced more output than the replay buffer could retain.

Opening another connection with the same shell ID replaces the existing connection. The replaced client receives close code 4000.

Common use cases

Security considerations

The shell can access customer-provided data, files, and secrets in the selected environment or on mounted filesystems. It can also connect to network destinations that the session can reach. The shell environment uses an allowlist and doesn’t inject AgentCore platform or workload credentials. The shell remains inside the session’s isolated microVM and cannot access another customer’s workload.

AgentCore sends the request ID and connection metadata to the harness Runtime log group in Amazon CloudWatch Logs. The service doesn’t log terminal input or output.

Amazon CloudTrail records InvokeAgentRuntimeCommandShell API calls, including the caller identity, timestamp, source IP address, resolved Runtime resource, and response status. CloudTrail doesn’t log terminal input or output.

For more Harness security guidance, see Security and access controls.

Error handling

The WebSocket upgrade can return the following errors:

Once connected, the following close codes indicate why the connection ended:

Best practices

Quotas and limits

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

Related topics