Preview internet apps reside as your coding agent builds them with Amazon Bedrock AgentCore runtime

Coding brokers now construct working internet apps: a dashboard, a product web page, a prototype {that a} product group needs to strive. The quickest option to evaluate that work is to open the app, use it, ask for a change, and verify the consequence. That loop works effectively when the app retains working the place the agent edits it, so every change reveals up within the browser inside seconds. When the app should be copied out and deployed some place else first, each change waits for a deployment, and the evaluate slows right down to that tempo.

Amazon Bedrock AgentCore is a platform to construct, join, and optimize brokers at scale, together with your selection of agent framework and basis mannequin (FM). AgentCore runtime, a functionality of Amazon Bedrock AgentCore, runs every agent session in its personal remoted microVM. With Session endpoints, you possibly can open an app working in that session from your individual browser. Session Endpoints give every session an authenticated URL that forwards every request’s HTTP methodology, path, question string, and physique, and WebSocket connections, to the ports you permit. You’ll be able to watch the web page replace because the agent saves every file.

On this submit, you deploy a coding agent that retains a Vite web site working in its session, then open one native web page with a chat on the left and the reside web site on the best. You ask the agent to modify the location to a darkish shade theme, observe its steps as they stream in, and watch the web site change with out a refresh. Lastly, you have a look at what occurs internally: a second port in the identical session, and the requests the Session endpoint refuses.

The whole pattern, together with the pocket book this submit follows, is within the 14-remote-access folder of the agentcore-samples GitHub repo.

How Session endpoints work

Every session will get its personal Session endpoint, and 6 particulars form how you utilize it.

You select which ports it reaches. You set allowedPorts while you name CreateAgentRuntime: 1–5 entries, every a single port or a spread inside 8000–12000, excluding the reserved platform ports. Permitting a port doesn’t begin a server, so your software should pay attention on it, certain to 0.0.0.0.

The URL arrives with the session. The InvokeAgentRuntime response carries it within the X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url header, which SDKs that mannequin it expose as sessionEndpointUrl.

Each request is authenticated. For a runtime that makes use of AWS Id and Entry Administration (IAM), every HTTP request, HTTP/2 stream, and WebSocket handshake carries a Signature Model 4 (SigV4) signature. The caller additionally wants bedrock-agentcore:InvokeAgentRuntimeProxy on the runtime and its runtime endpoint. For a runtime with an inbound JSON Net Token (JWT) authorizer, every request carries a bearer token as an alternative. Realizing the URL doesn’t grant entry.

The host identify selects the port. Your shopper connects on port 443 whatever the goal port, and a prefix on the host identify chooses the port contained in the session:

https://8090--.runtime.bedrock-agentcore..on.aws/index.html
https://8081--.runtime.bedrock-agentcore..on.aws/standing

It carries the protocols your server speaks. HTTP/1.1 and HTTP/2 requests, together with server-sent occasions and gRPC, and WebSocket connections all cross by. This walkthrough makes use of HTTP/1.1 and WebSocket.

It’s scoped to 1 session. The URL wants credentials on each request and lasts solely so long as the session, so use it to construct, check, and evaluate what your agent produces. To serve an app to your customers, deploy it to a internet hosting service equivalent to AWS Amplify Internet hosting.

A browser can’t add a SigV4 signature or a bearer token to the requests a web page makes by itself, so the Session endpoint shopper within the bedrock-agentcore SDK can open a neighborhood endpoint in your machine. Your browser opens http://localhost:8088, and the native endpoint provides your credentials to every request and WebSocket handshake earlier than forwarding it.

A Session endpoint is completely different from a runtime endpoint, which AgentCore runtime already offers. Use a runtime endpoint, equivalent to DEFAULT, to succeed in your agent, which controls which model of it callers will attain. InvokeAgentRuntime calls resolve by it, so you possibly can hold growth and manufacturing on completely different variations and promote or roll again with out altering callers. Use a Session endpoint to see what your agent runs in its session, equivalent to an online preview. It’s an authenticated URL that reaches solely the ports you permit, works with whichever model the session runs, and stops working when the session ends. For full documentation, discuss with Connect with runtime periods by a session endpoint.

