帮你快速理解、总结文档立即下载
文档中心>Agent Runtime>SDK 使用指南>Windows Agent Arena(WAA)沙箱操作

Windows Agent Arena(WAA)沙箱操作

最近更新时间:2026-10-13 17:57:30
我的收藏

目标与结果

本文介绍如何使用 agr CLI 在腾讯云 Agent Runtime 中创建 Windows Agent Arena(WAA)沙箱,并通过公网访问沙箱桌面与控制服务。
完成本文操作后,您将获得:
一个状态为 ACTIVE 的 WAA 沙箱工具。
一个状态为 RUNNING 的 WAA 沙箱实例。
可在浏览器中打开的 Windows 桌面地址,以及截图、平台信息、命令执行等入口。

前提条件

使用前请确认以下条件已满足:
1. 已注册腾讯云账号,并完成实名认证。
2. 已开通腾讯云 Agent Runtime 服务。如未开通,可 提交工单 申请开通。
3. 已获取 API 密钥(SecretId / SecretKey):
进入 访问管理 > API 密钥管理。
新建密钥或使用已有密钥,记录 SecretId 和 SecretKey。
4. 已选择目标地域。本文以广州为例,其他地域的可用性以当前控制台为准:
地域
Region ID
Domain
广州
ap-guangzhou
tencentags.com
北京
ap-beijing
tencentags.com
上海
ap-shanghai
tencentags.com

步骤概览

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@latest
export 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-guangzhou
agr 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"

参数说明

参数
含义
--tool-name
工具名称,全局唯一。建议使用小写字母、数字和短横线,例如 my-waa-tool。
--tool-type waa
指定创建 WAA(Windows Agent Arena)沙箱类型。
--network-configuration
网络配置,PUBLIC 表示沙箱可访问公网;实例端口鉴权由 --auth-mode 控制。
--default-timeout
限时沙箱的默认存活时长,到期自动停止。仅用于方式一,请勿与 --persistent 混用。
--persistent
常驻沙箱:该工具的实例不受超时和最长存活时长回收限制。仅用于方式二,请勿与 --default-timeout 混用。
说明:
限时 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 5
done
[ "$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"
参数
含义
--auth-mode PUBLIC
公网认证模式。业务端口无需 Token,ENVD 管理端口 49983 仍需携带 Token。
--timeout
实例存活时长,超时自动停止。常驻沙箱(--persistent)的实例不受该参数影响。
注意:
PUBLIC 会让 5000 等业务端口允许匿名访问,包括 /setup/execute 命令执行接口。请只用于隔离的测试实例,不要在沙箱中放入敏感数据,用完及时删除。
等待实例与服务就绪。RUNNING 仅代表实例状态,控制服务与桌面可能仍在启动;以下轮询有次数上限,失败时停止并排查:
REGION=ap-guangzhou
DOMAIN=tencentags.com
for 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 5
done
[ "$STATUS" = "RUNNING" ] || exit 1

# RUNNING 不代表 Windows 内的 WAA 服务已经就绪
echo ">>> 等待 WAA 服务与桌面就绪..."
READY=false
for 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 5
done
[ "$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-guangzhou
DOMAIN=tencentags.com

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"
说明:
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/screenshot
https://8006-<instance_id>.ap-guangzhou.tencentags.com/vnc.html
常用端口:
端口
功能
路径
是否需要 Token(PUBLIC 模式)
8006
noVNC 桌面
/vnc.html
否(PUBLIC 模式);也可使用 CLI Token 生成连接地址
5000
沙箱控制服务
/screenshot、/platform、/setup/execute
否
9222
Chromium CDP
/json/version
否(需先启动 Chrome 1337 和 CDP 代理 9222)
49983
ENVD 管理端口
-
是(管理端口在 PUBLIC 模式下仍需 Token)
说明:
端口是否可用取决于镜像内对应服务是否已启动。特别是 9222 需要单独启动 Chrome 和 CDP 代理,不能仅凭实例进入 RUNNING 就认定可用。

结果验证

检查实例状态、平台信息和桌面截图:
# 预期输出 RUNNING
agr instance get "$INSTANCE_ID" -o json --non-interactive --jq '.Data.Status'

# 预期返回 Windows
curl -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-guangzhou
DOMAIN=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 不可用时,可通过截图确认桌面是否正常显示。

查看平台信息

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

在沙箱内执行命令

# 获取当前用户和主机名
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)。

浏览器自动化(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”。

查看 noVNC 静态资源目录

以下命令查看 noVNC Web 服务的静态资源目录,返回内容包括 app/、core/、vendor/ 和 vnc.html 等。该入口不用于浏览 Windows 沙箱文件系统。
curl -k -sS --max-time 10 "https://8006-${INSTANCE_ID}.${REGION}.${DOMAIN}/"

端到端创建脚本

在已安装 agr 并配置凭据的 Bash 环境运行。脚本创建常驻 WAA 沙箱,校验工具和实例状态,再等待 5000/8006 服务并保存截图。脚本成功后仍需在浏览器中确认桌面连接;CDP 需另按“浏览器自动化(CDP)”启动。
#!/bin/bash
set -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 5
done
[ "$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 5
done
[ "$STATUS" = "RUNNING" ] || exit 1

# RUNNING 不代表 Windows 内的 WAA 服务已经就绪
echo ">>> 等待 WAA 服务与桌面就绪..."
READY=false
for 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 5
done
[ "$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 清理本次创建的资源;常驻实例成功后也需主动删除。

实例生命周期与资源清理

# 查询实例详情
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
注意:
实例或工具使用完成后请及时删除,避免持续占用资源。删除类操作请只针对自己创建的资源。

常见问题排查

实例创建失败

检查是否已开通 Agent Runtime 服务。运行 agr doctor -o json,若 Connectivity 不为 ok,请根据返回错误排查网络、凭据、权限与服务开通情况。
检查 API 密钥是否正确。运行 agr status -o json,确认 Auth.SecretId.Present 为 true。
若提示 timeout too large:限时沙箱实例最长存活 24 小时,请缩短 --timeout / --default-timeout。

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 服务可能仍在初始化,请等待后重试;以实际桌面连接为准。
可通过截图接口确认桌面是否正常显示。

截图请求超时或返回 502

首次截图可能较慢,建议把客户端超时放宽到 60 秒。
若持续 502,沙箱内桌面服务可能尚未就绪或不可达,稍后重试或先打开 noVNC 确认。

CDP 返回 502

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

命令执行返回 error

WAA 是 Windows 环境,请使用 Windows 命令(whoami、dir、hostname),不要使用 Linux 命令(id、ls)。

--network 报 unknown flag

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

WAA 与 OSWorld 沙箱差异

特性
WAA
OSWorld
操作系统
Windows
Linux
桌面
noVNC(8006,页面 /vnc.html)
noVNC(5910,页面路径以镜像为准)
控制服务
5000(同一套 API)
5000(同一套 API)
命令语法
Windows
Linux
CDP
9222(需启动 Chrome 和 CDP 代理)
9222(需在沙箱内启动)
说明:
WAA 和 OSWorld 在 5000 端口共用同一套控制 API(/screenshot、/platform、/setup/execute),接口一致,仅底层操作系统不同。

相关文档