[Update] Session endpoints, a feature that allows direct access to servers running within Amazon Bedrock AgentCore Runtime sessions, has been added!

[Update] Session endpoints, a feature that allows direct access to servers running within Amazon Bedrock AgentCore Runtime sessions, has been added!

AgentCore Runtime has added a new feature, Session endpoints, so I tried whether a website inside a session can be previewed directly from the browser!
2026.11.01

This page has been translated by machine translation. View original

Introduction

Hello, I'm Jinno from the Consulting Department, and I love supermarkets.

On October 30, 2026, the official AWS blog announced Session endpoints for Amazon Bedrock AgentCore Runtime! It is a feature that provides an endpoint for directly accessing the server running inside a session. It's a little unusual that it was introduced only in the blog and not in What's New. (Sorry if I missed it...)

https://aws.amazon.com/blogs/machine-learning/preview-web-apps-live-as-your-coding-agent-builds-them-with-amazon-bedrock-agentcore-runtime/

There was also solid information in the official documentation!

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html

To me, this update feels like it lets you build an experience similar to Claude's Artifacts using AgentCore's managed features...!

First we'll go over what changed, then have an agent built with Strands harness create a whole website, and preview the resulting site in our own browser to experience this update!

Main changes

First, what kind of update is this? Let's look at the API changes!

API Change
CreateAgentRuntime / UpdateAgentRuntime / GetAgentRuntime allowedPorts and the port and path of protocolConfiguration were added
InvokeAgentRuntime sessionEndpointUrl was added to the response

There are two main changes: one is that you can now directly access the server inside a session, and the other is that you can now change the agent's listening port and path.

First, I drew a picture of the first change!

Until now, even though you could call the agent from a PC with InvokeAgentRuntime, you couldn't reach the website inside the session. From now on, the session URL reaches the website directly

Until now you could invoke the agent and run commands, but you couldn't open a website running inside the session in your own browser. From now on, you can access allowed ports through a dedicated URL (session URL)!

It's nice to have another easy way to check an AI agent's output!

Let's dig a little deeper into how it works!

How session URLs work

First, let's see how a session URL is issued.

To use a session URL, you specify the ports to allow access to when creating the Runtime.
This setting is allowedPorts.

When you invoke the agent on a Runtime configured this way, the response includes a session URL (sessionEndpointUrl). If you want to access an arbitrary port, specify it by prefixing the URL with the port number, like 8081--. If you don't add it, the request reaches the agent's listening port.

セッションURLの形
https://<識別子>.runtime.bedrock-agentcore.<リージョン>.on.aws/            ← エージェントの待ち受けポート
https://8081--<識別子>.runtime.bedrock-agentcore.<リージョン>.on.aws/      ← 8081番

Here is the flow as a picture.

Receive the session URL in the InvokeAgentRuntime response. If you prepend 8081-- and send a signed request, GET /index.html reaches the website on port 8081 as is. Without a port prefix, it reaches the listening port 9090

The method and path reach the server inside as they are, so you can call the routes your app has. All destination ports, including the listening port, must be registered in allowedPorts.
You can use ports 8000 to 12000, up to a maximum of 5 entries.

Of course, just knowing the URL isn't enough to access it. Authentication and authorization using the method configured on the Runtime are required, and with IAM authentication you attach a signature (SigV4) made with AWS credentials to every request. The caller also needs the bedrock-agentcore:InvokeAgentRuntimeProxy permission.
With JWT authentication, you attach a Bearer Token.

Changing the listening port and path

The other change is that you can now set the port and path the agent listens on to anything you like!

Until now the agent was specified to listen on port 8080 at /invocations, but with this update you can change it to, for example, port 9090 at /agent/invoke. What you configure are the port and path of protocolConfiguration.

Here's a picture for this one too.

Until now, InvokeAgentRuntime always reached POST /invocations on port 8080. From now on, it reaches POST /agent/invoke on port 9090 as specified in protocolConfiguration

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-configure-invocation.html

Note that what changes is just the single destination used when invoking the agent; it doesn't add more entry points for invocation!

When you want to call separate routes per path, use the session URL. The two settings can each be used on their own. This time, since we have the chance, we'll try combining both!

Prerequisites

