Preview web apps live as your coding agent builds them with Amazon Bedrock AgentCore runtime

Amazon Web Services introduced Session endpoints for Amazon Bedrock AgentCore runtime, letting developers open a web app running inside an agent's isolated microVM session directly in a browser via an authenticated URL. Each session endpoint forwards HTTP method, path, query string, body and WebSocket connections to ports the developer allows through the `allowedPorts` parameter on CreateAgentRuntime, which accepts 1–5 entries within the 8000–12000 range, excluding reserved platform ports. The URL is returned in the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url` header of the InvokeAgentRuntime response, and every request must carry a SigV4 signature or JWT bearer token, so knowing the URL alone does not grant access.

Artificial Intelligence https://aws.amazon.com/blogs/machine-learning/ Preview web apps live as your coding agent builds them with Amazon Bedrock AgentCore runtime Coding agents now build working web apps: a dashboard, a product page, a prototype that a product team wants to try. The fastest way to review that work is to open the app, use it, ask for a change, and check the result. That loop works well when the app keeps running where the agent edits it, so each change shows up in the browser within seconds. When the app must be copied out and deployed somewhere else first, every change waits for a deployment, and the review slows down to that pace. Amazon Bedrock AgentCore https://aws.amazon.com/bedrock/agentcore/ is a platform to build, connect, and optimize agents at scale, with your choice of agent framework and foundation model FM . AgentCore runtime https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html , a capability of Amazon Bedrock AgentCore, runs each agent session in its own isolated microVM. With Session endpoints https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html , you can open an app running in that session from your own browser. Session Endpoints give each session an authenticated URL that forwards each request’s HTTP method, path, query string, and body, and WebSocket connections, to the ports you allow. You can watch the page update as the agent saves each file. In this post, you deploy a coding agent that keeps a Vite website running in its session, then open one local page with a chat on the left and the live website on the right. You ask the agent to switch the site to a dark color theme, follow its steps as they stream in, and watch the website change without a refresh. Finally, you look at what happens internally: a second port in the same session, and the requests the Session endpoint refuses. The complete sample, including the notebook this post follows, is in the 14-remote-access folder https://github.com/awslabs/agentcore-samples/tree/main/01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints of the agentcore-samples GitHub repo https://github.com/awslabs/agentcore-samples . How Session endpoints work Each session gets its own Session endpoint, and six details shape how you use it. You choose which ports it reaches. You set allowedPorts when you call CreateAgentRuntime https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API CreateAgentRuntime.html : 1–5 entries, each a single port or a range within 8000–12000, excluding the reserved platform ports https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html runtime-reserved-ports . Allowing a port doesn’t start a server, so your application must listen on it, bound to 0.0.0.0 . The URL arrives with the session. The InvokeAgentRuntime https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API InvokeAgentRuntime.html response carries it in the X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url header, which SDKs that model it expose as sessionEndpointUrl . Every request is authenticated. For a runtime that uses AWS Identity and Access Management IAM https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html , each HTTP request, HTTP/2 stream, and WebSocket handshake carries a Signature Version 4 SigV4 https://docs.aws.amazon.com/IAM/latest/UserGuide/reference sigv.html signature. The caller also needs bedrock-agentcore:InvokeAgentRuntimeProxy on the runtime and its runtime endpoint. For a runtime with an inbound JSON Web Token JWT authorizer https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/inbound-jwt-authorizer.html , each request carries a bearer token instead. Knowing the URL doesn’t grant access. The host name selects the port. Your client connects on port 443 regardless of the target port, and a prefix on the host name chooses the port inside the session: It carries the protocols your server speaks. HTTP/1.1 and HTTP/2 requests, including server-sent events and gRPC, and WebSocket connections all pass through. This walkthrough uses HTTP/1.1 and WebSocket. It’s scoped to one session. The URL needs credentials on every request and lasts only as long as the session, so use it to build, test, and review what your agent produces. To serve an app to your users, deploy it to a hosting service such as AWS Amplify Hosting https://aws.amazon.com/amplify/hosting/ . A browser can’t add a SigV4 signature or a bearer token to the requests a page makes on its own, so the Session endpoint client in the bedrock-agentcore SDK https://github.com/aws/bedrock-agentcore-sdk-python can open a local endpoint on your machine. Your browser opens http://localhost:8088 , and the local endpoint adds your credentials to each request and WebSocket handshake before forwarding it. A Session endpoint is different from a runtime endpoint https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html , which AgentCore runtime already provides. Use a runtime endpoint, such as DEFAULT , to reach your agent, which controls which version of it callers will reach. InvokeAgentRuntime calls resolve through it, so you can keep development and production on different versions and promote or roll back without changing callers. Use a Session endpoint to see what your agent runs in its session, such as a web preview. It’s an authenticated URL that reaches only the ports you allow, works with whichever version the session runs, and stops working when the session ends. For complete documentation, refer to Connect to runtime sessions through a session endpoint https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-session-endpoints.html . Solution overview The sample has four parts. A coding agent runs in the session on port 8080 and edits the website’s files with four tools: list, read, write, and edit. The agent starts a Vite https://vite.dev/ development server on port 8090, which serves the website and pushes each saved change to the browser over its hot-reload WebSocket. On your machine, PreviewApp serves the preview page, sends your prompts to InvokeAgentRuntime , and opens a local endpoint for the website. As Figure 1 shows, the preview page loads the website from the Vite development server on port 8090 through the local endpoint and the Session endpoint, and sends your prompts through InvokeAgentRuntime to the agent on port 8080. The numbers show the order of the steps for one request. Before step 1, PreviewApp has already called InvokeAgentRuntime once to start the session, which starts the agent and the Vite development server. PreviewApp read the Session endpoint URL from that response and opened a local endpoint for port 8090. The numbered steps in Figure 1 then follow one request for a change: 1. The site pane of the preview page loads the website from the local endpoint on localhost:8088 . The local endpoint adds your credentials to each request and the WebSocket handshake, and forwards them to the Session endpoint. The Session endpoint checks the signature and the port against allowedPorts , then forwards them to the Vite development server on port 8090. The page keeps the Vite hot-reload WebSocket open. 2. You send a prompt from the chat pane. PreviewApp sends it to InvokeAgentRuntime as a standard AWS API call signed with your AWS credentials, and the runtime delivers it to the agent on port 8080. The agent’s steps stream back to the chat pane as it works. 3. The agent calls Claude Haiku 5.5 in Amazon Bedrock to decide what to change. 4. The agent reads the site’s files and saves the ones it changes. The Vite development server serves those files and watches them for changes. 5. When a file is saved, Vite pushes the change over the WebSocket opened in step 1, back through the Session endpoint and the local endpoint, and the site pane updates without a refresh. 6. From the notebook, PreviewApp reads the agent’s /status route on port 8081 through the same Session endpoint. Only the port changes. Port 8080 isn’t in allowedPorts , because InvokeAgentRuntime reaches the agent without going through the Session endpoint. Prerequisites To follow the walkthrough, you need: - An AWS account in an AWS Region where AgentCore runtime Session endpoints are available, with credentials configured. - Permissions to create an AWS Identity and Access Management IAM role, upload to Amazon Simple Storage Service Amazon S3 https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html , and create a runtime, plus bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:InvokeAgentRuntimeProxy on that runtime and its DEFAULT runtime endpoint. For details, refer to IAM permissions for AgentCore runtime https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html . - Python 3.10 or later, with bedrock-agentcore 1.25.2 or later and boto3 1.43.122 or later. - Git https://git-scm.com/ , to clone the sample repo, and a Jupyter https://jupyter.org/ environment, such as JupyterLab or Visual Studio Code with the Jupyter extension, to run the notebook. - Access to Claude Haiku 5.5 https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-haiku-5-5.html in Amazon Bedrock. For model availability by Region, refer to Regional availability by models https://docs.aws.amazon.com/bedrock/latest/userguide/models-region-compatibility.html . - Node.js https://nodejs.org/ 22 or later with npm , which the deployment script uses to package the agent and the website. The sample deploys the agent as a zip file in Amazon S3 with direct code deployment for Node.js https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-code-deploy-node.html , so you don’t need Docker or an Amazon Elastic Container Registry Amazon ECR https://aws.amazon.com/ecr/ repository. Session endpoints work with microVM runtimes, not with the Instances compute type, and Session endpoint URLs are reachable over public HTTPS. AWS PrivateLink isn’t supported for inbound connections. Deploy the agent and its website First, you deploy the runtime, and the configuration you choose here decides which ports the Session endpoint can reach. The deployment script bundles the agent into one file, adds the website and its dependencies for the runtime’s Linux on Arm64 system, uploads the zip to Amazon S3, and creates the runtime. The following excerpt from deploy.py shows the two settings that matter for this post. protocolConfiguration says where the agent listens for InvokeAgentRuntime , and allowedPorts lists the ports the Session endpoint can reach: 8090 for the website and 8081 for the agent’s status route. Port 8080 isn’t in the list, because InvokeAgentRuntime reaches the agent without it. For the port and path settings, refer to Configure your agent’s serving port and invocation path https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-configure-invocation.html . The website’s Vite configuration makes the development server reachable from the Session endpoint. It listens on 0.0.0.0 at port 8090 and doesn’t restrict the Host header server.allowedHosts is true , because requests arrive under a host name the runtime assigns rather than localhost . The Session endpoint authenticates every request before it reaches the server, so the server doesn’t need its own host check. To deploy the runtime: 1. Clone the sample repo and change to the sample folder: 2. Open session endpoints preview.ipynb from the sample folder. 3. Run the install cell, which installs the Python dependencies. 4. Run the %run deploy.py cell. Deployment takes a few minutes, mostly waiting for the runtime to reach the READY status. Open the preview With the runtime ready, you start the preview. One call does three things: it starts a session which starts the website , opens a local endpoint for port 8090, and serves the preview page on localhost:8087 . Inside start , the calls that use Session endpoints are short. The first InvokeAgentRuntime call returns the URL in a response header, session endpoint url reads it, and the Session endpoint client opens a local endpoint for port 8090: To open the preview: 1. Run the cell that starts PreviewApp . 2. Open the printed link, http://localhost:8087 , in your browser. The page shows the website on the right, served from port 8090 in the session, and a short guide with suggested requests on the left. Ask the agent for a change Now you ask for a change and watch it arrive. Each prompt goes to the agent through InvokeAgentRuntime . The agent reads the files it needs, writes the ones it changes, and reports each step as it happens. When a file is saved, the Vite development server pushes the change over its WebSocket, through the Session endpoint and the local endpoint, and the website updates in place. To ask for a change: 1. On the preview page, choose Switch this website to a dark coffee-house color theme . 2. Follow the agent’s steps in the chat pane as it reads and saves files. 3. Watch the site pane. It changes when the agent saves the stylesheet, and a banner names the file the change came from. The following video shows the preview page while the agent works through several requests. Choosing a suggested request sends it to the agent, the chat pane lists each file the agent reads and saves, and the site pane on the right updates without a refresh, from the dark theme to a green Order ahead button. The steps stream because the agent answers with server-sent events when you ask it to. You can send the same prompts from Python with app.ask , which reads the stream with iter events from the bedrock-agentcore SDK. The open page updates in the same way: The output of this Python script should resemble the following: Reach a second port in the same session The website isn’t the only server you can reach. The agent serves /status on port 8081, which lists each prompt and the files it changed. The same Session endpoint reaches it, and the only difference is the port argument.