AI Agent后端MCP 服务浏览器控制Agent 评测【免费下载链接】sandboxAll-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.项目地址https://gitcode.com/gh_mirrors/sandbox103/sandbox点击查看免费下载本文是 AIO SandboxAll-in-One Sandbox for AI Agents中Bash Pipe/v1/bash的深度使用指南。Bash Pipe 是面向 Agent 编程式工作流设计的子进程管道命令执行服务与基于 PTY 的 Shell Terminal 互补它独立区分stdout与stderr支持基于 offset 的增量输出读取并提供了exec、output、write、kill等一组完整 REST API。读完本文你将掌握如何用 curl 或官方 Python/TypeScript SDK 执行短命令、轮询长任务、启动长驻服务并优雅停止、向进程 stdin 写入数据、管理会话状态以及如何正确区分HTTP 请求成功与命令执行成功。什么是 Bash Pipe与 Shell Terminal 的定位差异AIO Sandbox 提供了两套命令执行能力/v1/shell与/v1/bash。/v1/bash是一个基于子进程管道subprocess pipe的命令执行服务专门为编程式和 Agent 友好的工作流设计与 PTY 驱动的 Shell Terminal 有本质区别。对比项/v1/shell/v1/bash后端Terminal / PTYsubprocess pipe适用场景交互式终端、WebSocket UI、人工接管Agent 工具调用、短命令、长命令轮询输出合并的单一output字段独立的stdout和stderr读取模型终端快照 等待wait/view基于offset/stderr_offset的增量读取stdin终端输入流写入运行中进程的 stdin 管道命令标识会话级每条命令都有独立的command_id从 SDK 源码可以进一步印证这种设计取向Python SDK 中 BashClient 的文档明确指出status是命令生命周期状态而非成功标志非零退出码同样会返回completed因此消费方必须再检查exit_code。执行短命令一次 exec 完成大多数工具调用对绝大多数 Agent 工具调用来说一次POST /v1/bash/exec请求即可拿到完整结果。响应中的status表示命令生命周期状态exit_code才是命令成功与否的指标。curl -X POST http://localhost:8080/v1/bash/exec \ -H Content-Type: application/json \ -d { command: pwd ls -la, exec_dir: /home/gem, timeout: 30, hard_timeout: 120 }典型响应结构如下session_id标识会话、command_id标识单条命令offset与stderr_offset是后续/output轮询的增量读取起点stdout/stderr在此次请求中可获得的输出。{ success: true, data: { session_id: SESSION_ID, command_id: COMMAND_ID, command: pwd ls -la, status: completed, stdout: /home/gem\n..., stderr: null, exit_code: 0, offset: 128, stderr_offset: 0 } }关于status的完整取值SDK 类型定义给出了精确说明见 bash_exec_result.py 与 BashExecResult.tspending已接受但尚未开始执行通常仅内部可见running仍在执行async_modetrue时立即返回或同步模式下超过timeout时返回completed进程已退出exit_code可用注意非零退出码同样使用completed它不代表成功timed_out超过hard_timeout被强制结束killed被/v1/bash/kill、会话清理或内部执行失败终止。使用官方 SDKPython 与 TypeScript除了 curlAIO Sandbox 提供了官方 SDK 封装。Python 侧由 agent_sandbox 包提供Sandbox客户端from agent_sandbox import Sandbox client Sandbox(base_urlhttp://localhost:8080) result client.bash.exec( commandprintf out\\n printf err\\n 2, timeout30, hard_timeout120, ).data print(result.stdout) print(result.stderr) print(result.exit_code)TypeScript 侧由agent-infra/sandbox提供SandboxClient对应实现见 Client.tsimport { SandboxClient } from agent-infra/sandbox; const client new SandboxClient({ baseUrl: http://localhost:8080 }); const response await client.bash.exec({ command: printf out\\n printf err\\n 2, timeout: 30, hard_timeout: 120, }); if (!response.ok) { throw new Error(Bash exec failed); } console.log(response.body.data?.stdout); console.log(response.body.data?.stderr); console.log(response.body.data?.exit_code);注意 Python SDK 中client.bash.exec(...)返回的是.data即ResponseBashExecResult而with_raw_response才能拿到含 HTTP 状态的原始响应见 client.pyTypeScript 侧则通过response.ok判断 HTTP 层面是否成功。长命令与增量输出exec output 轮询模式当命令在timeout内没有执行完毕时/v1/bash/exec会返回status: running命令继续在后台运行此时需要用/v1/bash/output增量读取输出。第一步启动一个在 1 秒内无法完成的命令让 exec 返回 running 状态。# 1. Start a command. If it is not done within 1 second, it returns running. curl -X POST http://localhost:8080/v1/bash/exec \ -H Content-Type: application/json \ -d { command: sleep 3; echo done, timeout: 1, hard_timeout: 30 }第二步携带 exec 响应中返回的session_id、offset、stderr_offset继续读取增量输出。# 2. Continue reading with the returned session_id, offset, and stderr_offset. curl -X POST http://localhost:8080/v1/bash/output \ -H Content-Type: application/json \ -d { session_id: SESSION_ID, offset: 0, stderr_offset: 0, wait: true, wait_timeout: 10 }关于wait参数waitfalse会立即返回当前可获得的输出waittrue则长轮询long-poll直到有新输出、命令结束或wait_timeout超时。SDK 文档client.py给出了推荐消费模式从/exec开始若命令仍在running则反复调用/output每次都复用上一次返回的offset和stderr_offset只拉取新数据直到data.command.status不再是running最后用exit_code判定成功与否。对 Agent 轮询的建议优先使用waittrue避免无意义的空轮询empty polling消耗请求次数与延迟。长驻进程async_mode output kill 三段式对于不会自行退出的服务例如 HTTP 服务器应当使用async_mode: true立即返回然后读取启动日志用完后再调用/kill终止。curl -X POST http://localhost:8080/v1/bash/exec \ -H Content-Type: application/json \ -d { command: python3 -m http.server 3000 --directory /tmp, async_mode: true, hard_timeout: 3600 }读取启动日志确认服务是否已就绪curl -X POST http://localhost:8080/v1/bash/output \ -H Content-Type: application/json \ -d { session_id: SESSION_ID, offset: 0, stderr_offset: 0, wait: true, wait_timeout: 5 }停止进程默认发送SIGTERMSDK 支持SIGTERM、SIGKILL、SIGINT三种信号见 client.pycurl -X POST http://localhost:8080/v1/bash/kill \ -H Content-Type: application/json \ -d { session_id: SESSION_ID, signal: SIGTERM }hard_timeout在这里作为兜底保护如果 3600 秒内服务没有结束进程会被强制终止并返回timed_out。SDK 中hard_timeoutNone表示不设上限见 client.py。向 stdin 写入驱动 cat、脚本与 REPL/v1/bash/write向运行中进程的 stdin 管道写入数据适用于cat、带提示符的脚本、REPL 等交互式程序。对于行缓冲line-buffered程序每行末尾需要包含\n。第一步启动一个等待 stdin 的进程cat会一直阻塞直到 stdin 关闭。# Start a process that waits for stdin. curl -X POST http://localhost:8080/v1/bash/exec \ -H Content-Type: application/json \ -d { command: cat, async_mode: true, hard_timeout: 120 }第二步写入一行输入。# Write one line of input. curl -X POST http://localhost:8080/v1/bash/write \ -H Content-Type: application/json \ -d { session_id: SESSION_ID, input: hello from stdin\n }第三步读取回显输出。# Read the echoed output. curl -X POST http://localhost:8080/v1/bash/output \ -H Content-Type: application/json \ -d { session_id: SESSION_ID, offset: 0, wait: true, wait_timeout: 5 }一个值得注意的细节部分程序包括一些 REPL 和交互式命令会把提示符写到stderr所以消费方应当同时检查stdout和stderr不要只盯着stdout判断进程是否在等待输入。会话状态exec_dir 与 cd/export 的边界/v1/bash为每次exec创建新进程。同一个session_id仅保留API 层状态例如默认工作目录命令内部的cd和export不会影响后续请求——因为每次 exec 都是全新进程命令内部的目录切换与变量导出随进程退出而消失。设置会话默认工作目录exec_dir必须是绝对路径curl -X POST http://localhost:8080/v1/bash/exec \ -H Content-Type: application/json \ -d { command: pwd, exec_dir: /tmp }复用同一个会话注意这里的${MY_VAR}来自会话初始化时的环境而不是上一次命令内export的结果curl -X POST http://localhost:8080/v1/bash/exec \ -H Content-Type: application/json \ -d { session_id: SESSION_ID, command: pwd echo ${MY_VAR:-unset} }如果后续命令需要在某个目录中继续执行请再次传入exec_dir或更新 API 层会话默认值不要依赖命令内的cd。SDK 文档对此有明确说明client.pyexec_dir每次调用都会生效——若会话已存在其默认工作目录会被更新供后续调用使用。另外POST /v1/bash/sessions/create还支持一个snapshot_path参数见 client.py指向一个 shell 快照脚本在会话初始化时被 source。它仅作为初始化快照生效命令侧的 env 变更不会在每次 exec 后回写。参数速查表POST /v1/bash/exec常用参数参数类型说明commandstring要执行的 shell 命令session_idstring目标会话省略时自动创建exec_dirstring绝对路径工作目录会更新会话默认值envobject仅对本次命令生效的额外环境变量async_modeboolean为true时立即返回runningtimeoutnumber软超时超时后返回running命令继续在后台运行hard_timeoutnumber硬超时到期会杀掉进程并返回timed_outmax_output_lengthnumber同步响应中内联stdout/stderr的最大长度默认50000设为0可对本请求禁用截断关于max_output_lengthSDK 源码补充了截断实现细节见 client.py当输出超过该长度时采用中间截断——保留头尾、中间用标记替换且该参数仅在同步模式async_modefalse下生效。POST /v1/bash/output常用参数参数类型说明session_idstring目标会话command_idstring可选指定某个异步命令不设置时读取会话级输出offsetnumber从该 stdout 字节偏移处开始读取stderr_offsetnumber从该 stderr 字节偏移处开始读取waitboolean是否长轮询等待新输出wait_timeoutnumberwaittrue时的最大等待时间错误处理HTTP 成功不等于命令成功/v1/bash的HTTP 成功只代表请求被服务接受不代表命令本身执行成功。推荐的检查顺序检查 HTTP 状态码检查响应中的success字段用data.status判断命令生命周期当statuscompleted时用exit_code判断命令是否成功。import requests response requests.post( http://localhost:8080/v1/bash/exec, json{command: python3 missing.py, timeout: 30}, ) response.raise_for_status() payload response.json() result payload[data] if result[status] running: print(command is still running; call /v1/bash/output) elif result[status] completed and result[exit_code] ! 0: print(command completed with a non-zero exit code) elif result[status] in {timed_out, killed}: print(fcommand interrupted: {result[status]})SDK 文档同样强调client.pystatus是生命周期状态而非成败标志timed_out/killed时应把当前已产生的输出作为部分结果呈现并向用户提示命令被中断另外空的stdout/stderr不代表命令没有运行。完整 API 清单与会话管理/v1/bash提供以下端点POST /v1/bash/exec执行命令POST /v1/bash/output增量读取输出POST /v1/bash/write写入 stdinPOST /v1/bash/kill发送信号终止进程GET /v1/bash/sessions列出所有活跃会话会话状态为ready表示可接受命令closed表示已关闭不可复用见 client.pyPOST /v1/bash/sessions/create显式创建会话可指定初始exec_dir与snapshot_pathPOST /v1/bash/sessions/{session_id}/close关闭会话上述端点均有对应的 Python 同步/异步客户端方法exec/output/write/kill/sessions/create_session/close_session含AsyncBashClient异步版本与 TypeScript 客户端实现便于直接在 Agent 代码中集成。与 Shell Terminal 的协同如果你需要的是 REPL、交互式程序或真实终端行为请改用基于 PTY 的 Shell Terminal它提供 REST 与 WebSocket 两种接入方式支持waitview的快照读取适合 WebTerminal UI 与人工接管。而 Bash Pipe 的独立stdout/stderr、offset 增量读取与command_id粒度使其成为 Agent 工具调用与长命令轮询的首选。两套 API 共享同一份文件系统命令写入/tmp/test.txt后可直接通过 File API 读取在编排 Agent 工作流时可以灵活组合。赞分享AI Agent后端MCP 服务浏览器控制Agent 评测【免费下载链接】sandboxAll-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.项目地址https://gitcode.com/gh_mirrors/sandbox103/sandbox点击查看免费下载相关推荐Haystack E2B 集成指南为 Agent 接入实时云沙箱执行 Bash 命令与文件操作Haystack E2B 集成指南为 Agent 接入实时云沙箱执行 Bash 命令与文件操作 导读 E2B 是面向 AI Agent 的云端沙箱服务本文讲人工智能大模型RAGAI AgentNLPVibe Coding Platform 的 Run Command 工具为 AI Agent 设计沙箱命令执行的完整指南Vibe Coding Platform 的 Run Command 工具为 AI Agent 设计沙箱命令执行的完整指南 导读 Run Command 是示例工程前端后端Kimi Code 的 Bash 工具Agent 执行 Shell 命令的完整实战指南与源码解析Kimi Code 的 Bash 工具Agent 执行 Shell 命令的完整实战指南与源码解析 导读 Kimi Code 是一个面向下一代 Agent 的编AI Agent代码智能体人工智能大模型CLI上一篇终极防撤回指南RevokeMsgPatcher如何守护你的聊天隐私安全下一篇终极解决Compose Multiplatform桌面预览任务与Gradle配置缓存兼容性全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考