首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >Agent 沙箱是什么?EdgeOne Makers 内置沙箱的工具清单、权限控制与生命周期

Agent 沙箱是什么?EdgeOne Makers 内置沙箱的工具清单、权限控制与生命周期

原创
作者头像
克劳德2048
发布于 2026-11-17 09:56:09
发布于 2026-11-17 09:56:09
250
举报

摘要: 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 小时。

一、Agent 沙箱是什么,为什么需要它

大模型本身只能生成文本。要让它真正完成任务——比如"把这个 CSV 算一下并生成图表""打开这个网页看看价格""把结果写进文件"——就需要一个能执行这些动作的环境。

这个环境必须满足三个条件:能执行任意代码和命令、与其他用户的执行环境完全隔离、用完能自动回收。自建方案通常要起容器、管生命周期、做清理,工作量不小。

沙箱工具把这部分做成了平台能力。它承载的是 Agent 的"副作用"操作,也就是会改变外部状态或依赖外部环境的动作:执行 shell 命令、读写文件、用浏览器访问网页、运行代码片段、做网页搜索。

二、沙箱的两层 API:给模型用和给开发者用

平台把同一个沙箱实例包装成两层 API 暴露在 context 上,这是理解沙箱设计的关键:

视角

字段

给谁用

粒度

LLM 视角

context.tools.*

传给 LLM 的工具清单,按 framework 包装为原生对象

已扁平化为原子工具,便于按需放开调用范围

开发者视角

context.sandbox.*

开发者代码中直接调用的沙箱原子 API

按模块组织:commands / files / browser / runCode 顶层方法

两层底层共用同一个沙箱实例。 context.tools 中需要沙箱能力的内置工具,其内部实现就是直接调用 context.sandbox.*,不存在两套独立逻辑。

实际开发中的用法区分:让模型自主决定何时执行的动作,放进 context.tools 交给 LLM;流程中固定要做的步骤,用 context.sandbox 在代码里直接调。

三、平台内置的 14 个原子工具

工具按能力原子化,每个工具一一对应到底层 sandbox 方法。LLM 通过工具名加描述的语义匹配选工具,业务侧也能按工具名细粒度配置允许调用范围。

工具名

入参

说明

commands

cmd, cwd?, env?, timeout?

执行一次性 shell 命令

files_read

path

读文件

files_write

path, content

写文件,不存在则创建,存在则覆盖

files_list

path

列目录,条目仅含 name / type / path

files_exists

path

检查文件或目录是否存在

files_remove

path

删除文件或目录

files_make_dir

path

创建目录

browser_fetch

url

用真实 Chromium 导航并获取页面元信息与 HTML

browser_screenshot

url?, fullPage?

截图,返回 { base64Image }

browser_click

selector

点击当前页面元素

browser_type

selector, text

在当前页面元素中输入文本

browser_evaluate

script

在当前页面上下文执行 JavaScript

code_interpreter

language, code, timeout?

代码执行

web_search

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 提供四个选择方法用于收窄范围:

方法

返回值

适用场景

all()

所有内置工具

允许模型使用完整 sandbox 能力

get(name)

指定名称的单个工具

精确注册或手动调用某个原子工具

files()

六个 files 系列工具

快速注册文件能力

browser()

五个 browser 系列工具

快速注册浏览器能力

只给文件和浏览器能力,不开放 shell 命令与代码解释器:

代码语言:javascript
复制
const safeTools = [
  ...context.tools.files(),
  ...context.tools.browser(),
]

进一步禁用写入与删除类能力,在分组结果上继续过滤:

代码语言:javascript
复制
const readonlyFileTools = context.tools.files()
  .filter((tool) => !['files_write', 'files_remove', 'files_make_dir'].includes(tool.name))

这是沙箱接入时最值得花时间的一步。 面向外部用户的 Agent 建议从最小集合开始,确认业务需要哪些动作再逐个放开,而不是先用 all() 跑通再想着收窄。

五、沙箱实例的生命周期

维度

说明

实例归属

一对话一实例,按 conversation_id 维度托管

创建时机

懒加载,首次访问沙箱工具时由适配层创建

跨请求复用

实例未被销毁时,同 conversation_id 的沙箱请求落到同一实例

生命周期上限

由 edgeone.json 的 sandbox.timeout 控制,到点自动回收

隔离性

