@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.md +138 -0
  2. package/dist/act-B9hLQls6.mjs +19 -0
  3. package/dist/act-CrX0JwWY.cjs +42 -0
  4. package/dist/ai-sdk.cjs +63 -7
  5. package/dist/ai-sdk.d.cts +13 -3
  6. package/dist/ai-sdk.d.mts +13 -3
  7. package/dist/ai-sdk.mjs +63 -7
  8. package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
  9. package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
  10. package/dist/decision-object-B5zGSPFp.d.mts +15 -0
  11. package/dist/decision-object-DBcLWVvv.d.cts +15 -0
  12. package/dist/{run-agent-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
  13. package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
  14. package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
  15. package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
  16. package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
  17. package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
  18. package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
  19. package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
  20. package/dist/index.cjs +660 -286
  21. package/dist/index.d.cts +168 -9
  22. package/dist/index.d.mts +168 -9
  23. package/dist/index.mjs +639 -271
  24. package/dist/internal-C3Lqu538.d.cts +43 -0
  25. package/dist/internal-DUcdhk-i.d.mts +43 -0
  26. package/dist/log.cjs +2 -2
  27. package/dist/log.d.cts +1 -1
  28. package/dist/log.d.mts +1 -1
  29. package/dist/log.mjs +2 -2
  30. package/dist/machines.cjs +457 -41
  31. package/dist/machines.d.cts +114 -43
  32. package/dist/machines.d.mts +114 -43
  33. package/dist/machines.mjs +457 -42
  34. package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
  35. package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
  36. package/dist/openai.cjs +149 -36
  37. package/dist/openai.d.cts +28 -10
  38. package/dist/openai.d.mts +28 -10
  39. package/dist/openai.mjs +149 -36
  40. package/dist/otel.d.cts +1 -1
  41. package/dist/otel.d.mts +1 -1
  42. package/dist/{run-agent-BGdx5913.d.mts → run-agent-30mH2moE.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.d.mts} +91 -9
  44. package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
  45. package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BaNyz6Q3.d.cts} +4 -4
  46. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
  47. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  48. package/dist/tanstack-ai.cjs +62 -4
  49. package/dist/tanstack-ai.d.cts +18 -6
  50. package/dist/tanstack-ai.d.mts +18 -6
  51. package/dist/tanstack-ai.mjs +62 -4
  52. package/dist/testing.cjs +2493 -1502
  53. package/dist/testing.d.cts +360 -256
  54. package/dist/testing.d.mts +360 -256
  55. package/dist/testing.mjs +2489 -1503
  56. package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
  57. package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
  58. package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
  59. package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
  60. package/dist/{usage-BDiJKyv9.d.cts → usage-Bm5nvpow.d.cts} +6 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -1
  62. package/dist/utils-7lSa4H-i.d.cts +403 -0
  63. package/dist/utils-CBbKw2fM.d.mts +403 -0
  64. package/dist/validate.cjs +44 -12
  65. package/dist/validate.d.cts +6 -6
  66. package/dist/validate.d.mts +6 -6
  67. package/dist/validate.mjs +44 -12
  68. package/dist/verify-ChyX6jq0.mjs +2306 -0
  69. package/dist/verify-CwlombbC.cjs +2359 -0
  70. package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
  71. package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
  72. package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
  73. package/dist/with-model-calls-BkOwdroS.mjs +213 -0
  74. package/docs/act.md +102 -0
  75. package/docs/advanced.md +105 -0
  76. package/docs/any-stack.md +62 -0
  77. package/docs/choosing-a-run-mode.md +55 -0
  78. package/docs/debugging.md +29 -0
  79. package/docs/decisions.md +473 -0
  80. package/docs/environment-and-policy.md +188 -0
  81. package/docs/evals.md +509 -0
  82. package/docs/event-log.md +312 -0
  83. package/docs/from-a-loop.md +528 -0
  84. package/docs/generate-machines.md +110 -0
  85. package/docs/hosts.md +414 -0
  86. package/docs/human-in-the-loop.md +177 -0
  87. package/docs/index.md +48 -0
  88. package/docs/judgments.md +281 -0
  89. package/docs/langgraph-comparison.md +198 -0
  90. package/docs/machines-as-data.md +454 -0
  91. package/docs/machines-presets.md +198 -0
  92. package/docs/machines.md +497 -0
  93. package/docs/messages.md +67 -0
  94. package/docs/meta.json +52 -0
  95. package/docs/models-and-providers.md +268 -0
  96. package/docs/multi-agent.md +68 -0
  97. package/docs/observability.md +109 -0
  98. package/docs/patterns.md +31 -0
  99. package/docs/persistence.md +207 -0
  100. package/docs/quickstart.md +121 -0
  101. package/docs/roadmap.md +22 -0
  102. package/docs/scope.md +75 -0
  103. package/docs/statechart-policy-examples.md +69 -0
  104. package/docs/steps.md +56 -0
  105. package/docs/strangler-fig.md +323 -0
  106. package/docs/text-requests.md +250 -0
  107. package/docs/thinking-in-state-machines.md +324 -0
  108. package/docs/tools.md +249 -0
  109. package/docs/upgrading.md +37 -0
  110. package/docs/usage-and-budgets.md +518 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +492 -0
  113. package/docs/xstate-4-and-5-apps.md +161 -0
  114. package/llms.txt +53 -0
  115. package/package.json +10 -3
  116. package/readme.md +30 -15
  117. package/skills/add-evals/SKILL.md +3 -1
  118. package/skills/add-traces/SKILL.md +6 -1
  119. package/skills/build-machine/SKILL.md +84 -0
  120. package/skills/generate-machine/SKILL.md +1 -1
  121. package/skills/graph-engineering/SKILL.md +13 -3
  122. package/skills/improve-machine/SKILL.md +21 -2
  123. package/skills/loop-to-machine/SKILL.md +147 -192
  124. package/skills/loop-to-machine/reference.md +260 -0
  125. package/dist/utils-BnXdWih3.d.mts +0 -108
  126. package/dist/utils-ebVpCYoF.d.cts +0 -108
  127. package/dist/verify-Bpahmr34.mjs +0 -1241
  128. package/dist/verify-DCLZa9R0.cjs +0 -1288
  129. package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
  130. package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