We'll proceed with the following setup!

Item Version, etc.
Region Tokyo (ap-northeast-1)
Python 3.14
Container base image ghcr.io/astral-sh/uv:python3.14-bookworm-slim
boto3 1.43.123
bedrock-agentcore 1.25.2
strands-harness 0.3.2 (strands-agents 1.62.0)
fastapi / uvicorn 0.162.0 / 0.54.0
Model Claude Haiku 5.5 (jp.anthropic.claude-haiku-5-5)

Handling allowedPorts and sessionEndpointUrl requires boto3 1.43.122 or later. The client that accesses session URLs with signatures was added in bedrock-agentcore 1.25.2.

Now let's get started!

Trying it out

Here's the setup for this time!
We'll have the Strands harness agent listen on port 9090 at /agent/invoke. The site the agent builds will be served on port 8081 in the same session.

The Runtime entrance verifies the signed request from the PC using the signature and allowedPorts. Without a port, it reaches the agent on port 9090. 8081-- reaches the website on port 8081. 8082--, where nothing is listening, results in 502. 8090--, which isn't allowed, results in 403 at the entrance

For allowedPorts, we'll include port 9090 and the range 8081 to 8083.
We'll deliberately leave nothing listening on port 8082, and together with the non-allowed port 8090 we'll check the differences between the errors.

Setup

Let's install the dependencies and so on!

セットアップ
uv init --python 3.14 agentcore-session-endpoints
cd agentcore-session-endpoints
uv add "boto3>=1.43.122" "bedrock-agentcore>=1.25.2"

# コンテナに入れるエージェント側のプロジェクト
mkdir agent && cd agent
uv init --bare --no-workspace --name session-endpoint-agent --python 3.14
uv add "strands-harness==0.3.2" fastapi uvicorn
cd ..

Preparing the agent

Strands harness, which we use this time, is a package that lets you create, with create_harness(), an agent equipped with tools such as shell and file operations and a system prompt. It's good for quickly having it build something, so we'll use it!

I introduced it in more detail in a previous article!

https://dev.classmethod.jp/articles/strands-harness-vs-agent/

We instruct the agent to create files in /tmp/workspace/site, and in the same process we also start a server that serves ./site on port 8081.
On port 9090 we also add /files as a custom route to be called from the session URL.

agent/main.py
import os
import threading
from functools import partial
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel
from strands_harness import create_harness

WORKSPACE = Path("/tmp/workspace")
SITE_DIR = WORKSPACE / "site"
SITE_DIR.mkdir(parents=True, exist_ok=True)
os.chdir(WORKSPACE)

agent = create_harness(
    model="jp.anthropic.claude-haiku-5-5",
    instructions=(
        "あなたはWebサイトを作るアシスタントです。"
        "ファイルはすべて ./site 配下に作成してください。"
        "./site はポート8081で配信済みなので、サーバーを起動する必要はありません。"
    ),
    session=False,
    memory=False,
    callback_handler=None,
)

app = FastAPI()

class InvokeRequest(BaseModel):
    prompt: str

@app.get("/ping")
def ping():
    return {"status": "Healthy"}

# protocolConfiguration.path で指定したパス
@app.post("/agent/invoke")
def invoke(request: InvokeRequest):
    result = agent(request.prompt)
    return {"response": str(result).strip()}

# セッションURLからだけ届く独自のルート
@app.get("/files")
def files():
    return {"files": sorted(str(p.relative_to(SITE_DIR)) for p in SITE_DIR.rglob("*") if p.is_file())}

def serve_site():
    handler = partial(SimpleHTTPRequestHandler, directory=str(SITE_DIR))
    ThreadingHTTPServer(("0.0.0.0", 8081), handler).serve_forever()

if __name__ == "__main__":
    threading.Thread(target=serve_site, daemon=True).start()
    uvicorn.run(app, host="0.0.0.0", port=9090)

You may be familiar with BedrockAgentCoreApp in the AgentCore SDK, which can create a server for agents, but when using it the entry path is fixed to /invocations. Since we also want to try changing the path this time, I prepared /agent/invoke with FastAPI, same as the example in the official documentation.

Deploying

We'll make it a container image and deploy it. Place the following Dockerfile in agent/.

