@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,268 @@
1
+ ---
2
+ title: Models and providers
3
+ description: Reuse models and executors from other AI frameworks via AI SDK LanguageModel objects, TanStack AI text adapters, and OpenAI-compatible endpoints.
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 how to supply models to a machine's [executors](hosts.md), and which capabilities each integration path supports.
9
+
10
+ ## Reusing models from other frameworks
11
+
12
+ A host's [executors](hosts.md) are the only integration point. Most frameworks expose models as an AI SDK **`LanguageModel`** object. Pass that object to `createAiSdkExecutors({ models })` to get a full `{ generateText, streamText, decide }` set.
13
+
14
+ ```ts
15
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
16
+
17
+ const executors = createAiSdkExecutors({
18
+ models: { quick: someLanguageModel, careful: anotherLanguageModel },
19
+ });
20
+
21
+ await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
22
+ ```
23
+
24
+ ## Declaring models once
25
+
26
+ When the models are already declared in `setupAgent({ models })`, pass the machine, or the setup result, instead of repeating the map. The adapter reads the models registered for that machine, including through `machine.provide(...)`.
27
+
28
+ ```ts
29
+ import { z } from "zod";
30
+ import { runAgent, setupAgent } from "@statelyai/agent";
31
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
32
+
33
+ const agentSetup = setupAgent({
34
+ context: z.object({ prompt: z.string() }),
35
+ input: z.object({ prompt: z.string() }),
36
+ models: { quick: someLanguageModel },
37
+ });
38
+
39
+ const machine = agentSetup.createMachine({
40
+ context: ({ input }) => input,
41
+ initial: "writing",
42
+ states: {
43
+ writing: {
44
+ invoke: {
45
+ src: "agent.generateText",
46
+ input: ({ context }) => ({ model: "quick", prompt: context.prompt }),
47
+ onDone: { target: "done" },
48
+ },
49
+ },
50
+ done: { type: "final" },
51
+ },
52
+ });
53
+
54
+ await runAgent(machine, {
55
+ input: { prompt: "Why state machines?" },
56
+ executors: createAiSdkExecutors(machine),
57
+ });
58
+ ```
59
+
60
+ - `createAiSdkExecutors(machine)` and `createAiSdkExecutors(agentSetup)` resolve the same `models`.
61
+ - `createTanStackAiExecutors` accepts the same three forms.
62
+ - Host settings still need the options form: `createAiSdkExecutors({ models: agentSetup.models, settings })`.
63
+ - Anything else throws when the executors are built, not on the first call. That includes a setup or machine that declared no models.
64
+ - Core stays provider-free: it stores the models without reading them, and only the adapter interprets them.
65
+
66
+ There are five integration paths. The first two both go through `createAiSdkExecutors`, so they appear as one row in the [support table](#support-by-path).
67
+
68
+ - **AI SDK adapter.** Accepts any `LanguageModel`, including models from Mastra, Cloudflare Workers AI through `workers-ai-provider`, OpenRouter's AI SDK provider, and any `@ai-sdk/*` package. Supports all three executors, including `decide`.
69
+ - **OpenAI-compatible endpoints.** Point `createOpenAI({ baseURL })` from `@ai-sdk/openai` at any OpenAI-shaped endpoint, such as Groq, Ollama, vLLM, Together, or LM Studio, then pass the result to the same adapter. Supports all three executors, including `decide`.
70
+ - **TanStack AI adapter.** `createTanStackAiExecutors` from `@statelyai/agent/tanstack-ai` accepts any TanStack AI text adapter, such as `openaiText` or `anthropicText`. Supports all three executors, including `decide`. See [Hosts](hosts.md#tanstack-ai-adapter).
71
+ - **Hand-written executors.** Write the three executors yourself against a provider's HTTP API, or against a client that is not an AI SDK `LanguageModel`, such as a LangChain `BaseChatModel`. Supports all three executors, but you map structured output and decision retries yourself. See [Hosts](hosts.md) and [LangChain models](#langchain-models).
72
+ - **Raw `ai` functions.** Pass the `ai` package's `generateText` and `streamText` as your `executors` set. This path supports text only. `decide` requires the adapter, and structured output is best-effort.
73
+
74
+ <!-- viz: executor sourcing paths: LanguageModel object -> createAiSdkExecutors -> { generateText, streamText, decide } -->
75
+
76
+ ## Host-owned model settings
77
+
78
+ <!-- settings and model-entry precedence from src/ai-sdk/index.ts and src/ai-sdk/mappers.ts -->
79
+
80
+ Pass provider-specific settings to `createAiSdkExecutors`, not the machine. An object applies to every call; a function can vary settings by request. A model entry may also pair one model with its defaults.
81
+
82
+ ```ts
83
+ const executors = createAiSdkExecutors({
84
+ models: {
85
+ quick: openai("gpt-6-luna"),
86
+ careful: { model: openai("gpt-6.1-sol"), settings: { reasoning: "high" } },
87
+ },
88
+ settings: (request) => ({ temperature: request.name === "draft" ? 0.7 : 0 }),
89
+ });
90
+ ```
91
+
92
+ Precedence is global `settings`, then model-entry settings, then portable generation fields declared by the request.
93
+
94
+ ## Decision models
95
+
96
+ <!-- decision-model entries from src/ai-sdk/index.ts (decideWithDecisionModel) -->
97
+
98
+ An AI SDK decision model, such as TypeSafe's Jev, goes in the same models map as the language models. A decide request whose model ref names it is answered through `experimental_decide` instead of a structured-output object or tool call.
99
+
100
+ ```ts no-check
101
+ import { openai } from "@ai-sdk/openai";
102
+ import { typeSafeAi } from "@ai-sdk/typesafe-ai";
103
+
104
+ const executors = createAiSdkExecutors({
105
+ models: { desk: openai("gpt-6-luna"), judge: typeSafeAi.decisionModel("jev-latest") },
106
+ });
107
+ ```
108
+
109
+ - The request must be a closed choice: `payloads` on `agent.decide`, or `decideNext`. A request without `options` throws.
110
+ - The adapter asks one `choice` question. Each option id is a label, and its criterion is the option's description, or the event as JSON when it has none. The instructions are the request's `system` and `prompt`, and the state is the request's `input`.
111
+ - The result carries the chosen option's event, the call's usage, and `confidence` when the model reports it.
112
+ - A label that is not an option is a failed attempt, retried like any other. A retry appends each earlier attempt's reason to the instructions.
113
+ - A text request on a decision model throws. Host `settings` apply to language models only.
114
+ - `resolveModel` may return a decision model too.
115
+
116
+ ## Mastra models
117
+
118
+ Mastra is a TypeScript agent framework that configures agents with an AI SDK `LanguageModel`. Pass the same models to `createAiSdkExecutors`, and expose the run through a Mastra tool.
119
+
120
+ ```ts
121
+ import { z } from "zod";
122
+ import { Agent } from "@mastra/core/agent";
123
+ import { createTool } from "@mastra/core/tools";
124
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
125
+ import { runToQuiescence } from "@statelyai/agent";
126
+
127
+ const executors = createAiSdkExecutors({ models });
128
+
129
+ const startWorkflow = createTool({
130
+ id: "start_workflow",
131
+ description: "Start the drafting workflow from the user's request.",
132
+ inputSchema: z.object({ prompt: z.string() }),
133
+ outputSchema: z.object({ status: z.string() }),
134
+ execute: async ({ prompt }) => {
135
+ const result = await runToQuiescence(createAgentRuntime(machine, { executors }), {
136
+ input: { prompt },
137
+ });
138
+ return { status: result.status };
139
+ },
140
+ });
141
+
142
+ export const hostAgent = new Agent({
143
+ id: "drafting-host",
144
+ name: "Drafting Host",
145
+ instructions: "Call start_workflow with the user's request, then report what came back.",
146
+ model: "openai/gpt-6-luna",
147
+ tools: { start_workflow: startWorkflow },
148
+ });
149
+ ```
150
+
151
+ Any framework that exposes a `LanguageModel` works the same way. The machine and the Mastra agent share one model definition. See [`examples/mastra-host`](https://github.com/statelyai/agent/tree/next/examples/mastra-host) for the full bridge, including pause and resume across tool calls.
152
+
153
+ ## LangChain models
154
+
155
+ LangChain chat models are not AI SDK `LanguageModel` objects, so they take the hand-written path. Wrap any `BaseChatModel` in the three executors and the machine keeps LangChain's model config, callbacks, and retries.
156
+
157
+ - `generateText` and `streamText` call the model's `invoke` and `stream`.
158
+ - `decide` binds one tool per allowed event and forces a tool call.
159
+ - LangSmith tracing is env-var driven, so a wrapped model traces without code changes. For tracing the machine's own spans instead, see [Observability](observability.md).
160
+
161
+ See [`examples/langchain-host`](https://github.com/statelyai/agent/blob/next/examples/langchain-host/index.ts) for both directions: LangChain models as executors, and the machine handed to a LangChain `createAgent` loop as `start_workflow` and `resume_workflow` tools.
162
+
163
+ ## Cloudflare Workers AI
164
+
165
+ Workers AI runs models on Cloudflare's edge and is reached through a binding on the Worker's `env`. The `workers-ai-provider` package turns that binding into an AI SDK provider, so its models are ordinary `LanguageModel` objects.
166
+
167
+ ```ts no-check
168
+ import { createWorkersAI } from "workers-ai-provider";
169
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
170
+
171
+ export default {
172
+ async fetch(request, env) {
173
+ // Model IDs here are illustrative; substitute your provider's current models.
174
+ const workersai = createWorkersAI({ binding: env.AI });
175
+ const result = await runToQuiescence(
176
+ createAgentRuntime(machine, {
177
+ executors: createAiSdkExecutors({
178
+ models: { quick: workersai("@cf/meta/llama-3.1-8b-instruct") },
179
+ }),
180
+ }),
181
+ { input: await request.json() },
182
+ );
183
+ return Response.json(result);
184
+ },
185
+ };
186
+ ```
187
+
188
+ Pass Cloudflare-specific per-call options through request `metadata`. The host reads `metadata`; the machine only carries it.
189
+
190
+ ## Ollama and OpenAI-compatible endpoints
191
+
192
+ Ollama runs models locally and serves them over an OpenAI-compatible HTTP API. Point the AI SDK's OpenAI provider at the local endpoint. Pass a placeholder `apiKey`: the provider throws while building request headers when neither `apiKey` nor `OPENAI_API_KEY` is set, even for a local server that ignores the value.
193
+
194
+ ```ts
195
+ import { createOpenAI } from "@ai-sdk/openai";
196
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
197
+
198
+ // Model IDs here are illustrative; substitute your provider's current models.
199
+ const ollama = createOpenAI({ baseURL: "http://localhost:11434/v1", apiKey: "ollama" });
200
+
201
+ await runToQuiescence(
202
+ createAgentRuntime(machine, {
203
+ executors: createAiSdkExecutors({
204
+ models: { quick: ollama("llama3.1") },
205
+ }),
206
+ }),
207
+ { input },
208
+ );
209
+ ```
210
+
211
+ To use Groq, vLLM, Together, OpenRouter, or LM Studio, change `baseURL` and use the endpoint's real `apiKey`. Nothing else changes.
212
+
213
+ For OpenAI itself, `@statelyai/agent/openai` maps the three executors onto the raw `openai` package, with no `ai` dependency. By default, calls with function tools use the Responses API, and tool-free calls use Chat Completions. `api: "chat"` sends every call to Chat Completions. See [Hosts](hosts.md#openai-sdk-adapter).
214
+
215
+ To avoid depending on `ai` or `openai`, write the three executors over raw `fetch` against the same OpenAI endpoints. Build the request body from the plain `AgentTextRequest` fields. For structured output, `providerOutputSchema` and `getJsonSchema` from `@statelyai/agent` build the `{ result, reasoning? }` schema to send; on the way back, `parseProviderOutput` validates the model's JSON against it and returns `{ result, reasoning? }`, which is already the shape an executor returns. Use `parseOutput` when you validate a bare value on its own, against the schema the request declared. Use `renderDecisionAttempts` for decision retries. See [Hosts](hosts.md).
216
+
217
+ ## Testing with a mock model
218
+
219
+ To exercise the adapter path itself without a provider, put one of the AI SDK's own mock models from `ai/test` in the `models` map.
220
+
221
+ ```ts
222
+ import { MockLanguageModelV3 } from "ai/test";
223
+ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
224
+
225
+ const executors = createAiSdkExecutors({
226
+ models: {
227
+ fast: new MockLanguageModelV3({
228
+ doGenerate: async () => ({
229
+ content: [{ type: "text", text: "Because transitions constrain behavior." }],
230
+ finishReason: { unified: "stop", raw: "stop" },
231
+ usage: {
232
+ inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 },
233
+ outputTokens: { total: 1, text: 1, reasoning: 0 },
234
+ },
235
+ warnings: [],
236
+ }),
237
+ }),
238
+ },
239
+ });
240
+ ```
241
+
242
+ When the adapter is not what is under test, a plain function executor that routes on `request.name` is lighter. See [Evals](evals.md#plain-function-executors).
243
+
244
+ ## Support by path
245
+
246
+ | Path | `generateText` | `streamText` | `decide` | Structured output |
247
+ | --------------------------- | -------------- | ------------ | -------- | ----------------- |
248
+ | `createAiSdkExecutors` | yes | yes | yes | yes |
249
+ | `createOpenAiExecutors` | yes | yes | yes | yes |
250
+ | `createTanStackAiExecutors` | yes | yes | yes | yes |
251
+ | Hand-written executors | yes | yes | yes | yes (you map it) |
252
+
253
+ The `decide` executor asks for one structured-output object naming the event, or a closed choice's option id (one `choice` question for a decision model). `decideMode: 'tool'` maps each event to a forced tool call instead. Structured output is requested as `{ result, reasoning? }`. Both live in the adapter layer, so an executor is either an adapter's or a function of yours that returns `{ result }`. See [Text requests](text-requests.md) and [Decisions](decisions.md).
254
+
255
+ ## Reference hosts by provider
256
+
257
+ Each example is a runnable host for one provider stack.
258
+
259
+ | Example | Backing |
260
+ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
261
+ | [ai-sdk-host](https://github.com/statelyai/agent/blob/next/examples/ai-sdk-host/index.ts) | Vercel AI SDK, through the optional adapter |
262
+ | [openai-sdk-host](https://github.com/statelyai/agent/blob/next/examples/openai-sdk-host/index.ts) | `createOpenAiExecutors` from `@statelyai/agent/openai`, over the raw `openai` package (Responses + Chat Completions) |
263
+ | [tanstack-ai-stream](https://github.com/statelyai/agent/blob/next/examples/tanstack-ai-stream/index.ts) | `createTanStackAiExecutors` from `@statelyai/agent/tanstack-ai`, streamed to a `useChat` client over AG-UI |
264
+ | [anthropic-sdk-host](https://github.com/statelyai/agent/blob/next/examples/anthropic-sdk-host/index.ts) | raw `@anthropic-ai/sdk` (Messages); structured via forced tool call, decisions via `tool_choice: { type: 'any' }` |
265
+ | [langchain-host](https://github.com/statelyai/agent/blob/next/examples/langchain-host/index.ts) | LangChain `BaseChatModel` (`@langchain/core`), wrapped into the executor contract |
266
+ | [mastra-host](https://github.com/statelyai/agent/blob/next/examples/mastra-host/index.ts) | Mastra `Agent` and `createTool`, bridging to `runToQuiescence` |
267
+ | [cloudflare-agent-host](https://github.com/statelyai/agent/blob/next/examples/cloudflare-agent-host/index.ts) | Durable Object |
268
+ | [cloudflare-workers-ai-host](https://github.com/statelyai/agent/blob/next/examples/cloudflare-workers-ai-host/index.ts) | Workers AI binding |
@@ -0,0 +1,68 @@
1
+ # Multi-agent composition
2
+
3
+ Multi-agent systems are ordinary XState actor composition.
4
+
5
+ ## Child machines
6
+
7
+ Register a child machine under `actors`, invoke it from a state, and handle its typed output with `onDone`. `runToQuiescence` recursively binds Agent request actors in registered child machines.
8
+
9
+ ## Long-lived actors
10
+
11
+ Invoke an agent machine at a parent state when it must survive transitions among nested substates. Send it events with XState's `sendTo`; receive outputs or emitted events through normal XState channels.
12
+
13
+ ## Parallel teams
14
+
15
+ Use parallel states when the branch topology is known in the artifact. Use spawned actors when it is dynamic. Generic fan-out, child collection, actor identity, and persistence belong to XState rather than an Agent-specific abstraction.
16
+
17
+ ## Collecting dynamic children
18
+
19
+ Spawned children are named at runtime, so the machine's event union cannot name their done events. Handle the canonical `xstate.done.actor` event and branch on `actorId`. `DoneActorEventOf<TLogic, TId?>` types that handler against the child's own output, which is XState's `DoneActorEvent` applied to the logic's `OutputFrom`.
20
+
21
+ ```ts no-check
22
+ "xstate.done.actor": ({ context, event }) => {
23
+ const { actorId, output } = event as DoneActorEventOf<typeof researchLogic>;
24
+ if (!actorId.startsWith("research-")) return undefined;
25
+ return { context: { findings: { ...context.findings, [actorId]: output.finding } } };
26
+ }
27
+ ```
28
+
29
+ ## Barriers
30
+
31
+ Spawned children that must all reach a checkpoint before any proceeds use two events: a child→parent status event and a parent→child release event.
32
+
33
+ - **Child.** On entry to its checkpoint state, it sends the parent a status event, then waits for `RELEASE`.
34
+ - **Parent.** It counts status events. When every child has reported (or finished), it sends each held child `RELEASE`.
35
+
36
+ ```ts no-check
37
+ // Child: report, then wait.
38
+ ready: {
39
+ entry: ({ context, parent }, enq) => {
40
+ if (parent) enq.sendTo(parent, { type: "CHILD_READY", id: context.id });
41
+ },
42
+ on: { RELEASE: { target: "working" } },
43
+ },
44
+
45
+ // Parent: hold until everyone reported, then release them all.
46
+ collecting: {
47
+ on: {
48
+ CHILD_READY: ({ context, event, children }, enq) => {
49
+ const ready = [...context.ready, event.id];
50
+ if (ready.length + context.finished.length < context.total) {
51
+ return { context: { ready } };
52
+ }
53
+ for (const id of ready) enq.sendTo(children[`worker:${id}`], { type: "RELEASE" });
54
+ return { context: { ready: [] } };
55
+ },
56
+ },
57
+ },
58
+ ```
59
+
60
+ - **Release per child instead.** Send `RELEASE` in the `CHILD_READY` handler itself; the barrier disappears and each child proceeds on its own.
61
+ - **Safety lives in the child.** The child takes `RELEASE` only in its checkpoint state, so a stray or forged release cannot skip a step. Check it with `canReach` on the child machine.
62
+ - **Preset.** `createApprovalBatchMachine` is this pattern for tool calls: one child per call, the checkpoint is approval, and `executeWhen` picks barrier or per-child release. See [Preset machines](machines-presets.md#createapprovalbatchmachine).
63
+
64
+ ## Events from one model turn
65
+
66
+ [`agent.act`](act.md) sends several events from one tool loop, each applied as it arrives. Use it when every event the model calls is safe to apply; use the approval batch when each needs a verdict first.
67
+
68
+ See [hierarchical teams](https://github.com/statelyai/agent/blob/next/examples/hierarchical-teams), [swarm handoff](https://github.com/statelyai/agent/blob/next/examples/swarm-handoff), [deep research](https://github.com/statelyai/agent/blob/next/examples/deep-research), and [game loop agent](https://github.com/statelyai/agent/blob/next/examples/game-loop-agent).
@@ -0,0 +1,109 @@
1
+ # Observability
2
+
3
+ Use XState inspection for actor/runtime behavior and Agent traces for model-request behavior.
4
+
5
+ ## Inspect a run
6
+
7
+ The package does not ship a visualizer. A run streams XState's inspection events through the `inspect` option, and the Stately inspector renders them live: the machine diagram, the active state, and every event.
8
+
9
+ ```sh
10
+ pnpm add -D @statelyai/sdk
11
+ ```
12
+
13
+ ```ts no-check
14
+ import { createInspector } from "@statelyai/sdk/inspect";
15
+
16
+ const inspector = createInspector({ name: "Refund agent" });
17
+ await inspector.ready; // the URL is null until the relay registers the session
18
+ console.log("Open", inspector.inspectorUrl);
19
+
20
+ try {
21
+ const result = await runAgent(machine, { input, executors, inspect: inspector.inspect });
22
+ } finally {
23
+ inspector.destroy(); // also when runAgent throws, so the connection closes
24
+ }
25
+ ```
26
+
27
+ - `inspector.inspect` is an XState `inspect` callback, so it is passed as is. `createAgentRuntime` takes the same option.
28
+ - `createInspector` connects to the hosted relay (`wss://sky.stately.ai`) unless `url` or `STATELY_INSPECT_URL` names another one.
29
+ - Create one inspector per run. Session ids are unique only within one actor system, so a reused inspector collides actor ids across runs.
30
+ - With the hosted relay, `inspectorUrl` is a one-time claim link for that session. Open it while the process runs; a new run prints a new one.
31
+ - Each actor in the run reaches the inspector once, under one handle, though the durable runtime re-creates actor objects between steps. Compare actors by `sessionId`, not by object.
32
+ - [examples/tanstack-ai-stream/inspect.ts](https://github.com/statelyai/agent/blob/next/examples/tanstack-ai-stream/inspect.ts) and [examples/next-host/agent-runtime.ts](https://github.com/statelyai/agent/blob/next/examples/next-host/agent-runtime.ts) wire it behind `STATELY_INSPECT=1`.
33
+ - `type: "choice"` states and other transient states (left at once by `always`) never appear in the viewer's snapshot sequence: they resolve within the same macrostep. `canReach` still counts them as reached.
34
+ - A `runAgent` started inside a wrapped workflow (a nested run per tool call, for example) appears in the inspector only when it gets its own `inspect` option: the workflow does not receive one, so pass the same inspector explicitly. It is a separate root actor with its own thread, and it does not resume with the outer run.
35
+
36
+ ### Local relay
37
+
38
+ For a test or an offline run, start a relay in the process instead of the hosted one:
39
+
40
+ ```sh
41
+ pnpm add -D @statelyai/sdk ws
42
+ ```
43
+
44
+ ```ts no-check
45
+ import { createInspector } from "@statelyai/sdk/inspect";
46
+ import { createNodeInspectionRelay } from "@statelyai/sdk/node-relay";
47
+
48
+ const relay = createNodeInspectionRelay({ port: 0 }); // any free port
49
+ await relay.start();
50
+ let inspector: ReturnType<typeof createInspector> | undefined;
51
+ try {
52
+ inspector = createInspector({ url: relay.url, roomId: "local", session: "direct" });
53
+ await inspector.ready;
54
+ await runAgent(machine, { input, executors, inspect: inspector.inspect });
55
+ } finally {
56
+ inspector?.destroy();
57
+ await relay.stop();
58
+ }
59
+ ```
60
+
61
+ - `@statelyai/sdk/node-relay` imports `ws`, an optional peer of `@statelyai/sdk`. Without it, the import fails with `Cannot find package 'ws'`.
62
+ - A `choice` state, or one left at once by `always`, is passed through within one step, so no snapshot shows it. Read it from `describeMachine` or `explorePaths`'s `reachedStates`.
63
+ - `session: "direct"` connects with the room id only, which is what a local relay expects.
64
+ - A test's viewer connects a WebSocket to `${relay.url}?r=<roomId>` and registers as a viewer. That is the relay endpoint, not an inspector page.
65
+
66
+ ## Trace one run
67
+
68
+ ```ts no-check
69
+ await runToQuiescence(
70
+ createAgentRuntime(machine, {
71
+ executors,
72
+ inspect: (event) => xstateInspector.next(event),
73
+ onTrace: (event) => exporter.write(serializeTraceEvent(event)),
74
+ }),
75
+ { input },
76
+ );
77
+ ```
78
+
79
+ Agent trace kinds are `run.start`, `request.start`, `request.end`, `request.error`, `stream.chunk`, `machine.transition`, `emit`, `usage.dropped`, and `run.end`.
80
+
81
+ A `machine.transition` event carries `from.value`, the state value the event arrived in, next to `snapshot`, the state after it. The first transition of a stream (the init event, or a restore on resume) has no earlier state, so its `from.value` equals its `snapshot.value`. `traceTransitions` sets it the same way for a plain actor. When the host's own event had no transition in the active state, the runtime's `machine.transition` also carries `ignored: true` (the event `result.ignored` reports), so evals can count those events from the trace alone.
82
+
83
+ A `request.end` event carries the call's `output` and `raw`, plus what the executor reported about the call itself: `usage` when it reported tokens, and `finishReason` when it reported why the call stopped, normalized to `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. See [Finish reason and truncation](text-requests.md#finish-reason-and-truncation).
84
+
85
+ Trace handlers are observers: an `onTrace`, `onTransition`, `onChunk`, `onResult`, `onEvent`, or `on` handler that throws is reported with `console.error`, and the run continues.
86
+
87
+ `serializeTraceEvent` creates a JSON-safe projection. Traces are observations, not a persistence protocol; the [event log](event-log.md) is.
88
+
89
+ `usage.dropped` means the `@agent.usage` event was not delivered to the machine, because no active state accepted it or the leg had already settled. The spend is still journaled and still counted: the entry is in the event log, and `getUsageFromEvents` folds it into the totals. Only the machine event is dropped.
90
+
91
+ ## Live progress
92
+
93
+ Use `onTrace` for `stream.chunk` and `machine.transition` events while the run
94
+ is active. The returned `AgentRunResult` supplies the terminal `done`, `idle`,
95
+ or `error` status. Domain failure remains part of the machine's typed output.
96
+
97
+ ## State paths in logs
98
+
99
+ `getStatePath(snapshot)` renders a state value as one deterministic string, so a log line or a progress field survives nesting and parallel regions. `String(snapshot.value)` renders every non-atomic value as `[object Object]`.
100
+
101
+ ```ts no-check
102
+ onTransition: (snapshot) => log.info({ state: getStatePath(snapshot) });
103
+ ```
104
+
105
+ An atomic state renders as `writing`, a nested one as `review.editing.draft`, and a parallel one as `p:{left.x,right.a.b}` with its regions sorted by name.
106
+
107
+ ## OpenTelemetry
108
+
109
+ Use `createOtelTraceHandler` from `@statelyai/agent/otel` as an `onTrace` sink. Framework telemetry and XState inspection remain composable with it.
@@ -0,0 +1,31 @@
1
+ # Agent patterns
2
+
3
+ The examples are non-trivial state machines, not special runner APIs.
4
+
5
+ ## Control-flow patterns
6
+
7
+ - [Evaluator/optimizer](https://github.com/statelyai/agent/blob/next/examples/ai-sdk-evaluator-optimizer)
8
+ - [Validate and repair](validate-and-repair.md) ([example](https://github.com/statelyai/agent/blob/next/examples/generate-and-repair))
9
+ - [Reflection writer](https://github.com/statelyai/agent/blob/next/examples/reflection-writer)
10
+ - [Plan and execute](https://github.com/statelyai/agent/blob/next/examples/plan-and-execute)
11
+ - [Corrective RAG](https://github.com/statelyai/agent/blob/next/examples/corrective-rag)
12
+ - [Deep research](https://github.com/statelyai/agent/blob/next/examples/deep-research)
13
+ - [Guardrails](https://github.com/statelyai/agent/blob/next/examples/guardrails)
14
+ - [Hierarchical teams](https://github.com/statelyai/agent/blob/next/examples/hierarchical-teams)
15
+ - [Swarm handoff](https://github.com/statelyai/agent/blob/next/examples/swarm-handoff)
16
+ - [Parallel streams](https://github.com/statelyai/agent/blob/next/examples/parallel-streams)
17
+
18
+ ## Human and long-running patterns
19
+
20
+ - [Long-running onboarding](https://github.com/statelyai/agent/blob/next/examples/long-running-onboarding)
21
+ - [Snapshot migration](https://github.com/statelyai/agent/blob/next/examples/snapshot-migration)
22
+ - [Review tool calls](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls)
23
+ - [SQL approval](https://github.com/statelyai/agent/blob/next/examples/sql-agent)
24
+ - [Context compaction](https://github.com/statelyai/agent/blob/next/examples/context-compaction)
25
+ - [Statechart policy examples](statechart-policy-examples.md): reviewer quorum, booking compensation, and scheduler-driven approval deadlines
26
+
27
+ ## Host portability
28
+
29
+ The same machine artifact runs through AI SDK, Anthropic, OpenAI, LangChain, Mastra, Cloudflare, Next.js, or plain XState examples. Host adapters supply requests; they do not redefine agent control flow.
30
+
31
+ Generic orchestration such as fan-out remains ordinary XState composition.