Stately Agent – 안전한 상태 머신 기반 AI 에이전트

이것은 무엇인가

• XState 상태 머신으로 LLM 기반 에이전트를 구축할 수 있는 TypeScript/JavaScript 라이브러리입니다. 머신이 제어 흐름을 소유하고, 언어 모델은 머신이 검증하는 이벤트만 제안합니다.

왜 중요한가

• 모든 가능한 전이가 코드로 정의되고 가드되므로 에이전트가 잘못된 작업을 수행할 수 없음을 보장합니다.
• 라이브 API 키 없이도 에이전트를 결정적이고, 검사 가능하며, 재개 가능하고, 테스트 가능하게 만듭니다.
• 모든 JavaScript 런타임(Node, Vercel, 브라우저)에서 작동하며 Vercel AI SDK, OpenAI SDK 또는 TanStack AI와 함께 사용할 수 있습니다.

---

핵심 개념

개념	기능
머신 정의	XState를 사용하여 에이전트의 상태, 가드, 타입이 지정된 요청을 설명합니다.
모델 제안	LLM은 이벤트(예: AUTO_REFUND)를 생성하도록 요청받습니다.
가드 검증	상태 머신은 이벤트를 가드와 대조 확인합니다. 잘못된 이벤트는 거부되고 모델에 다시 요청합니다.
실행기	선택한 AI 제공자를 호출하는 일반 함수(decide, generateText 등). 호스트가 제공하며 라이브러리에 내장되지 않습니다.
환경 및 정책	비즈니스 규칙은 TypeScript 코드(environment)로 존재합니다. JSON 인코딩 정책은 모델이 편집할 수 있지만 verifyAgentConfig로 승격이 게이트됩니다.
영속성 및 내구성	XState의 스냅샷 API를 사용합니다. 스냅샷은 어디든 저장할 수 있습니다(파일, 데이터베이스, durable objects).

---

빠른 시작(환불 요청 예시)

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" }) }
  }
});

// Mock 실행기 – 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를 import하지 않습니다.
• JSON 정책 – 모델이 JSON 정책을 재작성할 수 있지만 verifyAgentConfig가 hold-out 테스트 이득을 기반으로 승격을 게이트합니다.
• 내구성 있는 스냅샷 – XState의 네이티브 스냅샷 형식으로 에이전트를 어디서나 영속화하고 복원할 수 있습니다.
• 내장 패턴 – ReAct, plan-and-execute, RAG, supervisor 등이 단일 파일 템플릿으로 제공됩니다.
• 프로바이더 없이 테스트 – MockLanguageModelV3를 사용하여 오프라인에서 에이전트를 단위 테스트할 수 있습니다.
• 관찰 가능성 및 예산 – 문서에는 로깅, 사용량 추적, 예산 강제를 위한 훅이 포함되어 있습니다.

---

일반적인 사용 사례

• 고객 서비스 봇 – 규제 제한(예: 환불 상한, 데이터 프라이버시 규칙)을 따라야 하는 경우.
• 워크플로 자동화 – 각 단계가 검증된 상태 전이인 경우(승인 흐름, 티켓 트리아지).
• 도구 호출 에이전트 – 실행 전에 도구 인수의 엄격한 검증이 필요한 경우.
• 자기 개선 에이전트 – 배포 전에 자동으로 심사되는 정책 업데이트를 제안할 수 있는 경우.
• 모든 스택에 임베딩 – 서버리스 함수부터 장기 실행 durable objects까지, 제어 흐름이 전적으로 상태 머신에 있기 때문입니다.

---

자세히 알아보기

• 문서: https://stately.ai/docs/packages/agent
• 예시: examples/ 폴더(Twenty Questions, Chameleon, Ticket triage 등)
• LangGraph 비교: docs/langgraph-comparison.md
• 패턴 라이브러리: docs/patterns.md

---

TL;DR

Stately Agent를 사용하면 LLM 기반 에이전트를 형식 상태 머신으로 작성할 수 있습니다. 모델은 이벤트를 제안할 뿐이며, 머신이 비즈니스 규칙을 강제하므로 모든 JavaScript 환경에서 안전하고, 테스트 가능하며, 이식 가능한 에이전트를 만들 수 있습니다.