agent/Dockerfile
FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY main.py ./
EXPOSE 9090 8081
CMD ["uv", "run", "--no-sync", "main.py"]

AgentCore Runtime runs on arm64, so we build for arm64. We push the resulting image to Amazon ECR, the storage location for container images.

build_push.sh
#!/bin/sh
set -eu
REGION=ap-northeast-1
REPO=session-endpoint-demo
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGISTRY=$ACCOUNT.dkr.ecr.$REGION.amazonaws.com

aws ecr describe-repositories --repository-names $REPO --region $REGION >/dev/null 2>&1 \
  || aws ecr create-repository --repository-name $REPO --region $REGION >/dev/null
aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $REGISTRY
docker buildx build --platform linux/arm64 -t $REGISTRY/$REPO:latest --push agent

We create the Runtime by specifying the image in ECR.
The key points this time are the two places, protocolConfiguration and allowedPorts. Specify them as follows!

deploy.py(Runtimeを作る部分)
runtime = control.create_agent_runtime(
    agentRuntimeName=NAME,
    agentRuntimeArtifact={"containerConfiguration": {"containerUri": image_uri}},
    roleArn=role_arn,
    networkConfiguration={"networkMode": "PUBLIC"},
    # エージェントの待ち受けを 9090番の /agent/invoke に変える
    protocolConfiguration={"serverProtocol": "HTTP", "port": 9090, "path": "/agent/invoke"},
    # セッションURLから届くポート
    allowedPorts=[
        {"port": 9090},
        {"portRange": {"from": 8081, "to": 8083}},
    ],
)
Full deploy.py (including creation of the execution role)
deploy.py
import json
import time

import boto3

REGION = "ap-northeast-1"
NAME = "session_endpoint_demo"
ROLE_NAME = "AgentCoreSessionEndpointDemoRole"

account_id = boto3.client("sts").get_caller_identity()["Account"]
image_uri = f"{account_id}.dkr.ecr.{REGION}.amazonaws.com/session-endpoint-demo:latest"

# 実行ロール(ECRからのイメージ取得、Bedrockのモデル呼び出し、ログ出力)
iam = boto3.client("iam")
try:
    role_arn = iam.get_role(RoleName=ROLE_NAME)["Role"]["Arn"]
except iam.exceptions.NoSuchEntityException:
    role_arn = iam.create_role(
        RoleName=ROLE_NAME,
        AssumeRolePolicyDocument=json.dumps({
            "Version": "2012-10-17",
            "Statement": [{
                "Effect": "Allow",
                "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
                "Action": "sts:AssumeRole",
                "Condition": {"StringEquals": {"aws:SourceAccount": account_id}},
            }],
        }),
    )["Role"]["Arn"]
    iam.put_role_policy(
        RoleName=ROLE_NAME,
        PolicyName="runtime",
        PolicyDocument=json.dumps({
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": ["ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer"],
                    "Resource": f"arn:aws:ecr:{REGION}:{account_id}:repository/session-endpoint-demo",
                },
                {"Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*"},
                {
                    "Effect": "Allow",
                    "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
                    "Resource": "*",
                },
                {
                    "Effect": "Allow",
                    "Action": [
                        "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents",
                        "logs:DescribeLogGroups", "logs:DescribeLogStreams",
                    ],
                    "Resource": "*",
                },
            ],
        }),
    )
    time.sleep(15)  # ロールの反映待ち

control = boto3.client("bedrock-agentcore-control", region_name=REGION)
runtime = control.create_agent_runtime(
    agentRuntimeName=NAME,
    agentRuntimeArtifact={"containerConfiguration": {"containerUri": image_uri}},
    roleArn=role_arn,
    networkConfiguration={"networkMode": "PUBLIC"},
    # エージェントの待ち受けを 9090番の /agent/invoke に変える
    protocolConfiguration={"serverProtocol": "HTTP", "port": 9090, "path": "/agent/invoke"},
    # セッションURLから届くポート
    allowedPorts=[
        {"port": 9090},
        {"portRange": {"from": 8081, "to": 8083}},
    ],
)
runtime_id = runtime["agentRuntimeId"]

while (detail := control.get_agent_runtime(agentRuntimeId=runtime_id))["status"] not in ("READY", "CREATE_FAILED"):
    time.sleep(5)

