高代码 Agent 部署与使用指南

1. 准备容器镜像

公开镜像中不要包含密钥和业务数据。镜像构建示例请参见使用 Python SDK 快速创建高代码 Agent。

应用应监听 0.0.0.0，并实现健康检查和所需的对话接口。确认实际启动命令、服务端口、健康检查路径及协议路径。

2. 创建 Agent 并选择镜像

1. 登录 AgentCore 控制台，选择目标地域和 Workspace。

2. 进入 Agent 列表，单击 创建 Agent，选择 自定义代码 / 镜像。

3. 填写 Agent 名称和可选的描述。

4. 在 选择代码来源 中选择 容器镜像。

5. 依次选择 容器镜像实例、镜像仓库 和 镜像版本。

建议每次发布使用明确的版本标签，以便确认实际部署内容。

3. 配置启动方式和执行角色

在创建页面填写以下启动配置。

按页面显示的执行角色状态处理授权：

授权窗口被拦截时，应允许弹出窗口后重试。执行角色用于应用访问云资源；外部系统调用 Agent 使用 Endpoint 页面提供的鉴权信息。

使用模型、MCP 或 Skill 时，需要在应用代码中完成接入。相关方法请参见对应 SDK 指南。

4. 声明对话协议

在 协议配置 中单击 配置，选择应用已实现的协议，填写 Path，并按需添加 Header，完成后保存。可同时选择两种协议。

Path 应以 / 开头，填写应用实际路由，不包含域名。例如应用使用 /v1/chat/completions，应将预填值改为该路径。

Header 用于该 Agent 协议接口所需的固定请求头，没有额外要求时留空。不要把下游模型的 API Key 填入这里。

勾选协议不会自动生成接口或工具事件。未声明协议，或协议与实际路由、响应格式不一致，会影响控制台调试。

5. 配置运行资源和健康检查

在 高级配置 中按应用需求配置。

健康检查失败可能导致实例停止接收流量或重启。修改应用端口时，也要核对健康检查端口。

Python SDK 镜像快速入门使用以下配置。其他应用应按实际实现填写。

6. 配置网络和日志

检查 ACR 网络访问控制：未启用 VPC 访问时检查公网拉取路径，并按需将页面显示的 Workspace 公网出口 IP 加入 ACR 白名单；启用 VPC 访问时，确认仓库允许对应 VPC 访问。

应用应输出必要的启动及错误日志，避免记录密钥或敏感内容。

7. 提交创建并验证

1. 核对镜像版本、启动命令、服务端口、执行角色、协议和健康检查，单击 立即创建。

2. 返回 Agent 列表查看状态，打开详情，在 概览与配置 中核对已保存的镜像和运行配置。

3. 等待实例及调试端点就绪，进入 调试，选择已声明的协议。

4. 发送一条简单消息，检查返回结果，再验证模型、工具或业务资源调用。

5. 如需重新开始对话，单击 创建会话。异常时记录会话 ID、失败时间，并打开 运行日志 排查。

AGUI 执行过程和工具事件由应用实际输出的协议事件决定，勾选协议不会自动补齐事件。

8. 更新镜像

1. 构建新镜像并推送到 ACR。

2. 在 Agent 的 概览与配置 中进入 编辑配置。

3. 刷新镜像版本列表，选择新版本，并同步调整发生变化的入口、端口、协议和健康检查。

4. 保存后等待更新完成，再验证调试和业务调用。

仅推送镜像不会代替 Agent 配置更新，应在详情中核对实际选择的版本。

更新可能影响正在处理的请求，请选择合适的业务时间窗口操作。

1. 准备代码包

格式和运行要求

依赖可以在本地或 CI 中准备。含原生扩展、二进制依赖或 JNI 的应用，需要特别检查操作系统、CPU 架构和语言版本兼容性，避免直接打包 macOS、Windows 或 ARM 环境生成的不兼容依赖。

仅包含 requirements.txt、package.json 或 pom.xml 等依赖描述文件，不能代替实际运行依赖。

包内结构和启动命令

