编码代理现在能够构建可运行的 Web 应用，例如仪表板、产品页面或产品团队想要尝试的原型。审查这类工作时，最快捷的方式是打开应用、使用它、要求修改并检查结果。如果应用在代理编辑它的地方持续运行，这个循环就会非常高效，每次更改都能在几秒钟内显示在浏览器中。反之，如果应用必须先复制出来再部署到其他地方，那么每次更改都要等待部署，审查速度就会降到部署的速度。
Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化代理的平台，支持您选择的代理框架和基础模型。AgentCore 运行时是 Amazon Bedrock AgentCore 的一项能力，它在独立的微虚拟机中运行每个代理会话。借助 Session 端点，您可以从自己的浏览器打开在该会话中运行的应用。Session 端点为每个会话提供一个经过身份验证的 URL，该 URL 将每个请求的 HTTP 方法、路径、查询字符串和正文以及 WebSocket 连接转发到您允许的端口。当代理保存每个文件时，您可以看到页面更新。
在本文中，您将部署一个编码代理，使其在会话中保持 Vite 网站运行，然后打开一个本地页面，左侧是聊天窗口，右侧是实时网站。您要求代理将网站切换为深色主题，跟随其流式输出的步骤，并无需刷新即可看到网站变化。最后，您将了解内部机制：同一会话中的第二个端口，以及 Session 端点拒绝的请求。
完整的示例（包括本文遵循的笔记本）位于 agentcore-samples GitHub 仓库的 14-remote-access 文件夹中。
Session 端点的工作原理
每个会话都有自己的 Session 端点，六个细节决定了您如何使用它。
您选择它可访问的端口。在调用 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) 授权器的运行时，每个请求携带持有者令牌。知道 URL 并不授予访问权限。
主机名选择端口。您的客户端始终通过端口 443 连接，无论目标端口是什么，主机名上的前缀会选择会话内的端口：
https://8090--.runtime.bedrock-agentcore..on.aws/index.html https://8081--.runtime.bedrock-agentcore..on.aws/status
它承载您的服务器支持的协议。HTTP/1.1 和 HTTP/2 请求（包括服务器发送事件和 gRPC）以及 WebSocket 连接均可通过。本演练使用 HTTP/1.1 和 WebSocket。
它仅作用于一个会话。该 URL 需要在每个请求上提供凭证，并且仅在会话持续期间有效，因此请使用它来构建、测试和审查代理生成的内容。要将应用提供给用户，请将其部署到托管服务，例如 AWS Amplify Hosting。
浏览器无法自行向页面发出的请求添加 SigV4 签名或持有者令牌，因此 bedrock-agentcore SDK 中的 Session 端点客户端可以在您的机器上打开一个本地端点。您的浏览器打开 http://localhost:8088，本地端点会在将每个请求和 WebSocket 握手转发之前添加您的凭证。
Session 端点与 AgentCore 运行时已提供的运行时端点不同。使用运行时端点（例如 DEFAULT）来访问您的代理，它控制调用方将访问哪个版本。InvokeAgentRuntime 调用通过它解析，因此您可以将开发和生产保持在不同的版本上，并在不更改调用方的情况下进行升级或回滚。使用 Session 端点查看代理在其会话中运行的内容，例如 Web 预览。它是一个经过身份验证的 URL，仅能访问您允许的端口，可与会话运行的任何版本配合使用，并在会话结束时停止工作。有关完整文档，请参阅“通过会话端点连接到运行时会话”。
解决方案概述
该示例包含四个部分。一个编码代理在会话中的端口 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 凭证签名的标准 AWS API 调用发送到 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 账户，并已配置凭证。
创建 IAM 角色、上传到 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 ECR 仓库。Session 端点适用于微虚拟机运行时，而不适用于 Instances 计算类型，并且 Session 端点 URL 可通过公共 HTTPS 访问。入站连接不支持 AWS PrivateLink。
部署代理及其网站
首先，您部署运行时，您在此处选择的配置决定了 Session 端点可以访问哪些端口。部署脚本将代理打包到一个文件中，添加网站及其依赖项以用于运行时的 Linux on Arm64 系统，将 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 端点在请求到达服务器之前对每个请求进行身份验证，因此服务器不需要自己的主机检查。
要部署运行时：
- 克隆示例仓库并切换到示例文件夹：
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
- 从示例文件夹中打开 session_endpoints_preview.ipynb。
- 运行安装单元格，它会安装 Python 依赖项。
- 运行 %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()
要打开预览：
运行启动 PreviewApp 的单元格。
在浏览器中打开打印的链接 http://localhost:8087。
页面右侧显示从会话中端口 8090 提供的网站，左侧显示一个简短指南和建议请求。
要求代理进行更改
现在您要求进行更改并观察它到达。每个提示都通过 InvokeAgentRuntime 发送到代理。代理读取所需的文件，写入更改的文件，并在每个步骤发生时报告。当文件保存时，Vite 开发服务器通过其 WebSocket 推送更改，经过 Session 端点和本地端点，网站就会就地更新。
要请求更改：
在预览页面上