Agent Runtime 使用 Agent 沙箱

一、目标与结果

完成这篇操作后，你将获得：

·一个状态为 ACTIVE 的 WAA 沙箱工具。

·一个状态为 RUNNING 的 WAA 沙箱实例。

·可在浏览器中打开的 Windows 桌面地址，以及截图、平台信息、命令执行等入口。

二、前提条件

使用前请确认以下条件已满足：

1. 已注册腾讯云账号，并完成实名认证。

2. 已开通腾讯云 Agent Runtime 服务。如未开通，可 提交工单 申请开通。

3. 已获取 API 密钥（SecretId / SecretKey）：

·登录 腾讯云控制台。

·进入 访问管理 > API 密钥管理。

·新建密钥或使用已有密钥，记录 SecretId 和 SecretKey。

4. 已选择目标地域。这篇以广州为例，其他地域的可用性以当前控制台为准：

三、步骤概览

1. 安装 agr CLI。

2. 配置腾讯云凭证。

3. 设置默认地域与 Domain。

4. 验证配置与连通性。

5. 创建 WAA 沙箱工具。

6. 创建沙箱实例。

7. 获取并打开 Windows 桌面。

五、步骤 1：安装 agr CLI

# 方式一：脚本安装curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | sh# 方式二：go install（需要 Go 环境）go install github.com/TencentCloudAgentRuntime/ags-cli/cmd/agr@latestexport PATH="$HOME/go/bin:$PATH"# 验证安装agr version -o json –non-interactive

详细安装说明请参见 agr CLI 安装与配置。

六、步骤 2：配置腾讯云凭证

注意：凭证仅写入本地 ~/.agr/config.toml。请勿将 SecretId / SecretKey 写入文档或提交到代码仓库。也可改用环境变量 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY。

agr init \\ –secret-id "<YOUR_SECRET_ID>" \\ –secret-key "<YOUR_SECRET_KEY>" \\ –non-interactive

七、步骤 3：设置默认地域与 Domain

agr config set region ap-guangzhouagr config set domain tencentags.com

八、步骤 4：验证配置与连通性

agr doctor -o json –non-interactive

检查配置、凭据和 API 连通性诊断结果。Connectivity 失败时，结合返回错误排查网络、凭据、权限和服务开通情况；该命令不检查 Windows 内的桌面或控制服务是否就绪。

九、步骤 5：创建 WAA 沙箱工具

WAA 是平台内置的 Windows 沙箱类型。你可以根据需要创建限时沙箱或常驻沙箱，两者不要混用。

十、方式一：创建限时沙箱工具

TOOL_NAME="my-waa-tool-$(date +%s)-$$"TOOL_ID=$(agr tool create \\ –tool-name "$TOOL_NAME" \\ –tool-type waa \\ –network-configuration '{"NetworkMode":"PUBLIC"}' \\ –default-timeout 1h \\ -o json –non-interactive –jq '.Data.ToolId')echo "ToolId: $TOOL_ID"

十一、方式二：创建常驻沙箱工具

TOOL_NAME="my-waa-tool-$(date +%s)-$$"TOOL_ID=$(agr tool create \\ –tool-name "$TOOL_NAME" \\ –tool-type waa \\ –network-configuration '{"NetworkMode":"PUBLIC"}' \\ –persistent \\ -o json –non-interactive –jq '.Data.ToolId')echo "ToolId: $TOOL_ID"

十二、参数说明

注意：说明：

注意：限时 WAA 沙箱实例的最长存活时长为 24 小时；常驻沙箱（–persistent）的实例不受该上限约束。

确认工具状态为 ACTIVE，否则停止后续创建并排查：

for attempt in $(seq 1 24); do TOOL_STATUS=$(agr tool get "$TOOL_ID" -o json –non-interactive –jq '.Data.Status') echo "工具状态: $TOOL_STATUS" [ "$TOOL_STATUS" = "ACTIVE" ] && break [ "$TOOL_STATUS" = "FAILED" ] && exit 1 sleep 5done[ "$TOOL_STATUS" = "ACTIVE" ] || { echo "工具未就绪，请排查并清理本次资源" >&2; exit 1; }

