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

通过 Amazon Bedrock AgentCore 运行时实时预览编码代理构建的 Web 应用 | 人工智能

通过 Amazon Bedrock AgentCore 运行时实时预览编码代理构建的 Web 应用

编码代理现在可以构建功能完善的 Web 应用：仪表板、产品页面、产品团队希望尝试的原型。最快捷的审核方式是直接打开应用、使用它、提出修改需求并查看结果。当代理编辑应用时应用能持续运行，这种工作流效果很好，因为每次修改都能在几秒钟内呈现在浏览器中。当应用必须先复制到其他地方部署时，每次修改都需要等待部署完成，审核速度就会降到部署的节奏。

Amazon Bedrock AgentCore 是一个平台，可用于构建、连接和规模化优化代理，您可选择任意代理框架和基础模型（FM）。作为 Amazon Bedrock AgentCore 的一项功能，AgentCore 运行时会在每个隔离的微虚拟机（microVM）中运行每个代理会话。通过会话端点（Session endpoints），您可以从自己的浏览器打开在该会话中运行的应用。会话端点为每个会话提供经过身份验证的 URL，该 URL 会将每个请求的 HTTP 方法、路径、查询字符串和正文，以及 WebSocket 连接转发到您允许的端口。您可以实时观看页面在代理保存每个文件时更新。

在本文中，您将部署一个编码代理，该代理在其会话中持续运行一个 Vite 网站，然后打开一个本地页面，左侧是聊天窗口，右侧是实时网站。您要求代理将网站切换为深色主题，跟随其逐步操作，并观察网站在不刷新的情况下实时变化。最后，您将查看内部实现：同一会话中的第二个端口，以及会话端点拒绝的请求。

完整示例（包括本文所遵循的笔记本）位于 agentcore-samples GitHub 仓库的 14-remote-access 文件夹中。

会话端点的工作原理

每个会话都会获得自己的会话端点，六个细节决定了您如何使用它。

您可以选择允许访问的端口。在调用 CreateAgentRuntime 时，通过 allowedPorts 参数设置，可输入 1–5 个条目，每个条目可以是单个端口或 8000–12000 范围内的端口（排除保留的平台端口）。允许端口不会启动服务器，因此您的应用必须监听该端口并绑定到 0.0.0.0。

URL 随会话一起到达。InvokeAgentRuntime 响应通过 X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url 头部携带该 URL，该头部在 SDK 中暴露为 sessionEndpointUrl。

每个请求都经过身份验证。对于使用 AWS Identity and Access Management (IAM) 的运行时，每个 HTTP 请求、HTTP/2 流和 WebSocket 握手都会携带 Signature Version 4 (SigV4) 签名。调用者还需要在运行时及其运行时端点上拥有 bedrock-agentcore:InvokeAgentRuntimeProxy 权限。对于使用入站 JSON Web Token (JWT) 授权器的运行时，每个请求则携带 bearer token。仅知道 URL 并不能获得访问权限。

主机名选择端口。无论目标端口是什么，客户端始终通过端口 443 连接，主机名上的前缀会选择会话内的端口：

https://8090--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/index.html
https://8081--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/status

它承载着您的服务器所使用的协议。HTTP/1.1 和 HTTP/2 请求（包括服务器推送事件和 gRPC），以及 WebSocket 连接都会经过该端点。本指南使用 HTTP/1.1 和 WebSocket 作为示例。

该端点仅限于单个会话。每次请求都需要在 URL 中添加凭证，且有效期仅限于当前会话。因此请使用该端点构建、测试和审查代理生成的内容。若要将应用提供给用户，请将其部署到托管服务（如 AWS Amplify Hosting）。

浏览器无法自行向页面请求添加 SigV4 签名或 bearer token，因此 bedrock-agentcore SDK 中的 Session 端点客户端可以在您的本地机器上开启一个本地端点。您的浏览器会访问 http://localhost:8088，本地端点会在将请求和 WebSocket 握手转发前，自动添加您的凭证。

