Stately Agent – 安全的状态机驱动 AI 代理

它是什么

• 一个 TypeScript/JavaScript 库，允许您将 LLM 驱动的代理构建为 XState 状态机。机器拥有控制流，语言模型仅提出机器验证的事件。

为什么重要

• 保证代理永远无法执行无效操作，因为每个可能的转换都在代码中定义并受到保护。
• 无需实时 API 密钥，即可使代理确定性、可检查、可恢复且可测试。
• 适用于任何 JavaScript 运行时（Node、Vercel、浏览器），并可搭配 Vercel AI SDK、OpenAI SDK 或 TanStack AI。

---

核心概念

概念	功能
机器定义	使用 XState 描述代理的状态、守卫和类型化请求。
模型提案	要求 LLM 生成事件（例如 AUTO_REFUND）。
守卫验证	状态机根据守卫检查事件；非法事件被拒绝并要求模型重新尝试。
执行器	调用所选 AI 提供者的普通函数（decide、generateText 等）。它们由宿主提供，未内置于库中。
环境与策略	业务规则以 TypeScript 代码（environment）形式存在。JSON 编码的策略可由模型编辑，但晋升前由 verifyAgentConfig 把关。
持久性与耐用性	使用 XState 的快照 API；您可以将快照存储在任何地方（文件、数据库、持久对象）。

---

快速开始（退款请求示例）

import { runAgent, setupAgent } from "@statelyai/agent";
import { z } from "zod";

const agentSetup = setupAgent({
  context: z.object({ request: z.string(), amount: z.number() }),
  input:   z.object({ request: z.string(), amount: z.number() }),
  output:  z.object({ outcome: z.enum(["refunded", "review"]) }),
  events: {
    AUTO_REFUND: {},
    REVIEW: z.object({ reason: z.string() })
  }
});

const refundMachine = agentSetup.createMachine({
  context: ({ input }) => input,
  initial: "deciding",
  states: {
    deciding: {
      invoke: { src: "agent.decide", input: ({ context }) => ({
        model: "fast",
        system: "Choose AUTO_REFUND for eligible requests. Otherwise choose REVIEW.",
        prompt: `${context.request}\nAmount: $${context.amount}`,
        allowedEvents: ["AUTO_REFUND", "REVIEW"]
      }) },
      on: {
        AUTO_REFUND: ({ context }) =>
          context.amount <= 100 ? { target: "refunded" } : undefined,
        REVIEW: { target: "review" }
      }
    },
    refunded: { type: "final", output: () => ({ outcome: "refunded" }) },
    review:   { type: "final", output: () => ({ outcome: "review" }) }
  }
});

// 模拟执行器 – 无需 API 密钥
const result = await runAgent(refundMachine, {
  input: { request: "I was charged twice", amount: 75 },
  executors: { decide: async () => ({ event: { type: "AUTO_REFUND" } }) }
});

if (result.status === "done") console.log(result.output); // → { outcome: 'refunded' }

模型只能发出 AUTO_REFUND 或 REVIEW。AUTO_REFUND 上的守卫强制执行 100 美元限额，因此非法选择会自动被拒绝。

安装

# 核心库 + XState (alpha) + Zod 用于模式验证
pnpm add @statelyai/agent@alpha xstate@6.0.0-alpha.64 zod

# 可选的 AI‑SDK 执行器 (Vercel AI SDK)
pnpm add ai@^7 @ai-sdk/openai@^4

# 或原始 OpenAI SDK 执行器
pnpm add openai

# 或 TanStack AI 执行器
pnpm add @tanstack/ai @tanstack/ai-openai

需要 Node 22.18+。

工作原理（架构）

flowchart LR
  M[代理机器<br/>状态·守卫·请求] -->|请求| R[runAgent]
  R -->|执行器调用| E[宿主执行器<br/>generateText·streamText·decide]
  E -->|API 调用| L[LLM 提供者]
  L -->|结果| E
  E -->|结果| R
  R -->|事件/输出| M

1. 机器定义代理能做什么。
2. runAgent 调用机器并将控制权交给执行器。
3. 执行器调用选定的 LLM（通过 AI SDK、OpenAI SDK 等）。
4. LLM 返回事件；机器根据守卫对其进行验证。
5. 如果有效，机器转换；否则模型被要求重试。

---

主要功能（如 README 中列出的）

• 类型化契约 – 用于上下文、输入、输出和事件的 zod 模式确保编译时安全。
• 模型无关 – 通过执行器插入任何提供者；核心从不导入 AI SDK。
• JSON 策略 – 模型可以重写 JSON 策略，但 verifyAgentConfig 根据保留测试收益来把关晋升。
• 持久快照 – XState 的原生快照格式允许您在任何地方持久化并恢复代理。
• 内置模式 – 现成的 ReAct、计划与执行、RAG、监督者等，作为单文件模板。
• 无提供者测试 – MockLanguageModelV3 允许您离线单元测试代理。
• 可观测性与预算 – 文档包含日志记录、使用跟踪和预算执行的钩子。

---

典型用例

• 客户服务机器人 – 必须遵守监管限制（例如退款上限、数据隐私规则）。
• 工作流自动化 – 每个步骤都是已验证的状态转换（审批流程、工单分类）。
• 工具调用代理 – 需要在执行前严格验证工具参数。
• 自我改进代理 – 可以建议策略更新，并在部署前自动审查。
• 嵌入任何堆栈 – 从 serverless 函数到长期运行的持久对象，因为控制流完全位于状态机中。

---

了解更多

• 文档：https://stately.ai/docs/packages/agent
• 示例：examples/ 文件夹（二十个问题、变色龙、工单分类等）
• 与 LangGraph 比较：docs/langgraph-comparison.md
• 模式库：docs/patterns.md

---

TL;DR

Stately Agent 允许您将 LLM 驱动的代理编写为形式化状态机。模型仅建议事件；机器强制执行业务规则，使代理在任何 JavaScript 环境中都安全、可测试且可移植。