阿里云无影Agent开发套件AgentBay：从零到一的对接与使用完全指南

第一章：理解AgentBay——AI Agent的云端基础设施

1.1 什么是无影AgentBay？

无影AgentBay是阿里云无影推出的AI Agent云端执行基础设施。它以Sandbox沙箱为核心载体，为智能体框架和应用提供浏览器自动化、代码执行、桌面应用操控、移动应用自动化在内的多样化执行能力。AgentBay定位为AI时代的Agent云基础设施，面向企业、开发者和AI厂商，提供从开发、测试到规模化运行的全生命周期服务。

从技术架构来看，AgentBay底层基于阿里云无影资源池，全球部署，就近接入，提供Serverless服务能力，客户可以一键调度环境会话。它集成了Browser、File、Terminal等标准MCP工具集，支持通过SDK加API或者MCP Server快速接入，两者均兼容。与传统的虚拟机不同，AgentBay是一个完整的AI Agent云基础设施平台，不是简单的虚拟机。

1.2 核心能力解读

AgentBay集成云上沙箱环境、算力调度、持久化数据存储和企业级安全多项核心能力，功能丰富，接入简单，扩展灵活。具体而言，其核心能力包括：沙箱环境覆盖Linux、Windows、Android系统层的Computer Use、Mobile Use到Browser Use、Code Space等应用层的多个主流环境，为Agent的自动化应用提供全方位支持。数据持久化方面，升级了跨平台数据漫游系统，支持状态和内存级别的持久化，确保任务切换时的状态连续性，资源可以按需加载、实时切换，完全不需要重启机器。企业级安全方面，采用数据加密传输和权限严格隔离，实现本地环境零侵入，为用户和厂商设置双重保险。

1.3 为什么需要AgentBay？

对于AI Agent开发者而言，本地设备难以支撑高并发、高算力需求的Agent任务，尤其是需要大量GPU运算的工作，普通办公电脑难以胜任。AgentBay将AI分配的任务直接接入高性能的云端环境，自带海量MCP工具和环境，在云端轻松完成任务执行、算力弹性扩容，让运行时间大幅缩短。Agent执行各种任务时经常消耗大量本地算力，AgentBay通过云端执行机制，任务在阿里云的资源池中执行，不占用本地计算资源，提供Serverless服务，按需分配计算资源，支持弹性扩展，根据任务需求自动调整资源。

在安全与隐私层面，无影AgentBay为每个用户提供完全隔离的VM环境，环境会话结束后即重置，不留存任何数据。通过API Key进行身份认证，提供安全的访问控制机制，本地数据不会上传到云端，云端数据不会被保留，除非用户明确授权和要求。

第二章：对接前的准备工作

2.1 账号准备

使用无影AgentBay需要先注册阿里云账号并完成实名认证。新用户可享受试用权益，首次试用可申请新用户试用资格，获得一定额度的免费体验资源。

需要先登录阿里云控制台，点击：阿里云控制台，在产品列表中找到无影Agent开发套件AgentBay并开通服务。

2.2 申请API Key

API Key是无影AgentBay身份认证的核心凭证。在左侧导航栏中单击服务管理，在服务管理页面上单击创建API KEY，在创建API KEY对话框中输入名称，并单击确定。为保障数据安全，请勿共享API Key。

如需使用国际站服务，需将API Key替换为阿里云国际站无影AgentBay服务创建的API KEY。

2.3 镜像选择

镜像定义了AgentBay沙箱运行的操作系统环境和预装软件。根据业务需求在MCP地址的IMAGEID字段中指定合适的镜像。目前支持以下几类镜像：

• 云电脑Windows：windows_latest
• 云电脑Linux：linux_latest
• 云浏览器：browser_latest
• 代码沙箱：code_latest
• 云手机：mobile_latest

将IMAGEID字段设置为指定版本的系统镜像，包括系统镜像和自定义镜像。在左侧导航栏选择镜像管理（Beta），在系统镜像页签或自定义镜像页签中获取镜像ID。