Answer overview

The pattern has 4 components. A coding agent runs within the session on port 8080 and edits the web site’s information with 4 instruments: record, learn, write, and edit. The agent begins a Vite growth server on port 8090, which serves the web site and pushes every saved change to the browser over its hot-reload WebSocket. In your machine, PreviewApp serves the preview web page, sends your prompts to InvokeAgentRuntime, and opens a neighborhood endpoint for the web site. As Determine 1 reveals, the preview web page hundreds the web site from the Vite growth server on port 8090 by the native endpoint and the Session endpoint, and sends your prompts by InvokeAgentRuntime to the agent on port 8080. The numbers present the order of the steps for one request.

Determine 1: Answer structure

Earlier than step 1, PreviewApp has already known as InvokeAgentRuntime as soon as to begin the session, which begins the agent and the Vite growth server. PreviewApp learn the Session endpoint URL from that response and opened a neighborhood endpoint for port 8090. The numbered steps in Determine 1 then observe one request for a change:

1. The location pane of the preview web page hundreds the web site from the native endpoint on localhost:8088. The native endpoint provides your credentials to every request and the WebSocket handshake, and forwards them to the Session endpoint. The Session endpoint checks the signature and the port towards allowedPorts, then forwards them to the Vite growth server on port 8090. The web page retains the Vite hot-reload WebSocket open.
2. You ship a immediate from the chat pane. PreviewApp sends it to InvokeAgentRuntime as a regular AWS API name signed together with your AWS credentials, and the runtime delivers it to the agent on port 8080. The agent’s steps stream again to the chat pane as it really works.
3. The agent calls Claude Haiku 5.5 in Amazon Bedrock to resolve what to vary.
4. The agent reads the location’s information and saves those it modifications. The Vite growth server serves these information and watches them for modifications.
5. When a file is saved, Vite pushes the change over the WebSocket opened in step 1, again by the Session endpoint and the native endpoint, and the location pane updates with out a refresh.
6. From the pocket book, PreviewApp reads the agent’s /standing route on port 8081 by the identical Session endpoint. Solely the port modifications.

Port 8080 isn’t in allowedPorts, as a result of InvokeAgentRuntime reaches the agent with out going by the Session endpoint.

Conditions

To observe the walkthrough, you want:

• An AWS account in an AWS Area the place AgentCore runtime Session endpoints can be found, with credentials configured.
• Permissions to create an AWS Id and Entry Administration (IAM) function, add to Amazon Easy Storage Service (Amazon S3), and create a runtime, plus bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:InvokeAgentRuntimeProxy on that runtime and its DEFAULT runtime endpoint. For particulars, discuss with IAM permissions for AgentCore runtime.
• Python 3.10 or later, with bedrock-agentcore 1.25.2 or later and boto3 1.43.122 or later.
• Git, to clone the pattern repo, and a Jupyter setting, equivalent to JupyterLab or Visible Studio Code with the Jupyter extension, to run the pocket book.
• Entry to Claude Haiku 5.5 in Amazon Bedrock. For mannequin availability by Area, discuss with Regional availability by fashions.
• Node.js 22 or later with npm, which the deployment script makes use of to package deal the agent and the web site.

The pattern deploys the agent as a zipper file in Amazon S3 with direct code deployment for Node.js, so that you don’t want Docker or an Amazon Elastic Container Registry (Amazon ECR) repository. Session endpoints work with microVM runtimes, not with the Cases compute sort, and Session endpoint URLs are reachable over public HTTPS. AWS PrivateLink isn’t supported for inbound connections.

Deploy the agent and its web site

First, you deploy the runtime, and the configuration you select right here decides which ports the Session endpoint can attain. The deployment script bundles the agent into one file, provides the web site and its dependencies for the runtime’s Linux on Arm64 system, uploads the zip to Amazon S3, and creates the runtime.

