
摘要: Agent 沙箱是承载智能体执行副作用的隔离实例。EdgeOne Makers 内置沙箱工具提供 commands、files、browser、code_interpreter、web_search 共 14 个原子工具,通过 context.tools 给模型调用、context.sandbox 给开发者调用,按 conversation_id 一对话一实例并物理隔离。
Agent 沙箱解决的是一件事:让大模型从"只能输出文本"变成"能动手执行"。 EdgeOne Makers 内置的沙箱工具底层是腾讯云的隔离实例,专门承载 Agent 执行过程中的副作用——跑命令、读写文件、操控浏览器、运行代码。它按 conversation_id 一对话一实例托管,不同对话的实例物理隔离,首次访问时懒加载创建,到 sandbox.timeout 配置的时间点自动回收。免费版的并发上限是 20 个实例,单实例最长运行 1 小时。
大模型本身只能生成文本。要让它真正完成任务——比如"把这个 CSV 算一下并生成图表""打开这个网页看看价格""把结果写进文件"——就需要一个能执行这些动作的环境。
这个环境必须满足三个条件:能执行任意代码和命令、与其他用户的执行环境完全隔离、用完能自动回收。自建方案通常要起容器、管生命周期、做清理,工作量不小。
沙箱工具把这部分做成了平台能力。它承载的是 Agent 的"副作用"操作,也就是会改变外部状态或依赖外部环境的动作:执行 shell 命令、读写文件、用浏览器访问网页、运行代码片段、做网页搜索。
平台把同一个沙箱实例包装成两层 API 暴露在 context 上,这是理解沙箱设计的关键:
视角 | 字段 | 给谁用 | 粒度 |
|---|---|---|---|
LLM 视角 |
| 传给 LLM 的工具清单,按 framework 包装为原生对象 | 已扁平化为原子工具,便于按需放开调用范围 |
开发者视角 |
| 开发者代码中直接调用的沙箱原子 API | 按模块组织:commands / files / browser / runCode 顶层方法 |
两层底层共用同一个沙箱实例。 context.tools 中需要沙箱能力的内置工具,其内部实现就是直接调用 context.sandbox.*,不存在两套独立逻辑。
实际开发中的用法区分:让模型自主决定何时执行的动作,放进 context.tools 交给 LLM;流程中固定要做的步骤,用 context.sandbox 在代码里直接调。
工具按能力原子化,每个工具一一对应到底层 sandbox 方法。LLM 通过工具名加描述的语义匹配选工具,业务侧也能按工具名细粒度配置允许调用范围。
工具名 | 入参 | 说明 |
|---|---|---|
| cmd, cwd?, env?, timeout? | 执行一次性 shell 命令 |
| path | 读文件 |
| path, content | 写文件,不存在则创建,存在则覆盖 |
| path | 列目录,条目仅含 name / type / path |
| path | 检查文件或目录是否存在 |
| path | 删除文件或目录 |
| path | 创建目录 |
| url | 用真实 Chromium 导航并获取页面元信息与 HTML |
| url?, fullPage? | 截图,返回 |
| selector | 点击当前页面元素 |
| selector, text | 在当前页面元素中输入文本 |
| script | 在当前页面上下文执行 JavaScript |
| language, code, timeout? | 代码执行 |
| query, maxResults?, site? | 轻量级网页搜索,返回 title / href / snippet / date |
两个常见疑问的官方答复:browser_screenshot 返回的是 PNG 的 base64,不返回 URL,也不在沙箱内保存文件,需要展示给前端或持久化时自行落对象存储换 URL。browser_fetch 与直接发 HTTP 请求的区别在于它用真实 Chromium 导航(CDP 加 Playwright),能拿到 JS 渲染后的页面内容,而普通 HTTP fetch 只能拿原始响应;需要轻量抓接口时在 commands 里用 curl 更合适。
把全部 14 个工具无差别开放给模型,等于给了它执行任意命令和删除任意文件的能力。context.tools 提供四个选择方法用于收窄范围:
方法 | 返回值 | 适用场景 |
|---|---|---|
| 所有内置工具 | 允许模型使用完整 sandbox 能力 |
| 指定名称的单个工具 | 精确注册或手动调用某个原子工具 |
| 六个 files 系列工具 | 快速注册文件能力 |
| 五个 browser 系列工具 | 快速注册浏览器能力 |
只给文件和浏览器能力,不开放 shell 命令与代码解释器:
const safeTools = [
...context.tools.files(),
...context.tools.browser(),
]进一步禁用写入与删除类能力,在分组结果上继续过滤:
const readonlyFileTools = context.tools.files()
.filter((tool) => !['files_write', 'files_remove', 'files_make_dir'].includes(tool.name))这是沙箱接入时最值得花时间的一步。 面向外部用户的 Agent 建议从最小集合开始,确认业务需要哪些动作再逐个放开,而不是先用 all() 跑通再想着收窄。
维度 | 说明 |
|---|---|
实例归属 | 一对话一实例,按 |
创建时机 | 懒加载,首次访问沙箱工具时由适配层创建 |
跨请求复用 | 实例未被销毁时,同 |
生命周期上限 | 由 |
隔离性 | 不同对话的沙箱实例物理隔离 |
懒加载的实际意义:不会因为 handler 启动就预热沙箱。一个 Agent 如果本轮对话没触发任何沙箱工具,就不会创建实例,也不消耗沙箱配额。
跨请求复用的实际意义:同一对话中第一轮写进沙箱的文件,第二轮还能读到(前提是实例未过期)。这让多步骤任务可以把中间产物留在沙箱里,不必每轮重新准备。
方法挂载在 context.sandbox 顶层,用于管理实例本身的生命周期与对外暴露。
方法 | 用途 |
|---|---|
| 获取沙箱实例某个端口的外部访问地址 |
| 获取数据面访问 token |
| 获取当前沙箱信息(instanceId、expiresAt 等) |
| 延长当前沙箱实例寿命 |
| 销毁沙箱实例 |
getHost(port) 的典型用法是把沙箱内启动的服务暴露给浏览器。返回值形如 https://<port>-<instance>.sandbox.example.com:
// 沙箱里跑个 vite dev server,再把它的访问地址返给前端
await context.sandbox.commands.run('nohup npx vite --port 5173 &', { timeout: 10 })
const previewUrl = context.sandbox.getHost(5173)
return Response.json({ previewUrl })await ctx.sandbox.commands.run('nohup python -m http.server 8000 &', timeout=10)
preview_url = ctx.sandbox.get_host(8000)
return {'preview_url': preview_url}续期的正确写法是先查剩余时间再决定是否续。extendTimeout 的真实生效时长以后端返回为准——要求的秒数超出后端允许的剩余可续期窗口时,后端会截断并在 message 字段说明实际续到什么时候:
const info = context.sandbox.getInfo()
const remainingMs = new Date(info.expiresAt).getTime() - Date.now()
if (remainingMs < 60_000) {
await context.sandbox.extendTimeout(600)
}kill() 的使用时机:一次性脚本结束、或确认整个对话结束希望立刻释放实例配额时主动调用。不调也会按 timeout 自动回收。
context.tools.* 的输出格式由 edgeone.json 中的 framework 字段决定:
framework | 输出格式 |
|---|---|
|
|
| Node 为轻量 function-tool 兼容对象,Python 为 |
| Node 为 lightweight wrapper,Python 为 LangChain StructuredTool |
| 同 LangGraph |
| Node 为 lightweight wrapper,Python 为 CrewAI BaseTool |
一个必须知道的前提:平台不会默认安装 langchain-core 或 @langchain/core/tools。需要真实框架 tool 对象时,要用 helper 方法注入框架的 class 或 factory。
框架 | Node helper | Python helper |
|---|---|---|
LangGraph / DeepAgents |
|
|
CrewAI |
|
|
Claude Agent SDK |
|
|
OpenAI Agents SDK | 无需 helper | 无需 helper |
OpenAI Agents SDK 最简单,直接传:
import { Agent } from '@openai/agents'
const agent = new Agent({
name: 'Assistant',
instructions: 'Use sandbox tools.',
tools: context.tools.all(),
model,
})LangGraph 需要把框架自己的 tool factory 传进来:
import { tool } from '@langchain/core/tools'
import { createReactAgent } from '@langchain/langgraph/prebuilt'
const allTools = context.tools.toLangChainTools(tool)
const agent = createReactAgent({ llm: model, tools: allTools })from langchain_core.tools import StructuredTool
from langgraph.prebuilt import create_react_agent
all_tools = ctx.tools.to_langchain_tools(StructuredTool)
agent = create_react_agent(model, tools=all_tools)Claude Agent SDK 走 MCP 路径。toClaudeMcpServer() 把沙箱内置工具转成 MCP server bundle,再传给 createSdkMcpServer 注册。传入的 name 会同步成 mcp__<name>__<tool> 前缀:
import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
export async function onRequest(context: any) {
const edgeoneMcp = context.tools.toClaudeMcpServer()
const mcpServers = [
createSdkMcpServer({ name: edgeoneMcp.name, tools: edgeoneMcp.tools }),
]
const allowedTools = edgeoneMcp.allowedTools
}DeepAgents 复用 LangChain 形态,可以只挑特定工具:
import { createDeepAgent } from 'deepagents'
import { tool } from '@langchain/core/tools'
const tools = context.tools.toLangChainTools(tool, ['web_search'])
const agent = await createDeepAgent({
model, tools,
systemPrompt: 'Use web_search for public web discovery.',
})免费版沙箱配额:
项 | 免费版 |
|---|---|
总内存时长 | 10 万 GB-s/月 |
最大并发运行数 | 20 个 |
单实例最长运行时间 | 3600 秒 |
默认超时时间 | 300 秒 |
edgeone.json 中 agents.sandbox.timeout 可配置范围为 300~3600 秒,默认 300 秒。官方说明免费版沙箱实例的最长运行时长为 1 小时,需要更长可提交工单申请。
沙箱并发 20 低于会话并发 40,这是容量设计时的实际瓶颈:如果每个会话都会触发沙箱,并发上限由沙箱侧决定。
错误码对照:
错误码 | 说明 |
|---|---|
| 并发实例数、总内存时长配额或单实例最大运行时长超限 |
| 参数校验失败,如缺少 conversation_id、授权 Token |
| 授权 Token 无效或过期 |
| 沙箱服务操作失败(限频、超时等) |
| 沙箱服务网络异常,或数据面运行时客户端依赖缺失 |
| 沙箱实例不存在或已过期 |
| 兜底错误码,详情查看 message 字段 |
本地调试日志默认关闭,在运行环境变量中加入开关即可开启,日志输出到本地 CLI 的 stderr:
MAKERS_AGENT_TOOLKIT_DEBUG=1日志会对 token、auth、password、secret、key 等敏感字段做脱敏,截图结果不打印完整 base64,只打印摘要长度。
沙箱工具的接入路径是四步:在 edgeone.json 里填对 framework、按框架用对应 helper 拿到工具对象、用 files() / browser() / get() 收窄权限范围而不是直接 all()、按业务最长任务设置 sandbox.timeout。
三个容易踩的点:以为 browser_screenshot 会返回图片 URL(实际返回 base64,需自行落存储);用 LangGraph 或 CrewAI 时忘记平台不预装框架依赖、没走 helper 注入;容量规划时只看会话并发 40 而忽略沙箱并发 20 才是瓶颈。
产品完整能力与控制台入口见 EdgeOne Makers 产品页:https://cloud.tencent.com/product/makers
当前首购特惠 EdgeOne Makers 专业版 Pro 套餐 39 元/月,具体以活动页实际展示为准:https://cloud.tencent.com/act/pro/makers-pro
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。