@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,324 @@
1
+ ---
2
+ title: Thinking in state machines
3
+ description: A design tutorial. Take one hand-rolled agent loop, name the states hiding inside it, and turn them into a machine you can test, resume, and inspect.
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 shows how to find the states hidden in an agent loop, name them, and write them down as a machine. A typical loop already contains a state machine, spread across a `while` loop, a few booleans, and an `if` ladder.
9
+
10
+ The example is a support triage agent. It classifies a ticket, drafts a reply, has the reply reviewed, and sometimes hands off to a human.
11
+
12
+ For the mechanical refactor of an existing codebase, see [Migrating from a hand-rolled loop](from-a-loop.md). This page covers the design work that comes first.
13
+
14
+ <!-- xstate version requirement from package.json#peerDependencies -->
15
+
16
+ > **Version requirement.** Build the machine with the exact `xstate` version this package peers on, `6.0.0-beta.0`. See the [Quickstart](quickstart.md). Machines authored for XState v5 usually port with few changes, but a machine object imported from a separate `xstate@5` install does not bind. Write event-transition guards as functions that return `undefined`. XState v6 drops named string guards on `on`, and the function form is what makes `snapshot.can(event)` reflect the guard.
17
+
18
+ ## The loop to model
19
+
20
+ The following loop is a working version of the agent.
21
+
22
+ ```ts no-check
23
+ async function triage(ticket: string) {
24
+ let category: string | null = null;
25
+ let draft: string | null = null;
26
+ let revisions = 0;
27
+ let escalated = false;
28
+
29
+ while (true) {
30
+ if (!category) {
31
+ category = await classify(ticket);
32
+ if (category === "unknown") escalated = true;
33
+ } else if (escalated) {
34
+ const reply = await waitForHumanReply(ticket, draft); // can block for days
35
+ return reply;
36
+ } else if (!draft) {
37
+ draft = await writeReply(ticket, category);
38
+ } else {
39
+ const verdict = await review(draft); // "send" | "revise" | "escalate"
40
+ if (verdict === "send") return draft;
41
+ if (verdict === "escalate") escalated = true;
42
+ if (verdict === "revise") {
43
+ if (revisions >= 2) return draft; // stop revising
44
+ revisions++;
45
+ draft = null;
46
+ }
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ The loop is correct, but four things are hard to do with it:
53
+
54
+ - Testing requires mocking `classify`, `writeReply`, and `review`, and assuming the branch order is right.
55
+ - Resuming is not possible. `waitForHumanReply` holds the process open, and the four local variables are not written down anywhere.
56
+ - Observing the run requires a `console.log` at every branch, because the loop never names where it is.
57
+ - Bounding the work depends on one `revisions >= 2` check that a later edit can bypass.
58
+
59
+ ## The implicit states
60
+
61
+ Read the loop again and ask what the agent is in the middle of at any instant. The answers are the states. They are already in the source, under other names.
62
+
63
+ | In the loop | The state it is really in |
64
+ | ------------------------------------ | ------------------------- |
65
+ | `!category` | `classifying` |
66
+ | `category` set, deciding what's next | `routing` |
67
+ | `!draft` | `drafting` |
68
+ | draft exists, verdict pending | `reviewing` |
69
+ | `escalated`, blocked in `await` | `awaitingHuman` |
70
+ | `return draft` | `sent` (final) |
71
+
72
+ <!-- viz: support triage machine: classifying -> routing (choice) -> drafting -> reviewing -> sending/awaitingHuman, with the REVISE loop back to drafting capped by revisions < 2 -->
73
+
74
+ Look for the following patterns in any loop:
75
+
76
+ - A nullable local variable such as `draft` marks a state boundary. Before the value exists and after it exists are different states.
77
+ - A boolean flag such as `escalated` is a state named as an adjective.
78
+ - A string verdict such as `"send" | "revise" | "escalate"` is an event set.
79
+ - A counter compared to a constant such as `revisions >= 2` is a guard.
80
+ - A blocking `await` on a person is a wait, not work.
81
+
82
+ Two states can run the same code and still be different states. `drafting` after classification and `drafting` after a revision run the same code, but only the second increments a counter. The loop needs a flag to tell them apart. The machine tells them apart by which transition arrived.
83
+
84
+ ## States as prompts
85
+
86
+ Each state that calls the model owns one prompt. The model does one of two things: it produces a value, or it chooses an event. `classify` and `writeReply` produce values, so they become text logic, and the prompt sits next to the state that uses it.
87
+
88
+ ```ts no-check
89
+ const classifyTicket = createTextLogic({
90
+ schemas: { input: z.object({ ticket: z.string() }), output: z.string() },
91
+ model: "triage",
92
+ system: "Classify the ticket as billing, technical, or unknown. Output one word.",
93
+ prompt: ({ input }) => input.ticket,
94
+ });
95
+ ```
96
+
97
+ The `classifying` state invokes this logic. Its `onDone` sets where the value lands and which state comes next. Keep one prompt per state. A prompt that describes three jobs at once can do the wrong one.
98
+
99
+ ## Transitions as legal moves
100
+
101
+ In the loop, `review` returned a string and the loop branched on it. In the machine, the model chooses an event from a list the machine supplies, and the transition is the branch.
102
+
103
+ ```ts no-check
104
+ reviewing: {
105
+ invoke: {
106
+ src: 'agent.decide',
107
+ input: ({ context }) => ({
108
+ model: 'reviewer',
109
+ system: 'Review the drafted reply. SEND it, ask to REVISE, or ESCALATE to a human.',
110
+ prompt: `Ticket:\n${context.ticket}\n\nDraft:\n${context.draft}`,
111
+ allowedEvents: ['SEND', 'REVISE', 'ESCALATE'],
112
+ }),
113
+ },
114
+ on: {
115
+ SEND: { target: 'sending' },
116
+ ESCALATE: { target: 'awaitingHuman' },
117
+ REVISE: { target: 'drafting' },
118
+ },
119
+ },
120
+ ```
121
+
122
+ A returned string can hold any value, and every caller has to validate it. A chosen event is checked against the snapshot before it takes effect, so an event the state does not accept never happens. See [Decisions](decisions.md).
123
+
124
+ ## Guards as policy
125
+
126
+ `revisions >= 2` was a rule inside a branch. As a guard, it becomes part of the graph, and it applies to the model rather than being described to it.
127
+
128
+ Write event transitions as functions that return `undefined` when the move is illegal.
129
+
130
+ ```ts no-check
131
+ // Wrong: the cap lives in the prompt.
132
+ system: 'Ask to REVISE at most twice.',
133
+
134
+ // Right: the cap is a transition.
135
+ REVISE: ({ context, event }) =>
136
+ context.revisions < 2
137
+ ? { target: 'drafting', context: { note: event.note, revisions: context.revisions + 1 } }
138
+ : undefined,
139
+ ```
140
+
141
+ Returning `undefined` has an effect on the decision. The decision core checks each candidate with `snapshot.can(event)`, records the refusal as `rejected-by-guard`, and asks the model again with the remaining legal moves.
142
+
143
+ ## Idle states as waits
144
+
145
+ `await waitForHumanReply(...)` holds a process open for work that may take days. If the process dies, everything before that line is lost.
146
+
147
+ A wait is a state with no invoke and an `on` handler.
148
+
149
+ ```ts no-check
150
+ awaitingHuman: {
151
+ on: {
152
+ HUMAN_REPLY: ({ event }) => ({ target: 'sending', context: { draft: event.reply } }),
153
+ },
154
+ },
155
+ ```
156
+
157
+ When no work is in flight, `runToQuiescence` settles with `{ status: 'idle', snapshot }` instead of hanging. Persist the snapshot and show the person their options. [`getAcceptedEvents(snapshot)`](human-in-the-loop.md) lists the legal events. To resume later, in the same process or another one, pass the snapshot back with the event. See [Human in the loop](human-in-the-loop.md).
158
+
159
+ ## The finished machine
160
+
161
+ The machine below makes the same four model calls and applies the same policy as the loop, without the flags. The `routing` state uses `type: "choice"`, which resolves its branch immediately, without an event or a model call. See [Choice states](machines.md#choice-states).
162
+
163
+ ```ts
164
+ import { z } from "zod";
165
+ import { openai } from "@ai-sdk/openai";
166
+ import { createTextLogic, runToQuiescence, setupAgent } from "@statelyai/agent";
167
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
168
+
169
+ // Model IDs here are illustrative; substitute your provider's current models.
170
+ const models = {
171
+ triage: openai("gpt-6-luna"),
172
+ reviewer: openai("gpt-6-luna"),
173
+ };
174
+
175
+ const classifyTicket = createTextLogic({
176
+ schemas: { input: z.object({ ticket: z.string() }), output: z.string() },
177
+ model: "triage",
178
+ system: "Classify the ticket as billing, technical, or unknown. Output one word.",
179
+ prompt: ({ input }) => input.ticket,
180
+ });
181
+
182
+ const writeReply = createTextLogic({
183
+ schemas: {
184
+ input: z.object({ ticket: z.string(), category: z.string(), note: z.string() }),
185
+ output: z.string(),
186
+ },
187
+ model: "triage",
188
+ system: "You write support replies. Output only the reply.",
189
+ prompt: ({ input }) =>
190
+ `Ticket (${input.category}):\n${input.ticket}\n\nReviewer note:\n${input.note}`,
191
+ });
192
+
193
+ const agentSetup = setupAgent({
194
+ models,
195
+ context: z.object({
196
+ ticket: z.string(),
197
+ category: z.string().nullable(),
198
+ draft: z.string().nullable(),
199
+ note: z.string(),
200
+ revisions: z.number(),
201
+ via: z.enum(["model", "human"]),
202
+ }),
203
+ events: {
204
+ SEND: {},
205
+ REVISE: z.object({ note: z.string() }),
206
+ ESCALATE: z.object({ reason: z.string() }),
207
+ HUMAN_REPLY: z.object({ reply: z.string() }),
208
+ },
209
+ input: z.object({ ticket: z.string() }),
210
+ output: z.object({ reply: z.string(), via: z.enum(["model", "human"]) }),
211
+ actors: { classifyTicket, writeReply },
212
+ });
213
+
214
+ const triageMachine = agentSetup.createMachine({
215
+ id: "triage",
216
+ context: ({ input }) => ({
217
+ ticket: input.ticket,
218
+ category: null,
219
+ draft: null,
220
+ note: "",
221
+ revisions: 0,
222
+ via: "model" as const,
223
+ }),
224
+ output: ({ context }) => ({ reply: context.draft ?? "", via: context.via }),
225
+ initial: "classifying",
226
+ states: {
227
+ classifying: {
228
+ invoke: {
229
+ src: "classifyTicket",
230
+ input: ({ context }) => ({ ticket: context.ticket }),
231
+ onDone: ({ output }) => ({ target: "routing", context: { category: output.result } }),
232
+ },
233
+ },
234
+ // `type: 'choice'` is a library pseudo-state, not native XState.
235
+ routing: {
236
+ type: "choice",
237
+ choice: ({ context }) =>
238
+ context.category === "unknown" ? { target: "awaitingHuman" } : { target: "drafting" },
239
+ },
240
+ drafting: {
241
+ invoke: {
242
+ src: "writeReply",
243
+ input: ({ context }) => ({
244
+ ticket: context.ticket,
245
+ category: context.category ?? "unknown",
246
+ note: context.note,
247
+ }),
248
+ onDone: ({ output }) => ({ target: "reviewing", context: { draft: output.result } }),
249
+ },
250
+ },
251
+ reviewing: {
252
+ invoke: {
253
+ src: "agent.decide",
254
+ input: ({ context }) => ({
255
+ model: "reviewer",
256
+ system: "Review the drafted reply. SEND it, ask to REVISE, or ESCALATE to a human.",
257
+ prompt: `Ticket:\n${context.ticket}\n\nDraft:\n${context.draft}`,
258
+ allowedEvents: ["SEND", "REVISE", "ESCALATE"],
259
+ }),
260
+ onError: { target: "awaitingHuman" }, // reached after retries are exhausted
261
+ },
262
+ on: {
263
+ SEND: { target: "sending" },
264
+ ESCALATE: { target: "awaitingHuman" },
265
+ REVISE: ({ context, event }) =>
266
+ context.revisions < 2
267
+ ? {
268
+ target: "drafting",
269
+ context: { note: event.note, revisions: context.revisions + 1 },
270
+ }
271
+ : undefined,
272
+ },
273
+ },
274
+ // No invoke. The run settles as idle here, and you persist the snapshot.
275
+ awaitingHuman: {
276
+ on: {
277
+ HUMAN_REPLY: ({ event }) => ({
278
+ target: "sending",
279
+ context: { draft: event.reply, via: "human" as const },
280
+ }),
281
+ },
282
+ },
283
+ sending: { type: "final" },
284
+ },
285
+ });
286
+
287
+ const result = await runToQuiescence(
288
+ createAgentRuntime(triageMachine, { executors: createAiSdkExecutors({ models }) }),
289
+ { input: { ticket: "I was charged twice for March." } },
290
+ );
291
+ if (result.status === "done") console.log(result.output.reply);
292
+ if (result.status === "idle") console.log("waiting on a human", result.snapshot);
293
+ ```
294
+
295
+ Every local variable from the loop is now either context or a state name. The loop's `escalated` flag becomes `output.via`, which records whether the model or a human produced the reply.
296
+
297
+ The revision cap behaves differently from the loop. The loop returned the current draft once `revisions >= 2`. The machine's guard returns `undefined`, so the third `REVISE` is rejected and the reviewer must choose `SEND` or `ESCALATE` instead. To reproduce the loop's behavior, target `sending` from the rejected branch instead of returning `undefined`.
298
+
299
+ For what the machine gives you over the loop, see the [overview](index.md).
300
+
301
+ ## Context must be replay-stable
302
+
303
+ Context is replayed. A persisted snapshot resumes by re-applying the [event log](event-log.md), so anything the machine writes into context has to produce the same value on the second pass as on the first.
304
+
305
+ - No `Date.now()`, `new Date()`, `performance.now()`, `Math.random()`, or `crypto.randomUUID()` in context, entry actions, or transition results.
306
+ - Measure elapsed time, generate ids, and read the clock in the host, then pass the value in as event or input data. It is then recorded in the log and replays identically.
307
+ - The same rule covers derived, rendered strings. Compute them in a final state's `output` or in the host, not as a context field kept in sync by hand.
308
+
309
+ A machine that breaks this rule still runs, but its replays diverge, and a divergence surfaces as an `AgentReplayDivergenceError` rather than as a wrong answer.
310
+
311
+ ## Machines you cannot rewrite
312
+
313
+ The design work above assumes you are writing the machine. Existing machines can still be hosted without Agent-specific authoring.
314
+
315
+ - The machine already exists and contains nothing agent-specific. Any machine whose invokes resolve to values and whose events you can enumerate can be driven. Use [`getAcceptedEvents(snapshot)`](human-in-the-loop.md) for the candidates and call `resolveDecision` gated by `snapshot.can(event)`. See [plain-xstate](https://github.com/statelyai/agent/blob/next/examples/plain-xstate/index.ts).
316
+
317
+ Prompts do not have to live in the machine. Leave bare `src` strings and bind a separate prompt map through the `actors` option of `runToQuiescence`, which is shorthand for `machine.provide({ actors })`. The explicit invokes remain part of the graph, which is what lets a machine round-trip through JSON with `setupAgent.fromConfig`. See [Machines as data](machines-as-data.md).
318
+
319
+ ## Related
320
+
321
+ - [Migrating from a hand-rolled loop](from-a-loop.md): the same translation applied to a working refund agent, one step at a time.
322
+ - [Agent machines](machines.md): the authoring reference for states, requests, and transitions.
323
+ - [Decisions](decisions.md): candidate events, retries, and guard rejection.
324
+ - [Agent patterns](patterns.md): common shapes this decomposition produces, one runnable file each.
package/docs/tools.md ADDED
@@ -0,0 +1,249 @@
1
+ ---
2
+ title: Tools
3
+ description: Define tools, attach them to a text request, and let the host run the tool loop while the machine stays in one state.
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
+ Tools belong to a request, not to a machine state. The machine decides when a request runs. The model picks which tools to call. The host executes them. The machine does not see the intermediate tool calls.
9
+
10
+ <!-- viz: data-flow figure of the tool loop: machine invokes a tool-carrying request -> host executor runs model/tool turns up to maxSteps -> final output validated -> single onDone transition back in the machine -->
11
+
12
+ ## The tool contract
13
+
14
+ <!-- AgentTool/AgentToolDescriptor from src/types.ts -->
15
+
16
+ `AgentTool` is a minimal structural contract, so tools from any SDK work without changes:
17
+
18
+ | Field | Type | Meaning |
19
+ | --------------- | ------------------------------------ | ------------------------------------------------ |
20
+ | `description?` | `string` | What the model reads to decide whether to call. |
21
+ | `inputSchema?` | Standard Schema or any schema object | Arguments contract. |
22
+ | `outputSchema?` | Standard Schema or any schema object | Result contract, when the host wants one. |
23
+ | `execute?` | `(...args) => unknown` | The implementation the host runs. |
24
+ | anything else | `unknown` | Passed through untouched (`providerOptions`, …). |
25
+
26
+ - A bare function is shorthand for `execute`, typed as `AgentToolExecute`.
27
+ - `AgentTools` is `Record<string, AgentTool | undefined>`, keyed by tool name.
28
+ - `inputSchema` is widened to `object` so an SDK-native tool assigns without a cast. Core reads it as a Standard Schema when it can.
29
+
30
+ A native AI SDK tool owns its input typing, so the argument to `execute` needs no cast:
31
+
32
+ ```ts
33
+ import { tool } from "ai";
34
+ import { z } from "zod";
35
+
36
+ const calculate = tool({
37
+ description: "Do arithmetic on two numbers.",
38
+ inputSchema: z.object({ op: z.enum(["add", "multiply"]), a: z.number(), b: z.number() }),
39
+ execute: async ({ op, a, b }) => ({ value: op === "add" ? a + b : a * b }), // typed
40
+ });
41
+ ```
42
+
43
+ Without an SDK, a plain object is enough. Core reads `description` and `inputSchema`, then runs `execute`:
44
+
45
+ ```ts
46
+ const calculate = {
47
+ description: "Do arithmetic on two numbers.",
48
+ inputSchema: z.object({ op: z.enum(["add", "multiply"]), a: z.number(), b: z.number() }),
49
+ execute: async (input: unknown) => {
50
+ const { op, a, b } = input as { op: "add" | "multiply"; a: number; b: number };
51
+ return { value: op === "add" ? a + b : a * b };
52
+ },
53
+ };
54
+ ```
55
+
56
+ ## Attaching tools to a request
57
+
58
+ Put `tools` on any [text request](text-requests.md), either inline in `setupAgent({ requests })` or on a standalone `createTextLogic`.
59
+
60
+ - `maxSteps` is a typed field on the request. It bounds the host-side tool loop. Without it, the request is single-step.
61
+ - `toolChoice` constrains selection. It accepts `'auto'`, `'none'`, `'required'`, or `{ type: 'tool', name }`.
62
+
63
+ ```ts no-check
64
+ import { z } from "zod";
65
+ import { setupAgent } from "@statelyai/agent";
66
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
67
+ import { openai } from "@ai-sdk/openai";
68
+
69
+ const models = { assistant: openai("gpt-6-luna") };
70
+
71
+ const agentSetup = setupAgent({
72
+ models,
73
+ context: z.object({ query: z.string(), finalAnswer: z.string().nullable() }),
74
+ input: z.object({ query: z.string() }),
75
+ output: z.object({ finalAnswer: z.string() }),
76
+ requests: {
77
+ answer: {
78
+ schemas: { input: z.object({ query: z.string() }), output: z.string() },
79
+ model: "assistant",
80
+ system: "Answer in one sentence. Use calculate for arithmetic.",
81
+ prompt: ({ input }) => input.query,
82
+ tools: { calculate },
83
+ maxSteps: 5,
84
+ },
85
+ },
86
+ });
87
+
88
+ export const toolCallingMachine = agentSetup.createMachine({
89
+ id: "tool-calling",
90
+ context: ({ input }) => ({ query: input.query, finalAnswer: null }),
91
+ initial: "answering",
92
+ states: {
93
+ answering: {
94
+ invoke: {
95
+ src: "answer",
96
+ input: ({ context }) => ({ query: context.query }),
97
+ onDone: ({ output }) => ({ target: "done", context: { finalAnswer: output.result } }),
98
+ },
99
+ },
100
+ done: { type: "final", output: ({ context }) => ({ finalAnswer: context.finalAnswer ?? "" }) },
101
+ },
102
+ });
103
+ ```
104
+
105
+ Run the machine with any executor set. The machine is the same for scripted and real models.
106
+
107
+ ```ts
108
+ import { runToQuiescence } from "@statelyai/agent";
109
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
110
+
111
+ const result = await runToQuiescence(
112
+ createAgentRuntime(toolCallingMachine, { executors: createAiSdkExecutors({ models }) }),
113
+ { input: { query: "What is 42 times 17?" } },
114
+ );
115
+ ```
116
+
117
+ For approval and progress around real tools, see [review-tool-calls](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls/index.ts).
118
+
119
+ ## Execution flow through the host
120
+
121
+ <!-- toAiSdkTools / maxStepsSetting from src/ai-sdk/mappers.ts and src/ai-sdk/index.ts -->
122
+
123
+ 1. The machine invokes the request. Core lowers it to an `AgentTextRequest` carrying `tools`, `toolChoice`, and `metadata`.
124
+ 2. The executor maps tools to its SDK. `createAiSdkExecutors` passes a native `tool({...})` through unchanged and wraps a plain descriptor or bare function in `tool()`. A tool with no `inputSchema` gets a permissive one.
125
+ 3. `maxSteps` becomes `stopWhen: stepCountIs(maxSteps)`. The loop runs entirely inside the executor.
126
+ 4. The final output is validated against the request's output schema and returned to `onDone` as `output.result`, next to the executor's response messages in `output.messages`.
127
+
128
+ The machine observes the request boundary, not each intermediate tool call. For
129
+ example, `maxSteps: 5` permits up to five AI SDK-controlled steps before the
130
+ machine receives `onDone`. Model individual calls as states when the machine
131
+ must approve, persist, retry, or reject them separately.
132
+
133
+ Two consequences follow:
134
+
135
+ - Tool-carrying requests do not retry. The AI SDK adapter retries invalid structured output only when the request has no tools, because a tool loop may already have caused side effects.
136
+ - `metadata` is host-owned. A host that does not understand a key ignores it, so requests stay portable.
137
+
138
+ The raw executor result, including tool calls and results, reaches host code through `runToQuiescence`'s `onResult(request, { raw })` and the `request.end` trace event. See [Observability](observability.md).
139
+
140
+ ## Tool results in messages
141
+
142
+ <!-- message model from src/types.ts and src/utils.ts -->
143
+
144
+ Tool calls and results stay in the executor framework's native message objects. A tool-carrying request resolves with them in `output.messages`, and the machine stores them explicitly as context in `onDone`:
145
+
146
+ ```ts no-check
147
+ answering: {
148
+ invoke: {
149
+ src: "answer",
150
+ input: ({ context }) => ({ query: context.query }),
151
+ onDone: ({ context, output }) => ({
152
+ target: "done",
153
+ context: {
154
+ finalAnswer: output.result,
155
+ messages: [...context.messages, ...output.messages],
156
+ },
157
+ }),
158
+ },
159
+ },
160
+ ```
161
+
162
+ Build these parts by hand only when the machine owns the loop, such as in a ReAct-style machine or when replaying a transcript. With a host-run tool loop, the intermediate calls stay inside the executor. See [Messages](messages.md).
163
+
164
+ ## Presets and ejecting
165
+
166
+ `createToolLoopMachine` from `@statelyai/agent/machines` is a prebuilt version of the machine above: one `answering` state and one tool-carrying request. See [Preset machines](machines-presets.md) for its options, including `maxSteps`.
167
+
168
+ Eject from the preset when the tool loop needs machine states of its own:
169
+
170
+ - To approve or reject each of a turn's tool calls before it runs, use `createApprovalBatchMachine`. See [Approval gate](#approval-gate).
171
+ - To model approval as machine states, with approve, edit, and reject steps that persist and resume, eject to [examples/review-tool-calls](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls/index.ts).
172
+ - To model each think, act, and observe turn as its own transition, use explicit request, tool, and observation states.
173
+
174
+ > **Note:** There is no built-in MCP client. MCP discovery, auth, and transport are the host's responsibility. Pass the discovered tool descriptors into `tools` like any other tool. See [Scope](scope.md).
175
+
176
+ ## Approval gate
177
+
178
+ `createApprovalBatchMachine` from `@statelyai/agent/machines` gates one model turn's tool calls: a policy allows, asks about, or denies each call, a person approves or rejects the asked ones, and only approved calls execute. See [Preset machines](machines-presets.md#createapprovalbatchmachine).
179
+
180
+ ### AI SDK `needsApproval`
181
+
182
+ A tool with `needsApproval: true` comes back from `generateText` unexecuted, as a `tool-approval-request` content part. Run those calls through the batch, then answer each request in a `tool` message:
183
+
184
+ - **Executed.** `tool-approval-response` with `approved: true`, plus the batch's `tool-result`. The SDK skips an approved call that already has a result, so it does not run twice.
185
+ - **Rejected or cancelled.** `tool-approval-response` with `approved: false`. The SDK reports it to the model as denied.
186
+ - **Failed.** `approved: true` plus an `error-text` tool result.
187
+
188
+ ```ts no-check
189
+ import { generateText, type ModelMessage } from "ai";
190
+
191
+ const first = await generateText({ model, tools, messages });
192
+ const requests = first.content.filter((part) => part.type === "tool-approval-request");
193
+
194
+ // 1. Map the unexecuted calls to the batch input.
195
+ const calls = requests.map(({ toolCall }) => ({
196
+ id: toolCall.toolCallId,
197
+ name: toolCall.toolName,
198
+ args: toolCall.input,
199
+ }));
200
+
201
+ // 2. Run the batch; resume it with APPROVE / REJECT events until it is done.
202
+ const batch = createApprovalBatchMachine({
203
+ policy,
204
+ execute: createAsyncLogic({
205
+ run: ({ input }) =>
206
+ tools[input.call.name].execute(input.call.args, { toolCallId: input.call.id, messages }),
207
+ }),
208
+ });
209
+ const done = await runBatchToDone(batch, { calls }); // host-specific: approval UI, persistence
210
+
211
+ // 3. Feed the results back as one tool message, and continue.
212
+ const toolMessage: ModelMessage = {
213
+ role: "tool",
214
+ content: done.output.results.flatMap((result, index) => {
215
+ const { approvalId, toolCall } = requests[index]!;
216
+ const approved = result.status === "executed" || result.status === "failed";
217
+ return [
218
+ { type: "tool-approval-response", approvalId, approved, reason: result.reason },
219
+ ...(approved
220
+ ? [
221
+ {
222
+ type: "tool-result",
223
+ toolCallId: toolCall.toolCallId,
224
+ toolName: toolCall.toolName,
225
+ output:
226
+ result.status === "executed"
227
+ ? { type: "json", value: result.result }
228
+ : { type: "error-text", value: result.error },
229
+ },
230
+ ]
231
+ : []),
232
+ ];
233
+ }),
234
+ };
235
+ await generateText({
236
+ model,
237
+ tools,
238
+ messages: [...messages, ...first.response.messages, toolMessage],
239
+ });
240
+ ```
241
+
242
+ `results` is in input order, so `results[index]` answers `requests[index]`. Persist `done.output.approveAlways` and have `policy` allow those tool names on later turns.
243
+
244
+ ## Related
245
+
246
+ - Read more about [Text requests](text-requests.md), the request a tool attaches to, including structured and streaming output.
247
+ - Read more about [Hosts](hosts.md), including executors, model aliases, and writing your own adapter.
248
+ - Read more about [Messages](messages.md), the message model that tool parts live in.
249
+ - Read more about [Preset machines](machines-presets.md), including `createToolLoopMachine`.
@@ -0,0 +1,37 @@
1
+ ---
2
+ title: Upgrading between alphas
3
+ description: The breaking changes you are most likely to hit when you move an app from an earlier 2.0 alpha to the current one, and where to find the rest.
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 lists the breaking changes an app on an earlier 2.0 alpha is most likely to hit. Every release's full notes are in `CHANGELOG.md`, which ships in the package: `node_modules/@statelyai/agent/CHANGELOG.md`.
9
+
10
+ ## Peer versions
11
+
12
+ - **XState:** exactly the version in the package's `peerDependencies` (`6.0.0-beta.0` today). Upgrade it in the same change as the agent package.
13
+ - **AI SDK:** `ai` 7.0.128 or newer for `@statelyai/agent/ai-sdk`, which imports `experimental_decide`. An older `ai` fails at import time with `does not provide an export named 'experimental_decide'`. Adapter SDKs are optional peers with no version range, so npm installs the core next to any `ai`, `openai`, `@tanstack/ai`, or `ajv`.
14
+ - **Ajv:** `ajv` 8.20.0 or newer for `@statelyai/agent/validate`, which imports `ajv/dist/2020.js`. Ajv 6 installs, then fails when that subpath is imported.
15
+
16
+ ## Removed and moved APIs
17
+
18
+ | Was | Now |
19
+ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
20
+ | `defineModels({ ... })` | A plain `models` map, passed to `setupAgent({ models })` and to `createAiSdkExecutors({ models })`. Pass `executors` to `runAgent` explicitly. |
21
+ | `createScriptedExecutors` | Removed; the package ships no model mock. Write plain executors that return `{ result }`, or use the AI SDK's `MockLanguageModelV3` behind `createAiSdkExecutors`. |
22
+ | `assertAgentMachine`, `lintAgentMachine`, `simulateAgent`, `explorePaths`, `canReach` from `@statelyai/agent` | The same names from `@statelyai/agent/testing`. `assertAgentMachine(machine)` is also `lintAgentMachine(machine, { throw: true })`. |
23
+ | `replay`, `initEntry`, `createReplayEntry`, `getUsageFromEvents`, the stores from `@statelyai/agent` | The same names from `@statelyai/agent/log`. |
24
+ | `setupAgent({ isIdle })`, `idleTags` | Removed. A run settles `idle` when the machine waits on an event; `isAgentIdle(snapshot)` tells a human wait from a stuck machine. |
25
+
26
+ ## Changed shapes
27
+
28
+ - **Text request output.** A request invoke's `onDone` output is `{ result, messages }`: read `output.result.field`, not `output.field`. Executors return `{ result, messages?, usage? }`, not `{ output }`.
29
+ - **Schemas.** Every schema must be a [Standard Schema](https://standardschema.dev). `setupAgent` throws `invalid-schema` for one that is not, such as a zod 3.23 schema.
30
+ - **Undefined fields.** Object fields set to `undefined` in input and events are dropped before they are logged, as `JSON.stringify` drops them, so JSON-sanitizing written only for them can go. Other non-JSON values still fail a run that has a `store`.
31
+ - **Exploration types.** Type `payloads`, `dedupeBy`, and `canReach` predicate callbacks with `ExploreSnapshot` (and the target with `CanReachTarget`) from `@statelyai/agent/testing`, not with your own `xstate`'s `AnyMachineSnapshot`.
32
+ - **Requests.** A `requests` entry needs a `prompt` or `messages`. `setupAgent` throws `invalid-request` for one with neither, even when the executor builds its own model call.
33
+
34
+ ## Checking an upgrade
35
+
36
+ - Run the type checker first: most of the changes above are type errors.
37
+ - Search `CHANGELOG.md` between your old version's heading and the new one for **Breaking** and **Removed**.