几行代码，写一个生产级 Agent

作者：Chris Chen

Agent 开发现状

早期的 Agent 跟普通后端差别不大——客服、问答、查订单这些场景里，它更像一个带业务接口的 LLM 服务。但随着模型能力增强，Agent 开始真正"动手"——处理文件、改代码、跑测试、操作浏览器、串复杂系统，逐渐接管过去需要人工完成的工作。为了限制权限边界、控制资源使用，沙箱成为必备项。

接下来直觉的做法，是把 Agent 逻辑与工具塞进同一个沙箱，链路短、状态共享方便。这个架构很简洁，但当进入企业级场景，多租户、安全隔离、成本效率等方面会有较多挑战。例如：改一行逻辑要重建一个包含完整工具链的镜像；并发场景下每个对话独占一份完整沙箱，资源开销快速堆叠；Agent 逻辑、凭证跟不可信代码在一个环境中，prompt injection 的攻击面变大；状态绑死在沙箱中，销毁即丢，难以恢复。

于是行业开始探索更解耦的方式——Agent 逻辑、工具沙箱、状态各自独立，每个组件按自己的生命周期调度，互不绑定。

但解耦组件多了，链路变长，环境割裂，落地时通常面临两类难题：要么业务代码与配置都要按平台特定形态写——导入平台 SDK、继承平台基类、声明平台专属配置；要么计算、状态、沙箱、可观测从一堆独立服务里挑出来自己拼装、自己适配框架。本地调试与链路追踪 也变得尤为重要。

Makers 的选择

Makers 不重新定义 Agent 开发方式——入口函数里只有一个 context 入参，没有平台 SDK，也没有专属配置。Claude Agent SDK、OpenAI Agents SDK、LangGraph、DeepAgents、CrewAI 等主流框架直接拿来就用，写的就是框架文档里的代码；也可以手搓一个属于自己的。运行时上下文里封装好各框架原生的会话记忆、沙箱原子接口、实时可观测，把基础设施与底层依赖交给平台，Agent 本身留给开发者。

另一个特点是 Web 应用与 Agent 同栈——同一个项目里既能写 Agent 也能写前端，一次部署、同一个域名。

几行代码跑起来

下面通过 CLI 拉一个 OpenAI Agents 模板，先把它跑起来：

$ npm install -g edgeone
$ edgeone makers create --template openai-agents-starter-node
$ cd openai-agents-starter-node && edgeone makers dev
 ▸ runtime  http://localhost:8088
 ▸ devtools http://localhost:8088/agent-metrics

打开 :8088 就能直接和模板自带的对话界面聊上。

打开 :8088/agent-metrics，平台已在 Runtime 启动时为 @openai/agents 与 OpenAI SDK 注册好 instrumentor，每一次请求的 LLM 调用、工具调用、Session 读写都自动入树，本地 SQLite 实时落盘——不需要额外接一行埋点代码。

几行代码背后

在模板里的主 handler 中除了一个由平台注入的 context，没有任何来自平台的 import：

// agents/chat/index.ts —— 路径自动映射到 POST /chat
import OpenAI from 'openai'
import { Agent, run, OpenAIChatCompletionsModel } from '@openai/agents'

export async function onRequest(context: any) {
  const { message, conversation_id } = context.request.body
  const { AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL } = context.env

  const client = new OpenAI({ apiKey: AI_GATEWAY_API_KEY, baseURL: AI_GATEWAY_BASE_URL })
  const session = context.store.openaiSession(conversation_id)
  const agent = new Agent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
    model: new OpenAIChatCompletionsModel(client, '@makers/hy3-preview'),
    tools: [context.tools.web_search],
  })
  const result = await run(agent, message, { session })
  return Response.json({ reply: result.finalOutput })
}

handler 里出现的三类平台能力——模型网关、会话存储、内置工具——都包在 context 上。

context.env 里的 AI_GATEWAY_* 是项目创建时平台自动签发并注入的环境变量，把它们交给 OpenAI SDK，调用就走内置的 AI 网关，不需要单独申请 Key——平台限时赠送了多种模型的 Token 额度；当然你也可以换成自己的 API Key。

context.store.openaiSession(cid) 返回的是 @openai/agents 原生的 Session，传给 run() 就接管对话历史读写——框架看到的是它自己的接口，平台对框架透明。换到 LangGraph、Claude Agent SDK 等其他框架，context.store 上挂的同样有各框架原生的会话存储类型，底层由平台 Blob 存储接管。

context.tools.* 是平台预置的工具集合，覆盖网页搜索、代码解释器、浏览器操作等常见动作，直接放进框架的 tools 里就行。沙箱类工具会在同对话首次调用时懒起一个微 VM，后续复用，超时回收——不会因为 handler 启动而预热，也不会因为冷启动而每次重建。

需要自定义工具时，context.sandbox 暴露的是沙箱原子接口，可以自由组合：

const runPython = tool({
  name: 'run_python',
  parameters: z.object({ code: z.string() }),
  execute: async ({ code }) => {
    const sb = await context.sandbox()       // 懒加载，按对话复用
    return await sb.codeInterpreter.run(code)
  },
})

部署上线

本地跑通后，edgeone makers deploy 一行上线，上线后看到的是同一组 span、同一套 instrumentation。同项目里的前端代码也会一并部署，挂同一个域名。

平台资源调度会按 conversation_id 将同一对话请求落到同一 Agent 实例与工具沙箱，按需创建、空闲回收、业务代码无感。

到这里，一个能跑联网工具、带会话记忆、自带可观测、生产就绪的 Agent 就齐了。开发者真正写的，仍然是 @openai/agents 文档里的那几行。

我们还备了 LangGraph、Claude Agent SDK、CrewAI、DeepAgents 等其他框架的模板，以及 Python、JavaScript 两个不依赖任何框架的最小示例。除了 edgeone makers create 拉到本地，也可以直接在模板列表里一键部署到自己账号。

模板列表 →

文档 →