# AgentSphere


## 产品介绍

- [什么是AgentSphere](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0001.md): AgentSphere是华为云面向Agent应用打造的一站式基础设施产品组合，由Agent Sandbox（智能体沙箱）、Agent Gateway（智能体网关）、Agent Identity（智能体身份）、Agent Storage四大核心产品组成，为Agent强化学习（RL）训练和Agent在线服务（如智能助手）两大场景提供高性能沙箱
- [产品优势](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0002.md): AgentSphere采用轻控制面、宿主机闭环的架构设计，实现面向Agent RL场景的超大规模沙箱底座：十万级批创能力：支持单次批量创建十万级沙箱实例，满足Agentic RL训练中大规模并发Rollout的需求。百毫秒级启动：基于内存快照和缓存加速技术，沙箱启动百毫秒级时延，提升训练效率，降低训练成本。
- [产品功能](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0003.md): 本页面介绍了AgentSphere产品组合支持的主要功能。关于各功能支持的地域（Region）信息，可通过控制台查询详情。多类型沙箱AgentSphere支持多种类型的沙箱运行环境，包括代码解释器沙箱、自定义沙箱，覆盖从代码执行到全环境模拟的全部场景需求。十万级沙箱批创支持十万级沙箱实例的批量创建，满足RL训练中脉冲式弹性需求。
- [应用场景](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0004.md): 场景描述大模型后训练阶段，需要通过大规模并行Rollout生成训练数据。每次训练迭代需创建数万甚至数十万个沙箱实例，运行客户的业务代码并收集轨迹数据，训练结束后销毁沙箱并启动新一轮训练。传统方式的弊端传统基于K8s的容器方案在面对超大规模沙箱创建时，存在启动时延高、批创性能不足、镜像分发慢等瓶颈，GPU等待时间长导致训练成本居高不下。
- [权限管理](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0006.md): 如果您需要使用AgentSphere服务，为企业中的员工设置不同的访问权限，以达到不同员工之间的权限隔离，您可以使用统一身份认证服务（Identity and Access Management，简称IAM）进行精细的权限管理。智能体沙箱仅支持身份策略授权。如下表所示，包括智能体沙箱身份策略中的所有系统身份策略。
- [约束与限制](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0007.md): 为防止资源滥用，平台限定了各服务资源的配额，对用户的资源数量和容量做了限制。如果当前资源配额限制无法满足使用需要，您可以通过工单申请提升资源配额。
- [与其他云服务的关系](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0008.md): 华为云其他高阶服务均可作为Agent的工具集、模型等。
- [基本概念](https://support.huaweicloud.com/productdesc-agentsphere/agentsphere_01_0009.md): 智能体沙箱是AgentSphere的核心运行组件，为Agent应用提供安全隔离的执行环境。每个沙箱实例包含独立的CPU、内存、文件系统和网络空间，支持代码执行、浏览器操作、全环境模拟等多种场景。沙箱之间通过MicroVM技术实现内核级隔离，防止沙箱逃逸。

## 快速入门

- [5分钟开通沙箱并运行代码](https://support.huaweicloud.com/qs-agentsphere/agentsphere_02_0001.md): 在AI Agent开发中，Agent通常需要执行用户提交的代码或脚本（如数据处理、数学计算、图表生成等），直接在服务器上执行未知代码存在安全风险，可能导致系统资源被耗尽或敏感数据泄露。

## 用户指南

- [沙箱概述](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0002.md): 智能体沙箱为AI Agent提供安全隔离的执行环境，支持多种执行环境类型，满足不同Agent任务的运行需求。每个沙箱实例运行在独立的虚拟化环境中，拥有独立的文件系统、网络空间和进程环境，实例间完全隔离，防止恶意代码逃逸和横向攻击。安全隔离：每个沙箱实例运行在独立的虚拟化环境中，进程、文件系统、网络相互隔离，防止恶意代码逃逸和横向攻击。
- [开始使用沙箱](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0003.md): 本文主要介绍AgentSphere沙箱的整体使用流程，帮助您了解从准备到运行任务的各环节及其关系，助您快速上手。使用沙箱大致可分为三个阶段：准备、运行、清理。准备沙箱模板：选择代码解释器模板或创建自定义模板，模板定义了实例的镜像、资源规格、网络配置等，是创建实例的前提。详情请参见沙箱模板概述。
- [沙箱模板概述](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0005.md): 沙箱模板是沙箱实例的规格定义，描述了实例创建时的运行环境配置，包括镜像、资源规格、网络配置、存储挂载和环境变量等参数。模板是静态定义，本身不运行任务。通过模板可以将环境配置标准化和复用，避免每次创建实例时重复配置。一个模板可以创建多个沙箱实例。在使用沙箱模板时，您可以根据需求创建模板。
- [创建沙箱模板](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0006.md): 您可以创建新的沙箱模板，调整沙箱镜像或参数配置。本文介绍如何创建沙箱模板。如果您需要创建自定义沙箱模板，需要先构建沙箱镜像，详情请参见构建沙箱镜像。如果您需要使用OBS对象存储，需要先配置访问OBS服务的VPC终端节点，详情请参见配置访问OBS服务的终端节点。代码解释器沙箱：基于函数计算的多语言代码执行环境。
- [构建沙箱镜像](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0007.md): AgentSphere沙箱通过内置的ENVD（环境守护进程，Environment Daemon）来提供文件操作、进程管理和环境变量设置等能力。由于当前沙箱仅支持单容器部署，ENVD需要作为容器内的常驻进程运行，因此您需要基于自己的业务镜像进行自定义构建，将ENVD集成到镜像中。已安装Docker用于构建镜像。
- [管理沙箱模板](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0010.md): 沙箱模板创建后，您可以根据业务变化对模板进行操作，包括复制和删除。沙箱模板删除后无法恢复，请谨慎操作。
- [沙箱实例概述](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0012.md): 沙箱实例是基于沙箱模板创建的运行态沙箱，是AgentSphere中实际执行任务的环境。每个实例运行在独立的虚拟化环境中，拥有独立的文件系统、网络空间和进程环境，实例间完全隔离。沙箱实例是基于沙箱模板创建的运行环境，创建时从模板继承配置，创建后则独立于模板运行：创建时：实例从模板继承镜像、资源规格、网络配置、存储挂载、环境变量等配置。
- [创建沙箱实例](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0013.md): 沙箱实例基于沙箱模板创建，创建时从模板继承镜像、资源规格、网络配置等参数，同时支持覆盖部分配置（如环境变量等）。实例创建后自动进入运行中状态，即可接受Agent任务执行。本文介绍如何创建沙箱实例。如果您需要使用OBS对象存储，需要先配置访问OBS服务的VPC终端节点，详情请参见配置访问OBS服务的终端节点。
- [监控与日志](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0015.md): AgentSphere提供沙箱实例的运行状态监控和日志采集能力。通过监控可查看实例的CPU、内存等资源使用情况，帮助您掌握实例运行健康状况；通过日志可追踪实例的标准输出和标准错误信息，用于问题排查和性能分析。创建沙箱实例时，选择的沙箱模板中已配置日志对接LTS或对接AOM，详情请参见日志监控配置。
- [删除沙箱实例](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0016.md): 当沙箱实例完成任务或不再需要时，您可以手动删除实例以释放资源。删除后实例内置文件系统中的数据将被清除且不可恢复，如需保留数据请在删除前导出或使用外挂存储。沙箱实例删除后无法恢复，请谨慎操作。
- [API Key概述](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0018.md): API Key是调用AgentSphere API和SDK的认证凭证，通过API或SDK操作沙箱资源时（如创建沙箱模板、创建沙箱实例等），需携带API Key进行身份鉴权。API Key的使用流程可大致分为创建、配置、调用、停用/删除四个环节。具体如下：在控制台创建API Key，API Key仅在创建时显示一次，需立即妥善保存。
- [创建API Key](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0019.md): API Key是沙箱的长期访问凭证，用于E2B API和SDK的认证，适用于自动化脚本、CI/CD流水线和长期运行的后台服务。本文介绍如何在控制台创建API Key。请妥善保管您的API Key，建议定期重置以确保安全。使用IAM用户创建API Key时，请先确认该用户已启用“编程访问”，具体确认方法请参见管理IAM用户的基本信息。
- [管理API Key](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0020.md): API Key创建后，您可以根据安全策略和业务变化对其进行管理，包括停用和删除操作。停用API Key可临时暂停其访问权限，支持再次启用；删除API Key则永久移除该凭证，适用于不再使用的场景。
- [网关实例概述](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0023.md): 智能体网关（Agent Gateway）是面向Agent应用的企业级智能体网关，用于管理客户端、 Agent与其他工具之间的所有交互。作为Agent与外部系统、数据源及Agent间交互的统一流量入口与策略执行中枢，负责统一处理来自多端的异构请求，负责高效、稳定地调用各类工具与服务。
- [创建网关实例](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0024.md): 智能体网关（Agent Gateway）实例作为Agent流量统一出入口，对出入站流量进行统一管理。智能体网关当前支持入站功能，入站实例部署在沙箱或Agent前，用以将流量转发至沙箱或Agent应用，并提供网络访问配置、安全防护、身份认证等能力。智能体网关当前只支持入站能力，出站能力暂不支持。一个网关实例最多可关联10个VPC。
- [管理网关实例](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0025.md): 网关实例创建后，可以根据实际业务需求对网关实例的配置进行调整。网关实例创建后，可以为网关实例新增关联多个VPC，一个网关实例最多可关联10个VPC。当前仅支持共享公网入口，公网访问开启后将产生公网出流量费用（按实际使用量计费），请谨慎操作。
- [导出网关实例列表信息](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0026.md): 可以将当前账号下拥有的网关实例信息，以Excel文件的形式导出至本地。当前支持导出全部实例的信息、导出选中部分实例的信息。导出的信息包括网关实例的名称、ID、状态、网关部署位置、私网访问、公网访问、关联目标、创建时间和描述等信息。选择“导出全部数据到XLSX”：系统会将当前区域内所有网关实例的信息自动导出为Excel文件，并下载至本地。
- [工作负载身份概述](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0028.md): 工作负载身份是指AI智能体在运行、调用服务、访问资源、执行跨系统交互等工作负载场景中，用于标识自身身份、完成权限校验、实现安全交互的核心凭证体系，是保障智能体资源访问安全、权限精细化管控、交互行为可追溯的核心基础。当前AgentSphere仅支持API Key类型的工作负载身份，在创建沙箱模板配置网关后系统将会自动创建。
- [查看工作负载身份](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0029.md): 创建沙箱模板成功后，您可以进入智能体身份模块查看系统自动创建的工作负载身份的详细信息。
- [配置访问OBS服务的终端节点](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0033.md): 在使用AgentSphere时，您可能需要配置访问OBS服务的VPC终端节点（VPCEP）。规格确认无误，单击“提交”，任务提交成功。参数信息配置有误，需要修改，单击“上一步”，修改参数，然后单击“提交”。

## 最佳实践

- [使用AgentSphere智能体沙箱部署OpenClaw](https://support.huaweicloud.com/bestpractice-agentsphere/agentsphere_04_0001.md): 随着AI Agent在企业业务中的广泛应用，开发者需要一个安全、隔离的运行环境来部署和调试AI Agent应用。OpenClaw是一款开源的AI Agent网关，支持通过即时通讯软件与大模型进行对话交互，适用于智能客服、企业内部助手等场景。

## SDK参考

- [配置本地E2B SDK执行环境](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0001.md): AgentSphere提供了安全隔离的云上沙箱环境，支持代码执行、文件管理和命令运行等能力，广泛应用于AI Agent代码解释器、自动化测试、数据处理等场景。为了降低迁移成本，AgentSphere兼容了E2B SDK，您可以复用已有的E2B工作流和示例代码，仅需修改环境变量即可无缝切换到AgentSphere沙箱服务。
- [沙箱实例管理](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0002.md): 沙箱实例是AgentSphere的核心运行单元。本节介绍如何创建、获取列表、获取信息、连接、暂停和删除沙箱实例。以下示例均基于E2B SDK，请确保已完成配置本地E2B SDK执行环境。您可以使用Sandbox.create方法创建沙箱实例，创建时需指定模板名称，也可以指定超时时间、环境变量等参数。
- [文件操作](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0003.md): AgentSphere沙箱实例提供了独立的文件系统，您可以通过SDK进行文件读写、目录管理、文件查询等操作。以下示例均基于E2B SDK，请确保已完成配置本地E2B SDK执行环境。您可以使用files.write方法向沙箱实例写入文件，使用files.read方法读取文件内容。支持写入文本和JSON等格式的数据。
- [执行命令](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0004.md): 您可以在沙箱实例中执行终端命令，支持指定执行用户、设置环境变量、流式输出和超时控制。以下示例均基于E2B SDK，请确保已完成配置本地E2B SDK执行环境。
- [运行代码](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0005.md): 使用代码解释器沙箱（code-interpreter）模板来创建沙箱，该模板预装了代码执行环境，支持多种编程语言，支持代码解释和结果返回，您可以直接在沙箱实例中运行代码。使用代码解释器沙箱（code-interpreter）模板，需要把健康检查的端口设置为49999，协议为HTTP，检查路径为/health。
- [进程管理](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0006.md): AgentSphere沙箱实例支持通过PTY（伪终端）创建交互式终端会话，适用于需要实时交互的场景，如运行交互式程序、模拟终端操作、自动化Shell脚本测试等。与commands.run不同，PTY会话支持持续的输入输出流，可以模拟真实终端的行为，包括终端窗口大小调整、TTY属性检测等。