第三章：MCP协议接入

3.1 MCP协议介绍

AgentBay平台基于开源标准化协议MCP（Model Context Protocol）为AI模型与运行环境之间提供了统一的交互接口。该平台实现了与云端运行环境的深度集成，使开发者能够通过MCP直接访问会话管理、文件操作、命令执行、应用管理及窗口控制等云端功能。

无影AgentBay完全支持MCP协议，提供标准化的MCP接口，确保与现有MCP生态兼容。它提供了主流的MCP工具集，包括Browser工具支持浏览器操作、File工具支持文件操作、Terminal工具支持终端操作。这一设计使得AgentBay可以与现有的MCP Server生态系统无缝集成，支持现有MCP Server的功能扩展，提供统一的接口标准，便于管理和集成。

3.2 在Cursor中配置MCP

以Cursor V0.50.5版本为例，展示如何在MCP工具中添加无影AgentBay的MCP Server：

步骤一：打开Cursor Settings，在左侧导航栏中单击MCP
步骤二：在MCP Servers面板上单击Add new global MCP server
步骤三：在mcp.json文件中粘贴MCP地址代码块

3.3 SSE方式配置

SSE（Server-Sent Events）方式适用于WebSocket流式传输场景，配置代码如下：

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=YOUR_API_KEY&IMAGEID=browser_latest"
    }
  }
}

其中YOUR_API_KEY替换为步骤一获取的API KEY，IMAGEID替换为所选的镜像ID。

3.4 Stdio方式配置

Stdio方式适用于本地命令行执行，配置代码如下：

{
  "mcpServers": {
    "wuying_mcp_server": {
      "command": "npx",
      "args": ["-y", "wuying-agentbay-mcp-server"],
      "env": {
        "APIKEY": "akm—*****",
        "IMAGEID": "browser_latest"
      }
    }
  }
}

npx命令会自动下载并运行wuying-agentbay-mcp-server包，通过环境变量传递API密钥和镜像ID。

接入完成后，执行命令即可让Agent建立AgentBay云浏览器会话，在浏览器中打开阿里云官网。

第四章：SDK编程接入与Web SDK集成

4.1 SDK接入方式概述

AgentBay支持Python、Java、TypeScript等多种语言的SDK接入。无影AgentBay推出Java SDK，助力Java应用安全接入AI Agent，通过云端沙箱隔离执行环境，解决本地执行的安全、并发与依赖难题，支持Spring AI、LangChain4j等主流框架，实现高并发、可扩展的智能体开发。Python SDK则简化了与MCP服务器的交互，提供易于使用的接口来连接MCP服务器、读取资源和调用工具。

4.2 Python SDK安装与初始化

# 安装无影AgentBay Python SDK
pip install wuying-agentbay-sdk

# 基础初始化示例
from wuying_agentbay import AgentBayClient

client = AgentBayClient(
    api_key="YOUR_API_KEY",
    image_id="browser_latest"
)

# 创建会话
session = client.create_session()

# 执行浏览器自动化任务
result = session.run_browser_action(
    action="navigate",
    url="https://www.aliyun.com"
)

print(result)

4.3 Web SDK前端集成

无影Web SDK是用于连接无影AgentBay智能沙箱的Web端开发工具。通过集成Web SDK，用户可以根据业务需求快速定制和搭建使用无影AgentBay的Web客户端。

SDK的目录结构如下：

├── WuyingWebDemo.html    // SDK示例
├── WuyingWebSDK.js       // SDK的接口文件
└── sdk                  // iframe内嵌资源文件
    └── ASP
        └── container.html

4.4 Web SDK Session创建

通过Ticket创建Session的代码示例：

