statelyai/agent

Create state-machine-powered LLM agents using XState

What it solves

它解決了 AI agent 的不可預測性，透過提供一個將 agent 的控制流與模型的決策過程分離的邏輯層。與其讓模型擁有完全的控制權，這個工具允許開發者定義 agent 必須遵循的明確規則、邊界與有效的轉換。

How it works

它將模型請求與決策整合進 XState，將 agent 視為一個狀態機。狀態機定義了允許的動作（events）與規則（guards）。當 agent 需要做出選擇時，它會使用 agent.decide 要求模型從目前允許的 events 中挑選一個。接著，狀態機將驗證該選擇是否被允許；如果一個 guard 拒絕了模型的提案，該決策將會重試。這種架構允許 agent 被暫停，其狀態（snapshot）可以被儲存，之後再重新啟動。

Who it’s for

對於需要對工作流進行嚴格控制、需要能夠在不呼叫 API 的情況下視覺化與測試 agent 邏輯，以及需要支援 "human-in-the-loop" 互動的 AI agent 開發者而言。

Highlights

  • Explicit Control Flow: 使用狀態機來定義 agent 可以做與不能做的事情。
  • Bounded Decisions: 模型只能針對目前狀態提出有效的 events。
  • State Persistence: 能夠儲存 XState snapshots 以停止並在不同程序中重新啟動 agent。
  • Provider Agnostic: 雖然它提供了 Vercel AI SDK 的 adapter，但核心邏輯並不依賴於特定的模型提供者。
  • Verifiable Logic: 狀態機可以進行 linting、模擬與探索，而不需要 API key。