print("status:", detail["status"])
print("protocolConfiguration:", detail.get("protocolConfiguration"))
print("allowedPorts:", detail.get("allowedPorts"))

with open("runtime.json", "w") as f:
    json.dump({"arn": runtime["agentRuntimeArn"], "id": runtime_id}, f)

Run the script to deploy!

実行
chmod +x build_push.sh
./build_push.sh
uv run deploy.py
実行結果
status: READY
protocolConfiguration: {'serverProtocol': 'HTTP', 'port': 9090, 'path': '/agent/invoke'}
allowedPorts: [{'port': 9090}, {'portRange': {'from': 8081, 'to': 8083}}]

It deployed without problems and became READY! The GetAgentRuntime response also contains the port and path we set.

Now that the Runtime is ready, let's have the agent build a site and take a look at it!

Having it build a whole site

As usual, we invoke the agent with InvokeAgentRuntime and get the sessionEndpointUrl from the response.

invoke.py(セッションURLを取り出す部分)
response = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn,
    runtimeSessionId=session_id,
    contentType="application/json",
    payload=json.dumps({"prompt": sys.argv[1]}).encode(),
)

print("runtimeSessionId:", response["runtimeSessionId"])
print("sessionEndpointUrl:", response.get("sessionEndpointUrl"))
Full invoke.py
invoke.py
import json
import sys
import uuid

import boto3
from botocore.config import Config

REGION = "ap-northeast-1"
runtime_arn = json.load(open("runtime.json"))["arn"]

# 引数でセッションIDを渡すと、同じセッションで続きを依頼する
session_id = sys.argv[2] if len(sys.argv) > 2 else str(uuid.uuid4())
client = boto3.client(
    "bedrock-agentcore", region_name=REGION, config=Config(read_timeout=900)
)
response = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn,
    runtimeSessionId=session_id,
    contentType="application/json",
    payload=json.dumps({"prompt": sys.argv[1]}).encode(),
)

print("runtimeSessionId:", response["runtimeSessionId"])
print("sessionEndpointUrl:", response.get("sessionEndpointUrl"))
print(json.loads(response["response"].read())["response"])

with open("session.json", "w") as f:
    json.dump({"session_id": session_id, "url": response.get("sessionEndpointUrl")}, f)

The theme is a website for a fictional café, "Kotori Coffee," and we'll have it build the whole thing with three files: HTML, CSS, and JavaScript!

実行
uv run invoke.py "架空のカフェ「ことり珈琲」のWebサイトを新規作成してください。index.html・style.css・script.js の3ファイル構成で、トップ・メニュー・営業時間のセクションを入れてください。"
実行結果(抜粋)
runtimeSessionId: 55f06e7e-0bb1-46b7-97bf-3f8fac1f78a9
sessionEndpointUrl: https://<識別子>.runtime.bedrock-agentcore.ap-northeast-1.on.aws
「ことり珈琲」のWebサイトを `./site` に作成しました(`index.html` / `style.css` / `script.js`)。ポート8081で配信されており、3ファイルとも 200 で取得できることを確認しています。
(構成やscript.jsの機能などの説明が続く)

It created the three files in about a minute and a half!
The response includes sessionEndpointUrl too! We'll use this URL to access the site inside the session.

Also, a response came back even from an app that doesn't have /invocations!
It's properly reaching /agent/invoke on port 9090 as specified in protocolConfiguration.

Accessing the session URL

Let's send requests to the session URL!
An IAM signature is required, but session_endpoint_client in bedrock-agentcore attaches it for us.

We'll send requests to the following four endpoints:

  • /files on the no-port-specified (port 9090)
  • index.html on port 8081
  • Port 8082 (allowed, but nothing is running)
  • Port 8090 (not included in allowedPorts)
check.py
import json

from bedrock_agentcore.runtime import AgentCoreRuntimeClient

session = json.load(open("session.json"))
client = AgentCoreRuntimeClient(region="ap-northeast-1")
endpoint = client.session_endpoint_client(session["url"])

# ポート指定なし = エージェントの待ち受けポート(9090)の独自ルート
files = endpoint.request("GET", "/files")
print("GET /files ->", files.status, files.json())

