@statelyai/agent 2.0.0-alpha.37 → 2.0.0-alpha.39
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 +51 -0
- package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
- package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
- package/dist/ai-sdk.cjs +4 -4
- package/dist/ai-sdk.d.cts +2 -3
- package/dist/ai-sdk.d.mts +2 -3
- package/dist/ai-sdk.mjs +4 -4
- package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
- package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
- package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
- package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
- package/dist/effects-B9IvUPVh.mjs +23 -0
- package/dist/effects-DrWcUGgc.cjs +34 -0
- package/dist/evals.cjs +810 -0
- package/dist/evals.d.cts +595 -0
- package/dist/evals.d.mts +595 -0
- package/dist/evals.mjs +801 -0
- package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
- package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
- package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
- package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
- package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
- package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
- package/dist/index.cjs +136 -98
- package/dist/index.d.cts +73 -134
- package/dist/index.d.mts +73 -134
- package/dist/index.mjs +117 -75
- package/dist/internal-BzlpzSux.d.cts +14 -0
- package/dist/internal-BzlpzSux.d.mts +14 -0
- package/dist/log.cjs +2 -3
- package/dist/log.d.cts +2 -2
- package/dist/log.d.mts +2 -2
- package/dist/log.mjs +3 -3
- package/dist/machines.cjs +1 -719
- package/dist/machines.d.cts +2 -424
- package/dist/machines.d.mts +2 -424
- package/dist/machines.mjs +2 -709
- package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
- package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
- package/dist/openai.cjs +3 -3
- package/dist/openai.d.cts +2 -3
- package/dist/openai.d.mts +2 -3
- package/dist/openai.mjs +3 -3
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/policy.cjs +77 -0
- package/dist/policy.d.cts +143 -0
- package/dist/policy.d.mts +143 -0
- package/dist/policy.mjs +75 -0
- package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
- package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
- package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
- package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
- package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
- package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
- package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
- package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
- package/dist/tanstack-ai.cjs +4 -4
- package/dist/tanstack-ai.d.cts +2 -3
- package/dist/tanstack-ai.d.mts +2 -3
- package/dist/tanstack-ai.mjs +4 -4
- package/dist/testing.cjs +122 -996
- package/dist/testing.d.cts +36 -695
- package/dist/testing.d.mts +36 -695
- package/dist/testing.mjs +112 -977
- package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
- package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
- package/dist/trajectory-BFjXaooB.d.cts +96 -0
- package/dist/trajectory-BFjXaooB.d.mts +96 -0
- package/dist/trajectory-BUXj_1Ue.mjs +152 -0
- package/dist/trajectory-CoZSv4wF.cjs +157 -0
- package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
- package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
- package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
- package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
- package/dist/validate.cjs +4 -4
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +4 -4
- package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
- package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
- package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
- package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
- package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
- package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
- package/docs/advanced.md +5 -5
- package/docs/choosing-a-run-mode.md +7 -7
- package/docs/debugging.md +6 -8
- package/docs/decisions.md +6 -5
- package/docs/environment-and-policy.md +1 -1
- package/docs/evals.md +57 -43
- package/docs/event-log.md +14 -16
- package/docs/from-a-loop.md +3 -3
- package/docs/generate-machines.md +4 -4
- package/docs/hosts.md +22 -29
- package/docs/human-in-the-loop.md +5 -8
- package/docs/index.md +4 -4
- package/docs/judgments.md +5 -7
- package/docs/langgraph-comparison.md +6 -6
- package/docs/machines-as-data.md +12 -17
- package/docs/machines-presets.md +17 -120
- package/docs/machines.md +13 -13
- package/docs/models-and-providers.md +19 -25
- package/docs/multi-agent.md +1 -1
- package/docs/observability.md +6 -8
- package/docs/persistence.md +15 -25
- package/docs/quickstart.md +4 -4
- package/docs/statechart-policy-examples.md +1 -1
- package/docs/steps.md +5 -6
- package/docs/strangler-fig.md +72 -7
- package/docs/text-requests.md +10 -12
- package/docs/thinking-in-state-machines.md +8 -8
- package/docs/tools.md +10 -12
- package/docs/upgrading.md +1 -1
- package/docs/usage-and-budgets.md +51 -56
- package/docs/validate-and-repair.md +9 -14
- package/docs/verify.md +53 -7
- package/docs/xstate-4-and-5-apps.md +19 -28
- package/llms.txt +1 -1
- package/package.json +31 -6
- package/readme.md +32 -24
- package/dist/internal-C3Lqu538.d.cts +0 -43
- package/dist/internal-DUcdhk-i.d.mts +0 -43
- package/dist/types-DQUOOaZO.d.cts +0 -238
- package/dist/types-DQUOOaZO.d.mts +0 -238
- package/skills/add-evals/SKILL.md +0 -152
- package/skills/add-traces/SKILL.md +0 -152
- package/skills/build-machine/SKILL.md +0 -84
- package/skills/generate-machine/SKILL.md +0 -335
- package/skills/graph-engineering/SKILL.md +0 -43
- package/skills/improve-machine/SKILL.md +0 -261
- package/skills/improve-machine/reference.md +0 -101
- package/skills/loop-to-machine/SKILL.md +0 -205
- package/skills/loop-to-machine/policy.md +0 -154
- package/skills/loop-to-machine/reference.md +0 -260
|
@@ -17,7 +17,7 @@ Usage is available at three layers, listed from coarsest to finest.
|
|
|
17
17
|
|
|
18
18
|
The first two layers are observational. Only the third can change what the agent does.
|
|
19
19
|
|
|
20
|
-
<!-- viz: usage flow: executor result ->
|
|
20
|
+
<!-- viz: usage flow: executor result -> runAgent aggregation into result.usage, -> onResult/onTrace on the host, -> @agent.usage event into machine context and guards -->
|
|
21
21
|
|
|
22
22
|
## The usage result
|
|
23
23
|
|
|
@@ -26,7 +26,7 @@ The first two layers are observational. Only the third can change what the agent
|
|
|
26
26
|
Every settled `AgentRunResult` carries `usage`, on all three variants: `done`, `idle`, and `error`.
|
|
27
27
|
|
|
28
28
|
```ts
|
|
29
|
-
const result = await
|
|
29
|
+
const result = await runAgent(machine, { executors, input });
|
|
30
30
|
|
|
31
31
|
result.usage.modelCalls; // number, always present
|
|
32
32
|
result.usage.totalTokens; // number | undefined (only calls that reported it)
|
|
@@ -44,7 +44,7 @@ Four things affect how you read these numbers.
|
|
|
44
44
|
- Usage is per run, not per conversation. A resumed run counts only its own calls, not the history behind `snapshot` or `events`. Add prior results' totals yourself for a conversation-wide figure.
|
|
45
45
|
- A tool loop is one request but several model calls. An executor reports its steps as `modelCalls` on its result, and the adapters do. An executor that reports none counts as one call.
|
|
46
46
|
- Judgments are not counted. An `experimental_decide` actor is an ordinary actor, so its calls appear in neither `usage` nor `maxModelCalls`. See [Judgments](judgments.md).
|
|
47
|
-
- Usage comes from your executor. `
|
|
47
|
+
- Usage comes from your executor. `runAgent` reads `usage` from the raw executor result. That is the `usage` field alongside `result`, on the flat field names the AI SDK also uses, from an adapter or any custom executor following that shape. Non-finite values are dropped.
|
|
48
48
|
|
|
49
49
|
### Billing
|
|
50
50
|
|
|
@@ -80,23 +80,21 @@ Two callbacks report usage per call. Both are live and read-only.
|
|
|
80
80
|
- `onTrace` on a `request.end` event: `usage?: AgentCallUsage` is normalized, and present only when the executor reported usage. See [Observability](observability.md#trace-one-run).
|
|
81
81
|
|
|
82
82
|
```ts
|
|
83
|
-
await
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
{ input },
|
|
99
|
-
);
|
|
83
|
+
await runAgent(machine, {
|
|
84
|
+
executors,
|
|
85
|
+
onResult: (request, { raw }) => {
|
|
86
|
+
const usage = (raw as { usage?: AgentCallUsage }).usage;
|
|
87
|
+
if (usage) {
|
|
88
|
+
console.log(request.kind, request.id, usage);
|
|
89
|
+
}
|
|
90
|
+
},
|
|
91
|
+
onTrace: (event) => {
|
|
92
|
+
if (event.type === "request.end" && event.usage) {
|
|
93
|
+
console.log(event.request.id, event.usage.totalTokens);
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
input,
|
|
97
|
+
});
|
|
100
98
|
```
|
|
101
99
|
|
|
102
100
|
Use these for dashboards, per-tenant metering, and cost alerts. Neither can stop the run. To deliver usage to the machine, use [`@agent.usage`](#the-agentusage-event).
|
|
@@ -106,10 +104,7 @@ Use these for dashboards, per-tenant metering, and cost alerts. Neither can stop
|
|
|
106
104
|
`maxModelCalls` caps the number of model and decision calls one run may make. The default is `100`. Decision retries count separately.
|
|
107
105
|
|
|
108
106
|
```ts
|
|
109
|
-
const result = await
|
|
110
|
-
createAgentRuntime(machine, { executors, maxModelCalls: 20 }),
|
|
111
|
-
{ input },
|
|
112
|
-
);
|
|
107
|
+
const result = await runAgent(machine, { executors, maxModelCalls: 20, input });
|
|
113
108
|
|
|
114
109
|
if (result.status === "error" && result.cause === "max-model-calls") {
|
|
115
110
|
result.usage.modelCalls; // 20
|
|
@@ -128,10 +123,13 @@ if (result.status === "error" && result.cause === "max-model-calls") {
|
|
|
128
123
|
`maxModelCalls` is per run. For a conversation that resumes once per turn, pass the calls earlier turns spent as `modelCallsSpent`. They count against `maxModelCalls` and appear in `budget.modelCalls`, but not in this run's `usage.modelCalls`.
|
|
129
124
|
|
|
130
125
|
```ts no-check
|
|
131
|
-
const result = await
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
126
|
+
const result = await runAgent(machine, {
|
|
127
|
+
executors,
|
|
128
|
+
maxModelCalls: 30,
|
|
129
|
+
modelCallsSpent: thread.modelCalls,
|
|
130
|
+
snapshot,
|
|
131
|
+
event,
|
|
132
|
+
});
|
|
135
133
|
thread.modelCalls += result.usage.modelCalls;
|
|
136
134
|
```
|
|
137
135
|
|
|
@@ -172,9 +170,7 @@ function withBudget(base: AgentRequestExecutors, maxCalls: number): AgentRequest
|
|
|
172
170
|
};
|
|
173
171
|
}
|
|
174
172
|
|
|
175
|
-
await
|
|
176
|
-
input,
|
|
177
|
-
});
|
|
173
|
+
await runAgent(machine, { executors: withBudget(executors, 20), input });
|
|
178
174
|
```
|
|
179
175
|
|
|
180
176
|
A wrapper is still host-side. The machine cannot read its counts or react to them. For that, use `@agent.usage` and a guard.
|
|
@@ -215,7 +211,7 @@ Model-call results reach the machine with usage stripped out.
|
|
|
215
211
|
- A text invoke's `onDone` receives `{ result, messages }` only: the validated result and the executor's response messages. The runner drops the rest of the executor result, including usage (`src/run-agent.ts`).
|
|
216
212
|
- A decision delivers only the chosen event. `resolveDecision` returns the validated event and drops the executor's `usage` (`src/decision.ts`).
|
|
217
213
|
|
|
218
|
-
`@agent.usage` carries the tokens instead. After every settled model call that reported usage, `
|
|
214
|
+
`@agent.usage` carries the tokens instead. After every settled model call that reported usage, `runAgent` delivers the event to the machine, so `context` can fold it and guards can read it. You can then keep both counters in `context`: increment turns in `onDone`, and fold tokens in the `@agent.usage` handler.
|
|
219
215
|
|
|
220
216
|
### Rules
|
|
221
217
|
|
|
@@ -224,8 +220,8 @@ Model-call results reach the machine with usage stripped out.
|
|
|
224
220
|
| **Not model-facing** | The `@agent.*` namespace is excluded from `getAcceptedEvents` and `parseAgentEvent`. The event is never a decision candidate, even under `allowedEvents: ['*']`, and cannot be forged from a wire message. |
|
|
225
221
|
| **Durability** | The event is folded into machine context, so a native snapshot from `result.persist()` retains the counters when a later runtime resumes with `{ snapshot }`. |
|
|
226
222
|
| **Run scope** | `result.usage` counts calls made during that run only. Persist cumulative counters in machine context when they must survive snapshot resume. |
|
|
227
|
-
| **Stragglers** | A call that settles after a `
|
|
228
|
-
| **Coverage** | Only usage your executor reports is delivered. No `usage` on the result means no event. [`simulateAgent`](verify.md) scripts return no usage, so a token counter stays `0` under simulation. Test budgets with `
|
|
223
|
+
| **Stragglers** | A call that settles after a `runAgent` leg resolved still folds into `result.usage`, but its machine event is dropped. Watch `usage.dropped` on `onTrace` if a counter looks short. |
|
|
224
|
+
| **Coverage** | Only usage your executor reports is delivered. No `usage` on the result means no event. [`simulateAgent`](verify.md) scripts return no usage, so a token counter stays `0` under simulation. Test budgets with `runAgent` and a usage-reporting mock. |
|
|
229
225
|
|
|
230
226
|
Opt in with a transition.
|
|
231
227
|
|
|
@@ -267,8 +263,8 @@ import {
|
|
|
267
263
|
AGENT_USAGE_EVENT_TYPE,
|
|
268
264
|
createAgentSchemas,
|
|
269
265
|
createTextLogic,
|
|
270
|
-
runToQuiescence,
|
|
271
266
|
setupAgent,
|
|
267
|
+
runAgent,
|
|
272
268
|
} from "@statelyai/agent";
|
|
273
269
|
|
|
274
270
|
const researchStep = createTextLogic({
|
|
@@ -357,10 +353,11 @@ const executors = {
|
|
|
357
353
|
}),
|
|
358
354
|
};
|
|
359
355
|
|
|
360
|
-
const result = await
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
356
|
+
const result = await runAgent(machine, {
|
|
357
|
+
maxModelCalls: 20,
|
|
358
|
+
executors,
|
|
359
|
+
input: { topic: "otter migration", maxTurns: 5, maxTokens: 1500 },
|
|
360
|
+
});
|
|
364
361
|
|
|
365
362
|
if (result.status === "done") {
|
|
366
363
|
result.output.stoppedBy; // 'tokens' (3 calls, 1560 >= 1500)
|
|
@@ -397,11 +394,11 @@ deciding: {
|
|
|
397
394
|
}
|
|
398
395
|
```
|
|
399
396
|
|
|
400
|
-
## Usage without
|
|
397
|
+
## Usage without runAgent
|
|
401
398
|
|
|
402
399
|
### Uncontrolled: `provideExecutors` + `createActor`
|
|
403
400
|
|
|
404
|
-
Delivery is built in, but it follows the binding boundary. `provideExecutors` does not descend into invoked child machines, so a child with its own agent invokes needs its own `provideExecutors(...)` call. Until it has one, its calls report no usage anywhere. `
|
|
401
|
+
Delivery is built in, but it follows the binding boundary. `provideExecutors` does not descend into invoked child machines, so a child with its own agent invokes needs its own `provideExecutors(...)` call. Until it has one, its calls report no usage anywhere. `runAgent` rebinds children and reports their usage to the root. A [long-lived actor](choosing-a-run-mode.md#long-lived-actor) has no run cycle, so no stragglers are dropped either.
|
|
405
402
|
|
|
406
403
|
```ts no-check
|
|
407
404
|
import { createActor, toPromise } from "xstate";
|
|
@@ -481,21 +478,19 @@ estimateCost("openai/gpt-6-luna", result.usage);
|
|
|
481
478
|
```ts no-check
|
|
482
479
|
let spentUsd = 0;
|
|
483
480
|
|
|
484
|
-
await
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
{ input },
|
|
498
|
-
);
|
|
481
|
+
await runAgent(machine, {
|
|
482
|
+
executors,
|
|
483
|
+
onTrace: (event) => {
|
|
484
|
+
if (event.type !== "request.end" || !event.usage) {
|
|
485
|
+
return;
|
|
486
|
+
}
|
|
487
|
+
// A decision carries `model` directly; a text request carries it on `input`.
|
|
488
|
+
const model =
|
|
489
|
+
event.request.kind === "decision" ? event.request.model : event.request.input.model;
|
|
490
|
+
spentUsd += estimateCost(model, event.usage);
|
|
491
|
+
},
|
|
492
|
+
input,
|
|
493
|
+
});
|
|
499
494
|
```
|
|
500
495
|
|
|
501
496
|
`@agent.usage` carries the same `model` attribution, so the machine can keep a per-model spend counter in `context` and guard on it, instead of only reporting one from the host.
|
|
@@ -163,10 +163,7 @@ The machine's own cap is `checkingRepairBudget`. It is the one the app reasons a
|
|
|
163
163
|
`maxModelCalls` is the second cap, and a different kind. It is the host's runaway backstop, it counts every model and decision call in the run, and the machine cannot read it. See [Usage and budgets](usage-and-budgets.md#the-global-backstop-maxmodelcalls).
|
|
164
164
|
|
|
165
165
|
```ts no-check
|
|
166
|
-
const result = await
|
|
167
|
-
createAgentRuntime(machine, { executors, maxModelCalls: 10 }),
|
|
168
|
-
{ input },
|
|
169
|
-
);
|
|
166
|
+
const result = await runAgent(machine, { executors, maxModelCalls: 10, input });
|
|
170
167
|
```
|
|
171
168
|
|
|
172
169
|
With three author calls and `maxRepairs: 2`, a worst-case run makes five calls, so `result.usage.modelCalls` is `5`.
|
|
@@ -182,17 +179,15 @@ const answers: Record<string, string[]> = {
|
|
|
182
179
|
};
|
|
183
180
|
const calls: string[] = [];
|
|
184
181
|
|
|
185
|
-
const result = await
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
return { result: answers[request.name].shift() };
|
|
191
|
-
},
|
|
182
|
+
const result = await runAgent(machine, {
|
|
183
|
+
executors: {
|
|
184
|
+
generateText: async (request) => {
|
|
185
|
+
calls.push(request.name);
|
|
186
|
+
return { result: answers[request.name].shift() };
|
|
192
187
|
},
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
);
|
|
188
|
+
},
|
|
189
|
+
input: { prompt: "a turnstile" },
|
|
190
|
+
});
|
|
196
191
|
|
|
197
192
|
expect(result.output.repairs).toBe(1);
|
|
198
193
|
expect(calls).toEqual(["generateConfig", "generateConfig", "generateConfig", "repairConfig"]);
|
package/docs/verify.md
CHANGED
|
@@ -45,7 +45,7 @@ assertAgentMachine(machine, { warnings: true });
|
|
|
45
45
|
| `decide-without-events` | error | A state invokes `agent.decide` but neither it nor any ancestor handles any event, so the chosen event can never be delivered. |
|
|
46
46
|
| `decide-allows-human-event` | error | A decision's literal `allowedEvents` names an event the state or an ancestor handles through a transition tagged `meta: { actor: "human" }`, so the model is never offered it. See [Events a person sends](decisions.md#events-a-person-sends). |
|
|
47
47
|
| `invoke-without-on-error` | warning | An invoke declares no `onError`, and neither its state nor any ancestor handles an actor error, so a rejected request or actor lands the machine in an error state with no modeled recovery. Add `onError` targeting a `failed` final state or a bounded retry. |
|
|
48
|
-
| `direct-object-src` | warning | An invoke `src` is a direct object or machine value that `
|
|
48
|
+
| `direct-object-src` | warning | An invoke `src` is a direct object or machine value that `runAgent` cannot rebind, so it inherits no host executors. |
|
|
49
49
|
|
|
50
50
|
## Test assertions
|
|
51
51
|
|
|
@@ -75,7 +75,7 @@ test("happy path settles done", async () => {
|
|
|
75
75
|
});
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
Guards stay in force throughout. `canReach` and `simulateAgent` traverse the same machine transitions as `
|
|
78
|
+
Guards stay in force throughout. `canReach` and `simulateAgent` traverse the same machine transitions as `runAgent`, so a graph path that a guard rejects never counts as reachable. These tests pin the machine's shape as prompts and models change.
|
|
79
79
|
|
|
80
80
|
## Deterministic executors
|
|
81
81
|
|
|
@@ -93,13 +93,13 @@ const machine = emailDrafter.provide({
|
|
|
93
93
|
|
|
94
94
|
[examples/email-drafter/agent-logic.ts](https://github.com/statelyai/agent/blob/next/examples/email-drafter/agent-logic.ts) drives a full run this way, with fixed values and no model call.
|
|
95
95
|
|
|
96
|
-
Use deterministic executors when the test should exercise the real `
|
|
96
|
+
Use deterministic executors when the test should exercise the real `runAgent` path with canned model output. Use [`simulateAgent`](#scripted-playthroughs) when a model-free transition playthrough is enough.
|
|
97
97
|
|
|
98
98
|
## Scripted playthroughs
|
|
99
99
|
|
|
100
100
|
`simulateAgent(machine, { input, script, maxSteps? })` runs a deterministic, model-free transition playthrough. The `script` supplies responses as FIFO queues, so runs are reproducible.
|
|
101
101
|
|
|
102
|
-
This script keys by invoke **src**, not by request name. Executors that run the real `
|
|
102
|
+
This script keys by invoke **src**, not by request name. Executors that run the real `runAgent` path route by request name instead. See [Testing without a provider](evals.md#testing-without-a-provider).
|
|
103
103
|
|
|
104
104
|
- `decisions` holds the `ChosenEvent` to apply per decision, keyed by decision src, usually `agent.decide`.
|
|
105
105
|
- `text` holds output values for text requests, keyed by request src.
|
|
@@ -171,13 +171,13 @@ settled?.resolvedRequest; // { kind: 'text', src: 'parse', id: 'parse', outcome:
|
|
|
171
171
|
|
|
172
172
|
## Branch exploration
|
|
173
173
|
|
|
174
|
-
`explorePaths(machine, { input, maxDepth?, maxPaths?, maxNodes?, budget?, outputs?, errors?, payloads?, dedupeBy?, interleave?, children?, timers?, usage? })` enumerates decision and external-event branches without a model, and reports coverage.
|
|
174
|
+
`explorePaths(machine, { input, maxDepth?, maxPaths?, maxNodes?, budget?, outputs?, errors?, payloads?, dedupeBy?, interleave?, children?, timers?, usage?, steps? })` enumerates decision and external-event branches without a model, and reports coverage.
|
|
175
175
|
|
|
176
176
|
- At each decision, it forks one branch per candidate event. Guard-rejected candidates count in `prunedByGuard` and are not explored.
|
|
177
177
|
- A decision with no candidate the snapshot takes, because its guards refuse every one or the closed choice offers nothing, exhausts as it does in a live run. That branch records `{ type: 'xstate.error.actor', actorId }` and takes the invoke's `onError`. With no `onError`, it ends in an `error` terminal.
|
|
178
178
|
- At an idle wait, it forks one branch per externally accepted event and per armed timer. See [Timers](#timers).
|
|
179
179
|
- `outputs` is a map of output lists, keyed by src: a text request's src or any other invoked actor's src. A one-element list is a canned output, reused every time that src is reached. A text request resolves with it as its `result`. A longer list forks one branch per output. See [Payloads and invoke outputs](#payloads-and-invoke-outputs).
|
|
180
|
-
- A src with one canned output resolves without a fork, so it does not appear in the path.
|
|
180
|
+
- A src with one canned output resolves without a fork, so it does not appear in the path. `steps: true` records it. See [Steps](#steps).
|
|
181
181
|
- Each `done` terminal carries the machine's `output`, so one report lists every output the search reached.
|
|
182
182
|
- A src with no `outputs` entry halts that branch with a `needs-output` terminal instead of throwing. The terminal's `missingSrc` names it.
|
|
183
183
|
- `errors` is a map of canned failures per src. A src listed there forks an extra branch where that invoke is rejected, so states behind an `onError` are explored. A decision keys on its src, usually `agent.decide`, or on its invoke id; its success branch stays the per-candidate-event fork, so the failure is explored in addition to the candidates. The failure and the candidates are sibling branches: each spends one level of `maxDepth`.
|
|
@@ -219,6 +219,29 @@ const report = await explorePaths(machine, {
|
|
|
219
219
|
// report.terminals → one path per branch: the parsed state and the onError state
|
|
220
220
|
```
|
|
221
221
|
|
|
222
|
+
### Steps
|
|
223
|
+
|
|
224
|
+
`path` lists branch points only. `steps: true` adds `steps` to each terminal: every macrostep from the start, as an `ExploreStep`.
|
|
225
|
+
|
|
226
|
+
- `event`: the event the step processed. A host event, a fork, a canned output settling (`xstate.done.actor` or `xstate.error.actor`), or `xstate.init` for the start.
|
|
227
|
+
- `state`: the state value after the step.
|
|
228
|
+
- `started`: srcs of the invokes and spawned actors that started in the step. An actor restarted under the same id counts again.
|
|
229
|
+
- `settled`: srcs of the actors that finished, done or error, in the step.
|
|
230
|
+
|
|
231
|
+
```ts no-check
|
|
232
|
+
const report = await explorePaths(loopMachine, {
|
|
233
|
+
outputs: { turn: [{ kind: "continue" }] },
|
|
234
|
+
steps: true,
|
|
235
|
+
});
|
|
236
|
+
// report.terminals[0].steps → [
|
|
237
|
+
// { event: { type: "xstate.init" }, state: "running", started: ["turn"], settled: [] },
|
|
238
|
+
// { event: { type: "xstate.done.actor", actorId: "turn", … }, state: "running", started: ["turn"], settled: ["turn"] },
|
|
239
|
+
// …
|
|
240
|
+
// ]
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Steps are off by default: they cost memory for every step of every path. Steps cover the root machine. With `children: "coupled"`, a child's own moves show up through the events and outputs they deliver to the root.
|
|
244
|
+
|
|
222
245
|
### Payloads and invoke outputs
|
|
223
246
|
|
|
224
247
|
By default, events are applied as `{ type }`. A guard that reads the payload, such as `event.amount <= 100`, rejects every such event, so its target is never explored. Supply payloads to explore it.
|
|
@@ -416,6 +439,7 @@ Set `budget.ms` under the test runner's timeout, so a long search fails its asse
|
|
|
416
439
|
|
|
417
440
|
- A state path or state-node ID.
|
|
418
441
|
- A snapshot predicate, `(snapshot) => boolean`, for a property no single state names: a context invariant, a tag, a state plus context.
|
|
442
|
+
- An ordering, `{ after, reach }`, for a rule about order: "no turn starts after STOP". See [Ordering targets](#ordering-targets).
|
|
419
443
|
|
|
420
444
|
```ts no-check
|
|
421
445
|
const violation = await canReach(
|
|
@@ -467,6 +491,28 @@ const failure = await canReach(machine, "failed", {
|
|
|
467
491
|
// failure.reachable → true; failure.witness → [{ type: 'xstate.error.actor', actorId: 'parse' }]
|
|
468
492
|
```
|
|
469
493
|
|
|
494
|
+
### Ordering targets
|
|
495
|
+
|
|
496
|
+
A snapshot predicate sees one snapshot, so it cannot ask what happened earlier on the path. An ordering target can:
|
|
497
|
+
|
|
498
|
+
```ts no-check
|
|
499
|
+
const turnAfterStop = await canReach(
|
|
500
|
+
loopMachine,
|
|
501
|
+
{ after: "STOP", reach: (step) => step.started.includes("turn") },
|
|
502
|
+
{ outputs: { turn: [{ kind: "continue" }] }, interleave: "pending" },
|
|
503
|
+
);
|
|
504
|
+
// turnAfterStop.reachable → false with complete: true: no turn starts after STOP
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
- `after` and `reach` match [steps](#steps). `after` is an event type or a step predicate.
|
|
508
|
+
- `reach` is checked on each step after the first step that matched `after`, not on that step itself.
|
|
509
|
+
- `after` and `reach` may read an event's payload, so an event with no schema is unexpanded until `payloads` lists its variants, even when no transition reads it. A timer's step carries the event the timer delivers.
|
|
510
|
+
- The witness is the event sequence to the first violation.
|
|
511
|
+
- A turn already running when STOP arrives started before it, so it is not a violation. Check that turn with `settled` if the rule covers it.
|
|
512
|
+
- `dedupeBy` stays sound: the search adds "`after` has matched" to each key, so a snapshot reached before and after the trigger is explored both ways.
|
|
513
|
+
- Test the rule with a mutant that breaks it (a loop that starts another turn after STOP), as with a loosened guard.
|
|
514
|
+
- Don't match strings over `terminal.path` for an ordering rule: it lists branch points only and names actors by generated id.
|
|
515
|
+
|
|
470
516
|
## CI checks
|
|
471
517
|
|
|
472
518
|
Everything on this page runs without an API key, so a small script is enough for CI or a generation loop.
|
|
@@ -486,7 +532,7 @@ For machines authored as data, validate the config with `validateAgentConfig(con
|
|
|
486
532
|
- [Crash testing](persistence.md#crash-testing): `checkCrashRecovery` kills a run at every log append and in-flight effect, and checks each resume.
|
|
487
533
|
- [Debugging](debugging.md): scripted reproduction and the diagnostic codes in context.
|
|
488
534
|
- [Evals](evals.md): scoring runs on output, trajectory, and budget.
|
|
489
|
-
- [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `
|
|
535
|
+
- [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `runAgent`.
|
|
490
536
|
- [Machines as data](machines-as-data.md): verifying a machine lowered from a config.
|
|
491
537
|
- [Migrating from a hand-rolled loop](from-a-loop.md): pinning behavior across a refactor.
|
|
492
538
|
- [examples/verification](https://github.com/statelyai/agent/blob/next/examples/verification/index.ts): every API on this page run over one refund-approval machine, with no API key, including `canReach` proving that an over-limit payout without human approval is unreachable.
|
|
@@ -7,7 +7,7 @@ description: Isolate @statelyai/agent behind a workspace package so an app on XS
|
|
|
7
7
|
|
|
8
8
|
<!-- versions from package.json version and peerDependencies.xstate -->
|
|
9
9
|
|
|
10
|
-
`@statelyai/agent` peers on exactly `xstate@6.0.0-beta.
|
|
10
|
+
The current source of `@statelyai/agent` peers on exactly `xstate@6.0.0-beta.2`. The published `2.0.0-alpha.29` release used in this recipe peers on `xstate@6.0.0-alpha.69`; use that matching pair until a beta.2-compatible agent release is published. An app already using XState 4 or 5 for its own machines cannot install both versions into one `node_modules` tree and have each resolve the one it needs. This page isolates the agent in its own workspace package so the app keeps its XState version and never imports XState 6.
|
|
11
11
|
|
|
12
12
|
The same page applies to an app with no XState at all that cannot take a prerelease dependency in its main tree.
|
|
13
13
|
|
|
@@ -34,7 +34,7 @@ Put the agent in a workspace package that owns its own dependencies, and give th
|
|
|
34
34
|
"@statelyai/agent": "2.0.0-alpha.29",
|
|
35
35
|
"@ai-sdk/openai": "^4.0.0",
|
|
36
36
|
"ai": "^7.0.128",
|
|
37
|
-
"xstate": "6.0.0-
|
|
37
|
+
"xstate": "6.0.0-alpha.69",
|
|
38
38
|
"zod": "^4.4.3"
|
|
39
39
|
}
|
|
40
40
|
}
|
|
@@ -48,7 +48,7 @@ One async function in, one JSON-safe object out. Everything XState is inside it.
|
|
|
48
48
|
|
|
49
49
|
```ts no-check
|
|
50
50
|
// packages/agent/src/index.ts
|
|
51
|
-
import {
|
|
51
|
+
import { runAgent } from "@statelyai/agent";
|
|
52
52
|
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
53
53
|
import { models, generationMachine } from "./machine.js";
|
|
54
54
|
|
|
@@ -72,13 +72,11 @@ export async function runGeneration(
|
|
|
72
72
|
input: GenerationInput,
|
|
73
73
|
deps: GenerationDeps,
|
|
74
74
|
): Promise<GenerationOutput> {
|
|
75
|
-
const result = await
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
{ input },
|
|
81
|
-
);
|
|
75
|
+
const result = await runAgent(generationMachine(deps.lookup), {
|
|
76
|
+
executors: createAiSdkExecutors({ models }),
|
|
77
|
+
onTransition: (snapshot) => deps.onProgress?.(String(snapshot.value)),
|
|
78
|
+
input,
|
|
79
|
+
});
|
|
82
80
|
if (result.status !== "done") {
|
|
83
81
|
throw new Error(`Generation did not complete: ${result.status}`);
|
|
84
82
|
}
|
|
@@ -109,9 +107,9 @@ export async function POST(request: Request) {
|
|
|
109
107
|
|
|
110
108
|
## What can cross the boundary
|
|
111
109
|
|
|
112
|
-
Persisted snapshots are JSON. `result.persist()` returns a plain JSON value, and `
|
|
110
|
+
Persisted snapshots are JSON. `result.persist()` returns a plain JSON value, and `runAgent(machine, { snapshot, event })` takes one back, so a paused run can be stored by the app, in its own database, and resumed by a later call into the package. Pair `snapshot` with the `event` that unblocks the idle state: a resume with `snapshot` alone starts the run back at the same wait.
|
|
113
111
|
|
|
114
|
-
<!--
|
|
112
|
+
<!-- runAgent snapshot/event resume from src/run-agent.ts; exercised by src/docs-integration-recipes.test.ts -->
|
|
115
113
|
|
|
116
114
|
```ts no-check
|
|
117
115
|
// Inside the package: the app stores and returns the value, and never reads it.
|
|
@@ -121,12 +119,10 @@ export async function startGeneration(
|
|
|
121
119
|
input: GenerationInput,
|
|
122
120
|
deps: GenerationDeps,
|
|
123
121
|
): Promise<{ snapshot: unknown }> {
|
|
124
|
-
const result = await
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
{ input },
|
|
129
|
-
);
|
|
122
|
+
const result = await runAgent(generationMachine(deps.lookup), {
|
|
123
|
+
executors: createAiSdkExecutors({ models }),
|
|
124
|
+
input,
|
|
125
|
+
});
|
|
130
126
|
return { snapshot: result.status === "idle" ? result.persist() : null };
|
|
131
127
|
}
|
|
132
128
|
|
|
@@ -135,16 +131,11 @@ export async function resumeGeneration(
|
|
|
135
131
|
answer: string,
|
|
136
132
|
deps: GenerationDeps,
|
|
137
133
|
): Promise<GenerationOutput> {
|
|
138
|
-
const result = await
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
// Opaque to the app, typed again here at the package boundary.
|
|
144
|
-
snapshot: snapshot as Snapshot<unknown>,
|
|
145
|
-
event: { type: "ANSWER", answer },
|
|
146
|
-
},
|
|
147
|
-
);
|
|
134
|
+
const result = await runAgent(generationMachine(deps.lookup), {
|
|
135
|
+
executors: createAiSdkExecutors({ models }), // Opaque to the app, typed again here at the package boundary.
|
|
136
|
+
snapshot: snapshot as Snapshot<unknown>,
|
|
137
|
+
event: { type: "ANSWER", answer },
|
|
138
|
+
});
|
|
148
139
|
if (result.status !== "done") {
|
|
149
140
|
throw new Error(`Generation did not complete: ${result.status}`);
|
|
150
141
|
}
|
package/llms.txt
CHANGED
|
@@ -21,7 +21,7 @@ Not v5: transitions are plain functions returning `{ target, context }` (no `ass
|
|
|
21
21
|
- [Tools](docs/tools.md): Define tools, attach them to a text request, and let the host run the tool loop while the machine stays in one state.
|
|
22
22
|
- [Judgments with the AI SDK](docs/judgments.md): Ask classification, grading, relevance, and yes/no questions with the AI SDK's experimental_decide and Jev, and branch on the typed answers in a machine.
|
|
23
23
|
- [Messages](docs/messages.md): Build and store conversation history as a parts-based message model that mirrors the AI SDK without depending on it.
|
|
24
|
-
- [Preset machines](docs/machines-presets.md):
|
|
24
|
+
- [Preset machines](docs/machines-presets.md): `createApprovalBatchMachine`, which gates one model turn's tool calls on approval.
|
|
25
25
|
- [Choosing a run mode](docs/choosing-a-run-mode.md): Three ways to execute the same agent machine, what each one owns, and which to reach for.
|
|
26
26
|
- [Hosts and executors](docs/hosts.md): Give an agent machine the executor functions that call a model, and choose between the shipped AI SDK adapter or your own.
|
|
27
27
|
- [Use in any stack](docs/any-stack.md): One agent machine runs unchanged in a local script, an HTTP route, or an edge runtime. Only the executors are host-specific.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statelyai/agent",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.39",
|
|
4
4
|
"description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -21,7 +21,6 @@
|
|
|
21
21
|
"files": [
|
|
22
22
|
"dist",
|
|
23
23
|
"schemas",
|
|
24
|
-
"skills",
|
|
25
24
|
"docs",
|
|
26
25
|
"!docs/snippet-globals.ts",
|
|
27
26
|
"llms.txt",
|
|
@@ -36,6 +35,9 @@
|
|
|
36
35
|
"ai-sdk": [
|
|
37
36
|
"./dist/ai-sdk.d.mts"
|
|
38
37
|
],
|
|
38
|
+
"evals": [
|
|
39
|
+
"./dist/evals.d.mts"
|
|
40
|
+
],
|
|
39
41
|
"log": [
|
|
40
42
|
"./dist/log.d.mts"
|
|
41
43
|
],
|
|
@@ -48,6 +50,9 @@
|
|
|
48
50
|
"otel": [
|
|
49
51
|
"./dist/otel.d.mts"
|
|
50
52
|
],
|
|
53
|
+
"policy": [
|
|
54
|
+
"./dist/policy.d.mts"
|
|
55
|
+
],
|
|
51
56
|
"tanstack-ai": [
|
|
52
57
|
"./dist/tanstack-ai.d.mts"
|
|
53
58
|
],
|
|
@@ -80,6 +85,16 @@
|
|
|
80
85
|
"default": "./dist/ai-sdk.cjs"
|
|
81
86
|
}
|
|
82
87
|
},
|
|
88
|
+
"./evals": {
|
|
89
|
+
"import": {
|
|
90
|
+
"types": "./dist/evals.d.mts",
|
|
91
|
+
"default": "./dist/evals.mjs"
|
|
92
|
+
},
|
|
93
|
+
"require": {
|
|
94
|
+
"types": "./dist/evals.d.cts",
|
|
95
|
+
"default": "./dist/evals.cjs"
|
|
96
|
+
}
|
|
97
|
+
},
|
|
83
98
|
"./log": {
|
|
84
99
|
"import": {
|
|
85
100
|
"types": "./dist/log.d.mts",
|
|
@@ -120,6 +135,16 @@
|
|
|
120
135
|
"default": "./dist/otel.cjs"
|
|
121
136
|
}
|
|
122
137
|
},
|
|
138
|
+
"./policy": {
|
|
139
|
+
"import": {
|
|
140
|
+
"types": "./dist/policy.d.mts",
|
|
141
|
+
"default": "./dist/policy.mjs"
|
|
142
|
+
},
|
|
143
|
+
"require": {
|
|
144
|
+
"types": "./dist/policy.d.cts",
|
|
145
|
+
"default": "./dist/policy.cjs"
|
|
146
|
+
}
|
|
147
|
+
},
|
|
123
148
|
"./tanstack-ai": {
|
|
124
149
|
"import": {
|
|
125
150
|
"types": "./dist/tanstack-ai.d.mts",
|
|
@@ -168,7 +193,7 @@
|
|
|
168
193
|
"@opentelemetry/api": "^1.9.1",
|
|
169
194
|
"@opentelemetry/context-async-hooks": "^2.12.0",
|
|
170
195
|
"@opentelemetry/sdk-trace-base": "^2.12.0",
|
|
171
|
-
"@statelyai/sdk": "0.
|
|
196
|
+
"@statelyai/sdk": "0.47.0",
|
|
172
197
|
"@tanstack/ai": "^0.66.0",
|
|
173
198
|
"@types/node": "^22.20.5",
|
|
174
199
|
"@types/react": "^19.3.0",
|
|
@@ -187,7 +212,7 @@
|
|
|
187
212
|
"twoslash": "^0.3.9",
|
|
188
213
|
"typescript": "^7.0.2",
|
|
189
214
|
"vitest": "^5.0.3",
|
|
190
|
-
"xstate": "6.0.0-beta.
|
|
215
|
+
"xstate": "6.0.0-beta.2",
|
|
191
216
|
"zod": "^4.6.5"
|
|
192
217
|
},
|
|
193
218
|
"peerDependencies": {
|
|
@@ -196,7 +221,7 @@
|
|
|
196
221
|
"ai": "*",
|
|
197
222
|
"ajv": "*",
|
|
198
223
|
"openai": "*",
|
|
199
|
-
"xstate": "6.0.0-beta.
|
|
224
|
+
"xstate": "6.0.0-beta.2"
|
|
200
225
|
},
|
|
201
226
|
"peerDependenciesMeta": {
|
|
202
227
|
"@opentelemetry/api": {
|
|
@@ -227,7 +252,7 @@
|
|
|
227
252
|
"proto:prefabs": "tsx .scratch/prefabs/demo.ts",
|
|
228
253
|
"docs:check": "tsx scripts/check-docs-snippets.ts",
|
|
229
254
|
"typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples && pnpm run typecheck:example-packages",
|
|
230
|
-
"typecheck:src": "tsc --noEmit",
|
|
255
|
+
"typecheck:src": "tsc --noEmit && tsc -p tsconfig.exact-optional.json",
|
|
231
256
|
"typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
|
|
232
257
|
"typecheck:example-packages": "pnpm run build && tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit && tsc -p demo --noEmit",
|
|
233
258
|
"test:cloudflare": "pnpm --filter @statelyai/example-cloudflare-agent-host test && pnpm --filter @statelyai/example-cloudflare-workers-ai-host test",
|