AgentkitRemoteSandboxAgent 将一个文本任务交给 AgentKit 中的 Skill 或 CodeEnv 沙箱执行,并返回进度、工具事件和结果。它可以直接作为根智能体,也可以作为协调智能体的子智能体
与代码沙箱工具相比,这个入口委派完整任务,由远端智能体决定执行步骤;run_code、execute_skills 则作为工具供当前智能体调用
依赖与前提
- 安装 VeADK,并准备有权访问的 AgentKit Tool ID、地域和账号凭证
- Skill 沙箱需提供兼容的 A2A 服务;CodeEnv 镜像需支持 Codex Worker 协议 v1 和
tool_events - 运行环境能够访问 AgentKit 控制面和返回的沙箱会话端点
- 使用本地协调智能体时,还需完成模型配置;直接运行远端智能体时,模型能力由远端服务提供
CodeEnv 替换为实际工具类型:
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 检查事件。超时或取消后会尝试通知远端停止,但不能据此认定远端操作一定未执行;重试有副作用的任务前先确认执行状态