@@ -0,0 +1,281 @@
1
+ ---
2
+ title: Judgments with the AI SDK
3
+ description: Ask classification, grading, relevance, and yes/no questions with the AI SDK's experimental_decide and Jev, and branch on the typed answers in a machine.
4
+ ---
5
+
6
+ > **Alpha:** `@statelyai/agent` 2.0 is in alpha. APIs can change between releases; pin an exact version. Feedback: [github.com/statelyai/agent](https://github.com/statelyai/agent/issues).
7
+
8
+ This page covers when a step is a judgment, calling `experimental_decide` from an actor, the question types and their answers, thresholds, TypeSafe confidence, and testing without a key.
9
+
10
+ ## Judgments and generations
11
+
12
+ A **judgment** is a step whose output is a label, a probability, or a score on a scale, computed over evidence the machine already holds. A **generation** is a step whose output is free text the machine forwards.
13
+
14
+ - Judgments go to a decision model through the AI SDK's `experimental_decide`. Jev, TypeSafe's System One model, is one such model: it answers narrow typed questions over explicit state and returns probabilities, not prose. Routing a ticket, grading a document's relevance, scoring a draft, and reading a reviewer's reply as approve or reject are judgments.
15
+ - Generations stay [text requests](text-requests.md). Drafting a reply, rewriting a query, answering from documents, and writing a plan are generations.
16
+ - Decisions the model makes by choosing a machine event stay on [`agent.decide`](decisions.md), which is unrelated to the AI SDK's `experimental_decide`. Checks that are pure code stay in code.
17
+
18
+ `@statelyai/agent` has no judgment API of its own. A judgment is an ordinary XState actor that calls the AI SDK.
19
+
20
+ ## Install
21
+
22
+ ```sh
23
+ pnpm add ai @ai-sdk/typesafe-ai
24
+ ```
25
+
26
+ `@ai-sdk/typesafe-ai` is the AI SDK's TypeSafe provider. `typeSafeAi.decisionModel("jev-latest")` reads `TYPESAFE_AI_API_KEY` from the environment when it runs, not when the model is created.
27
+
28
+ ## A judgment actor
29
+
30
+ Wrap one `experimental_decide` call in `createAsyncLogic`, register it under `setupAgent({ actors })`, and invoke it by name like any other actor. Take the decision model as a parameter so tests and hosts can pass another one.
31
+
32
+ ```ts
33
+ import { z } from "zod";
34
+ import { createAsyncLogic } from "xstate";
35
+ import { experimental_decide, type Experimental_DecisionModel } from "ai";
36
+ import { typeSafeAi } from "@ai-sdk/typesafe-ai";
37
+ import { setupAgent } from "@statelyai/agent";
38
+
39
+ const judgeModel: Experimental_DecisionModel = typeSafeAi.decisionModel("jev-latest");
40
+
41
+ /** A ticket is flagged urgent when the probability that it is blocking clears this. */
42
+ export const URGENT_THRESHOLD = 0.5;
43
+
44
+ export function createClassifyTicket(model: Experimental_DecisionModel = judgeModel) {
45
+ return createAsyncLogic<
46
+ {
47
+ answers: {
48
+ team: { choice: "billing" | "technical" | "unclear" };
49
+ urgent: { probability: number };
50
+ };
51
+ },
52
+ { ticket: string; plan: string }
53
+ >({
54
+ run: async ({ input, signal }) => {
55
+ const { answers } = await experimental_decide({
56
+ model,
57
+ state: { ticket: input.ticket, plan: input.plan },
58
+ questions: {
59
+ team: {
60
+ type: "choice",
61
+ instructions: "Which team should handle `ticket`?",
62
+ criteria: {
63
+ billing: "Charges, refunds, invoices, or plan changes.",
64
+ technical: "Errors, outages, or a feature not working as documented.",
65
+ unclear: "`ticket` does not say enough to pick a team.",
66
+ },
67
+ },
68
+ urgent: {
69
+ type: "boolean",
70
+ instructions: "Does `ticket` describe a problem blocking the customer right now?",
71
+ },
72
+ },
73
+ abortSignal: signal,
74
+ });
75
+ return { answers };
76
+ },
77
+ });
78
+ }
79
+
80
+ const agentSetup = setupAgent({
81
+ context: z.object({
82
+ ticket: z.string(),
83
+ plan: z.string(),
84
+ team: z.string().nullable(),
85
+ urgent: z.boolean(),
86
+ }),
87
+ input: z.object({ ticket: z.string(), plan: z.string() }),
88
+ output: z.object({ team: z.string().nullable(), urgent: z.boolean() }),
89
+ actors: { classifyTicket: createClassifyTicket() },
90
+ });
91
+
92
+ export const triageMachine = agentSetup.createMachine({
93
+ context: ({ input }) => ({ ticket: input.ticket, plan: input.plan, team: null, urgent: false }),
94
+ initial: "classifying",
95
+ states: {
96
+ classifying: {
97
+ invoke: {
98
+ src: "classifyTicket",
99
+ input: ({ context }) => ({ ticket: context.ticket, plan: context.plan }),
100
+ onDone: ({ output }) => {
101
+ const { team, urgent } = output.answers;
102
+ return team.choice === "unclear"
103
+ ? { target: "needsHuman" }
104
+ : {
105
+ target: "routed",
106
+ context: { team: team.choice, urgent: urgent.probability >= URGENT_THRESHOLD },
107
+ };
108
+ },
109
+ onError: { target: "needsHuman" },
110
+ },
111
+ },
112
+ routed: {
113
+ type: "final",
114
+ output: ({ context }) => ({ team: context.team, urgent: context.urgent }),
115
+ },
116
+ needsHuman: {
117
+ type: "final",
118
+ output: () => ({ team: null, urgent: false }),
119
+ },
120
+ },
121
+ });
122
+ ```
123
+
124
+ - Each invoke sends one decision request. Independent questions over the same evidence belong in the same call, which answers every question against one shared `state`.
125
+ - `experimental_decide` rejects an empty `questions` map. When the questions are built from a list that can be empty, such as one boolean question per document, return `{ answers: {} }` without calling it.
126
+ - A missing `TYPESAFE_AI_API_KEY` or a failed request rejects the invoke, which the invoke's `onError` handles.
127
+ - `signal` is the actor's abort signal. Passing it as `abortSignal` cancels the call when the run is aborted or the machine leaves the invoking state.
128
+ - The output type is yours to declare. Narrow it to the fields the machine reads.
129
+
130
+ ## Question types
131
+
132
+ <!-- question and answer shapes from ai's DecisionQuestion / DecisionAnswer (experimental_decide) -->
133
+
134
+ | `type` | `criteria` | Answer | Read in `onDone` |
135
+ | --------- | ----------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------ |
136
+ | `choice` | An object of labels to descriptions, at least one label | `{ choice, probabilities? }` | `answers.team.choice` is the selected label, typed as the union of the labels. |
137
+ | `boolean` | Optional `{ true?, false? }` descriptions | `{ probability }` | `answers.urgent.probability` is the probability of true, from 0 to 1. |
138
+ | `score` | An array of level descriptions, lowest first, at least two levels | `{ score, probabilities? }` | `answers.quality.score` is a level index; it can fall between levels. |
139
+
140
+ Every question also takes `instructions`. Instructions, criteria descriptions, and `state` accept a string or JSON.
141
+
142
+ A score's `score` is the probability-weighted mean of its levels when the model returns a distribution, so compare it with a threshold instead of testing for equality. Keep the levels in an exported tuple to render the level text from an index.
143
+
144
+ ```ts
145
+ import { createAsyncLogic } from "xstate";
146
+ import { experimental_decide, type Experimental_DecisionModel } from "ai";
147
+
148
+ export const QUALITY_LEVELS = [
149
+ "Off-topic or missing the requested content.",
150
+ "On-topic but unclear or incomplete.",
151
+ "Clear and complete with minor issues.",
152
+ "Clear, complete, and ready to send.",
153
+ ] as const;
154
+
155
+ /** Accept a draft at or above "Clear and complete with minor issues." */
156
+ export const ACCEPT_SCORE = 2;
157
+
158
+ export function createGradeDraft(model: Experimental_DecisionModel) {
159
+ return createAsyncLogic<
160
+ { answers: { quality: { score: number } } },
161
+ { brief: string; draft: string }
162
+ >({
163
+ run: async ({ input, signal }) => {
164
+ const { answers } = await experimental_decide({
165
+ model,
166
+ state: { brief: input.brief, draft: input.draft },
167
+ questions: {
168
+ quality: {
169
+ type: "score",
170
+ instructions: "How well does `draft` meet `brief`?",
171
+ criteria: QUALITY_LEVELS,
172
+ },
173
+ },
174
+ abortSignal: signal,
175
+ });
176
+ return { answers };
177
+ },
178
+ });
179
+ }
180
+
181
+ // In the invoking state:
182
+ // onDone: ({ output }) =>
183
+ // output.answers.quality.score >= ACCEPT_SCORE ? { target: "done" } : { target: "revising" },
184
+ ```
185
+
186
+ ## Question design
187
+
188
+ - **Named state fields.** Pass the evidence as an object with named fields, such as `{ ticket, plan }` or `{ question, documents }`, and refer to them in instructions by backticked path, such as `` `documents[2]` ``.
189
+ - **One narrow judgment per question.** Put the judgment in the instructions and the possible answers in the criteria, each with a concrete description. Include a no-match label, such as `unclear`, when no answer may fit. Order score levels from lowest to highest, each describing a concrete situation.
190
+ - **Thresholds as exported constants.** The model returns probabilities and scores; the machine decides. Compare them against an exported constant in `onDone` or a guard, such as `URGENT_THRESHOLD` above, so a test can drive each branch with a value on either side.
191
+
192
+ The TypeSafe docs cover question design in depth: [primitives](https://docs.typesafe.ai/primitives.md), [state](https://docs.typesafe.ai/concepts/state.md), and [confidence](https://docs.typesafe.ai/confidence.md).
193
+
194
+ ## TypeSafe confidence
195
+
196
+ Jev reports a confidence per question, separate from the answer's probabilities. The AI SDK result carries it in provider metadata at `providerMetadata.typesafe.confidence[questionId]`. Other decision models do not report it, so treat a missing value as unsure.
197
+
198
+ ```ts
199
+ import { experimental_decide } from "ai";
200
+ import { typeSafeAi } from "@ai-sdk/typesafe-ai";
201
+
202
+ /** Route only when Jev is at least this sure of the team. */
203
+ export const ROUTING_CONFIDENCE = 0.6;
204
+
205
+ const { answers, providerMetadata } = await experimental_decide({
206
+ model: typeSafeAi.decisionModel("jev-latest"),
207
+ state: { ticket: "I was charged twice this month." },
208
+ questions: {
209
+ team: {
210
+ type: "choice",
211
+ instructions: "Which team should handle `ticket`?",
212
+ criteria: { billing: "Charges and refunds.", technical: "Errors and outages." },
213
+ },
214
+ },
215
+ });
216
+
217
+ const reported = (providerMetadata?.typesafe?.confidence as Record<string, unknown> | undefined)
218
+ ?.team;
219
+ const confidence = typeof reported === "number" ? reported : 0;
220
+ const route = confidence >= ROUTING_CONFIDENCE ? answers.team.choice : "needsHuman";
221
+ ```
222
+
223
+ Return the confidence from the actor next to `answers`, such as `{ answers, confidence }`, and compare it against the exported constant in `onDone` or a guard.
224
+
225
+ ## Judgments and budgets
226
+
227
+ A judgment actor calls the AI SDK itself, so the runtime never sees the call.
228
+
229
+ - Its calls are not in `result.usage` and do not count against `maxModelCalls`.
230
+ - No `@agent.usage` event is delivered for it.
231
+ - To cap judgments, count them in `context`: increment a counter in the invoke's `onDone` and guard the transition that starts the next one. See [Budgets as guards](usage-and-budgets.md#budgets-as-guards).
232
+
233
+ ## Testing without a key
234
+
235
+ A decision model is any object that implements the AI SDK's decision-model spec: `specificationVersion: "v4"`, `provider`, `modelId`, `supportedQuestionTypes`, and `doDecide`. An object that answers from a script runs `experimental_decide`'s own validation and result shaping, with no key and no network. Pass it to the actor factory and bind the actor through `createAgentRuntime(machine, { actors })` to replace the registered default.
236
+
237
+ ```ts
238
+ import type { Experimental_DecisionModel } from "ai";
239
+ import { runToQuiescence } from "@statelyai/agent";
240
+ import { expect, test } from "vitest";
241
+
242
+ const scripted: Experimental_DecisionModel = {
243
+ specificationVersion: "v4",
244
+ provider: "test",
245
+ modelId: "scripted-judge",
246
+ supportedQuestionTypes: ["choice", "boolean", "score"],
247
+ doDecide: async () => ({
248
+ answers: {
249
+ team: { type: "choice", choice: "billing" },
250
+ urgent: { type: "boolean", probability: 0.2 },
251
+ },
252
+ warnings: [],
253
+ }),
254
+ };
255
+
256
+ test("routes a double charge to billing", async () => {
257
+ const result = await runToQuiescence(
258
+ createAgentRuntime(triageMachine, {
259
+ actors: { classifyTicket: createClassifyTicket(scripted) },
260
+ }),
261
+ { input: { ticket: "I was charged twice this month.", plan: "pro" } },
262
+ );
263
+
264
+ expect(result.status === "done" && result.output).toEqual({ team: "billing", urgent: false });
265
+ });
266
+ ```
267
+
268
+ - `doDecide` receives `{ state, questions }`. The AI SDK wraps a plain `state` in one part, `[{ type: "json", value }]`, so read the machine's evidence from `state[0].value`. Record both to assert on the evidence and the questions the machine sent.
269
+ - To script TypeSafe confidence, return `providerMetadata: { typesafe: { confidence: { team: 0.9 } } }` from `doDecide`.
270
+ - The AI SDK validates answers: a `choice` must be one of the labels and the most probable one, `probabilities` must sum to 1, and a score with `probabilities` must equal their weighted mean. Omit `probabilities` from scripted answers unless a test needs them.
271
+ - The repository's examples share one scripted judge that keys answers by question id; see [examples/mock-judge.ts](https://github.com/statelyai/agent/blob/next/examples/mock-judge.ts).
272
+
273
+ ## Example
274
+
275
+ [examples/corrective-rag](https://github.com/statelyai/agent/blob/next/examples/corrective-rag/index.ts) grades retrieved documents with one boolean question per document in a single `experimental_decide` call, keeps the ones whose probability clears `RELEVANCE_THRESHOLD`, and routes to a query rewrite when none survive. The rewrite and the answer stay text requests.
276
+
277
+ ## Related
278
+
279
+ - [Text requests](text-requests.md)
280
+ - [Decisions](decisions.md)
281
+ - [Coming from LangGraph](langgraph-comparison.md)
@@ -0,0 +1,198 @@
1
+ ---
2
+ title: Coming from LangGraph
3
+ description: A construct-by-construct map from a LangGraph StateGraph to an agent machine, with one worked node.
4
+ ---
5
+
6
+ > **Alpha:** `@statelyai/agent` 2.0 is in alpha. APIs can change between releases; pin an exact version. Feedback: [github.com/statelyai/agent](https://github.com/statelyai/agent/issues).
7
+
8
+ Both libraries represent agent control flow explicitly. Stately Agent uses XState directly instead of introducing a second graph runtime.
9
+
10
+ ## Construct map
11
+
12
+ | LangGraph concept | Stately Agent / XState |
13
+ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
14
+ | `StateGraph` | XState machine |
15
+ | Node | State, invoked actor, or action |
16
+ | Tool/model node | Named Agent request actor |
17
+ | Grader / classifier node | An actor calling the AI SDK's `experimental_decide` with Jev via `@ai-sdk/typesafe-ai` ([judgments](judgments.md)) |
18
+ | Plain (non-model) node | An ordinary XState actor, usually `createAsyncLogic({ schemas, run })` |
19
+ | `START` / `END` | `initial` on the machine; a `type: 'final'` state whose `output` is the run's typed result |
20
+ | Conditional edge, a pure function of state | A [`type: 'choice'` state](machines.md#choice-states) |
21
+ | Conditional edge, a response to an event | A guarded [transition](machines.md#transitions); when the model picks the branch, `agent.decide` with `allowedEvents` |
22
+ | `Annotation` reducer | No reducers. A transition returns a partial `context` patch, so the merge is written where the change happens |
23
+ | `withStructuredOutput(schema)` | `schemas: { output }` on the request; the parsed value arrives as `output.result` in the invoke's `onDone` |
24
+ | Interrupt | A resting state that settles `runToQuiescence` as idle. See [Human in the loop](human-in-the-loop.md) |
25
+ | `new Command({ resume })` | A typed machine event: `runToQuiescence(createAgentRuntime(machine, {}), { snapshot, event })`, or `{ events, event }` from the log |
26
+ | Checkpointer | A persisted XState snapshot the host stores. See [Persistence](persistence.md) |
27
+ | `config.configurable.thread_id` | `runToQuiescence(createAgentRuntime(machine, { store, threadId }), {})`, which reads and appends the thread's [event log](event-log.md) |
28
+ | Stream events | `onTrace` (`stream.chunk`) plus XState inspection |
29
+ | Subgraph | Invoked child machine |
30
+
31
+ Stately Agent does not ship a checkpointer or event-log backend. `store` is an interface; the built-in implementation is in-memory, and a host implements it over its own database. Use the storage, retry, and interruption semantics of the framework hosting XState.
32
+
33
+ ## One node, before and after
34
+
35
+ A grading node routes to `generate` or `rewriteQuery`, and counts rewrites. In LangGraph the routing is a function that returns a node name, and the count is an `Annotation` reducer.
36
+
37
+ ```ts no-check
38
+ const GraphState = Annotation.Root({
39
+ grade: Annotation<"relevant" | "irrelevant" | null>({
40
+ reducer: (_l, r) => r,
41
+ default: () => null,
42
+ }),
43
+ attempts: Annotation<number>({ reducer: (l, r) => l + r, default: () => 0 }),
44
+ });
45
+
46
+ async function grade(state: typeof GraphState.State) {
47
+ const grader = model.withStructuredOutput(gradeSchema, { name: "grade" });
48
+ const result = await grader.invoke([{ role: "user", content: state.question }]);
49
+ return { grade: result.grade };
50
+ }
51
+
52
+ function routeAfterGrade(state: typeof GraphState.State) {
53
+ if (state.grade === "relevant" || state.attempts >= 2) return "generate";
54
+ return "rewriteQuery";
55
+ }
56
+
57
+ const workflow = new StateGraph(GraphState)
58
+ .addNode("grade", grade)
59
+ .addConditionalEdges("grade", routeAfterGrade, {
60
+ generate: "generate",
61
+ rewriteQuery: "rewriteQuery",
62
+ })
63
+ .addEdge("rewriteQuery", "retrieve");
64
+ ```
65
+
66
+ The machine names the same three things: the model call is a request, the routing is a state, and the counter is a patch on the transition that causes it.
67
+
68
+ ```ts
69
+ import { z } from "zod";
70
+ import { setupAgent } from "@statelyai/agent";
71
+
72
+ const gradeSchema = z.object({ grade: z.enum(["relevant", "irrelevant"]), reason: z.string() });
73
+
74
+ const agentSetup = setupAgent({
75
+ models,
76
+ context: z.object({
77
+ question: z.string(),
78
+ docs: z.array(z.string()),
79
+ grade: z.enum(["relevant", "irrelevant"]).nullable(),
80
+ attempts: z.number(),
81
+ }),
82
+ input: z.object({ question: z.string() }),
83
+ output: z.object({ answer: z.string().nullable() }),
84
+ requests: {
85
+ gradeDocs: {
86
+ model: "quick",
87
+ schemas: {
88
+ input: z.object({ question: z.string(), docs: z.array(z.string()) }),
89
+ output: gradeSchema, // withStructuredOutput
90
+ },
91
+ system: "Grade whether the documents answer the question.",
92
+ prompt: ({ input }) => `Q: ${input.question}\n\n${input.docs.join("\n---\n")}`,
93
+ },
94
+ rewriteQuery: {
95
+ model: "quick",
96
+ schemas: { input: z.object({ question: z.string() }), output: z.string() },
97
+ system: "Rewrite the question to retrieve better documents.",
98
+ prompt: ({ input }) => input.question,
99
+ },
100
+ },
101
+ });
102
+
103
+ const machine = agentSetup.createMachine({
104
+ context: ({ input }) => ({ question: input.question, docs: [], grade: null, attempts: 0 }),
105
+ initial: "grading", // START
106
+ states: {
107
+ grading: {
108
+ invoke: {
109
+ src: "gradeDocs",
110
+ input: ({ context }) => ({ question: context.question, docs: context.docs }),
111
+ onDone: ({ output }) => ({ target: "routing", context: { grade: output.result.grade } }),
112
+ },
113
+ },
114
+ // addConditionalEdges: a routing branch with no event and no side effect.
115
+ routing: {
116
+ type: "choice",
117
+ choice: ({ context }) =>
118
+ context.grade === "relevant" || context.attempts >= 2
119
+ ? { target: "generating" }
120
+ : { target: "rewriting" },
121
+ },
122
+ rewriting: {
123
+ invoke: {
124
+ src: "rewriteQuery",
125
+ input: ({ context }) => ({ question: context.question }),
126
+ // The `attempts` reducer, written on the transition that increments it.
127
+ onDone: ({ context, output }) => ({
128
+ target: "retrieving",
129
+ context: { question: output.result, attempts: context.attempts + 1 },
130
+ }),
131
+ },
132
+ },
133
+ // ...
134
+ },
135
+ });
136
+ ```
137
+
138
+ The differences worth planning for:
139
+
140
+ - **Merges are explicit.** LangGraph merges every node's return value through the channel's reducer. A machine transition returns the fields it changes, and omitted fields keep their values. There is nowhere for a reducer to live, so a running total is written as `attempts: context.attempts + 1` on the transition.
141
+ - **Routing is a state or a transition, not a return value.** A pure function of state is a `choice` state. A branch taken in response to something arriving is a guarded transition on an event. A branch the model picks is `agent.decide` with `allowedEvents`, and the machine rejects a choice the current state does not accept.
142
+ - **Resume is typed.** `Command({ resume })` carries an opaque value back into the interrupted node. Resuming a machine sends one of its declared events, and `parseAgentEvent` checks the payload at the boundary before anything runs. An event the state does not handle is ignored, the way a state machine always ignores one. See [Human in the loop](human-in-the-loop.md).
143
+
144
+ ## Worked examples
145
+
146
+ - [corrective-rag](https://github.com/statelyai/agent/blob/next/examples/corrective-rag/index.ts) ports LangGraph's canonical corrective-RAG graph. Its header maps every node and edge, and it folds the conditional edge into the grader's own `onDone` instead of a separate `choice` state.
147
+ - [Ported LangGraph examples](#ported-langgraph-examples) below lists every LangGraph tutorial, template, and community example ported to `examples/`. Each file's header comment maps the graph's nodes and edges to machine states.
148
+ - [Human in the loop](human-in-the-loop.md) covers `interrupt` and `Command({ resume })`: `meta.interaction`, idle settling, `eventFromInteraction`, and resuming from a snapshot.
149
+ - [Persistence](persistence.md) covers the checkpointer and `thread_id`: the event log, `store`, `threadId`, and host-owned `persist()`.
150
+ - [Migrating from a hand-rolled loop](from-a-loop.md) covers the same conversion from a `while` loop.
151
+
152
+ A machine can run with `runToQuiescence`, an application-owned XState actor, a pure `initialTransition` / `transition` loop, or XState's durable runtime. The artifact does not change. See [Choosing a run mode](choosing-a-run-mode.md).
153
+
154
+ ## Ported LangGraph examples
155
+
156
+ Every example below runs in the demo and has a test that scripts the model by request name. Classification, grading, relevance, and yes/no steps are [judgments](judgments.md) made with the AI SDK's `experimental_decide` and Jev via `@ai-sdk/typesafe-ai`, not text requests; live services (web search, vector stores, sandboxes) are replaced by small in-file sample data, labelled as such in the code. The right column names the construct the machine makes structural where the LangGraph version leaves it to a prompt or to `recursion_limit`.
157
+
158
+ | LangGraph source | Example | What the machine makes structural |
159
+ | ------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
160
+ | Corrective RAG (CRAG) | [corrective-rag](https://github.com/statelyai/agent/blob/next/examples/corrective-rag/index.ts) | the grade-then-branch choice, one acyclic correction pass |
161
+ | Adaptive RAG, Self-RAG | [adaptive-rag](https://github.com/statelyai/agent/blob/next/examples/adaptive-rag/index.ts) | route choice, then `MAX_REWRITES` and `MAX_REGENERATIONS` guards on both loops |
162
+ | Agentic RAG | [agentic-rag](https://github.com/statelyai/agent/blob/next/examples/agentic-rag/index.ts) | `agent.decide` over `RETRIEVE`/`ANSWER`, `RETRIEVE` rejected past the budget |
163
+ | Code assistant (AlphaCodium) | [code-assistant](https://github.com/statelyai/agent/blob/next/examples/code-assistant/index.ts) | a retry budget around code that really runs |
164
+ | Plan-and-execute, ReWOO | [plan-and-execute](https://github.com/statelyai/agent/blob/next/examples/plan-and-execute/index.ts) | a step budget that ends in `failed` |
165
+ | LLMCompiler | [llm-compiler](https://github.com/statelyai/agent/blob/next/examples/llm-compiler/index.ts) | plan validated by a choice state; ready tasks spawned per wave |
166
+ | Reflection | [reflection-writer](https://github.com/statelyai/agent/blob/next/examples/reflection-writer/index.ts) | a revision budget in context |
167
+ | Reflexion | [reflexion](https://github.com/statelyai/agent/blob/next/examples/reflexion/index.ts) | search-grounded critique, citations checked against retrieved passages |
168
+ | Tree of Thoughts (Game of 24) | [tree-of-thoughts](https://github.com/statelyai/agent/blob/next/examples/tree-of-thoughts/index.ts) | a hand-written scorer rejects illegal steps; `BEAM_SIZE` and `MAX_DEPTH` |
169
+ | Self-Discover | [self-discover](https://github.com/statelyai/agent/blob/next/examples/self-discover/index.ts) | a choice state bounds the selected module count, with one retry |
170
+ | Multi-agent supervisor | [agent-supervisor](https://github.com/statelyai/agent/blob/next/examples/agent-supervisor/index.ts) | routing through `agent.decide` under per-worker and turn guards |
171
+ | Hierarchical agent teams | [hierarchical-teams](https://github.com/statelyai/agent/blob/next/examples/hierarchical-teams/index.ts) | child machines with their own budgets |
172
+ | Swarm, multi-agent network | [swarm-handoff](https://github.com/statelyai/agent/blob/next/examples/swarm-handoff/index.ts) | `HANDOFF` under a guard; the active agent survives a snapshot |
173
+ | Map-reduce (`Send`), orchestrator-worker | [map-reduce](https://github.com/statelyai/agent/blob/next/examples/map-reduce/index.ts) | a spawned child per subject, reduced as they land, capped width |
174
+ | Prompt chaining | [prompt-chaining](https://github.com/statelyai/agent/blob/next/examples/prompt-chaining/index.ts) | the gate is a choice state over a pure check, with a bounded retry |
175
+ | Parallelization | [parallel-streams](https://github.com/statelyai/agent/blob/next/examples/parallel-streams/index.ts) | two regions streaming at once |
176
+ | Routing | [triage](https://github.com/statelyai/agent/blob/next/examples/triage/index.ts) | structured classification with one retry |
177
+ | Evaluator-optimizer | [ai-sdk-evaluator-optimizer](https://github.com/statelyai/agent/blob/next/examples/ai-sdk-evaluator-optimizer/index.ts) | explicit states with a strict critic gating the exit |
178
+ | Open Deep Research, local deep researcher | [deep-research](https://github.com/statelyai/agent/blob/next/examples/deep-research/index.ts) | a researcher spawned per query, results reduced as they land |
179
+ | STORM | [storm-writer](https://github.com/statelyai/agent/blob/next/examples/storm-writer/index.ts) | an interview child per editor with a turn cap |
180
+ | TNT-LLM | [tnt-llm](https://github.com/statelyai/agent/blob/next/examples/tnt-llm/index.ts) | per-document summary children, then a batch index drives the taxonomy loop |
181
+ | Data enrichment, company researcher | [data-enrichment](https://github.com/statelyai/agent/blob/next/examples/data-enrichment/index.ts) | a choice state decides completeness; one `MAX_LOOPS` budget |
182
+ | Information gathering (prompt generation) | [info-gathering](https://github.com/statelyai/agent/blob/next/examples/info-gathering/index.ts) | a choice state checks the requirement slots; `MAX_TURNS` idle turns |
183
+ | Memory agent, semantic-search memory | [long-term-memory](https://github.com/statelyai/agent/blob/next/examples/long-term-memory/index.ts) | the store is machine input and output; recall and a capped save are states |
184
+ | Wait for user input, breakpoints | [human-in-the-loop](https://github.com/statelyai/agent/blob/next/examples/human-in-the-loop/index.ts) | an idle review state with a bounded redraft loop |
185
+ | Review tool calls | [review-tool-calls](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls/index.ts) | each proposed call gated behind `APPROVE`/`EDIT`/`REJECT` |
186
+ | Customer support (airline) | [customer-support](https://github.com/statelyai/agent/blob/next/examples/customer-support/index.ts) | sensitive actions routed into the approval gate |
187
+ | SQL agent | [sql-agent](https://github.com/statelyai/agent/blob/next/examples/sql-agent/index.ts) | approval before the engine runs the query |
188
+ | Summarize conversation history | [context-compaction](https://github.com/statelyai/agent/blob/next/examples/context-compaction/index.ts) | an explicit `compacting` state |
189
+ | Chatbot simulation evaluation | [chatbot-simulation-eval](https://github.com/statelyai/agent/blob/next/examples/chatbot-simulation-eval/index.ts) | alternating turns under a `MAX_EXCHANGES` guard; the judge inside the machine |
190
+ | Handle tool-calling errors (model fallback) | [model-fallback](https://github.com/statelyai/agent/blob/next/examples/model-fallback/index.ts) | a validator actor and a choice state escalate to a stronger model once |
191
+ | Many tools (bigtool) | [tool-retrieval](https://github.com/statelyai/agent/blob/next/examples/tool-retrieval/index.ts) | a guard allows only the selected tools; call and reselection budgets |
192
+ | Extraction with retries | [generate-and-repair](https://github.com/statelyai/agent/blob/next/examples/generate-and-repair/index.ts) | a repair round the machine caps |
193
+ | Multi-agent debate (community) | [multi-agent-debate](https://github.com/statelyai/agent/blob/next/examples/multi-agent-debate/index.ts) | turn order and round count as edges; `MAX_ROUNDS` in the input schema |
194
+ | Essay grading system (community) | [essay-grader](https://github.com/statelyai/agent/blob/next/examples/essay-grader/index.ts) | choice states over exported thresholds stop at the first weak pass |
195
+ | Feynman-technique tutor (community) | [feynman-tutor](https://github.com/statelyai/agent/blob/next/examples/feynman-tutor/index.ts) | an idle explain-back state per checkpoint; a re-teach budget |
196
+ | Project manager assistant (community) | [project-planner](https://github.com/statelyai/agent/blob/next/examples/project-planner/index.ts) | the machine validates the graph and computes the critical path; a replan budget |
197
+
198
+ Not ported: examples that need a live browser or code sandbox (Web Voyager, USACO, CodeAct, Open SWE), and LATS, whose bounded tree search [tree-of-thoughts](https://github.com/statelyai/agent/blob/next/examples/tree-of-thoughts/index.ts) already shows.