The next excerpt from deploy.py reveals the 2 settings that matter for this submit. protocolConfiguration says the place the agent listens for InvokeAgentRuntime, and allowedPorts lists the ports the Session endpoint can attain: 8090 for the web site and 8081 for the agent’s standing route. Port 8080 isn’t within the record, as a result of InvokeAgentRuntime reaches the agent with out it. For the port and path settings, discuss with Configure your agent’s serving port and invocation path.

agentRuntimeArtifact={"codeConfiguration": {
    "code": {"s3": {"bucket": code_bucket(), "prefix": S3_PREFIX}},
    "runtime": "NODE_22",
    "entryPoint": ["app.js"],
}},
protocolConfiguration={"serverProtocol": "HTTP", "port": 8080, "path": "/invocations"},
allowedPorts=[{"port": 8090}, {"port": 8081}],

The web site’s Vite configuration makes the event server reachable from the Session endpoint. It listens on 0.0.0.0 at port 8090 and doesn’t limit the Host header (server.allowedHosts is true), as a result of requests arrive below a number identify the runtime assigns fairly than localhost. The Session endpoint authenticates each request earlier than it reaches the server, so the server doesn’t want its personal host verify.

To deploy the runtime:

1. Clone the pattern repo and alter to the pattern folder:

git clone https://github.com/awslabs/agentcore-samples.git
cd agentcore-samples/01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints

2. Open session_endpoints_preview.ipynb from the pattern folder.

3. Run the set up cell, which installs the Python dependencies.

4. Run the %run deploy.py cell. Deployment takes a couple of minutes, principally ready for the runtime to succeed in the READY standing.

Open the preview

With the runtime prepared, you begin the preview. One name does three issues: it begins a session (which begins the web site), opens a neighborhood endpoint for port 8090, and serves the preview web page on localhost:8087.

from preview_app import PreviewApp

app = PreviewApp().begin()
print("Open", app.url)

Inside begin(), the calls that use Session endpoints are brief. The primary InvokeAgentRuntime name returns the URL in a response header, session_endpoint_url reads it, and the Session endpoint shopper opens a neighborhood endpoint for port 8090:

reply = shopper.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn, runtimeSessionId=session_id,
    payload=json.dumps({"immediate": ""}).encode(), contentType="software/json",
)
endpoint = shopper.session_endpoint_client(session_endpoint_url(reply))
native = endpoint.open_local_endpoint(port=8090, local_port=8088).begin()

To open the preview:

1. Run the cell that begins PreviewApp.
2. Open the printed hyperlink, http://localhost:8087, in your browser.

The web page reveals the web site on the best, served from port 8090 within the session, and a brief information with urged requests on the left.

Ask the agent for a change

Now you ask for a change and watch it arrive. Every immediate goes to the agent by InvokeAgentRuntime. The agent reads the information it wants, writes those it modifications, and studies every step because it occurs. When a file is saved, the Vite growth server pushes the change over its WebSocket, by the Session endpoint and the native endpoint, and the web site updates in place.

To ask for a change:

1. On the preview web page, select Change this web site to a darkish coffee-house shade theme.
2. Observe the agent’s steps within the chat pane because it reads and saves information.
3. Watch the location pane. It modifications when the agent saves the stylesheet, and a banner names the file the change got here from.

The next video reveals the preview web page whereas the agent works by a number of requests. Selecting a urged request sends it to the agent, the chat pane lists every file the agent reads and saves, and the location pane on the best updates with out a refresh, from the darkish theme to a inexperienced Order forward button.

Determine 2: The preview web page because the agent works

The steps stream as a result of the agent solutions with server-sent occasions while you ask it to. You’ll be able to ship the identical prompts from Python with app.ask, which reads the stream with iter_events from the bedrock-agentcore SDK. The open web page updates in the identical approach:

for occasion in app.ask("Make the Order forward button inexperienced"):
    if "step" in occasion:
        print("  ", occasion["step"])
    elif "accomplished" in occasion:
        print(occasion["done"]["reply"])

The output of this Python script ought to resemble the next:

   Wanting on the web site's information
   Studying src/primary.js
   Studying src/type.css
   Studying index.html
   Saved src/type.css