Session 端点与 runtime 端点不同，后者由 AgentCore 运行时已提供。使用 runtime 端点（如 DEFAULT）可访问您的代理，控制调用者访问的代理版本。InvokeAgentRuntime 通过 runtime 端点进行解析，因此您可以在不同版本间保持开发与生产环境的独立性，并实现版本升级或回滚而无需修改调用者代码。使用 Session 端点可查看代理在会话期间的实际运行情况（如网页预览）。它是一个经过认证的 URL，仅能访问您授权的端口，兼容会话运行的任意版本，并在会话结束后失效。完整文档请参阅《通过 Session 端点连接运行时会话》。

解决方案概览

该示例包含四个部分。会话中的编码代理在 8080 端口运行，使用 list、read、write 和 edit 四种工具编辑网站文件。代理在 8090 端口启动 Vite 开发服务器，用于托管网站并通过热重载 WebSocket 将每次保存的更改推送到浏览器。在您的本地机器上，PreviewApp 提供预览页面，将您的提示发送至 InvokeAgentRuntime，并为网站开启本地端点。如图 1 所示，预览页面通过本地端点和 Session 端点从 8090 端口的 Vite 开发服务器加载网站，同时通过 InvokeAgentRuntime 将您的提示发送至 8080 端口的代理。数字标记了单次请求的步骤顺序。

图 1：解决方案架构

在步骤 1 之前，PreviewApp 已经调用过一次 InvokeAgentRuntime 以启动会话，该操作同时启动了代理和 Vite 开发服务器。PreviewApp 从响应中读取 Session 端点 URL，并为 8090 端口开启本地端点。图 1 中的编号步骤随后展示了一次更改请求的处理流程：

• 预览页面的站点面板从本地端点（localhost:8088）加载网站。本地端点为每个请求和 WebSocket 握手添加您的凭证后，将其转发至 Session 端点。Session 端点验证签名和端口是否在 allowedPorts 允许范围内，随后将请求转发至 8090 端口的 Vite 开发服务器。页面保持与 Vite 热重载 WebSocket 的连接。

• 您从聊天面板发送提示。PreviewApp 将其作为标准 AWS API 调用（使用您的 AWS 凭证签名）发送至 InvokeAgentRuntime，运行时将其传递给 8080 端口的代理。代理的处理步骤会以流式方式返回至聊天面板。

• 代理调用 Amazon Bedrock 中的 Claude Haiku 5.5 以决定需要进行哪些更改。

• 代理读取网站文件并保存其修改的文件。Vite 开发服务器提供这些文件并监视其更改。

• 当文件保存后，Vite 通过步骤1中打开的 WebSocket 将更改推回 Session 端点和本地端点，网站面板无需刷新即可更新。

• 从笔记本中，PreviewApp 通过相同的 Session 端点读取代理的 8081 端口上的 /status 路由。仅端口发生变化。

8080 端口不在 allowedPorts 中，因为 InvokeAgentRuntime 无需通过 Session 端点即可访问代理。

先决条件

要完成此操作指南，您需要：

• 在提供 AgentCore 运行时 Session 端点的 AWS 区域中拥有 AWS 账户，并配置了凭证。

• 创建 AWS 身份和访问管理 (IAM) 角色、上传到 Amazon Simple Storage Service (Amazon S3) 以及创建运行时的权限，以及在该运行时及其 DEFAULT 运行时端点上使用 bedrock-agentcore:InvokeAgentRuntime 和 bedrock-agentcore:InvokeAgentRuntimeProxy 的权限。有关详细信息，请参阅 AgentCore 运行时的 IAM 权限。

• Python 3.10 或更高版本，以及 bedrock-agentcore 1.25.2 或更高版本和 boto3 1.43.122 或更高版本。

• Git，用于克隆示例仓库，以及 Jupyter 环境（如 JupyterLab 或安装了 Jupyter 扩展的 Visual Studio Code），用于运行笔记本。

• 访问 Amazon Bedrock 中的 Claude Haiku 5.5。有关各区域模型可用性信息，请参阅 按区域划分的模型可用性。

• 安装 Node.js 22 或更高版本及 npm，部署脚本使用它们来打包代理和网站。

