本文带你使用 Deuz SDK 从零构建一个 Coding Agent（编码智能体）：它会读文件、改代码、跑测试，在工具报错时自愈重试，全程受预算与审批门禁控制。Deuz SDK 是一个零运行时依赖的 TypeScript AI Agent 框架，一个流式 API 即可接入 Claude、GPT、Gemini、Grok 等主流模型，跑在 Node、Bun、Deno 与 Edge 之上。

一、为什么选 Deuz SDK 来搭 Coding Agent 🧩

构建 Coding Agent 通常需要自己拼一堆积木：工具循环、子代理、错误恢复、预算控制、上下文压缩。Deuz SDK 把这些都变成了现成原语，官方 cookbook 里甚至有一份完整的 Coding Agent 构建手册，架构图长这样：

orchestrator（编排者，generateText / streamChat） └─ tools: { coder: agentTool(...) } ← 子代理 └─ coder 子代理 └─ tools: readFile / writeFile / applyPatch / runTests / runShellCommand

• 编排者（orchestrator）只负责和用户对话、拆任务，绝不直接碰文件系统
• coder 子代理负责真正的动手干活：读写文件、打补丁、跑测试、执行 shell 命令
• 审批策略、token/成本预算、自动压缩（compaction）在每一层都生效

官方基准测试中，Deuz SDK 在 Coding 场景拿到 76 分（见上方图表），并且核心包体积只有 10 MB，是同类框架里最轻的之一。

二、安装与第一个 Agent：5 分钟上手 🚀

先安装并配置一个模型 API Key（以 Anthropic 为例）：

npm install @deuz-sdk/core

import { runAgent } from '@deuz-sdk/core/agent'; import { createAnthropic } from '@deuz-sdk/core/anthropic'; const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); const result = await runAgent({ model: anthropic('claude-opus-4-8'), prompt: '解释一下彩虹是怎么形成的', maxSteps: 4, });

⚠️ 新手最容易踩的坑：maxSteps默认是1。带了工具却不设步数上限，循环只跑一轮工具调用就停了，模型根本看不到工具结果。任何真实工具场景请把它设大于 1。

三、定义 5 个编码工具：让 Agent 会读码、改码、跑测试

工具（Tool）就是模型能按名字调用的函数：description+parameters参数 schema +execute执行体。Coding Agent 需要 5 个核心工具：

关键写法只有一个原则：破坏性工具全部标记needsApproval: true，例如：

writeFile: { description: 'Write (overwrite) a UTF-8 text file in the workspace.', parameters: z.object({ path: z.string(), content: z.string() }), needsApproval: true, // 破坏性操作，需要审批 execute: async ({ path, content }, ctx) => { /* 只写在沙箱工作区内 */ }, };

另外三条工程铁律（来自官方 cookbook）：

1. 输出必须截断——一次不受限的runTests长日志就能撑爆上下文窗口和你的账单
2. stdout 和 stderr 分开捕获，不要混成一坥无法推理的 blob
3. 把ctx.signal传给所有子进程，这样编排者一 abort，测试/命令真正会被杀掉

四、用 agentTool 把 coder 包成子代理 🤖

agentTool能套娃一个完整的多步循环，包成一个普通工具供编排者调用：

import { agentTool } from '@deuz-sdk/core'; const coder = agentTool({ name: 'coder', description: 'Writes and tests code changes: reads/writes files, applies patches, runs the test suite.', model: coderModel, tools: codingTools, system: 'Read before you write, run tests after every change, keep diffs minimal.', maxSteps: 20, // 子代理天然多步，预算要比编排者更宽 });

然后编排者调用时只需要tools: { coder }——它唯一"知道"的就是 coder 这个工具。完整可参考 coding-agent cookbook 第 4、5 节。

五、自愈循环：工具抛错为什么不会崩 💊

这是 Coding Agent 与普通调用的本质区别。Deuz SDK 的 agentic loop 是**自愈（self-healing）**的：工具抛异常、参数校验失败、甚至模型幻觉出工具名，统统不会把整个调用炸掉，而是变成一条isError: true的tool_result喂回给模型，让它换参数重试或换工具。

同时内置失控保护（runaway guard）：同一个工具连续 3 步报错，循环直接硬停，避免模型对着坏工具死循环烧掉整个步数预算。细节见 tool-loop.mdx 自愈章节。

对 Coding Agent 来说这意味着：测试失败、命令打错、路径写错，都是模型"看得见的反馈"，而不是进程崩溃——这就是标题里"自愈循环"的来源。

六、预算、压缩与审批：让长任务跑得完、烧不起 💰

三个选项组合起来，让"多文件、多轮"的长会话既不超支也不失控：

• stopWhen: [totalTokensExceed(500_000), costExceeds(5.0)]——真实花费的硬上限，且统计的是编排者 + coder 的合并用量；跑完后result.providerMetadata?.deuz.stoppedBy会告诉你到底是预算还是模型自然结束的
• compaction: 'auto'——自动分层压缩历史，长时间会话不会撑爆上下文
• approveToolCall——一个策略函数继承到 coder 的每一层深度，runShellCommand、writeFile、applyPatch在每一层都被同一规则门禁

🛡️ 重要提醒：审批不是沙箱。needsApproval只决定"允不允许跑"，不管"跑起来能碰到什么"。文件与 shell 工具必须放进真实沙箱/受限工作区，命令走白名单，拒绝..路径穿越，且绝不要把主机密钥暴露给 shell 工具。

七、流式观察与持久化：看着 coder 干活、崩了能续上 🔁

• 流式渲染：把generateText换成streamChat，coder 子代理的完整规范流会以带agentPath标签的sub-agentparts 转发进fullStream，你在终端里就能实时看到[coder] calling runTests这样的逐代理活动流
• 持久化断点：给任一入口传session: { store, runId }，循环会在每个完成的步骤边界存一个AgentCheckpoint；进程挂了，之后用resumeFromCheckpoint从最后边界继续。审批挂起的状态也能通过approvalResponses续上

官方还提供了一个可直接运行的完整示例（Manus 风格的自治代理，含 plan → executor 子代理 →verifyStep验证器，CodeAct 沙箱里写码跑码）：

• 示例入口：examples/06-autonomous-agent/
• 自治手册：autonomous-agent cookbook，其中verifyStep会"驱动编排者直到子任务可验证完成"，是自愈循环的上层形态
• 工具循环参考：The Agentic Tool Loop
• 工具定义参考：Defining Tools

八、小结：你的 Coding Agent 已经跑起来了 ✅

回顾一下这套组合拳：5 个工具（读/写/补丁/测试/shell）+agentTool子代理+自愈工具循环+token/成本预算+自动压缩+审批门禁+持久化断点。没有任何新运行时，全部由generateText/streamChat+stopWhen+compaction: 'auto'组合而成——这就是 Deuz SDK 作为零依赖生产级 Agent 框架的用法。下一步建议直接跑 06-autonomous-agent 示例，把ANTHROPIC_API_KEY配好，观察它如何在.agent-workspace/里真正读写文件、执行命令并自验证结果。