The Order forward button is now inexperienced as an alternative of brown, with white textual content saved for distinction. You'll be able to see it within the hero part, just under the "Small batch espresso, roasted each morning" heading on the prime of the web page.

Attain a second port in the identical session

The web site isn’t the one server you possibly can attain. The agent serves /standing on port 8081, which lists every immediate and the information it modified. The identical Session endpoint reaches it, and the one distinction is the port argument.

standing = app.endpoint.request("GET", "/standing", port=8081)
print("GET /standing on port 8081: HTTP", standing.standing)
for edit in standing.json()["edits"]:
    print("  ", edit["prompt"], "->", ", ".be a part of(edit["files"]))

The output of this Python script ought to resemble the next:

GET /standing on port 8081: HTTP 200
   Make the Order forward button inexperienced -> src/type.css

What the Session endpoint refuses

When the runtime refuses a request, it solutions with an HTTP standing, an empty physique, and an error code in a response header, so you possibly can inform its refusals from errors your software returns. The pocket book sends a request to a port exterior allowedPorts and a request with out credentials, and the runtime refuses each with 403 AccessDenied.

The next desk lists the refusals you’re prone to meet whilst you construct with Session endpoints.

How entry to your session is protected

The runtime removes its personal authentication headers earlier than it forwards a request, so the web site doesn’t obtain your signature. Requests are recorded in AWS CloudTrail as InvokeAgentRuntimeProxy occasions, with the occasion supply bedrock-agentcore.amazonaws.com. The native endpoint acts together with your credentials, so it limits who can use it. It listens on 127.0.0.1 solely, solutions solely requests addressed to its personal native tackle, and refuses WebSocket connections opened by pages from different origins. Run the native endpoint solely whilst you use the preview. For extra data, see Log session endpoint requests in CloudTrail.

The entry controls don’t separate the web site from the agent. Each run in the identical session, so give the execution function solely the permissions the agent wants. If the runtime replaces the session’s compute, open connections shut, and the agent’s edits won’t survive except the session makes use of persistent storage. Consult with File system configurations for AgentCore runtime when you want the information to outlast the compute.

The agent’s file instruments resolve each path inside the location folder and refuse paths exterior it, so a immediate can’t make the agent change different information within the session. If different individuals can ship prompts to your coding agent, take into account Amazon Bedrock Guardrails to filter dangerous prompts and responses, and evaluate the agent’s modifications earlier than you publish them.

Clear up

To keep away from ongoing costs, cease the preview and delete the assets the pattern created. The web site the agent edited lives within the session, so it goes with the session.

To wash up:

1. Run the cease cell, and press Enter when the pocket book asks. This stops the preview web page, the native endpoint, and the session.

2. Run the %run cleanup.py cell, which deletes the runtime, the uploaded code, and the IAM function.

Conclusion

Session endpoints offer you authenticated entry to the purposes in an AgentCore runtime session from your individual instruments over HTTP/1.1, HTTP/2, and WebSocket, on the ports you permit. On this submit, you deployed a coding agent with a Vite web site in its session, opened the reside web site in your browser by a neighborhood endpoint, requested the agent for a darkish theme, and watched the change arrive because the agent saved the file. You additionally reached a second port in the identical session and confirmed what the Session endpoint refuses.

To go additional, run the pocket book with your individual web site within the web site folder, or change the agent’s instruments to match how your coding agent works. For the total set of choices, together with port ranges, OAuth, HTTP/2, and gRPC, discuss with Connect with runtime periods by a session endpoint.

To alter the port or path that InvokeAgentRuntime makes use of in your individual agent, discuss with Configure your agent’s serving port and invocation path. In case your agent additionally must run construct or check instructions in the identical session, discuss with Execute shell instructions in AgentCore runtime periods. To deploy your individual Node.js agent from a zipper file the way in which this pattern does, discuss with Direct code deployment for Node.js. For every part else the service presents, begin with Host agent or instruments with Amazon Bedrock AgentCore runtime, and discover extra examples within the agentcore-samples GitHub repo.

Concerning the creator