该示例将代理作为 zip 文件部署在 Amazon S3 中，使用 Node.js 的直接代码部署，因此您不需要 Docker 或 Amazon Elastic Container Registry (Amazon ECR) 仓库。Session 端点支持 microVM 运行时，但不支持 Instances 计算类型，且 Session 端点 URL 可通过公共 HTTPS 访问。不支持通过 AWS PrivateLink 进行入站连接。

部署代理及其网站

首先，您需要部署运行时，此处选择的配置决定了 Session 端点可以访问的端口。部署脚本将代理打包成一个文件，为运行时的 Arm64 系统添加网站及其依赖项，将 zip 文件上传到 Amazon S3，并创建运行时。

以下 deploy.py 的摘录显示了本文中重要的两个设置。protocolConfiguration 指定代理监听 InvokeAgentRuntime 的位置，allowedPorts 列出 Session 端点可以访问的端口：8090 用于网站，8081 用于代理的 /status 路由。8080 端口不在列表中，因为 InvokeAgentRuntime 不需要通过该端口访问代理。有关端口和路径设置的详细信息，请参阅 配置代理的服务端口和调用路径。

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}],

网站的 Vite 配置使开发服务器可以通过 Session 端点访问。它在 0.0.0.0 的 8090 端口监听，并不限制 Host 请求头（server.allowedHosts 为 true），因为请求是通过运行时分配的主机名而非 localhost 发起的。Session 端点会在请求到达服务器前完成身份验证，因此服务器无需进行主机检查。

部署运行时的步骤如下：

1. 克隆示例仓库并进入示例文件夹：

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

1. 从示例文件夹打开 session_endpoints_preview.ipynb。

1. 运行安装单元格以安装 Python 依赖项。

1. 运行 %run deploy.py 单元格。部署需要几分钟时间，主要等待运行时达到 READY 状态。

启动预览

运行时准备就绪后，启动预览。一次调用会执行三个操作：启动会话（同时启动网站）、为 8090 端口打开本地端点，并在 localhost:8087 上提供预览页面。

from preview_app import PreviewApp

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

在 start() 方法内部，使用 Session 端点的调用过程很简短。第一个 InvokeAgentRuntime 调用会通过响应头返回 URL，session_endpoint_url 读取该 URL，然后 Session 端点客户端为 8090 端口打开本地端点：

answer = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn, runtimeSessionId=session_id,
    payload=json.dumps({"prompt": ""}).encode(), contentType="application/json",
)
endpoint = client.session_endpoint_client(session_endpoint_url(answer))
local = endpoint.open_local_endpoint(port=8090, local_port=8088).start()

启动预览的步骤如下：

• 运行启动 PreviewApp 的单元格。
• 在浏览器中打开打印出的链接 http://localhost:8087。

页面右侧显示从会话的 8090 端口提供的网站，左侧显示包含建议请求的简要指南。

向代理请求更改

现在您可以请求更改并观察其生效过程。每个提示都会通过 InvokeAgentRuntime 发送到代理。代理读取所需文件，修改需要更改的文件，并实时报告每一步操作。当文件保存后，Vite 开发服务器会通过 WebSocket 将更改推送到会话端点和本地端点，网站会立即更新。

请求更改的步骤如下：

• 在预览页面上选择 "Switch this website to a dark coffee-house color theme"。
• 在聊天面板中跟随代理读取和保存文件的步骤。
• 观察站点面板。当代理保存样式表时，网站会立即更新，并显示一个横幅标明更改来源的文件名。

下述视频展示了代理处理多个请求时的预览页面。选择建议请求会将其发送给代理，聊天面板会列出代理读取和保存的每个文件，右侧的站点面板会实时更新，从深色主题变为绿色的"Order ahead"按钮。

图 2：代理工作时的预览页面

步骤实时显示是因为代理在响应请求时会发送服务器端事件。您可以通过 Python 使用 app.ask 方法发送相同提示，该方法通过 bedrock-agentcore SDK 的 iter_events 读取事件流。打开的页面会以相同方式更新：

for event in app.ask("Make the Order ahead button green"):
    if "step" in event:
        print("  ", event["step"])
    elif "done" in event:
        print(event["done"]["reply"])

该 Python 脚本的输出应类似于以下内容：

Looking at the site's files
   Reading src/main.js
   Reading src/style.css
   Reading index.html
   Saved src/style.css
