AgentKit
AgentKit
文档指南
请输入
- 文档首页
AgentKitAgentKit用户指南沙箱模板快速使用沙箱模版
复制全文
下载 pdf快速使用沙箱模版
文档反馈
问问助手本文以 AIO Sandbox（代码沙箱）和 VeADK（Python） 为主，面向第一次接触 AgentKit 的新手用户，带您从零跑通“创建沙箱模板 → 在 Agent 中集成沙箱模板 → 调用并验证”的完整操作流程。
适用场景
当 Agent 需要在隔离环境中完成代码运行、命令执行或产出中间文件等任务时，推荐使用 AIO Sandbox 类沙箱工具。它的价值在于：让运行环境以“工具”的形式被 Agent 按需调用，并由平台统一管理生命周期与安全隔离。
沙箱实例调用机制
AIO Sandbox 中的代码沙箱工具支持基于会话的智能调度管理：
- 自动创建：首次使用某个session_id调用时，系统会自动创建对应的工具实例。
- 会话复用：相同session_id的多次请求将共享同一个工具实例，保持代码执行的上下文连续性。
- 生命周期：每个实例默认有效期为 30 分钟，超时后自动销毁，您也可以手动调整实例生命周期时长，详见更新生命周期时长。
- 隔离性：不同session_id的请求使用独立的沙箱环境，互不干扰。
前提条件
在开始操作前，请确保已完成如下全部准备工作，不满足会导致后续操作流程无法完成。
- 基础权限：可以登录 AgentKit 控制台 并有权限创建工具。
- 本地 Python 环境：建议使用 Python 3.10 及以上版本，并可正常安装依赖。
- 已通过 VeADK 构建 Agent，并且该 Agent 已发布至 AgentKit 控制台智能体运行时，详细操作可参考使用 VeADK 开发并部署智能体。
- 以下配置为可选配置，根据实际需要选配，选配操作可能涉及费用（如TOS），本文为简便操作本文为简便操作均不配置。
- （可选）TOS：如果需要使用 TOS 存储沙箱模板数据，请确认：已开通对象存储 TOS，待创建沙箱模板的地域创建 TOS Bucket，详细操作可参见创建存储桶。
- （可选）日志：如果需要查看服务的运行日志，请确认已开通全栈可观测平台。
- （可选）已创建网关实例。本文演示操作均以共享模式创建沙箱模板。
操作步骤
步骤一：创建 AIO Sandbox 沙箱模板
- 登录AgentKit控制台。
- 在左侧导航树中，选择“沙箱模版”。
- 单击“创建沙箱模板”按钮，在创建页面参照下表完成参数配置，配置完成后单击“创建”按钮，完成操作。
说明
- 参数说明示例基本信息名称设置新创建沙箱模板的名称。注意
- 同一账号下沙箱模板名称唯一，不可重复。
- 沙箱模板创建成功后，不支持修改名称。
Sandbox_9dzj1f类型选择预置沙箱模板的类型，此处选择预置模板、AIO Sandbox。- AIO Sandbox：是 AI Agent 的一体化综合运行环境，包含Browser、Terminal、Code运行环境，适配多步骤复杂任务，支持自动根据任务切换运行环境。
AIO Sandbox所属网关选择沙箱模板所属的网关类型，此处配置为：共享模式。共享模式网络配置网络访问配置新创建沙箱模版被访问的方式。- 私网访问：通过私网访问沙箱模板，安全性更高。下拉选择目标私有网络（VPC）和子网，每个可用区仅支持选择一个子网。
- 公网访问：通过公网访问沙箱模板，是默认的访问方式。
公网访问权限与访问控制入站身份认证配置沙箱模板托管资源认证信息，用来控制谁可以访问此沙箱模板托管资源。此处配置为 API Key。说明输入名称后，将自动为沙箱模板创建和绑定 API Key，沙箱模板创建成功后，可在目标沙箱模板详情页查看。apikey_fqahex2m高级配置快照是否启用快照功能，此处配置为启用。- 默认不启用，如果有中间产物需保留/想续接上次状态，建议启用；一次性任务/成本敏感，不建议启用。
- 启用快照功能后，平台将会在沙箱模板实例到期前自动创建快照，保存实例数据和环境，可用于后续恢复实例。恢复操作详见使用快照恢复实例。
- 开启快照功能后，仅在实例到期前由系统触发快照创建操作，主动删除或异常回收的实例不保留。
启用观测服务是否启用观测服务，此处配置为不启用。注意不启用
步骤二：获取本地环境变量并在 Agent 中集成
- 在沙箱模板 Sandbox_9dzj1f 的“集成信息”页签下，获取环境变量配置信息。
-
- 在火山引擎访问控制控制台“API 访问密钥”下，单击“创建 Access Key”按钮创建 Access Key，创建成功后复制 Access Key ID（AK）和 Secret Access Key（SK）信息。
-
- 您本地 VeADK 构建的 Agent 项目结构如下所示，需为 Agent 添加 AK/SK 信息和沙箱模板 ID。
- 项目结构
- your_project├── __init__.py # 模块导出文件├── .env # 环境变量文件，需要在这里配置您所需的环境变量信息└── agent.py # Agent 定义文件
- 在本地环境设置环境变量
- 在您本地打开终端，执行source .venv/bin/activate命令激活虚拟环境。
- 输入如下命令设置环境变量，添加 AK/SK 信息，其中<your_access_key>、<your_secret_key>需替换为实际的 AK/SK 信息。
注意
- 由于 AK/SK 属于高敏感凭据，直接写入.env等静态配置文件存在泄露风险，在本地开发环境中配置火山引擎 AK/SK 时，推荐通过终端会话级环境变量导出的方式管理。
- 终端会话级环境变量为一次性配置，仅对当前终端窗口生效，关闭终端窗口后重新打开或开启新的终端窗口后，均需重新配置。
- export VOLCENGINE_ACCESS_KEY=<your_access_key>export VOLCENGINE_SECRET_KEY=<your_secret_key>
- 执行命令cd <Agent项目根目录>进入 Agent 项目根目录，<Agent项目根目录>需替换为您的实际根目录路径。
- 在.env中配置环境变量
- 继续在终端窗口执行如下命令，在.env文件中添加沙箱模板 ID 和 Region 信息，此命令为信息追加，不会覆盖已有沙箱模板信息。
- echo "AGENTKIT_TOOL_ID=<tool_id>" >> <Agent项目根目录>/.envecho "AGENTKIT_TOOL_REGION=<tool_region>" >> <Agent项目根目录>/.env
- 参数来源<tool_id>替换为沙箱模板的 ID 信息，此信息已在上述操作中获取。<tool_region>替换为沙箱模板所属的 Region，此信息已在上述操作中获取。<Agent项目根目录>替换为实际 Agent 的项目根目录路径，如/Users/Doc/personal_assistant。
- 执行如下命令，检查信息是否添加成功。
- cat <Agent项目根目录>/.env
- 操作结果：返回信息中已添加沙箱模板信息。
-
步骤三：结果验证
- 继续在终端窗口执行veadk web命令，启动 VeADK Web 界面。
说明
本文操作前提条件已明确在 VeADK 构建了 Agent，因此可以直接执行veadk web命令启动 VeADK Web 界面，若您还未完成 Agent 构建，直接执行此命令无法启动，请先参考使用 VeADK 开发并部署智能体。
- 在您的项目所在终端的本地浏览器中输入 VeADK Web 链接，选择目标 Agent 后输入提示词“1加到100等于多少，帮我写Python代码计算”，执行中出现“run_code”表明 Agent 已拉起沙箱实例并在沙箱实例中处理任务。
-
- 返回运行 veadk web 的终端里按键盘 Ctrl + C，终止进程，然后执行命令agentkit launch将本地配置推送到 AgentKit 平台智能体运行时中。
- 返回AgentKit控制台。在沙箱模板 Sandbox_9dzj1f 的“实例管理”页签下可看到沙箱实例已被 Agent 创建和使用。
说明
本操作在第一步创建沙箱模板时，开启了“快照”功能，如果“实例管理”页签下无实例，可能是因为实例生命周期结束，可在“快照”页签下看到一个实例信息。
-
常见问题排查
当遇到“跑不通”时，建议先按下面顺序排查：
- 环境变量是否缺失：AGENTKIT_TOOL_ID、VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY 是否都已正确设置。
- 地域是否一致：追加沙箱模板信息时配置的<tool_region>需与实际创建沙箱模板时选择的地域保持一致。
- AK/SK 是否有权限：确认 AK/SK 对应账号有权限访问 AgentKit 相关资源的权限。
- 沙箱模板状态是否可用：确认沙箱模板创建成功且未被删除；必要时可在控制台查看沙箱模板状态。
最近更新时间：2026.09.01 20:26:34
这个页面对您有帮助吗？
有用
有用
无用
无用