构建可靠的 TypeScript AI Agent：从 4B 本地模型到 Claude 3.5 Sonnet 的无缝切换

在当前的 AI Agent 开发领域，我们经常会陷入“演示陷阱”。你编写了几行代码，连接了像 Claude 3.5 Sonnet 这样的一流模型（通过 n1n.ai 轻松接入），在演示视频中它表现得完美无缺。然而，一旦进入真实的生产环境，情况就会变得异常复杂。当你为了降低成本或保护隐私，尝试切换到本地运行的 4B 参数小模型（如通过 Ollama 运行的 Qwen）时，原本稳健的逻辑往往会瞬间崩塌。模型可能会将 get_service_health 错误地调用为 getServiceHealth，或者幻觉出一个不存在的参数。大多数框架在面对这种微小错误时，只会抛出异常并直接终止运行。

这种从“闭源顶级模型”到“本地轻量级模型”之间的巨大鸿沟，正是 Reactive Agents 诞生的原因。这是一个基于 TypeScript 开发的框架，旨在确保无论是在高性能云端集群还是在个人笔记本电脑上，你的代码都能完整地完成任务循环。通过使用 n1n.ai 这样的模型聚合平台，开发者可以方便地在 DeepSeek-V3、OpenAI o3 和 Claude 等多种模型之间进行压力测试，确保代理的“外壳（Harness）”能够承担起稳定性的重任。

核心痛点：为什么小模型在工具调用上频繁翻车？

在与大语言模型（LLM）交互时，工具调用（Tool Calling）是连接推理与行动的桥梁。顶级模型经过了严格的 Schema 遵循训练，但参数量在 10B 以下的小模型则并非如此。它们经常遇到以下问题：

1. 命名不一致：将定义的 get_user 调用成 getUser 或 fetch_user。
2. 参数幻觉：在工具只需要 id 时，模型自作聪明地添加了 userId 字段。
3. 语法错误：生成了带有非法引号、多余逗号或格式错误的 JSON 字符串。

在传统的代理循环中，这些小错是致命的。Reactive Agents 的核心理念是：与其强求模型完美，不如让框架具备更强的容错能力。

解决方案：Reactive Agents 的“治愈管道” (Healing Pipeline)

Reactive Agents 的设计哲学认为，框架应该足够强韧，以抵消模型的不完善。其最引人注目的功能之一就是 治愈管道 (Healing Pipeline)。当模型发出工具调用指令时，框架不会直接执行，而是先进行一次“修复”：它会对工具名称进行模糊匹配，映射参数别名，并根据 Schema 校验类型。如果一个 4B 模型给出的指令是“几乎正确”的，治愈管道会在它进入后端逻辑之前将其修正。

import { ReactiveAgents } from 'reactive-agents'

// 仅需一行代码即可在本地与顶级模型间切换
const agent = await ReactiveAgents.create()
  .withProvider('ollama')
  .withModel('qwen3:4b') // 本地测试环境
  // .withProvider("anthropic").withModel("claude-3-5-sonnet") // 通过 n1n.ai 接入生产环境
  .withReasoning()
  .withTools({ tools: [getServiceHealth, getRecentDeploys] })
  .withContextProfile({ tier: 'local' }) // 针对小模型进行激进的提示词压缩
  .build()

const result = await agent.run('支付 API 正在报警。请调查原因并给出修复建议。')

通过 n1n.ai 提供的多模型接入能力，你可以轻松对比不同模型在开启“治愈管道”后的表现。你会发现，虽然 Claude 3.5 Sonnet 几乎不需要修复，但像 Llama 3.1 8B 这样的小模型，在开启修复后其任务完成率会从 40% 飙升至 90% 以上。

持久化运行：在进程崩溃中幸存

稳定性不仅关乎模型错误，还关乎基础设施的可靠性。长时间运行的 AI Agent 极易受到进程重启、容器调度或网络超时的影响。如果一个代理正在执行一个包含 10 个步骤的复杂调查任务，而服务器在第 9 步时重启了，传统的做法是丢失所有进度，重新支付 Token 费用从头开始。

Reactive Agents 引入了 .withDurableRuns()。该功能会将代理生命周期中的每一个迭代步骤都保存到持久化存储（如磁盘）中。如果进程意外中止，新的进程可以从最后一个检查点直接恢复运行。已经执行过的工具不会再次运行，这不仅节省了时间，更节省了在 n1n.ai 上消耗的 API 成本。

// 进程 A（运行中被强制终止）
const agent = await buildAgentWithDurableRuns()
for await (const step of agent.runStream(task)) {
  // 执行中...
}

// 进程 B（重启后的恢复进程）
const recoveredAgent = await buildAgentWithDurableRuns()
const activeRuns = await recoveredAgent.listRuns({ status: 'running' })
if (activeRuns.length > 0) {
  const result = await recoveredAgent.resumeRun(activeRuns[0].runId)
  console.log('任务在恢复后成功完成：', result.output)
}

这种持久化机制也是 “人机协作 (Human-in-the-Loop)” 的基石。你可以定义一个需要人工审批的工具，运行到此处时代理会自动暂停并保存状态。人类可以在数小时甚至数天后，从完全不同的 UI 或进程中通过 runId 唤醒并批准该操作。

12 阶段生命周期与 Hook 机制

与许多“黑盒”框架不同，Reactive Agents 为每一次运行定义了清晰的 12 个阶段，包括 bootstrap（引导）、guardrail（护栏）、cost-route（成本路由）、think（思考）、act（行动）和 verify（验证）等。开发者可以在任何阶段的“之前”、“之后”或“出错时”挂载 Hook，实现自定义监控或逻辑注入，而无需编写复杂的中间件。

由于该框架底层基于 Effect-TS 构建，它提供了一个完全类型化的错误通道。你面对的不再是模糊的 Error 对象，而是具有明确类型的超时、模型故障或工具执行错误。这使得在生产环境中调试复杂的代理逻辑变得前所未有的简单。

框架对比：为什么选择 Reactive Agents？

总结

构建一个能在演示中跑通的 Agent 很容易，但构建一个能在各种模型质量和基础设施波动下，稳定运行 10,000 次的 Agent 才是真正的挑战。Reactive Agents 为专业的 TypeScript AI 开发提供了必要的结构化保障。无论你是在本地利用轻量级模型进行原型开发，还是通过 n1n.ai 部署高价值的生产级代理，关注“外壳”的稳定性都是通往成功的捷径。

在 n1n.ai 获取免费的 API 密钥。