# 8081番 = エージェントが作ったサイト
page = endpoint.request("GET", "/index.html", port=8081)
print("GET :8081/index.html ->", page.status, page.headers.get("content-type"), len(page.data), "bytes")
print(page.text[:300])

# 許可したが何も待ち受けていないポートと、許可していないポート
for port in (8082, 8090):
    r = endpoint.request("GET", "/", port=port)
    print(f"GET :{port}/ ->", r.status, "proxy_error:", r.proxy_error)
実行結果(uv run check.py、抜粋)
GET /files -> 200 {'files': ['index.html', 'script.js', 'style.css']}
GET :8081/index.html -> 200 text/html 10197 bytes
<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  ...
  <title>ことり珈琲</title>
  <link rel="stylesheet" href="style.css">
GET :8082/ -> 502 proxy_error: PortNotReachable
GET :8090/ -> 403 proxy_error: AccessDenied

/files returned a list of the three files the agent created!
Port 8081 returned index.html, port 8082 gave 502 because nothing is running there, and port 8090 gave 403 because it isn't allowed, all as expected!

It could be called from the script without problems, so next let's look at it in the browser!

Previewing in the browser

Session URLs require a signature on every request, so you can't open them in a browser as is. So we use the local relay (open_local_endpoint) of bedrock-agentcore. It attaches a signature to requests received on port 8088 of your PC and forwards them to port 8081 of the session.

preview.py
import json

from bedrock_agentcore.runtime import AgentCoreRuntimeClient

session = json.load(open("session.json"))
client = AgentCoreRuntimeClient(region="ap-northeast-1")
endpoint = client.session_endpoint_client(session["url"])

# localhost:8088 へのリクエストに署名を付けて、セッションの8081番へ中継する
with endpoint.open_local_endpoint(port=8081) as local:
    print("Open", local.url)
    input("Enterで終了します")
実行
uv run preview.py

When you open the displayed http://localhost:8088...

The Kotori Coffee site made by the agent is displayed in my own browser. The business status display by script.js works too

The little bird is so cute!!!

That comment aside, the site the agent created inside the session is displayed in my own browser! Not only the CSS and fonts, but the open/closed judgment, which is processed by script.js, works too, and the "Today's business hours have ended" message is displayed without problems. I took the screenshot at 11:30 PM, so it correctly judged that it's after closing time!

Let's also lightly check the JavaScript behavior by operating the browser. Clicking "Sweets" in the menu narrowed it down to 3 items.

Clicking the Sweets tab in the browser narrowed the menu down to 3 items

In the business hours table, the row for Saturday, the day I ran this, is marked as "Today."

In the business hours table, the row for Saturday, the day I ran this, was marked as Today

Links and scripts in the page work just like on a normal site. It's nice to be able to touch and check what the agent made.

Having it fix things in the same session

Finally, with the preview still open, let's ask for a modification using the same session ID. If it reaches the same session, we should be able to see the updated screen at the same URL.

Replace the session ID at the end with the runtimeSessionId shown in the first run's output.

実行
uv run invoke.py "夜カフェ風に、背景を濃い紺色・文字を明るい色にした配色へ変えてください。" 55f06e7e-0bb1-46b7-97bf-3f8fac1f78a9
実行結果(抜粋)
runtimeSessionId: 55f06e7e-0bb1-46b7-97bf-3f8fac1f78a9
sessionEndpointUrl: https://<識別子>.runtime.bedrock-agentcore.ap-northeast-1.on.aws
配色を夜カフェ風(濃い紺の背景・明るい文字・ランプ色のアクセント)に変更しました。変更は `style.css` のみで、`index.html` と `script.js` は変えていません。

Since it's the same session, the session URL is also the same as the first time. When I reload the browser...

When I asked for a color scheme change in the same session, it changed to a night-café color scheme at the same URL

It changed to a night-café color scheme at the same URL!
There's no need to restart the local relay either!

You can keep repeating the flow of asking the agent, checking in the browser, and asking again.

Cleanup

Stop preview.py with Enter, then delete the Runtime, the ECR repository, and the execution role.

cleanup.py
cleanup.py
import json

import boto3

REGION = "ap-northeast-1"
runtime_id = json.load(open("runtime.json"))["id"]