// 通过Ticket来创建session
var userInfo = {
    ticket: 'xxx',
};
var appInfo = {
    osType: 'Android',
    appId: "android",
    appInstanceId: "ai-xxxxxx",
    productType: "AndroidCloud",
    connectionProperties: JSON.stringify({ authMode: "Session" })
};
var sessionParam = {
    openType: openType,
    iframeId: 'sessionIframe',
    resourceType: "local",
    connectType: 'app',
    userInfo: userInfo,
    appInfo: appInfo,
};
var wuyingSdk = Wuying.WebSDK;
session = wuyingSdk.createSession('appstream', sessionParam);

通过authCode创建Session的代码示例：

// 通过authCode来创建session
var userInfo = {
    sessionId: sessionId,
    authCode: authCode,
};
var appInfo = {
    osType: 'Android',
    appId: "android",
    resourceId: "p-xxxxxx",
    productType: "AndroidCloud",
    connectionProperties: JSON.stringify({ authMode: "Session" })
};
var sessionParam = {
    openType: openType,
    iframeId: 'sessionIframe',
    resourceType: "local",
    connectType: 'app',
    userInfo: userInfo,
    appInfo: appInfo,
};
var wuyingSdk = Wuying.WebSDK;
session = wuyingSdk.createSession('appstream', sessionParam);

第五章：模型服务配置与API管理

5.1 模型分组管理

在无影Agent管理中心中创建模型分组，用于管理Agent可调用的模型服务商和模型范围。创建后可将模型分组绑定至云电脑，作为Agent执行任务的推理引擎配置。模型分组创建API如下：

POST /api/CreateModelTemplate
Content-Type: application/json

{
    "BizType": 1,
    "AgentProvider": "OpenClaw",
    "Name": "model-template-001",
    "Description": "测试模型分组"
}

调用成功后返回信息示例：

{
    "Data": {
        "ModelTemplateId": "mt-xxxx"
    },
    "RequestId": "1CBAFFAB-B697-4049-A9B1-67E1FC5F****"
}

5.2 批量创建模型模板

在模型服务商模板下批量创建模型模板，支持一次性添加多个模型并指定其中一个为默认模型。已存在的模型将自动跳过，不会重复创建。批量创建API如下：

POST /api/BatchCreateLlmTemplates
Content-Type: application/json

{
    "ProviderTemplateId": "mpt-xxxx",
    "LlmTemplateItems": [
        {
            "LlmCode": "qwen3.6-plus",
            "Name": "Qwen3.6-Plus",
            "Description": "千问Plus系列模型",
            "Config": {
                "id": "qwen3.6-plus",
                "maxTokens": 65536,
                "contextWindow": 1000000
            },
            "IsDefaultModel": true
        }
    ]
}

5.3 创建模型服务商模板

在模型模板下创建模型服务商模板，用于配置Agent可调用的模型服务（如阿里云百炼、Token Plan、月之暗面等）的连接信息和密钥。

5.4 模型配置优先级

当Agent运行时自身配置了模型分组，且其所在的资源组也配置了模型分组时，资源组绑定的模型分组生效。即资源组设置优先级高于Agent运行时设置。

第六章：实战案例

6.1 实战一：表单填写代理

使用无影AgentBay SDK创建表单填写代理，将HTML表单上传至AgentBay并在浏览器中打开表单，根据自然语言指令自动填写数据。

from wuying_agentbay import AgentBayClient

def create_form_filling_agent():
    # 初始化AgentBay客户端
    client = AgentBayClient(
        api_key="YOUR_API_KEY",
        image_id="browser_latest"
    )
    
    # 创建新会话
    session = client.create_session()
    
    # 上传HTML表单到AgentBay环境
    form_html = """
    <form id="contactForm">
        <input name="name" type="text" />
        <input name="email" type="email" />
        <input name="phone" type="tel" />
        <button type="submit">提交</button>
    </form>
    """
    
    session.upload_form(form_html, filename="contact_form.html")
    
    # 打开表单页面
    session.navigate_to("https://agentbay-domain/contact_form.html")
    
    # 根据自然语言指令自动填写
    instructions = "请帮我填写姓名：张三，邮箱：zhangsan@example.com，电话：13800138000"
    
    session.fill_form_with_llm(
        instructions=instructions,
        llm_model="qwen-plus"
    )
    
    # 提交表单
    session.click_button("提交")
    
    # 获取提交结果
    result = session.get_page_content()
    return result