十三、步骤 6：创建沙箱实例

INSTANCE_ID=$(agr instance create \\ –tool-name "$TOOL_NAME" \\ –auth-mode PUBLIC \\ –timeout 1h \\ -o json –non-interactive –jq '.Data.InstanceId')echo "InstanceId: $INSTANCE_ID"

注意：PUBLIC 会让 5000 等业务端口允许匿名访问，包括 /setup/execute 命令执行接口。请只用于隔离的测试实例，不要在沙箱中放入敏感数据，用完及时删除。

等待实例与服务就绪。RUNNING 仅代表实例状态，控制服务与桌面可能仍在启动；以下轮询有次数上限，失败时停止并排查：

REGION=ap-guangzhouDOMAIN=tencentags.comfor attempt in $(seq 1 36); do STATUS=$(agr instance get "$INSTANCE_ID" -o json –non-interactive –jq '.Data.Status') echo " 状态: $STATUS" [ "$STATUS" = "RUNNING" ] && break case "$STATUS" in FAILED|STOPPED|STOPPING) echo "实例启动失败: $STATUS" >&2; exit 1;; esac sleep 5done[ "$STATUS" = "RUNNING" ] || exit 1# RUNNING 不代表 Windows 内的 WAA 服务已经就绪echo ">>> 等待 WAA 服务与桌面就绪…"READY=falsefor attempt in $(seq 1 24); do if PLATFORM=$(curl -k -fsS –max-time 10 "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/platform" 2>/dev/null) && \\ [ "$PLATFORM" = "Windows" ] && \\ curl -k -fsS –max-time 10 "https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/vnc.html" > /dev/null 2>&1; then READY=true break fi sleep 5done[ "$READY" = "true" ] || { echo "WAA 服务未就绪，请检查镜像与实例" >&2; exit 1; }curl -k -fsS –max-time 60 "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/screenshot" -o screenshot.png

十四、步骤 7：获取并打开桌面

先通过 CLI 取回访问 Token，再按 WAA 的 noVNC 页面路径 /vnc.html 拼接地址：

