Amazon Bedrock AgentCore 推出 Session endpoints，可实时预览编码智能体构建的 Web 应用

编程智能体现在可以构建可运行的 Web 应用：一个仪表盘、一个产品页面、一个产品团队想要试用原型。审查这些工作的最快方式是打开应用、使用它、请求更改，然后检查结果。当应用一直运行在智能体编辑它的地方时，这个循环运转良好，每次更改都能在几秒内出现在浏览器中。而当应用必须先复制出来并部署到别处时，每次更改都要等待部署，审查速度也就被拖慢到部署的节奏。

Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化智能体的平台，可自由选择智能体框架和基础模型（FM）。AgentCore runtime 是 Amazon Bedrock AgentCore 的一项功能，它在各自的隔离 microVM 中运行每个智能体会话。借助 Session endpoints，你可以从自己的浏览器打开该会话中运行的应用。Session Endpoints 为每个会话提供一个经过身份验证的 URL，将每个请求的 HTTP 方法、路径、查询字符串、请求体以及 WebSocket 连接转发到你允许的端口。当智能体保存每个文件时，你可以看到页面实时更新。

在本文中，你将部署一个编程智能体，它在其会话中保持一个 Vite 网站持续运行，然后打开一个本地页面，左侧是聊天窗口，右侧是实时网站。你让智能体把网站切换为深色主题，跟随它的操作步骤流式呈现的过程，并观察网站无需刷新即发生变化。最后，你将了解内部发生了什么：同一会话中的第二个端口，以及 Session endpoint 拒绝的请求。

完整的示例，包括本文所使用的 notebook，位于 agentcore-samples GitHub 仓库的 14-remote-access 文件夹中。

Session endpoints 的工作原理

每个会话都有自己专属的 Session endpoint，以下六个细节决定了你如何使用它。

你选择它可达的端口。 你在调用 CreateAgentRuntime 时设置 allowedPorts：1–5 个条目，每个条目为单个端口或 8000–12000 范围内的一个区间，不包括保留的平台端口。允许某个端口并不会启动服务器，因此你的应用必须监听该端口，并绑定到 0.0.0.0。

URL 随会话一起返回。InvokeAgentRuntime 响应会在 X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-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 签名或持有者令牌，因此 bedrock-agentcore SDK 中的 Session endpoint 客户端可以在你的机器上打开一个本地端点。你的浏览器打开 http://localhost:8088，本地端点会在转发之前将你的凭证添加到每个请求和 WebSocket 握手中。

Session endpoint 不同于 AgentCore runtime 已经提供的运行时端点。使用运行时端点（例如 DEFAULT）来访问你的智能体，它控制调用者将访问哪个版本。InvokeAgentRuntime 调用会通过它解析，因此你可以让开发和生产使用不同的版本，并在不更改调用者的情况下进行提升或回滚。使用 Session endpoint 可以查看你的智能体在其会话中运行的内容，例如网页预览。它是一个经过身份验证的 URL，只访问你允许的端口，与会话运行的任何版本配合工作，并在会话结束时停止工作。完整文档请参阅 Connect to runtime sessions through a session endpoint。

解决方案概览

该示例包含四个部分。一个编码智能体在会话中的 8080 端口上运行，并使用四个工具（list、read、write 和 edit）编辑网站文件。该智能体在 8090 端口上启动一个 Vite 开发服务器，该服务器提供网站服务，并通过其热重载 WebSocket 将每次保存的更改推送到浏览器。在你的机器上，PreviewApp 提供预览页面，将你的提示词发送到 InvokeAgentRuntime，并为网站打开一个本地端点。如图 1 所示，预览页面通过本地端点和 Session endpoint 从 8090 端口上的 Vite 开发服务器加载网站，并通过 InvokeAgentRuntime 将你的提示词发送到 8080 端口上的智能体。数字表示单个请求各步骤的顺序。

图 1：解决方案架构

在第 1 步之前，PreviewApp 已经调用过一次 InvokeAgentRuntime 来启动会话，这会启动智能体和 Vite 开发服务器。PreviewApp 从该响应中读取了 Session endpoint URL，并为 8090 端口打开了一个本地端点。图 1 中的编号步骤随后按一次更改请求依次进行：

1. 预览页面的网站面板从 localhost:8088 上的本地端点加载网站。本地端点将你的凭证添加到每个请求和 WebSocket 握手中，并将它们转发到 Session endpoint。Session endpoint 将签名和端口与 allowedPorts 进行校验，然后将它们转发到 8090 端口上的 Vite 开发服务器。页面保持 Vite 热重载 WebSocket 打开。
2. 你从聊天面板发送一个提示词。PreviewApp 将其作为一个使用你的 AWS 凭证签名的标准 AWS API 调用发送到 InvokeAgentRuntime，运行时将其传递给 8080 端口上的智能体。智能体的执行步骤在工作过程中流式传回聊天面板。
3. 智能体调用 Amazon Bedrock 中的 Claude Haiku 5.5 来决定要更改什么。
4. 智能体读取网站文件并保存它更改的文件。Vite 开发服务器提供这些文件的服务，并监视它们的更改。
5. 当文件被保存时，Vite 通过在第 1 步中打开的 WebSocket 推送该更改，经由 Session endpoint 和本地端点传回，网站面板无需刷新即完成更新。
6. 在该 notebook 中，PreviewApp 通过相同的 Session 端点在端口 8081 上读取智能体的 /status 路由。改变的只有端口。