boto3.client("bedrock-agentcore-control", region_name=REGION).delete_agent_runtime(agentRuntimeId=runtime_id)
boto3.client("ecr", region_name=REGION).delete_repository(repositoryName="session-endpoint-demo", force=True)

iam = boto3.client("iam")
iam.delete_role_policy(RoleName="AgentCoreSessionEndpointDemoRole", PolicyName="runtime")
iam.delete_role(RoleName="AgentCoreSessionEndpointDemoRole")
実行
uv run cleanup.py

Use cases

Finally, let's review where this can be used!

Session URLs

The first thing that comes to mind is checking a screen built by a coding agent on the spot, as we did this time. Just as Claude and Codex let you easily view output in their desktop apps, it seems similar things could be done in apps built with AgentCore!

Development servers and dashboards launched inside a session can be opened in the same way, so it could also be used for UIs that interact with the agent in real time.

Changing the listening port and path

This seems useful when you want to put an existing web app or API server onto AgentCore Runtime! Until now, for HTTP it had to be port 8080 with the path /invocations, so I think it will help in cases where you want to use other paths or port numbers...

Conclusion

You can now access the allowed ports of servers running inside a session with signed requests! I think it can be used in cases such as coding agent apps that want to show output immediately, or having AI build a UI in real time!

You can also change the agent's default listening port and path! It seems useful for cases where you absolutely need to change from the default port or path!

Thank you for reading to the end!

Supplement: Detailed specifications described in the documentation

The official documentation also describes specifications and notes that I didn't touch on this time, and I've briefly summarized the ones that caught my interest.

Validity period of session URLs

A session URL is tied to a session, and you can keep using the same URL while the session continues.

By default, the session's execution environment stops after 15 minutes without requests or after 8 hours. Even after it has stopped, sending a request to the URL prepares a new execution environment and makes access possible. However, in-memory state and files are not carried over, so if you want to keep the files you created, use session storage.

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html#runtime-session-endpoints-lifecycle

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-settings.html

By the way, I tried session storage in a previous article, so please refer to it as needed!

https://dev.classmethod.jp/articles/bedrock-agentcore-runtime-session-storage/

Default ports and paths

If you don't specify protocolConfiguration, the following values are used for each protocol.
You can also change only the port or only the path.

This feature is also supported for protocols other than HTTP!

Protocol Port Path
HTTP 8080 /invocations
AG-UI 8080 /invocations
MCP 8000 /mcp
A2A 9000 /

The path change applies only to InvokeAgentRuntime; invocation over WebSocket uses /ws on the listening port.

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-configure-invocation.html

Things to watch out for on the app side

The Host header of requests arriving from the session URL contains an internal hostname. For development servers that check the hostname, such as Vite, a setting like setting server.allowedHosts to true is required. Links and redirects within pages also need to be relative URLs.

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html#runtime-session-endpoints-how-it-works

Unsupported configurations

Session endpoints can't be used with Instances (capacity providers). Also, access is via public HTTPS and PrivateLink is not supported.

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html

Telling errors apart

For errors on the Runtime side, the body is empty and the reason is in the X-Amzn-Bedrock-AgentCore-Runtime-Error header. Besides the 502 and 403 we saw this time, there are the following.

Status Reason Main cause
401 AuthenticationRequired No credentials attached
404 SessionNotFound The URL is wrong or the session doesn't exist
424 RuntimeClientError The app doesn't start or respond in time
429 Throttled Too many requests

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html#runtime-session-endpoints-errors

Logging to CloudTrail

Requests to session URLs can be recorded in CloudTrail as a data event called InvokeAgentRuntimeProxy. Data events are not recorded by default, so configure them in a trail or an event data store. A web preview generates a request for each image or script, so be mindful of costs if you record them.

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html#runtime-session-endpoints-cloudtrail

Pricing

I couldn't find an item specific to Session endpoints on the pricing page (as of November 1, 2026). I think the usual AgentCore Runtime pricing probably applies. With microVMs, you are billed per second according to CPU and memory usage from preparation to termination of the execution environment. Once you're done previewing, stop the session or finish the cleanup.

https://aws.amazon.com/bedrock/agentcore/pricing/

Share this article