![[Update] Session endpoints, a feature that allows direct access to servers running within Amazon Bedrock AgentCore Runtime sessions, has been added!](https://devio2024-media.developers.io/image/upload/f_auto,q_auto/c_limit,w_1200/v1790875048/eyecatch/edq4dfptctqlcwjhffhs.png)
[Update] Session endpoints, a feature that allows direct access to servers running within Amazon Bedrock AgentCore Runtime sessions, has been added!
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...)
There was also solid information in the official documentation!
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 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.
https://<識別子>.runtime.bedrock-agentcore.<リージョン>.on.aws/ ← エージェントの待ち受けポート
https://8081--<識別子>.runtime.bedrock-agentcore.<リージョン>.on.aws/ ← 8081番
Here is the flow as a picture.

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.

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.

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!
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.
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/.
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.
#!/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!
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)
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.
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
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)
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)
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.
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 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.

In the business hours table, the row for Saturday, the day I ran this, is 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...

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
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.
By the way, I tried session storage in a previous article, so please refer to it as needed!
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.
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.
Unsupported configurations
Session endpoints can't be used with Instances (capacity providers). Also, access is via public HTTPS and PrivateLink is not supported.
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 |
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.
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.