REGION=ap-guangzhouDOMAIN=tencentags.comAGR_VNC_URL=$(agr instance browser vnc "$INSTANCE_ID" –port 8006 -o json –non-interactive –jq '.Data.VncUrl')VNC_TOKEN=${AGR_VNC_URL##*access_token=}VNC_TOKEN=${VNC_TOKEN%%&*}VNC_URL="https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/vnc.html?path=websockify?token=${VNC_TOKEN}"echo "$VNC_URL"

注意：说明：

注意：CLI 返回的地址中页面路径为 /novnc/vnc_lite.html，在 WAA 镜像下该路径会返回 404；WAA 的 noVNC 页面实际是 /vnc.html，因此需要按上面的方式用 access_token 重新拼接。Token 必须取自当前实例的 CLI 返回值，完整 URL 含访问凭证，请勿公开分享。

注意：实例进入 RUNNING 后，noVNC 服务可能仍在初始化。页面 HTTP 200 也不能代替桌面连接验证，请在浏览器中确认能看到 Windows 桌面。

十五、端口与访问地址

数据面访问地址格式：

https://<port>-<instance_id>.<region>.<domain>/<path>

以广州地域为例（请替换 instance_id）：

https://5000-<instance_id>.ap-guangzhou.tencentags.com/screenshothttps://8006-<instance_id>.ap-guangzhou.tencentags.com/vnc.html

常用端口：

注意：说明：

注意：端口是否可用取决于镜像内对应服务是否已启动。特别是 9222 需要单独启动 Chrome 和 CDP 代理，不能仅凭实例进入 RUNNING 就认定可用。

十六、结果验证

检查实例状态、平台信息和桌面截图：

# 预期输出 RUNNINGagr instance get "$INSTANCE_ID" -o json –non-interactive –jq '.Data.Status'# 预期返回 Windowscurl -k -sS –max-time 10 \\ "https://5000-${INSTANCE_ID}.ap-guangzhou.tencentags.com/platform"# 保存桌面截图curl -k -sS –max-time 60 \\ "https://5000-${INSTANCE_ID}.ap-guangzhou.tencentags.com/screenshot" \\ -o screenshot.png

在浏览器中打开步骤 7 得到的 noVNC 地址，确认能看到 Windows 桌面。

十七、常用操作示例

以下命令中的 INSTANCE_ID、REGION、DOMAIN 需替换为实际值：

INSTANCE_ID="your-instance-id"REGION=ap-guangzhouDOMAIN=tencentags.com

十八、获取并打开 noVNC 桌面

AGR_VNC_URL=$(agr instance browser vnc "$INSTANCE_ID" –port 8006 -o json –non-interactive –jq '.Data.VncUrl')VNC_TOKEN=${AGR_VNC_URL##*access_token=}VNC_TOKEN=${VNC_TOKEN%%&*}VNC_URL="https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/vnc.html?path=websockify?token=${VNC_TOKEN}"echo "$VNC_URL"# 浏览器打开（macOS）open "$VNC_URL"

十九、获取当前桌面截图

curl -k -sS –max-time 60 \\ "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/screenshot" \\ -o screenshot.png

注意：说明：

注意：在 noVNC 不可用时，可通过截图确认桌面是否正常显示。

20、查看平台信息

curl -k -sS –max-time 10 "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/platform"# 预期返回: Windows

21、在沙箱内执行命令

# 获取当前用户和主机名curl -k -sS –max-time 30 \\ -H 'Content-Type: application/json' \\ -d '{"command":"whoami && hostname","shell":true}' \\ "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/setup/execute"# 列出目录curl -k -sS –max-time 30 \\ -H 'Content-Type: application/json' \\ -d '{"command":"dir C:\\\\Users","shell":true}' \\ "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/setup/execute"

返回格式：

{ "error": "", "output": "<command output>", "returncode": 0, "status": "success"}

注意：说明：

注意：WAA 是 Windows 环境，请使用 Windows 命令（whoami、dir、hostname），不要使用 Linux 命令（id、ls）。

22、浏览器自动化（CDP）

依次启动 Chrome 和 CDP 代理：

curl -k -sS –max-time 60 \\ -H 'Content-Type: application/json' \\ -d '{ "command": [ "google-chrome", "–remote-debugging-port=1337", "–force-renderer-accessibility" ], "shell": false}' \\ "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/setup/launch"curl -k -sS –max-time 60 \\ -H 'Content-Type: application/json' \\ -d '{ "command": [ "socat", "tcp-listen:9222,fork", "tcp:localhost:1337" ], "shell": false}' \\ "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/setup/launch"

检查 CDP 入口：

curl -k -sS –max-time 10 "https://9222-${INSTANCE_ID}.${REGION}.${DOMAIN}/json/version"

返回的 webSocketDebuggerUrl 可用于连接 CDP；连接失败时见“CDP 返回 502”。

23、查看 noVNC 静态资源目录

以下命令查看 noVNC Web 服务的静态资源目录，返回内容包括 app/、core/、vendor/ 和 vnc.html 等。该入口不用于浏览 Windows 沙箱文件系统。

curl -k -sS –max-time 10 "https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/"

24、端到端创建脚本

在已安装 agr 并配置凭据的 Bash 环境运行。脚本创建常驻 WAA 沙箱，校验工具和实例状态，再等待 5000/8006 服务并保存截图。脚本成功后仍需在浏览器中确认桌面连接；CDP 需另按“浏览器自动化（CDP）”启动。

#!/bin/bashset -euo pipefail# ====== 修改以下变量 ======TOOL_NAME="my-waa-tool-$(date +%s)-$$"REGION="ap-guangzhou"DOMAIN="tencentags.com"TOOL_ID=""INSTANCE_ID=""# 失败时保留排查线索；按输出的 ID 清理本次创建的资源。trap 'rc=$?; if [ "$rc" -ne 0 ]; then echo "创建未完成（退出码 ${rc}）。ToolId=${TOOL_ID} InstanceId=${INSTANCE_ID}；请排查并清理本次资源。" >&2; fi' EXIT# ====== 创建工具 ======echo ">>> 创建沙箱工具…"TOOL_ID=$(agr –region "$REGION" –domain "$DOMAIN" tool create \\ –tool-name "$TOOL_NAME" \\ –tool-type waa \\ –network-configuration '{"NetworkMode":"PUBLIC"}' \\ –persistent \\ -o json –non-interactive –jq '.Data.ToolId')echo "ToolId: $TOOL_ID"# 确认工具就绪for attempt in $(seq 1 24); do TOOL_STATUS=$(agr –region "$REGION" –domain "$DOMAIN" tool get "$TOOL_ID" -o json –non-interactive –jq '.Data.Status') echo "工具状态: $TOOL_STATUS" [ "$TOOL_STATUS" = "ACTIVE" ] && break [ "$TOOL_STATUS" = "FAILED" ] && exit 1 sleep 5done[ "$TOOL_STATUS" = "ACTIVE" ] || { echo "工具未就绪，请排查并清理本次资源" >&2; exit 1; }# ====== 创建实例 ======echo ">>> 创建沙箱实例…"INSTANCE_ID=$(agr –region "$REGION" –domain "$DOMAIN" instance create \\ –tool-name "$TOOL_NAME" \\ –auth-mode PUBLIC \\ -o json –non-interactive –jq '.Data.InstanceId')echo "InstanceId: $INSTANCE_ID"# ====== 等待就绪 ======echo ">>> 等待实例启动（Windows 沙箱约需 30~90 秒）…"for attempt in $(seq 1 36); do STATUS=$(agr –region "$REGION" –domain "$DOMAIN" instance get "$INSTANCE_ID" -o json –non-interactive –jq '.Data.Status') echo " 状态: $STATUS" [ "$STATUS" = "RUNNING" ] && break case "$STATUS" in FAILED|STOPPED|STOPPING) echo "实例启动失败: $STATUS" >&2; exit 1;; esac sleep 5done[ "$STATUS" = "RUNNING" ] || exit 1# RUNNING 不代表 Windows 内的 WAA 服务已经就绪echo ">>> 等待 WAA 服务与桌面就绪…"READY=falsefor attempt in $(seq 1 24); do if PLATFORM=$(curl -k -fsS –max-time 10 "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/platform" 2>/dev/null) && \\ [ "$PLATFORM" = "Windows" ] && \\ curl -k -fsS –max-time 10 "https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/vnc.html" > /dev/null 2>&1; then READY=true break fi sleep 5done[ "$READY" = "true" ] || { echo "WAA 服务未就绪，请检查镜像与实例" >&2; exit 1; }curl -k -fsS –max-time 60 "https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/screenshot" -o screenshot.png# ====== 获取 noVNC URL ======AGR_VNC_URL=$(agr –region "$REGION" –domain "$DOMAIN" instance browser vnc "$INSTANCE_ID" –port 8006 -o json –non-interactive –jq '.Data.VncUrl')VNC_TOKEN=${AGR_VNC_URL##*access_token=}VNC_TOKEN=${VNC_TOKEN%%&*}VNC_URL="https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/vnc.html?path=websockify?token=${VNC_TOKEN}"# ====== 输出访问入口 ======echo ""echo "========================================="echo " WAA 实例、控制服务与 noVNC 页面检查通过"echo "========================================="echo "ToolId: $TOOL_ID"echo "InstanceId: $INSTANCE_ID"echo ""echo "noVNC 桌面: $VNC_URL"echo "截图: https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/screenshot"echo "平台信息: https://5000-${INSTANCE_ID}.${REGION}.${DOMAIN}/platform"echo "CDP（尚未启动；请执行“浏览器自动化（CDP）”）: https://9222-${INSTANCE_ID}.${REGION}.${DOMAIN}/json/version"echo ""echo "删除实例: agr –region "$REGION" –domain "$DOMAIN" instance delete $INSTANCE_ID –ignore-not-found –yes"echo "删除工具: agr –region "$REGION" –domain "$DOMAIN" tool delete $TOOL_ID –yes"

如需创建限时沙箱，请将 –persistent 替换为 –default-timeout 1h，并在 instance create 中补上 –timeout 1h。运行失败时按输出的 ID 清理本次创建的资源；常驻实例成功后也需主动删除。

25、实例生命周期与资源清理

# 查询实例详情agr instance get <instance-id> -o json –non-interactive# 列出所有运行中的实例agr instance list –filters '[{"Name":"Status","Values":["RUNNING"]}]' -o json –non-interactive# 删除实例（–yes 跳过确认，–ignore-not-found 允许重复执行）agr instance delete <instance-id> –ignore-not-found –yes -o json# 删除工具agr tool delete <tool-id> –yes -o json

注意：实例或工具使用完成后请及时删除，避免持续占用资源。删除类操作请只针对自己创建的资源。

27、实例创建失败

·检查是否已开通 Agent Runtime 服务。运行 agr doctor -o json，若 Connectivity 不为 ok，请根据返回错误排查网络、凭据、权限与服务开通情况。

·检查 API 密钥是否正确。运行 agr status -o json，确认 Auth.SecretId.Present 为 true。

·若提示 timeout too large：限时沙箱实例最长存活 24 小时，请缩短 –timeout / –default-timeout。

28、noVNC 桌面无法打开或 502/404

·页面路径必须是 /vnc.html（CLI 返回的 /novnc/vnc_lite.html 在 WAA 镜像下是 404）。

·使用步骤 7 的方法，从当前实例的 CLI 返回值提取 access_token，生成 /vnc.html?path=websockify?token=… 地址。PUBLIC 模式允许匿名业务访问，Token 不是该模式下桌面连接的强制条件；含 Token 的完整 URL 请勿公开分享。

·实例刚启动时 noVNC 服务可能仍在初始化，请等待后重试；以实际桌面连接为准。

·可通过截图接口确认桌面是否正常显示。

29、截图请求超时或返回 502

·首次截图可能较慢，建议把客户端超时放宽到 60 秒。

·若持续 502，沙箱内桌面服务可能尚未就绪或不可达，稍后重试或先打开 noVNC 确认。

30、CDP 返回 502

先按“浏览器自动化（CDP）”依次通过 /setup/launch 启动 Chrome 1337 和 CDP 代理 9222。检查两条请求的返回值、Chrome 进程以及 1337/9222 监听状态。仅让 Chrome 监听 127.0.0.1:9222 不能替代这套代理流程。

31、命令执行返回 error

WAA 是 Windows 环境，请使用 Windows 命令（whoami、dir、hostname），不要使用 Linux 命令（id、ls）。

32、–network 报 unknown flag

请使用 –network-configuration '{"NetworkMode":"PUBLIC"}'，而不是 –network。

33、WAA 与 OSWorld 沙箱差异

注意：说明：

注意：WAA 和 OSWorld 在 5000 端口共用同一套控制 API（/screenshot、/platform、/setup/execute），接口一致，仅底层操作系统不同。

34、相关文档

·agr CLI 安装与配置

·agr CLI 命令参考

·agr CLI 常用操作示例

·ags-cli 开源仓库

·数据结构

·网络模式

·公共参数

·创建自定义沙箱