Skip to main content
AgentkitRemoteSandboxAgent 将一个文本任务交给 AgentKit 中的 Skill 或 CodeEnv 沙箱执行,并返回进度、工具事件和结果。它可以直接作为根智能体,也可以作为协调智能体的子智能体 与代码沙箱工具相比,这个入口委派完整任务,由远端智能体决定执行步骤;run_code、execute_skills 则作为工具供当前智能体调用

依赖与前提

  • 安装 VeADK,并准备有权访问的 AgentKit Tool ID、地域和账号凭证
  • Skill 沙箱需提供兼容的 A2A 服务;CodeEnv 镜像需支持 Codex Worker 协议 v1 和 tool_events
  • 运行环境能够访问 AgentKit 控制面和返回的沙箱会话端点
  • 使用本地协调智能体时,还需完成模型配置;直接运行远端智能体时,模型能力由远端服务提供
运行示例会创建或复用云端沙箱会话,可能产生资源费用。沙箱可执行代码、命令和文件操作,并访问其网络可达的服务。请使用可信镜像,限制数据、网络和权限,并确认任务内容可以发送到该沙箱
以下为火山引擎配置,将 CodeEnv 替换为实际工具类型:
BytePlus 使用时应设置 CLOUD_PROVIDER=byteplus 和对应地域,并确认账号已开通兼容的 Tool 服务。当前入口读取凭证的变量名仍为 VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY,不会仅因平台切换而改读 BYTEPLUS_*;需要在这些变量中提供目标平台的凭证。端点覆盖选项见下方环境变量表 构造智能体不会发起网络请求;首次运行时才连接沙箱

使用方法

作为根智能体

将以下代码保存为 remote_sandbox.py,在已配置凭证的终端运行 python remote_sandbox.py:
remote_sandbox.py
成功时输出远端任务的最终结果,示例中的求和结果应为 5050。示例显式配置短期会话存储,以便 Runner 为这个根智能体创建会话

作为子智能体

协调智能体根据任务选择是否转交。为沙箱填写具体的 description,帮助协调智能体识别适合它的任务
coordinator.py
运行 python coordinator.py 后,协调智能体可通过 transfer_to_agent 转交,沙箱直接返回结果。任务是否转交由模型决定;必须交给沙箱的任务应使用根智能体入口

沙箱类型

未指定 tool_type 时,通过 AgentKit GetTool 自动发现。私有工具或兼容但返回其他类型的自定义工具应显式指定类型。AGENTKIT_TOOL_TYPE 是示例显式读取的变量,智能体不会自动读取它

参数

request_timeout + expiry_buffer + 2 * ready_timeout 必须小于 86400 秒,否则初始化失败。以上列出任务接入相关参数;还可使用 ADK BaseAgent 的通用回调配置

环境变量

凭证依次从会话状态、环境变量和运行环境 IAM Role 获取。临时凭证可通过绑定的 IAM Role 提供;不要将会话状态中的云凭证作为普通业务数据向用户展示

会话管理

同一应用、用户、会话和智能体可以复用有效的远端会话,保留沙箱中的文件与运行状态。ttl 默认为 30 分钟,最长为 24 小时;会话到期或被替换后,不应假定文件仍然存在,需将要保留的结果保存到持久存储 同一智能体实例不接受同一逻辑会话的重叠调用,会直接报错,不会自动排队。应用需按会话串行提交任务。等待就绪与执行分别受 ready_timeout、request_timeout 控制

入站身份凭证

当前上下文存在入站凭证时,智能体会通过 inbound_auth 请求头转发给沙箱,用于延续原始用户身份。没有入站凭证时不发送该头,这不代表绕过沙箱自身的访问认证;api_key 配置的 X-API-Key 与转发用户身份是不同用途 应只向受信任的沙箱转发身份凭证,配置方式见入站认证

错误处理

会话就绪超时、执行超时和协议不兼容等执行失败通常以带 error_message 的事件返回。并发调用冲突、初始化错误和取消仍可能向调用方传播,应用需要同时处理事件错误与调用异常 Runner.run 只提供文本结果;需要区分失败与普通回答或观察过程时,使用 Runner.run_async 检查事件。超时或取消后会尝试通知远端停止,但不能据此认定远端操作一定未执行;重试有副作用的任务前先确认执行状态
最后修改于 2026年9月19日