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

📖 本文导读

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

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

第三章：MCP协议接入

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

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

第六章：实战案例（表单填写代理 & 自动化测试代理）

第七章：高级配置与运维

第一章：理解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 = """

 

     

     

     

       提交

 

   """

   

   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对接使用的原创技术教程，内容基于官方文档与最佳实践整理，供开发者参考使用。