@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.36
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.
- package/CHANGELOG.md +111 -0
- package/dist/act-B9hLQls6.mjs +19 -0
- package/dist/act-CrX0JwWY.cjs +42 -0
- package/dist/ai-sdk.cjs +63 -7
- package/dist/ai-sdk.d.cts +13 -3
- package/dist/ai-sdk.d.mts +13 -3
- package/dist/ai-sdk.mjs +63 -7
- package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
- package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
- package/dist/decision-object-B5zGSPFp.d.mts +15 -0
- package/dist/decision-object-DBcLWVvv.d.cts +15 -0
- package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
- package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
- package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
- package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
- package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
- package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
- package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
- package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
- package/dist/index.cjs +660 -286
- package/dist/index.d.cts +168 -9
- package/dist/index.d.mts +168 -9
- package/dist/index.mjs +639 -271
- package/dist/internal-C3Lqu538.d.cts +43 -0
- package/dist/internal-DUcdhk-i.d.mts +43 -0
- package/dist/log.cjs +2 -2
- package/dist/log.d.cts +1 -1
- package/dist/log.d.mts +1 -1
- package/dist/log.mjs +2 -2
- package/dist/machines.cjs +457 -41
- package/dist/machines.d.cts +114 -43
- package/dist/machines.d.mts +114 -43
- package/dist/machines.mjs +457 -42
- package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
- package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
- package/dist/openai.cjs +149 -36
- package/dist/openai.d.cts +28 -10
- package/dist/openai.d.mts +28 -10
- package/dist/openai.mjs +149 -36
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
- package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
- package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
- package/dist/tanstack-ai.cjs +62 -4
- package/dist/tanstack-ai.d.cts +18 -6
- package/dist/tanstack-ai.d.mts +18 -6
- package/dist/tanstack-ai.mjs +62 -4
- package/dist/testing.cjs +399 -20
- package/dist/testing.d.cts +196 -255
- package/dist/testing.d.mts +196 -255
- package/dist/testing.mjs +395 -20
- package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
- package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
- package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
- package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
- package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
- package/dist/utils-7lSa4H-i.d.cts +403 -0
- package/dist/utils-CBbKw2fM.d.mts +403 -0
- package/dist/validate.cjs +44 -12
- package/dist/validate.d.cts +6 -6
- package/dist/validate.d.mts +6 -6
- package/dist/validate.mjs +44 -12
- package/dist/verify-Bink-Drw.cjs +2304 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
- package/dist/verify-Dpz1u5Pe.mjs +2251 -0
- package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
- package/dist/with-model-calls-BkOwdroS.mjs +213 -0
- package/docs/act.md +102 -0
- package/docs/advanced.md +105 -0
- package/docs/any-stack.md +62 -0
- package/docs/choosing-a-run-mode.md +55 -0
- package/docs/debugging.md +29 -0
- package/docs/decisions.md +473 -0
- package/docs/environment-and-policy.md +188 -0
- package/docs/evals.md +509 -0
- package/docs/event-log.md +311 -0
- package/docs/from-a-loop.md +528 -0
- package/docs/generate-machines.md +110 -0
- package/docs/hosts.md +414 -0
- package/docs/human-in-the-loop.md +177 -0
- package/docs/index.md +48 -0
- package/docs/judgments.md +281 -0
- package/docs/langgraph-comparison.md +198 -0
- package/docs/machines-as-data.md +454 -0
- package/docs/machines-presets.md +198 -0
- package/docs/machines.md +497 -0
- package/docs/messages.md +67 -0
- package/docs/meta.json +52 -0
- package/docs/models-and-providers.md +268 -0
- package/docs/multi-agent.md +68 -0
- package/docs/observability.md +109 -0
- package/docs/patterns.md +31 -0
- package/docs/persistence.md +136 -0
- package/docs/quickstart.md +121 -0
- package/docs/roadmap.md +22 -0
- package/docs/scope.md +75 -0
- package/docs/statechart-policy-examples.md +69 -0
- package/docs/steps.md +54 -0
- package/docs/strangler-fig.md +323 -0
- package/docs/text-requests.md +250 -0
- package/docs/thinking-in-state-machines.md +324 -0
- package/docs/tools.md +249 -0
- package/docs/upgrading.md +37 -0
- package/docs/usage-and-budgets.md +516 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +487 -0
- package/docs/xstate-4-and-5-apps.md +161 -0
- package/llms.txt +53 -0
- package/package.json +10 -3
- package/readme.md +30 -15
- package/skills/add-evals/SKILL.md +3 -1
- package/skills/add-traces/SKILL.md +6 -1
- package/skills/build-machine/SKILL.md +81 -0
- package/skills/generate-machine/SKILL.md +1 -1
- package/skills/graph-engineering/SKILL.md +13 -3
- package/skills/improve-machine/SKILL.md +21 -2
- package/skills/loop-to-machine/SKILL.md +147 -192
- package/skills/loop-to-machine/reference.md +260 -0
- package/dist/utils-BnXdWih3.d.mts +0 -108
- package/dist/utils-ebVpCYoF.d.cts +0 -108
- package/dist/verify-Bpahmr34.mjs +0 -1241
- package/dist/verify-DCLZa9R0.cjs +0 -1288
- package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
- 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.
|
package/docs/patterns.md
ADDED
|
@@ -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.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Persistence
|
|
2
|
+
|
|
3
|
+
The [event log](event-log.md) is the durable artifact. A snapshot is a cache over it.
|
|
4
|
+
|
|
5
|
+
- The log is an ordered array of the external inputs the machine received. A run is fully reconstructed from it.
|
|
6
|
+
- The persisted snapshot is the machine's serialized state at one point. It lets a resume skip the fold.
|
|
7
|
+
- Live run state — the actor, in-flight requests, stream chunks — is derived and disposable.
|
|
8
|
+
|
|
9
|
+
## Persist the log
|
|
10
|
+
|
|
11
|
+
Hand `runToQuiescence` a [store](event-log.md#stores) and the thread it owns. Entries are written as they are accepted, and no model call runs against a log that is not yet durable.
|
|
12
|
+
|
|
13
|
+
```ts no-check
|
|
14
|
+
const result = await runToQuiescence(createAgentRuntime(machine, { store, threadId, executors }), {
|
|
15
|
+
input,
|
|
16
|
+
});
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- A rejected write stops the run: `{ status: "error", cause: "journal" }`.
|
|
20
|
+
- `threadId` is required whenever `store` is given.
|
|
21
|
+
|
|
22
|
+
`onEvent` remains the observer seam — synchronous, never awaited. Persisting there is at-least-once: a crash between an entry and the host's flush loses it. See [Record a log](event-log.md#record-a-log).
|
|
23
|
+
|
|
24
|
+
`result.events` is a complete, self-contained segment: its first entry is the reserved `@agent.init` entry, so it replays with no side channel.
|
|
25
|
+
|
|
26
|
+
## Resume from the log
|
|
27
|
+
|
|
28
|
+
With a `store`, the thread's log is the resume: pass no `events` and no snapshot.
|
|
29
|
+
|
|
30
|
+
```ts no-check
|
|
31
|
+
const resumed = await runToQuiescence(createAgentRuntime(machine, { store, threadId, executors }), {
|
|
32
|
+
event: { type: "APPROVE" },
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
An empty thread starts fresh from `input`. Pass `events` explicitly to resume from a log the host holds itself (the store's thread length must then match it).
|
|
37
|
+
|
|
38
|
+
### Resume with an event off the wire
|
|
39
|
+
|
|
40
|
+
In a route handler the event arrives as JSON. Parse it at the boundary with `parseAgentEvent`, then pass the result as `event`:
|
|
41
|
+
|
|
42
|
+
```ts no-check
|
|
43
|
+
let event;
|
|
44
|
+
try {
|
|
45
|
+
event = parseAgentEvent(machine, await request.json());
|
|
46
|
+
} catch (error) {
|
|
47
|
+
return Response.json({ error: String(error) }, { status: 400 });
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const result = await runToQuiescence(createAgentRuntime(machine, { store, threadId, executors }), {
|
|
51
|
+
event,
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
if (result.ignored) {
|
|
55
|
+
return Response.json(
|
|
56
|
+
{ error: `'${result.ignored.type}' does not apply right now` },
|
|
57
|
+
{ status: 409 },
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- `parseAgentEvent` takes `unknown`: hand over the parsed JSON body as-is. It accepts the machine itself (reading the event schemas `setupAgent` registered) or any snapshot of it, and returns the event typed as the machine's event union.
|
|
63
|
+
- It throws `AgentInvalidEventPayloadError` (code `invalid-event-payload`) when the payload is not an object with a string `type`, when the type is a reserved `@agent.*` type, or when the fields fail the registered schema. Answer that with a 400.
|
|
64
|
+
- On success the schema-parsed event is returned: defaults filled, transforms applied.
|
|
65
|
+
- `parseAgentEvent` does not check whether the current state handles the event, and `runToQuiescence` adds no validation of its own.
|
|
66
|
+
- An event the resumed state has no transition for is ignored. The run settles normally and `result.ignored` carries the event. It is journaled like any other external input, so replay ignores it again.
|
|
67
|
+
|
|
68
|
+
- Recorded results are replayed, never re-executed.
|
|
69
|
+
- A request that was in flight when the log ended has no recorded completion, so it re-executes. Execution is at-least-once; key provider calls on [`info.callKey`](hosts.md#idempotency-keys).
|
|
70
|
+
- A log that already reached a final state settles immediately with the recorded output.
|
|
71
|
+
- The resumed result's `events` extends the same log, so the whole history stays replayable.
|
|
72
|
+
|
|
73
|
+
## Snapshot as cache
|
|
74
|
+
|
|
75
|
+
`persist()` output carries `agentMeta: { machineId, version, logId, logIndex }` — the lineage and position of the log it caches.
|
|
76
|
+
|
|
77
|
+
Pass `snapshot` alongside `events` to skip the fold:
|
|
78
|
+
|
|
79
|
+
```ts no-check
|
|
80
|
+
const resumed = await runToQuiescence(createAgentRuntime(machine, { executors }), {
|
|
81
|
+
events: await store.read(threadId),
|
|
82
|
+
snapshot: await snapshots.get(threadId),
|
|
83
|
+
event: { type: "APPROVE" },
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- Fast path: `agentMeta.logId` names the log, `logIndex` equals the log length, and the snapshot's state hash matches the tail entry's `verification.stateHash`. Length alone is not enough — a fork or a sibling thread can sit at the same index.
|
|
88
|
+
- Otherwise the log is replayed and the run resumes from the replayed state.
|
|
89
|
+
- A cache that disagrees with the state the log replays to throws `AgentSnapshotDivergedError` (code `snapshot-diverged`). Drop the snapshot and resume from `events` alone.
|
|
90
|
+
|
|
91
|
+
A snapshot is never authoritative within a version. Snapshot only at quiescent points: a mid-flight snapshot cannot carry in-flight request state, but the log can.
|
|
92
|
+
|
|
93
|
+
Resuming from a snapshot with no log also yields a self-contained log — the new segment's init entry carries that snapshot — so every result is replayable.
|
|
94
|
+
|
|
95
|
+
## Version bridge
|
|
96
|
+
|
|
97
|
+
A log is truth within one `machine.version`. Across a version change, pass the old `events` together with a `snapshot`:
|
|
98
|
+
|
|
99
|
+
```ts no-check
|
|
100
|
+
const migrated = await runToQuiescence(createAgentRuntime(machine, { executors }), {
|
|
101
|
+
events: oldEntries,
|
|
102
|
+
snapshot: oldSnapshot,
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- XState's machine-owned `migrate` runs on the snapshot.
|
|
107
|
+
- The result is a **new** segment. Its init entry carries the migrated snapshot and `metadata.migratedFrom`.
|
|
108
|
+
- The old log stays as history under the old version. Keep it if you need to replay the past.
|
|
109
|
+
- Old `events` with no `snapshot` throw `AgentMachineVersionMismatchError`: there is nothing to migrate from.
|
|
110
|
+
|
|
111
|
+
Declare the version and migration on the machine:
|
|
112
|
+
|
|
113
|
+
```ts no-check
|
|
114
|
+
const machine = setup.createMachine({
|
|
115
|
+
version: "2",
|
|
116
|
+
migrate: (snapshot, fromVersion) =>
|
|
117
|
+
fromVersion === "1"
|
|
118
|
+
? { ...snapshot, version: "2", context: upgrade(snapshot.context) }
|
|
119
|
+
: snapshot,
|
|
120
|
+
// ...
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Framework storage
|
|
125
|
+
|
|
126
|
+
Implement `AgentEventLogStore` against the host's database, or append through the framework's own mechanism: a Durable Object, workflow checkpoint, or server action store. See [Stores](event-log.md#stores) and [Hosts and executors](hosts.md).
|
|
127
|
+
|
|
128
|
+
The recipe per turn is one call: `runToQuiescence` reads the thread, runs, and writes back.
|
|
129
|
+
|
|
130
|
+
```ts no-check
|
|
131
|
+
const result = await runToQuiescence(createAgentRuntime(machine, { store, threadId, executors }), {
|
|
132
|
+
event: incoming,
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The framework remains responsible for transactionality, retries, interruption recovery, and retention.
|