建议进入项目目录后，将目录内的运行文件打包。例如：

cd my-agent
zip -r ../package.zip .

这样入口文件位于 ZIP 根目录。如果实际包结构为 my-agent/main.py，启动命令应填写 python my-agent/main.py。平台不会自动去掉外层文件夹。

如果需要执行多条启动命令，可以将逻辑写入代码包中的 start.sh，启动命令填写 sh start.sh。

代码包支持 Python 3.12、Node.js 22 和 Java 17，实际可用项以当前地域、Workspace 的 运行时 列表为准。使用代码包部署无需自行准备 ACR 镜像。

2. 创建 Agent 并选择运行时

1. 登录 AgentCore 控制台，选择目标地域和 Workspace。

2. 进入 Agent 列表，单击 创建 Agent，选择 自定义代码 / 镜像。

3. 填写 Agent 名称和可选的描述。

4. 在 选择代码来源 中选择 上传代码包。

5. 在 运行时 中选择与应用匹配的语言环境。列表加载失败时可单击 重试。

3. 提供代码包

上传代码包 同时用于部署方式和本地来源选项：先选择代码包部署，再在下方选择本地上传、OSS 或示例来源。

方式一：上传本地代码包

1. 在代码包来源中选择 上传代码包。

2. 单击 点击上传，或将 ZIP 文件拖入上传区域。

3. 页面会自动开始上传。等待出现“代码包上传成功！”。

4. 如需更换文件，单击 重新上传 或重新选择文件，并等待新文件上传成功。

5. 继续完成启动配置和其他部署配置。

上传区域显示文件名不代表上传已经完成。上传失败时，请检查文件格式、大小和网络后重试。

方式二：使用 OSS 代码包

1. 选择 使用 OSS 代码包。

2. 在 Bucket 名称 下拉框中选择当前账号、当前地域的 Bucket。可以搜索 Bucket 名称，也可以刷新列表。

3. 页面会检查 Bucket 授权状态。若提示需要授权，单击 前往授权，按页面提示完成授权；返回后刷新授权状态。

4. 在 OSS 目录 中填写 ZIP 文件的完整对象路径，包含文件名。

5. 单击 校验代码包。

6. 出现“代码包已就绪，可提交保存”后，继续完成其他部署配置。

填写示例：

OSS 目录 应填写对象路径，不要只填写 releases/v1/，也不要填写带 Bucket 名称的完整 URL。

Bucket 授权与代码包校验是两个步骤。授权完成后，仍需对具体文件单击 校验代码包。当前授权页面会提示对象读、写、删除权限，请核对页面展示的授权范围。导入代码包无需将 Bucket 设置为公开可读。

校验用于检查文件是否存在、大小是否符合要求以及是否可读取，不会启动应用。更换 Bucket 或对象路径后，需要重新校验。保存完成前，请保持来源文件可读，避免覆盖或删除文件。

使用 OSS 来源无需另外配置 挂载 OSS。如果应用需要挂载业务数据，再按实际需求配置数据挂载。

方式三：使用示例代码创建

1. 选择所需 运行时。

2. 选择 使用示例代码创建。页面会选择对应示例包并带入启动命令。

3. 核对服务端口、健康检查和对话协议配置。

4. 根据是否需要调用真实模型，填写或留空示例的模型环境变量。

5. 完成其他部署配置后提交创建。

示例配置如下：

三个示例使用相同的服务和协议配置：

示例模式会补齐 AGUI 协议。若此前已配置 AGUI 路径或请求头，请核对原配置是否适用于当前示例。

选定运行时后，可单击 下载示例代码包，按弹窗提示下载对应代码。示例包已包含运行所需依赖，可以直接部署；修改示例后需要重新打包。

示例支持以下环境变量，名称使用大写，区分大小写：

页面会补充这两个环境变量名称，已有同名值会保留。填写方式与运行结果如下：

首次体验可以将两项均留空。调用真实模型前，应先配置 Workspace 模型连接，并确保执行角色权限和网络满足访问要求。模型解析或调用失败时，示例会返回错误提示。

