Agent 框架使用
context.tools 是面向 LLM 的工具清单视角，已经按 framework 做了适配，业务代码不需要再做格式转换。平台内置工具清单
工具按能力原子化，每个工具一一对应到底层 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/ snite/ date |
工具选择快捷方法
context.tools 提供以下选择方法，返回值都是当前 framework 适配后的工具对象数组或单个工具对象：方法 | 返回值 | 适用场景 |
all() | 所有内置工具 | 允许模型使用完整 sandbox 能力 |
get(name) | 指定名称的单个工具 | 精确注册或手动调用某个原子工具 |
files() | files_read、files_write、files_list、files_exists、files_remove、files_make_dir | 快速注册文件能力 |
browser() | browser_fetch、browser_screenshot、browser_click、browser_type、browser_evaluate | 快速注册浏览器能力 |
示例：只给 Agent 文件和浏览器能力，不开放 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))
支持的框架
context.tools.* 的输出格式由 framework 决定，在 edgeone.json 中配置：{"agents": { "framework": "claude-agent-sdk" } // claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents}
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 | Node：lightweight LangChain-like wrapper；Python：LangChain StructuredTool |
crewai | Node：lightweight wrapper；Python：CrewAI BaseTool |
平台 不会默认安装langchain-core/@langchain/core/tools，需要真实框架 tool 对象时，优先使用下面的 helper 方法注入框架 class / factory。
框架 helper 方法
这些 helper 可以在 Makers Agent Runtime 注入的
context.tools 上直接调用。框架 | Node | Python | 说明 |
LangGraph / DeepAgents / LangChain | context.tools.toLangChainTools(toolFactory, names?) | ctx.tools.to_langchain_tools(StructuredTool, names=None) | 返回 LangChain 兼容工具， names 可传工具名或工具名数组 |
OpenAI Agents SDK | - | - | 无需 helper 方法 |
CrewAI | context.tools.toCrewAITools(baseToolOrFactory, names?) | ctx.tools.to_crewai_tools(BaseTool, names=None) | 返回 CrewAI 兼容工具，支持传 BaseTool 类或兼容 factory |
Claude Agent SDK | context.tools.toClaudeMcpServer(name?, options?) | ctx.tools.to_claude_mcp_server(name=None, options=None) | 返回 MCP bundle， name / tools / allowedTools |
Claude Agent SDK-toClaudeMcpServer
把 sandbox 内置工具转成 Claude Agent SDK 的 MCP server bundle，业务代码再传给
createSdkMcpServer / create_sdk_mcp_server 即可注册。参数
参数 | 说明 |
name | MCP server name，会同步成 mcp__<name>__<tool> 前缀 |
options.alwaysLoad / options.always_load | 默认会标记 anthropic/alwaysLoad，传 { alwaysLoad: false } 不会写入 anthropic/alwaysLoad metadata |
返回值
返回 MCP bundle 对象。
TS 示例
import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'export async function onRequest(context: any) {const edgeoneMcp = context.tools.toClaudeMcpServer()// 自定义 server nameconst customMcp = context.tools.toClaudeMcpServer('sandbox')const mcpServers = [createSdkMcpServer({name: edgeoneMcp.name,tools: edgeoneMcp.tools,}),]const allowedTools = edgeoneMcp.allowedTools// 将 mcpServers / allowedTools 传给 Claude Agent SDK}
Python 示例
from claude_agent_sdk import create_sdk_mcp_serverasync def handler(ctx):edgeone_mcp = ctx.tools.to_claude_mcp_server()# 自定义 server name# custom_mcp = ctx.tools.to_claude_mcp_server('sandbox')mcp_servers = [create_sdk_mcp_server(name=edgeone_mcp.name,tools=edgeone_mcp.tools,)]allowed_tools = edgeone_mcp.allowed_tools# 将 mcp_servers / allowed_tools 传给 Claude Agent SDK
OpenAI Agents SDK
无需 helper，把
context.tools.all() 传给 OpenAI Agents SDK 即可，仅暴露部分工具可以用 context.tools.files() / context.tools.browser() / context.tools.get(name) 组装即可，输出形态保持一致。TS 示例
import { Agent } from '@openai/agents'const agent = new Agent({name: 'Assistant',instructions: 'Use sandbox tools.',tools: context.tools.all(),model,})
Python 示例
from agents import Agent, Runneragent = Agent(name="Assistant",instructions="Use sandbox tools.",tools=context.tools.all(),)
LangGraph-toLangChainTools
toLangChainTools / to_langchain_tools 接受框架自身的 tool factory，返回真实 LangChain 工具对象。参数
参数 | 说明 |
toolFactory / StructuredTool | 模板自己 import 的 LangChain tool 函数（Node）或 StructuredTool 类（Python） |
names | 工具名称 |
返回值
LangChain 兼容工具数组（Python 是
StructuredTool 实例，Node 是 tool(...) factory 调用结果）。TS 示例
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 示例
# requirements.txt: pages-agent-toolkit, langchain-core, langgraphfrom langchain_core.tools import StructuredToolfrom langgraph.prebuilt import create_react_agentall_tools = ctx.tools.to_langchain_tools(StructuredTool)agent = create_react_agent(model, tools=all_tools)
DeepAgents-toLangChainTools
DeepAgents 基于 LangGraph，工具形态同 LangChain，复用
toLangChainTools / to_langchain_tools 即可，helper 参数与返回值与 LangGraph 一致，仅 agent 构造入口不同。参数
同 LangGraph：传入 LangChain
tool factory（Node）或 StructuredTool 类（Python），可选 names。返回值
LangChain 兼容工具数组，可直接作为
create_deep_agent(tools=...) / createDeepAgent({ tools, ... }) 的入参。TS 示例
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.',})
Python 示例
from deepagents import create_deep_agentfrom langchain_core.tools import StructuredTooltools = ctx.tools.to_langchain_tools(StructuredTool, names=['web_search'])agent = create_deep_agent(tools=tools,system_prompt='Use web_search for public web discovery.',)
CrewAI-toCrewAITools
toCrewAITools / to_crewai_tools 接受框架的 BaseTool 类（或兼容 factory），把 sandbox 内置工具包装成 CrewAI 工具实例。参数
参数 | 说明 |
baseToolOrFactory / BaseTool | CrewAI BaseTool 类，或返回 BaseTool 实例的 factory |
names | 工具名称 |
返回值
CrewAI 兼容工具数组（Python 是
BaseTool 子类实例，Node 是兼容对象）。TS 示例
const allTools = context.tools.toCrewAITools(CrewBaseToolOrFactory)const researcher = new Agent({role: 'Researcher',goal: 'Use sandbox tools to gather information.',tools: allTools,})
Python 示例
from crewai import Agentfrom crewai.tools import BaseToolall_tools = ctx.tools.to_crewai_tools(BaseTool)researcher = Agent(role='Researcher',goal='Use sandbox tools to gather information.',tools=all_tools,)
本地调试日志
调试日志默认关闭。开启后会把沙箱实例获取成功事件与沙箱工具执行日志输出到本地 CLI 的 stderr。
开启方式：在运行环境变量中加入
MAKERS_AGENT_TOOLKIT_DEBUG=1 开启。MAKERS_AGENT_TOOLKIT_DEBUG=1
日志会对敏感字段（
token / auth / password / secret / key）做脱敏；截图结果不会打印完整 base64Image，只打印摘要：[pages-agent-toolkit] tool.execute.start {"tool":"browser_screenshot","operation":"browser_screenshot","args":{"fullPage":true}}[pages-agent-toolkit] tool.execute.success {"tool":"browser_screenshot","operation":"browser_screenshot","durationMs":123,"result":{"base64ImageLength":193882,"savedToFile":false}}