不同对话的沙箱实例物理隔离

懒加载的实际意义:不会因为 handler 启动就预热沙箱。一个 Agent 如果本轮对话没触发任何沙箱工具,就不会创建实例,也不消耗沙箱配额。

跨请求复用的实际意义:同一对话中第一轮写进沙箱的文件,第二轮还能读到(前提是实例未过期)。这让多步骤任务可以把中间产物留在沙箱里,不必每轮重新准备。

六、沙箱实例控制:五个管理方法

方法挂载在 context.sandbox 顶层,用于管理实例本身的生命周期与对外暴露。

方法

用途

getHost(port)

获取沙箱实例某个端口的外部访问地址

envdAccessToken

获取数据面访问 token

getInfo()

获取当前沙箱信息(instanceId、expiresAt 等)

extendTimeout(seconds)

延长当前沙箱实例寿命

kill()

销毁沙箱实例

getHost(port) 的典型用法是把沙箱内启动的服务暴露给浏览器。返回值形如 https://<port>-<instance>.sandbox.example.com:

代码语言:typescript
复制
// 沙箱里跑个 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 })
代码语言:python
复制
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 字段说明实际续到什么时候:

代码语言:typescript
复制
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

输出格式

claude-agent-sdk

{ name, description, input_schema, execute },含 toClaudeMcpServer() helper

openai-agents-sdk

Node 为轻量 function-tool 兼容对象,Python 为 agents.FunctionTool

langgraph

Node 为 lightweight wrapper,Python 为 LangChain StructuredTool

deepagents

同 LangGraph

crewai

Node 为 lightweight wrapper,Python 为 CrewAI BaseTool

一个必须知道的前提:平台不会默认安装 langchain-core 或 @langchain/core/tools。需要真实框架 tool 对象时,要用 helper 方法注入框架的 class 或 factory。

框架

Node helper

Python helper

LangGraph / DeepAgents

context.tools.toLangChainTools(toolFactory, names?)

ctx.tools.to_langchain_tools(StructuredTool, names=None)

CrewAI

context.tools.toCrewAITools(baseToolOrFactory, names?)

ctx.tools.to_crewai_tools(BaseTool, names=None)

Claude Agent SDK

context.tools.toClaudeMcpServer(name?, options?)

ctx.tools.to_claude_mcp_server(name=None, options=None)

OpenAI Agents SDK

无需 helper

无需 helper

OpenAI Agents SDK 最简单,直接传:

代码语言:typescript
复制
import { Agent } from '@openai/agents'

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Use sandbox tools.',
  tools: context.tools.all(),
  model,
})

LangGraph 需要把框架自己的 tool factory 传进来:

代码语言:typescript
复制
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 })
代码语言:python
复制
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> 前缀:

代码语言:typescript
复制
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 形态,可以只挑特定工具:

代码语言:typescript
复制
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,这是容量设计时的实际瓶颈:如果每个会话都会触发沙箱,并发上限由沙箱侧决定。

错误码对照:

错误码

说明

SANDBOX_LIMIT_EXCEEDED

并发实例数、总内存时长配额或单实例最大运行时长超限

SANDBOX_INVALID_PARAMETER

参数校验失败,如缺少 conversation_id、授权 Token

SANDBOX_AUTHORIZATION_EXPIRED

授权 Token 无效或过期

SANDBOX_FAILED_OPERATION

沙箱服务操作失败(限频、超时等)

SANDBOX_NETWORK_ERROR

沙箱服务网络异常,或数据面运行时客户端依赖缺失

SANDBOX_INSTANCE_UNAVAILABLE

沙箱实例不存在或已过期

SANDBOX_UNKNOWN_ERROR

兜底错误码,详情查看 message 字段

本地调试日志默认关闭,在运行环境变量中加入开关即可开启,日志输出到本地 CLI 的 stderr:

代码语言:txt
复制
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 删除。

目录
  • 一、Agent 沙箱是什么,为什么需要它
  • 二、沙箱的两层 API:给模型用和给开发者用
  • 三、平台内置的 14 个原子工具
  • 四、权限控制:只给模型需要的工具
  • 五、沙箱实例的生命周期
  • 六、沙箱实例控制:五个管理方法
  • 七、五种框架怎么接入沙箱工具
  • 八、配额、错误码与本地调试
  • 总结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档