端口 8080 不在 allowedPorts 中，因为 InvokeAgentRuntime 无需经过 Session 端点即可访问该智能体。

前提条件

要按照本演练操作，你需要：

• 一个位于 AgentCore 运行时 Session 端点可用区域的 AWS 账户，并已配置好凭证。
• 创建 AWS Identity and Access Management (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），用于运行 notebook。
• 在 Amazon Bedrock 中访问 Claude Haiku 5.5。有关各区域的模型可用性，请参阅 Regional availability by models。
• 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 Linux 系统添加网站及其依赖项，将 zip 上传到 Amazon S3，并创建运行时。

以下来自 deploy.py 的摘录展示了本文涉及的两个重要设置。protocolConfiguration 指定智能体在何处监听 InvokeAgentRuntime，allowedPorts 列出了 Session 端点可以访问的端口：8090 用于网站，8081 用于智能体的状态路由。端口 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

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

3. 运行安装单元格，它会安装 Python 依赖项。

4. 运行 %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 读取它，然后 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()

要打开预览：

1. 运行以 PreviewApp 开头的单元格。
2. 在浏览器中打开打印出的链接 http://localhost:8087。

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

向智能体请求更改

现在你请求一个更改并观察它的到来。每个提示词都会通过 InvokeAgentRuntime 发送给智能体。智能体读取所需的文件、写入它要更改的文件，并在每个步骤发生时进行报告。当文件被保存时，Vite 开发服务器通过 WebSocket（经由 Session 端点和本地端点）推送更改，网站随即就地更新。

要请求更改：

1. 在预览页面上，选择将此网站切换为深色咖啡馆配色主题。
2. 在聊天窗格中跟随智能体读取和保存文件的步骤。
3. 观察网站窗格。当智能体保存样式表时它会发生更改，并且横幅会指明更改所来自的文件。

以下视频展示了智能体处理多个请求时的预览页面。选择一个建议请求会将其发送给智能体，聊天窗格会列出智能体读取和保存的每个文件，右侧的网站窗格无需刷新即从深色主题更新为绿色的 Order ahead 按钮。

图 2：智能体工作时的预览页面

这些步骤之所以能够流式传输，是因为当你要求时，智能体会以服务器发送事件进行响应。你可以通过 app.ask 从 Python 发送相同的提示词，它使用 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"]))

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

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

Session 端点会拒绝哪些请求

当运行时拒绝请求时，它会返回一个 HTTP 状态码、空的响应体，以及响应头中的错误代码，因此你可以将运行时的拒绝与应用程序自身返回的错误区分开。笔记本会发送一个发往 allowedPorts 之外端口的请求和一个不带凭证的请求，运行时对两者均以 403 AccessDenied 拒绝。

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

会话访问如何受到保护

运行时在转发请求之前会移除自己的身份验证头，因此网站不会收到你的签名。请求会作为 InvokeAgentRuntimeProxy 事件记录在 AWS CloudTrail 中，事件源为 bedrock-agentcore.amazonaws.com。本地端点以你的凭证运行，因此它限制了谁可以使用它。它只在 127.0.0.1 上监听，只响应发往其自身本地地址的请求，并拒绝来自其他来源页面发起的 WebSocket 连接。请仅在使用预览时运行本地端点。更多信息，请参阅 在 CloudTrail 中记录会话端点请求。

访问控制并未将网站与智能体分离。两者运行在同一个会话中，因此请只为执行角色授予智能体所需的权限。如果运行时替换了会话的计算资源，已打开的连接会关闭，智能体的修改也可能无法保留，除非会话使用持久化存储。如果你希望文件在计算资源结束后仍然保留，请参阅AgentCore 运行时的文件系统配置。

智能体的文件工具会将所有路径解析到站点文件夹内，并拒绝该文件夹之外的路径，因此提示词无法让智能体修改会话中的其他文件。如果其他人可以向你的编码智能体发送提示词，请考虑使用 Amazon Bedrock Guardrails 来过滤有害的提示词和响应，并在发布之前审查智能体的修改。

清理

为避免持续产生费用，请停止预览并删除示例创建的资源。智能体编辑的网站保存在会话中，因此它会随会话一起删除。

清理步骤：

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

2. 运行 %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 仓库中查找更多示例。

关于作者