6.2 实战二：自动化测试代理

使用无影AgentBay SDK创建测试代理，扫描Python项目，使用LLM生成测试用例，并在隔离的云环境中执行。项目结构如下：

├── README.md
├── .env
├── common/                      # 公共核心功能
│   ├── sample_project/          # 用于测试的示例项目
│   └── src/
│       └── base_auto_testing_agent.py  # 基础测试代理类
├── langchain/                   # LangChain集成
│   ├── data/                    # 输出数据目录
│   ├── src/
│   │   ├── auto_testing_agent.py
│   │   └── auto_testing_agent_example.py
│   └── requirements.txt

# auto_testing_agent.py示例
from wuying_agentbay import AgentBayClient
from langchain.agents import initialize_agent

class AutoTestingAgent:
    def __init__(self, api_key: str, project_path: str):
        self.client = AgentBayClient(api_key=api_key, image_id="code_latest")
        self.project_path = project_path
        self.session = None
    
    def scan_project(self):
        """扫描Python项目识别需要测试的模块"""
        session = self.client.create_session()
        session.upload_directory(self.project_path, "/workspace")
        
        modules = session.run_command(
            "find /workspace -name '*.py' -not -name 'test_*'"
        )
        return modules.split("\n")
    
    def generate_test_cases(self, modules):
        """使用LLM生成测试用例"""
        test_cases = []
        for module in modules:
            prompt = f"为模块{module}生成pytest测试用例"
            test_code = self.session.generate_with_llm(
                prompt=prompt,
                llm_model="qwen-plus",
                output_format="python"
            )
            test_cases.append(test_code)
        return test_cases
    
    def execute_tests(self, test_cases):
        """在隔离的云环境中执行测试"""
        results = []
        for test_case in test_cases:
            result = self.session.execute_pytest(test_case)
            results.append({
                "status": result.exit_code,
                "output": result.stdout,
                "duration": result.duration
            })
        return results
    
    def run(self):
        modules = self.scan_project()
        test_cases = self.generate_test_cases(modules)
        test_results = self.execute_tests(test_cases)
        return test_results

运行示例如下：

# 使用LangChain集成运行示例
python langchain/src/auto_testing_agent_example.py

第七章：高级配置与运维

7.1 SDK Endpoint配置

无影AgentBay SDK默认使用上海Endpoint。如需通过其他区域（例如新加坡）进行连接，需要配置不同的端点以获得更好的网络性能。配置方法如下：

# Linux/macOS环境下配置
$ export AGENTBAY_ENDPOINT=wuyingai.ap-southeast-1.aliyuncs.com

# Windows环境配置
> set AGENTBAY_ENDPOINT=wuyingai.ap-southeast-1.aliyuncs.com

目前支持的Endpoint区域：上海（默认）wuyingai.cn-shanghai.aliyuncs.com；新加坡wuyingai.ap-southeast-1.aliyuncs.com。

7.2 自定义镜像制作

使用在线镜像制作器，以直观的方式制作自定义云电脑镜像。使用云电脑或快照创建自定义镜像，或者将本地源镜像导入无影云电脑企业版控制台并生成自定义镜像。步骤如下：

步骤一：在左侧导航栏选择资源管理 > 云电脑企业版
步骤二：在云电脑企业版页面上找到目标云电脑
步骤三：在操作列中单击更多，选择创建镜像
步骤四：填写镜像名称和描述，选择镜像范围（系统盘及数据盘 或 仅系统盘）
步骤五：选择是否清理个人用户数据残留
步骤六：单击创建