The Order ahead button is now green instead of brown, with white text kept for contrast. You can see it in the hero section, just below the "Small batch coffee, roasted every morning" heading at the top of the page.

在同一会话中访问第二个端口

该网站并不是唯一可访问的服务器。代理服务在 8081 端口提供 /status 接口，用于列出每个提示和修改的文件。相同的 Session 端点可以访问该接口，唯一的区别是端口参数。

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

GET /status on port 8081: HTTP 200
   Make the Order ahead button green -> src/style.css

Session 端点拒绝的请求

当运行时拒绝请求时，会返回 HTTP 状态码、空响应体，并在响应头中包含错误代码，这样你可以区分运行时的拒绝与应用程序返回的错误。笔记本向不在 allowedPorts 中的端口发送请求，并发送没有凭证的请求，运行时会用 403 AccessDenied 拒绝这两种请求。

下表列出了使用 Session 端点构建时可能遇到的拒绝情况。

请求

运行时的响应

不在

allowedPorts

403 AccessDenied

没有有效凭证的请求

或

401 AuthenticationRequired

允许的端口但没有监听服务

502 PortNotReachable

会话已不存在的 URL

404 SessionNotFound

会话访问的保护机制

运行时在转发请求前会移除自身的认证头信息，因此网站不会收到你的签名。请求会在 AWS CloudTrail 中记录为 InvokeAgentRuntimeProxy 事件，事件来源为 bedrock-agentcore.amazonaws.com。本地端点使用你的凭证进行操作，因此会限制可访问的用户。它仅监听 127.0.0.1，只响应发送到本地地址的请求，并拒绝来自其他来源页面的 WebSocket 连接。在预览期间仅运行本地端点。如需更多信息，请参阅 CloudTrail 中的会话端点请求日志。

访问控制不会隔离网站和代理服务。两者运行在同一个会话中，因此请仅授予执行角色代理服务所需的权限。如果运行时替换了会话的计算资源，所有打开的连接将关闭，除非会话使用了持久化存储，否则代理服务的修改可能无法保留。如果需要文件在计算资源结束后仍存在，请参阅 AgentCore 运行时的文件系统配置。

代理服务的文件工具会解析网站文件夹内的所有路径，并拒绝外部路径，因此提示无法让代理服务修改会话中的其他文件。如果其他人可以向你的编码代理发送提示，请考虑使用 Amazon Bedrock Guardrails 过滤有害提示和响应，并在发布前审查代理的修改内容。

清理资源

为避免持续收费，请停止预览并删除示例创建的资源。代理编辑的网站存储在会话中，因此会随会话一起删除。

清理步骤如下：

1. 运行停止单元格，当笔记本提示时按 Enter。这将停止预览页面、本地端点和会话。

1. 运行 %run cleanup.py 单元格，该操作将删除运行时、上传的代码和 IAM 角色。

结论

会话端点通过 HTTP/1.1、HTTP/2 和 WebSocket 协议，让您通过自己工具访问 AgentCore 运行时会话中的应用程序，使用您允许的端口进行认证。在本文中，您部署了一个包含 Vite 网站的编码代理，在其会话中通过本地端点在浏览器中打开实时网站，向代理请求深色主题，并观察代理保存文件时主题变更的生效。您还访问了同一会话的第二个端口，确认了会话端点的拒绝机制。

如需进一步操作，可以使用自己的网站运行笔记本，或修改代理工具以匹配您编码代理的工作方式。如需完整选项（包括端口范围、OAuth、HTTP/2 和 gRPC），请参阅《通过会话端点连接到运行时会话》。

如需修改 InvokeAgentRuntime 在您代理中使用的端口或路径，请参阅《配置代理的服务端口和调用路径》。如果您的代理还需要在相同会话中运行构建或测试命令，请参阅《在 AgentCore 运行时会话中执行 shell 命令》。如需像本示例一样从 zip 文件部署自己的 Node.js 代理，请参阅《Node.js 的直接代码部署》。关于服务的其他功能，请从《使用 Amazon Bedrock AgentCore 运行时托管代理或工具》开始，更多示例请查看 agentcore-samples GitHub 仓库。

关于作者

'"`