工具、MCP 和 Skill 的接入用法以注释形式提供，需要根据业务补充实现并重新打包。

4. 配置启动方式和执行角色

完成代码包上传、OSS 校验或示例选择后，填写以下启动配置。

代码包部署无需填写平台内部目录、OSS 挂载路径或解压命令。

按页面显示的执行角色状态处理授权：

授权窗口被拦截时，应允许弹出窗口后重试。执行角色用于应用访问云资源；OSS 来源授权用于读取部署文件；外部系统调用 Agent 则使用 Endpoint 页面提供的鉴权信息。

使用模型、MCP 或 Skill 时，需要在应用代码中完成接入。相关方法请参见对应 SDK 指南。

5. 声明对话协议

在 协议配置 中单击 配置，选择应用已实现的协议，填写 Path，并按需添加 Header，完成后保存。可同时选择两种协议。

Path 应以 / 开头，填写应用实际路由，不包含域名。例如应用使用 /v1/chat/completions，应将预填值改为该路径。

Header 用于该 Agent 协议接口所需的固定请求头，没有额外要求时留空。不要把下游模型的 API Key 填入这里。

勾选协议不会自动生成接口或工具事件。未声明协议，或协议与实际路由、响应格式不一致，会影响控制台调试。

6. 配置运行资源和健康检查

在 高级配置 中按应用需求配置。

健康检查失败可能导致实例停止接收流量或重启。修改应用端口时，也要核对健康检查端口。

使用控制台代码包示例时，服务端口和健康检查端口均为 8080，健康检查路径为 /healthz。自有代码请按实际实现填写，不能只保留页面默认值。

7. 配置网络和日志

代码包方式无需配置自有 ACR 仓库。业务代码需要访问的外部服务，仍需满足对应网络条件。Hello World 代码包示例无需连接真实模型。

应用应输出必要的启动及错误日志，避免记录密钥或敏感内容。

8. 提交创建并验证

1. 核对运行时、代码包、启动命令、服务端口、执行角色、协议和健康检查，单击 立即创建。

2. 返回 Agent 列表查看状态，并在详情 概览与配置 中核对已保存的代码包和运行配置。

3. 等待实例及调试端点就绪，进入 调试，选择应用已声明的协议。

4. 使用本文代码包示例时选择 AGUI，发送一条简单消息。两个模型变量均留空时，应收到变量未配置的英文提示和 Hello World；完整配置后应收到真实模型响应。

5. 基础调用成功后，再验证工具和其他业务资源访问。异常时记录会话 ID、失败时间，并打开 运行日志 排查；需要新对话时单击 创建会话。

上传或校验成功只代表该步骤完成。平台会保存代码包，在启动时解压并执行入口命令，最终仍需验证应用能够正常启动和调用。

9. 更新代码包

1. 打开 Agent 详情，在 概览与配置 中进入 编辑配置。

2. 根据需要选择更新方式。

3. 核对运行时、启动命令、服务端口、健康检查和协议后，单击 保存。

4. 等待更新完成，再验证调试和业务调用。

覆盖原 OSS 路径中的文件，不会自动更新已部署 Agent。

例如，覆盖 releases/package.zip 后，Agent 仍使用先前保存的代码包副本。要部署新内容，需要进入 更新代码包，重新选择该来源，完成校验并保存。仅修改其他配置并保留当前代码包，不会重新读取 OSS 中的最新文件。

更新可能影响正在处理的请求，请选择合适的业务时间窗口操作。

10. 下载当前代码包

1. 打开 Agent 详情的 概览与配置。

2. 在 代码配置 中查看 运行时 和 代码包。

3. 单击代码包的文件名链接进行下载。

本地上传、OSS 导入和使用示例创建的已保存代码包，均可通过此入口下载。

下载内容为当前配置保存的代码包，不包含应用运行时产生的文件或修改。对于 OSS 来源，下载内容也不会随原 OSS 对象被覆盖而自动变化。

下载链接有有效期。链接过期或下载失败时，返回页面再次单击代码包文件名获取新链接。

通用问题

代码包常见问题