镜像名称长度为2~128个英文或中文字符，必须以大小写字母或中文开头，不能以http://或https://开头，可以包含数字、半角冒号、下划线或者短划线。创建镜像需要一定的时间，所需时间取决于云电脑系统包含的数据大小，使用云电脑创建镜像的过程中，请勿关机或者重启云电脑，以避免镜像创建失败。

7.3 安全与数据隔离

无影AgentBay的安全机制包括为每个用户提供完全隔离的VM环境，环境会话结束后即重置，不留存任何数据；通过API Key进行身份认证，提供安全的访问控制机制；本地数据不会上传到云端，云端数据不会被保留，除非用户明确授权和要求；提供安全的数据传输通道，支持数据加密存储。

7.4 计费与成本控制

无影AgentBay采用基础权益包、订阅权益包与后付费相结合的计费模式。基础权益包免费提供，支持使用无影AgentBay的基本功能。订阅权益包按月订阅，包含Pro权益包和Ultra权益包两种类型，使用时优先消耗订阅权益包内赠送的资源额度，超出部分将自动转为后付费。后付费根据实际资源使用量进行计量并实时扣费。新用户可0.01元领取100积分体验券，用于抵扣资源消耗，适用于金融分析、跨境电商、医疗诊断等多场景。

7.5 常见问题排查

API Key无效错误：请检查API Key是否正确填写，确认未过期且未被禁用。Image ID不存在：确认镜像ID正确，所选镜像在当前区域可用。Session超时：AgentBay会话默认有时效限制，长时间未活动会自动销毁，需在代码中配置超时重连机制或延长会话时长。权限不足：某些操作需要特定模型分组或资源组授权，请检查模型分组配置优先级，确保资源组设置正确。网络延迟：可通过配置Endpoint选择就近区域以获得更好的网络性能。

问答环节

Q1：无影AgentBay和普通的云电脑有什么区别？

A1：无影AgentBay不是简单的虚拟机，而是一个完整的AI Agent云基础设施平台。它集成了Browser、File、Terminal等标准MCP工具集，预集成大量面向Agent任务执行的标准工具，并以MCP封装以便企业快速集成。而普通云电脑仅提供基础的桌面环境，不具备Agent执行所需的标准工具集和任务调度能力。

Q2：市场上的AI Agent产品如何接入无影AgentBay？

A2：AI Agent产品可以通过以下方式接入：申请API Key → 完成自定义镜像制作和资源池定义配置 → 完成MCP服务配置（可选）→ 集成无影WEB SDK（可选）→ 客户端或服务端发起工具使用请求。接入方式包括通过无影服务端SDK加API接入，或通过MCP Server接入。

Q3：无影AgentBay支持哪些语言的SDK？

A3：目前支持Python SDK、Java SDK（支持Spring AI和LangChain4j无缝集成）、TypeScript/Web SDK等。Java SDK助力Java应用安全接入AI Agent，通过云端沙箱隔离执行环境，实现高并发、可扩展的智能体开发。

Q4：如何在MCP工具中使用无影AgentBay？

A4：支持SSE、Stdio、Streamable三种连接方式。以Cursor为例，打开Cursor Settings → MCP → Add new global MCP server，在mcp.json中粘贴MCP地址代码块，配置APIKEY和IMAGEID即可。

Q5：AgentBay如何保障用户数据安全？

A5：无影AgentBay为每个用户提供完全隔离的VM环境，环境会话结束后即重置，不留存任何数据；通过API Key进行身份认证；本地数据不会上传到云端，云端数据不会被保留，除非用户明确授权和要求；支持数据加密存储。

Q6：无影AgentBay的计费方式是什么？

A6：采用基础权益包（免费）、订阅权益包（Pro/Ultra，按月订阅）与后付费相结合的计费模式。优先消耗订阅权益包内赠送的资源额度，超出部分自动转为后付费。新用户可0.01元领取100积分体验券。

---

本文为阿里云无影Agent开发套件AgentBay对接使用的原创技术教程，内容基于官方文档与最佳实践整理，供开发者参考使用。