@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
package/docs/decisions.md
CHANGED
|
@@ -52,7 +52,7 @@ deciding: {
|
|
|
52
52
|
|
|
53
53
|
The `allowedEvents` list is typed against the machine's user-authored event schema, so a typo is a compile error. Framework events such as `@agent.usage` can be handled by the machine but are never model-facing candidates. Listing events explicitly also makes the candidate set visible in the machine.
|
|
54
54
|
|
|
55
|
-
> **Note:** `agent.decide` needs a snapshot-aware host such as `
|
|
55
|
+
> **Note:** `agent.decide` needs a snapshot-aware host such as `runAgent` to know which events are currently legal. With a [long-lived actor](choosing-a-run-mode.md#long-lived-actor), list `allowedEvents` explicitly. Wildcards and the omitted default cannot expand there.
|
|
56
56
|
|
|
57
57
|
### `allowedEvents` patterns
|
|
58
58
|
|
|
@@ -100,7 +100,7 @@ Guards are transition functions that return `undefined`. See [Transitions](machi
|
|
|
100
100
|
|
|
101
101
|
The candidate set is the `allowedEvents` list intersected with the events the state statically accepts. After the model picks one, `snapshot.can(event)` decides whether it is legal in the current snapshot. A chosen `ASK` on the final turn is rejected, and the model is asked again.
|
|
102
102
|
|
|
103
|
-
`
|
|
103
|
+
`runAgent` performs this check for you. When you call `resolveDecision` directly with a [long-lived actor](choosing-a-run-mode.md#long-lived-actor), pass the check through `canTake`:
|
|
104
104
|
|
|
105
105
|
```ts
|
|
106
106
|
import { resolveDecision } from "@statelyai/agent";
|
|
@@ -170,7 +170,7 @@ Retry behavior:
|
|
|
170
170
|
|
|
171
171
|
Core validates and retries. It never calls a model. Coercing the model into choosing exactly one option is the host's responsibility. The shipped AI SDK, OpenAI, and TanStack AI executors offer two modes, set by the `decideMode` option on each adapter:
|
|
172
172
|
|
|
173
|
-
- `'object'` (default for object payloads): one structured-output call. An open choice answers `{ event }`, where `event` is one candidate event, `type` included. Root unions of object payloads become separate event variants. A closed choice answers `{ choice }`, an enum of option ids. The
|
|
173
|
+
- `'object'` (default for object payloads): one structured-output call. An open choice answers `{ event }`, where `event` is one candidate event, `type` included. Root unions of object payloads become separate event variants. A closed choice answers `{ choice }`, an enum of option ids. The schema allows only one event per answer.
|
|
174
174
|
- `'tool'`: one tool per candidate event under a forced tool choice. Parallel tool calls are turned off where the provider allows it, and an answer that still calls more than one tool is rejected.
|
|
175
175
|
- A function of the request picks the mode per request. Returning `undefined` uses the default: `'object'` when every payload can be represented as object variants, otherwise `'tool'`. This avoids unsupported `allOf` schemas in strict structured-output providers.
|
|
176
176
|
|
|
@@ -375,7 +375,8 @@ A decision model such as Jev answers only closed choices. `'pick-then-fill'` tur
|
|
|
375
375
|
A decision can be answered by another machine: a policy that applies a rule when the facts are enough and asks a model only for the rest. `createPolicyDecider` turns a policy machine into a decide executor.
|
|
376
376
|
|
|
377
377
|
```ts no-check
|
|
378
|
-
import {
|
|
378
|
+
import { runAgent } from "@statelyai/agent";
|
|
379
|
+
import { createPolicyDecider } from "@statelyai/agent/policy";
|
|
379
380
|
|
|
380
381
|
const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
|
|
381
382
|
|
|
@@ -408,7 +409,7 @@ A machine does not have to know about AI. `decideNext` asks a model to pick one
|
|
|
408
409
|
- It never sends. The host sends the event, after checking `can` again, because the actor may have moved while the model was choosing.
|
|
409
410
|
|
|
410
411
|
```ts
|
|
411
|
-
import { decideNext } from "@statelyai/agent";
|
|
412
|
+
import { decideNext } from "@statelyai/agent/policy";
|
|
412
413
|
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
413
414
|
import { openai } from "@ai-sdk/openai";
|
|
414
415
|
import { createActor, createMachine } from "xstate";
|
|
@@ -182,7 +182,7 @@ The split pays off when there is a policy worth learning. Skip it in these cases
|
|
|
182
182
|
- [Machines as data](machines-as-data.md): the config format and `describeMachine`.
|
|
183
183
|
- [Testing and verification](verify.md): `canReach`, `explorePaths`, and payload variants.
|
|
184
184
|
- [Event log](event-log.md) and [Persistence](persistence.md): stores, threads, and replay.
|
|
185
|
-
- The [`graph-engineering`](https://github.com/statelyai/
|
|
185
|
+
- The [`graph-engineering`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/graph-engineering/SKILL.md) skill routes existing code to [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md), which converts the loop and checks parity with `compareRuns`. It routes new policies to [`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md). Then [`add-traces`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-traces/SKILL.md) persists runs, [`add-evals`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-evals/SKILL.md) writes evaluations for each state, and [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) proposes a pull request from traces, or reports that no candidate beat the current policy.
|
|
186
186
|
- [examples/self-improving-refunds](https://github.com/statelyai/agent/blob/next/examples/self-improving-refunds): a refund desk as the environment, JSON playbooks as the policy, an improvement loop, and a benchmark against a raw tool loop.
|
|
187
187
|
- [examples/code-review-loop](https://github.com/statelyai/agent/blob/next/examples/code-review-loop): review gates as the environment, a triage policy improved from traces against hidden tests, run with Claude Code in headless mode.
|
|
188
188
|
- [examples/tic-tac-toe](https://github.com/statelyai/agent/blob/next/examples/tic-tac-toe): a game as the environment, a policy over board features, and a `canReach` proof that it never loses as the bar for promotion.
|
package/docs/evals.md
CHANGED
|
@@ -4,7 +4,7 @@ Agent requests are independently executable, while the machine gives them meanin
|
|
|
4
4
|
|
|
5
5
|
## Testing without a provider
|
|
6
6
|
|
|
7
|
-
A test runs the real machine through `
|
|
7
|
+
A test runs the real machine through `runAgent` and replaces only the model. `@statelyai/agent` ships no model mock. There are two ways to replace the model:
|
|
8
8
|
|
|
9
9
|
- Mock the provider with the AI SDK's `MockLanguageModelV3`. The call still runs through `createAiSdkExecutors`, so the test covers prompt rendering, structured output parsing, and decision tool calls.
|
|
10
10
|
- Pass plain functions as executors. The test covers the machine only.
|
|
@@ -68,7 +68,7 @@ const machine = agent.createMachine({
|
|
|
68
68
|
|
|
69
69
|
```ts
|
|
70
70
|
import { MockLanguageModelV3 } from "ai/test";
|
|
71
|
-
import {
|
|
71
|
+
import { runAgent } from "@statelyai/agent";
|
|
72
72
|
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
73
73
|
|
|
74
74
|
function mockModel(text: string) {
|
|
@@ -88,10 +88,10 @@ function mockModel(text: string) {
|
|
|
88
88
|
const writer = mockModel("Checkout now supports saved cards.");
|
|
89
89
|
const judge = mockModel(JSON.stringify({ result: { score: 4 } }));
|
|
90
90
|
|
|
91
|
-
const result = await
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
);
|
|
91
|
+
const result = await runAgent(machine, {
|
|
92
|
+
executors: createAiSdkExecutors({ models: { writer, judge } }),
|
|
93
|
+
input: { topic: "saved cards at checkout" },
|
|
94
|
+
});
|
|
95
95
|
|
|
96
96
|
if (result.status === "done") {
|
|
97
97
|
console.log(result.output); // { draft: "Checkout now supports saved cards.", score: 4 }
|
|
@@ -112,28 +112,26 @@ The mock answers in the provider's format, not the request's:
|
|
|
112
112
|
An executor is a function of the request. Route on `request.name` to answer each request, and return the output value as `result`.
|
|
113
113
|
|
|
114
114
|
```ts
|
|
115
|
-
import {
|
|
115
|
+
import { runAgent } from "@statelyai/agent";
|
|
116
116
|
|
|
117
117
|
const calls: string[] = [];
|
|
118
118
|
|
|
119
|
-
const result = await
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
}
|
|
132
|
-
},
|
|
119
|
+
const result = await runAgent(machine, {
|
|
120
|
+
executors: {
|
|
121
|
+
generateText: async (request) => {
|
|
122
|
+
calls.push(request.name ?? "");
|
|
123
|
+
switch (request.name) {
|
|
124
|
+
case "draftEmail":
|
|
125
|
+
return { result: "Checkout now supports saved cards." };
|
|
126
|
+
case "scoreDraft":
|
|
127
|
+
return { result: { score: 4 } };
|
|
128
|
+
default:
|
|
129
|
+
throw new Error(`No answer for request "${request.name}"`);
|
|
130
|
+
}
|
|
133
131
|
},
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
);
|
|
132
|
+
},
|
|
133
|
+
input: { topic: "saved cards at checkout" },
|
|
134
|
+
});
|
|
137
135
|
|
|
138
136
|
console.log(calls); // ["draftEmail", "scoreDraft"]
|
|
139
137
|
```
|
|
@@ -199,10 +197,10 @@ A queue that runs dry throws an `AgentError` with code `seam-script-exhausted`,
|
|
|
199
197
|
|
|
200
198
|
## Per-state stats
|
|
201
199
|
|
|
202
|
-
`foldTraces` (from `@statelyai/agent/
|
|
200
|
+
`foldTraces` (from `@statelyai/agent/evals`) folds many runs' traces into one row per state: how many runs visited it, how many of those failed, how many options the guards withheld at decisions made there, and how many events it ignored.
|
|
203
201
|
|
|
204
202
|
```ts no-check
|
|
205
|
-
import { foldTraces } from "@statelyai/agent/
|
|
203
|
+
import { foldTraces } from "@statelyai/agent/evals";
|
|
206
204
|
|
|
207
205
|
// One AgentTraceEvent[] per run, collected with onTrace.
|
|
208
206
|
const stats = foldTraces(traces, {
|
|
@@ -224,10 +222,10 @@ const stats = foldTraces(traces, {
|
|
|
224
222
|
|
|
225
223
|
## Decision requests from traces
|
|
226
224
|
|
|
227
|
-
`getDecisionRequests` (from `@statelyai/agent/
|
|
225
|
+
`getDecisionRequests` (from `@statelyai/agent/evals`) lists the decisions a run asked for, read from its trace: each decision's first `request.start`, and the states the run was in.
|
|
228
226
|
|
|
229
227
|
```ts no-check
|
|
230
|
-
import { getDecisionRequests } from "@statelyai/agent/
|
|
228
|
+
import { getDecisionRequests } from "@statelyai/agent/evals";
|
|
231
229
|
|
|
232
230
|
for (const { states, request } of getDecisionRequests(trace, { name: "chooseResolution" })) {
|
|
233
231
|
const { event } = await decide(request); // a candidate decider
|
|
@@ -245,6 +243,20 @@ for (const { states, request } of getDecisionRequests(trace, { name: "chooseReso
|
|
|
245
243
|
|
|
246
244
|
## Parity with the code you replace
|
|
247
245
|
|
|
246
|
+
Start with `checkParity`. Pick a lower-level tool only when the old code does not route its side effects through one object.
|
|
247
|
+
|
|
248
|
+
| The old code | Use | Compares |
|
|
249
|
+
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
|
|
250
|
+
| Sends every side effect through one `effects` object | `checkParity`, see [Check parity](strangler-fig.md#check-parity) | Each effect's name, order, arguments, and result |
|
|
251
|
+
| Calls a model client or SDK directly | `createRecorder` and `compareRecordings`, see [Any model client](#any-model-client) | Each recorded call and the output |
|
|
252
|
+
| Changes on purpose, or a live model makes calls differ each run | `compareRuns`, see [Outcome labels](#outcome-labels) | The terminal outcome, the effects, and rule breaks |
|
|
253
|
+
|
|
254
|
+
`checkParity` records `before` with `createRecorder`, replays `after` against the recording, and compares the two with `compareRecordings`, in one call per scenario.
|
|
255
|
+
|
|
256
|
+
`compareRuns` labels a difference `intended` only when the candidate fixes a rule the baseline broke, or only the candidate reaches the scenario's `expected` outcome. Any other difference is a `regression`, including an effect the candidate adds on purpose with the same outcome. See [Outcome labels](#outcome-labels).
|
|
257
|
+
|
|
258
|
+
### Outcome labels
|
|
259
|
+
|
|
248
260
|
`compareRuns` (from `@statelyai/agent/testing`) runs every scenario through the existing implementation and its replacement, and labels each difference. Use it when you port a loop to a machine and need to show where they behave the same and where the machine differs on purpose.
|
|
249
261
|
|
|
250
262
|
```ts no-check
|
|
@@ -335,10 +347,11 @@ compareRecordings(recorder.recording, replay.recording); // { equivalent: true,
|
|
|
335
347
|
|
|
336
348
|
## Suite coverage
|
|
337
349
|
|
|
338
|
-
`traceCoverage` (from `@statelyai/agent/
|
|
350
|
+
`traceCoverage` (from `@statelyai/agent/evals`) reports which states and handlers no trace exercised, so a suite can say how much of the machine it covers.
|
|
339
351
|
|
|
340
352
|
```ts no-check
|
|
341
|
-
import { explorePaths
|
|
353
|
+
import { explorePaths } from "@statelyai/agent/testing";
|
|
354
|
+
import { traceCoverage } from "@statelyai/agent/evals";
|
|
342
355
|
|
|
343
356
|
const report = traceCoverage(machine, traces, {
|
|
344
357
|
reachable: await explorePaths(machine, { input }),
|
|
@@ -362,10 +375,10 @@ report.handlers[0];
|
|
|
362
375
|
|
|
363
376
|
## Where failures start
|
|
364
377
|
|
|
365
|
-
`firstDivergence` (from `@statelyai/agent/
|
|
378
|
+
`firstDivergence` (from `@statelyai/agent/evals`) finds the first step where a run departs from a reference, and names the state the run was in.
|
|
366
379
|
|
|
367
380
|
```ts no-check
|
|
368
|
-
import { firstDivergence, foldTraces } from "@statelyai/agent/
|
|
381
|
+
import { firstDivergence, foldTraces } from "@statelyai/agent/evals";
|
|
369
382
|
|
|
370
383
|
firstDivergence(failingTrace, passingTrace);
|
|
371
384
|
// { index: 0, state: "deciding", decision: "chooseResolution", actual: { event: "escalate", … }, expected: { event: "refund", … } }
|
|
@@ -391,10 +404,10 @@ const stats = foldTraces(traces, {
|
|
|
391
404
|
|
|
392
405
|
## Proposals from traces
|
|
393
406
|
|
|
394
|
-
`proposeApprovalRules` and `proposeCaps` (from `@statelyai/agent/
|
|
407
|
+
`proposeApprovalRules` and `proposeCaps` (from `@statelyai/agent/evals`) read many runs' traces and propose changes for a machine with no decision point: which approvals a rule could answer, and what each cap should be. They are proposals for a person. Nothing promotes them or edits the machine.
|
|
395
408
|
|
|
396
409
|
```ts no-check
|
|
397
|
-
import { proposeApprovalRules, proposeCaps } from "@statelyai/agent/
|
|
410
|
+
import { proposeApprovalRules, proposeCaps } from "@statelyai/agent/evals";
|
|
398
411
|
|
|
399
412
|
const rules = proposeApprovalRules(traces, {
|
|
400
413
|
approvalState: "awaitingApproval",
|
|
@@ -424,20 +437,21 @@ const caps = proposeCaps(traces, {
|
|
|
424
437
|
|
|
425
438
|
## Repeated runs
|
|
426
439
|
|
|
427
|
-
`repeatRuns` (from `@statelyai/agent/
|
|
440
|
+
`repeatRuns` (from `@statelyai/agent/evals`) runs every scenario `k` times and reports how reliably each one passes. With a live model, one run per scenario says little: τ-bench found the rate at which all `k` runs of a task pass (pass^k) falls well below the single-run rate.
|
|
428
441
|
|
|
429
442
|
```ts no-check
|
|
430
|
-
import { repeatRuns } from "@statelyai/agent/
|
|
443
|
+
import { repeatRuns } from "@statelyai/agent/evals";
|
|
431
444
|
|
|
432
445
|
const report = await repeatRuns({
|
|
433
446
|
scenarios, // [{ id, ...your fields }]
|
|
434
447
|
k: 5,
|
|
435
448
|
run: async (scenario, attempt) => {
|
|
436
449
|
const trace: AgentTraceEvent[] = [];
|
|
437
|
-
const result = await
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
450
|
+
const result = await runAgent(machine, {
|
|
451
|
+
executors,
|
|
452
|
+
onTrace: (event) => trace.push(event),
|
|
453
|
+
input: scenario.input,
|
|
454
|
+
});
|
|
441
455
|
return { trace, outcome: String(result.snapshot.value) };
|
|
442
456
|
},
|
|
443
457
|
passed: (scenario, { outcome }) => outcome === scenario.expected,
|
|
@@ -459,7 +473,7 @@ report.passHat(5); // the chance 5 runs of a scenario all pass
|
|
|
459
473
|
For runs collected elsewhere, such as CI shards or production replays, `summarizeRepeats` takes the runs per scenario and returns the same report. `repeatRuns` collects runs and calls it.
|
|
460
474
|
|
|
461
475
|
```ts no-check
|
|
462
|
-
import { summarizeRepeats } from "@statelyai/agent/
|
|
476
|
+
import { summarizeRepeats } from "@statelyai/agent/evals";
|
|
463
477
|
|
|
464
478
|
const report = summarizeRepeats([
|
|
465
479
|
{
|
|
@@ -475,10 +489,10 @@ const report = summarizeRepeats([
|
|
|
475
489
|
|
|
476
490
|
## Judge agreement
|
|
477
491
|
|
|
478
|
-
`judgeAgreement` (from `@statelyai/agent/
|
|
492
|
+
`judgeAgreement` (from `@statelyai/agent/evals`) measures how well a judge agrees with people on the same cases. Check it before a judge-graded eval gates anything.
|
|
479
493
|
|
|
480
494
|
```ts no-check
|
|
481
|
-
import { judgeAgreement } from "@statelyai/agent/
|
|
495
|
+
import { judgeAgreement } from "@statelyai/agent/evals";
|
|
482
496
|
|
|
483
497
|
const report = judgeAgreement(
|
|
484
498
|
confirmed.map((row) => ({
|
package/docs/event-log.md
CHANGED
|
@@ -38,6 +38,7 @@ interface AgentLogEntry {
|
|
|
38
38
|
attempts?: DecisionAttempt[];
|
|
39
39
|
decidedBy?: string;
|
|
40
40
|
actorPath?: string[];
|
|
41
|
+
ignored?: true;
|
|
41
42
|
}
|
|
42
43
|
```
|
|
43
44
|
|
|
@@ -49,12 +50,13 @@ interface AgentLogEntry {
|
|
|
49
50
|
- `attempts` holds the decision attempts the machine did not accept before this entry's event landed. Replay ignores it. See [Decision attempts](#decision-attempts).
|
|
50
51
|
- `decidedBy` names the `agent.decide` call an entry settles, as `<requestId>#<n>`: the chosen event, and the invoke's `xstate.done.actor` when the event left it running. A decision usually ends by sending its event, so its invoke never completes; a [`callKey`](hosts.md#idempotency-keys) for a log that cannot be folded counts it from this field. Inside an invoked child machine the call is named by the child's path, as `<childId>/<requestId>#<n>`. Replay ignores it.
|
|
51
52
|
- `actorPath` names the invoked child machine an entry was delivered to, as the invoke ids from the root down (`["worker"]`, `["worker", "review"]`). It is omitted for an entry the root received. Replay applies the event to that child's snapshot with the child's own logic.
|
|
53
|
+
- `ignored` is set when the machine had no transition for an event sent to it, in the state the event arrived in. It is never set on an `xstate.*` event. Only `recordLog` sets it. It records what happened in the live run. Replay does not read it and applies the event like any other.
|
|
52
54
|
|
|
53
55
|
Entries are strict JSON, and plain objects and arrays from another realm (a jest test's vm context) count as JSON. Object fields set to `undefined` in an input or event are dropped, as `JSON.stringify` drops them. `createReplayEntry`, `initEntry`, and every store append reject the other values JSON would drop or coerce (functions, symbols, bigint, non-finite numbers, `Date`, `Map`, `Set`, class instances, cycles, `undefined` array items) with `NonSerializableAgentEventError`, which carries the offending `path`. `Error` payloads on `xstate.error.actor` are normalized to `{ name, message, code?, cause?, "@error": true }`, keeping `code` when it is a string or a number; an `AgentDecisionExhaustedError` also keeps its `attempts`. `replay` turns objects marked `"@error"` back into `Error` objects, so an `onError` that checks `instanceof Error` takes the same branch on replay. A thrown plain object stays a plain object. Other properties of the thrown value are not kept. Use `assertJsonSerializable` and `assertAgentLogEntry` at custom transport boundaries.
|
|
54
56
|
|
|
55
57
|
## Record a log
|
|
56
58
|
|
|
57
|
-
`
|
|
59
|
+
`runAgent` returns a complete, self-contained segment as `result.events`. Two ways to get it into storage:
|
|
58
60
|
|
|
59
61
|
| | `store` | `onEvent` |
|
|
60
62
|
| -------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
|
|
@@ -68,10 +70,7 @@ Entries are strict JSON, and plain objects and arrays from another realm (a jest
|
|
|
68
70
|
Pass a [store](#stores) and the thread to write to. The run reads that thread as its resume log and appends to it.
|
|
69
71
|
|
|
70
72
|
```ts no-check
|
|
71
|
-
const result = await
|
|
72
|
-
createAgentRuntime(machine, { store, threadId: "session-1", executors }),
|
|
73
|
-
{ input },
|
|
74
|
-
);
|
|
73
|
+
const result = await runAgent(machine, { store, threadId: "session-1", executors, input });
|
|
75
74
|
```
|
|
76
75
|
|
|
77
76
|
- Entries are written in batches, each at its first entry's `index` as `expectedIndex`, so a concurrent writer conflicts instead of interleaving.
|
|
@@ -79,7 +78,7 @@ const result = await runToQuiescence(
|
|
|
79
78
|
- No model call starts until every entry before it is durable. Pure transitions never wait.
|
|
80
79
|
- A rejected write (an `AgentEventLogConflictError`, or any storage failure) aborts in-flight work and settles the run `{ status: "error", cause: "journal" }`. No further calls run.
|
|
81
80
|
- A `@agent.usage` entry that arrives after the run settled is still written, but the result does not wait for it. Await `result.drain()` before terminating the process if you care about those straggler entries; it resolves once every write issued so far has landed, and never rejects (a failed write already settled the run with `cause: "journal"`).
|
|
82
|
-
- `threadId` is required with a `store`; without it `
|
|
81
|
+
- `threadId` is required with a `store`; without it `runAgent` throws `AgentError` with code `missing-thread-id`.
|
|
83
82
|
- A thread that already has entries is resumed. `input` that differs from the input the thread started with throws `AgentError` with code `thread-input-mismatch`, since two runs sharing a thread id would otherwise get one result.
|
|
84
83
|
- If an entry cannot be written (an `input` or event that is not JSON), the run settles `{ status: "error", cause: "journal" }` instead of running without a log. Without a store, the log stops at that entry with a `console.warn`, and the run goes on.
|
|
85
84
|
- Passing `events` as well makes that log the resume, and it must BE the thread's log: a different length throws `AgentEventLogConflictError`, and an entry-for-entry mismatch at the same length throws `AgentError` with code `event-log-conflict`.
|
|
@@ -91,10 +90,11 @@ const result = await runToQuiescence(
|
|
|
91
90
|
```ts no-check
|
|
92
91
|
const appended: AgentLogEntry[] = [];
|
|
93
92
|
|
|
94
|
-
const result = await
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
93
|
+
const result = await runAgent(machine, {
|
|
94
|
+
executors,
|
|
95
|
+
onEvent: (entry) => appended.push(entry),
|
|
96
|
+
input,
|
|
97
|
+
});
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
### `recordLog`: a plain actor
|
|
@@ -141,6 +141,7 @@ const { snapshot } = replay(orderMachine, log.entries);
|
|
|
141
141
|
|
|
142
142
|
- An actor created from a `snapshot` starts its log from that snapshot.
|
|
143
143
|
- Each entry carries `verification.stateHash`, so `replay` verifies the fold.
|
|
144
|
+
- A sent event the machine had no transition for is recorded with `ignored: true`, so a refused attempt can be read from the log without a replay.
|
|
144
145
|
- Attached after `start()`, it misses the init event, and reading `log.entries` throws `AgentEventLogError`. An event that cannot be journaled (a payload that is not JSON) stops the recording the same way.
|
|
145
146
|
|
|
146
147
|
To build entries yourself, use `initEntry` for index 0 and `createReplayEntry` for each subsequent external input.
|
|
@@ -154,7 +155,7 @@ const { snapshot, persistedSnapshot } = replay(machine, entries);
|
|
|
154
155
|
```
|
|
155
156
|
|
|
156
157
|
- The first entry seeds the fold: `input` folds from `initialTransition`, `snapshot` restores purely and the rest of the log folds onto it.
|
|
157
|
-
- `replay(machine, entries.slice(0, n))` rebuilds the state as of any point in the log
|
|
158
|
+
- `replay(machine, entries.slice(0, n))` rebuilds the state as of any point in the log, with no side effects.
|
|
158
159
|
- Journaled child sessions are rebound to the sessions the current fold minted, so completions still apply.
|
|
159
160
|
|
|
160
161
|
## Verification
|
|
@@ -192,7 +193,7 @@ Replayability rests on pure transitions.
|
|
|
192
193
|
- Journal external inputs only when building entries by hand.
|
|
193
194
|
- Keep context JSON-serializable. Hold sessions, clients, and sockets in closures and store only their ids.
|
|
194
195
|
- Replay against the machine the runtime folded. When actors come in through `createAgentRuntime(machine, { actors })`, call `replay(machine.provide({ actors }), entries)`. The executor-bound machine is never needed; recorded results replace executors.
|
|
195
|
-
- A run whose initial state cannot be serialized to JSON produces no log: `result.events` is empty, `onEvent` never fires, and nothing is written to a `store`. `replay` rejects a log without an init entry, so `
|
|
196
|
+
- A run whose initial state cannot be serialized to JSON produces no log: `result.events` is empty, `onEvent` never fires, and nothing is written to a `store`. `replay` rejects a log without an init entry, so `runAgent` journals nothing rather than a suffix.
|
|
196
197
|
- `onEvent` alone does not make a call append-before-execute. A crash between an entry and the host's flush loses it. Use `store` when that matters.
|
|
197
198
|
|
|
198
199
|
## Fork
|
|
@@ -243,10 +244,7 @@ A host that decides with `decideNext` sends the event itself. Pass its `attempts
|
|
|
243
244
|
const { event, attempts } = await decideNext(snapshot, { decide, model, allowedEvents: "desk.*" });
|
|
244
245
|
|
|
245
246
|
if (event) {
|
|
246
|
-
await
|
|
247
|
-
event,
|
|
248
|
-
attempts,
|
|
249
|
-
});
|
|
247
|
+
await runAgent(machine, { store, threadId, event, attempts });
|
|
250
248
|
}
|
|
251
249
|
```
|
|
252
250
|
|
package/docs/from-a-loop.md
CHANGED
|
@@ -504,10 +504,10 @@ pnpm exec tsx examples/code-review-loop/run.ts --improve --policy v0
|
|
|
504
504
|
4. Replay the train and held-out tasks with the candidate.
|
|
505
505
|
5. Promote only with zero violations on both splits, a held-out objective no lower than before, and a combined objective strictly higher. `run.ts` writes a promoted policy to `policies/current.json`.
|
|
506
506
|
|
|
507
|
-
Inside Claude Code, the [`improve-machine` skill](https://github.com/statelyai/
|
|
507
|
+
Inside Claude Code, the [`improve-machine` skill](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) runs the same round with Claude Code as the improver:
|
|
508
508
|
|
|
509
509
|
```bash
|
|
510
|
-
|
|
510
|
+
npx skills add statelyai/skills --skill improve-machine -a claude-code
|
|
511
511
|
pnpm exec tsx examples/code-review-loop/run.ts --policy v0 --no-human
|
|
512
512
|
claude -p "Use the improve-machine skill on examples/code-review-loop. ..."
|
|
513
513
|
```
|
|
@@ -525,4 +525,4 @@ The full prompt and its allowed tools are in the [example's README](https://gith
|
|
|
525
525
|
- [Human in the loop](human-in-the-loop.md): idle states, `meta.interaction`, and resuming.
|
|
526
526
|
- [Environment and policy](environment-and-policy.md): the fixed environment, the generated policy, the objective, and the improvement loop.
|
|
527
527
|
- [code-review-loop](https://github.com/statelyai/agent/blob/next/examples/code-review-loop): Part 2's factory: `before.ts`, the machine, the policies, and the improvement round on Claude Code.
|
|
528
|
-
- [`
|
|
528
|
+
- [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md): one improvement round from traces, run by an agent.
|
|
@@ -86,13 +86,13 @@ A failed gate's `detail` is the repair prompt. Send it back to the model with th
|
|
|
86
86
|
|
|
87
87
|
## The skill
|
|
88
88
|
|
|
89
|
-
The full authoring procedure
|
|
89
|
+
The full authoring procedure is an agent skill in [statelyai/skills](https://github.com/statelyai/skills). It covers the environment and policy split, the schema location, the rules a config must follow, a few-shot config, the Ajv adapter, `verifyAgentConfig`, the repair loop, and persisting traces.
|
|
90
90
|
|
|
91
|
-
**[`
|
|
91
|
+
**[`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md)**
|
|
92
92
|
|
|
93
|
-
|
|
93
|
+
Install it with `npx skills add statelyai/skills --skill generate-machine`, or in Claude Code with `/plugin install stately-agent@stately` after `/plugin marketplace add statelyai/skills`. The agent then loads the skill on requests such as "author an agent machine for X" and runs the gates itself.
|
|
94
94
|
|
|
95
|
-
To improve a generated policy from its run traces, use [`
|
|
95
|
+
To improve a generated policy from its run traces, use [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md). See [Environment and policy](environment-and-policy.md).
|
|
96
96
|
|
|
97
97
|
## Limits
|
|
98
98
|
|
package/docs/hosts.md
CHANGED
|
@@ -3,21 +3,19 @@
|
|
|
3
3
|
The machine owns agent control flow. A host supplies model request executors.
|
|
4
4
|
|
|
5
5
|
```ts no-check
|
|
6
|
-
const result = await
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
return { result: response.text, messages: response.messages };
|
|
16
|
-
},
|
|
6
|
+
const result = await runAgent(machine, {
|
|
7
|
+
executors: {
|
|
8
|
+
generateText: async (request, { signal }) => {
|
|
9
|
+
const response = await mySdk.generate({
|
|
10
|
+
model: request.model,
|
|
11
|
+
prompt: request.prompt,
|
|
12
|
+
signal,
|
|
13
|
+
});
|
|
14
|
+
return { result: response.text, messages: response.messages };
|
|
17
15
|
},
|
|
18
|
-
}
|
|
19
|
-
|
|
20
|
-
);
|
|
16
|
+
},
|
|
17
|
+
input,
|
|
18
|
+
});
|
|
21
19
|
```
|
|
22
20
|
|
|
23
21
|
Text, stream, and decision executors all receive `(request, info)`; cancellation is `info.signal`.
|
|
@@ -35,7 +33,7 @@ Execution is at-least-once. A host runs the request and then journals its comple
|
|
|
35
33
|
- A [decision strategy](decisions.md#decision-strategies)'s sub-calls append their role: `<executionId>:<requestId>#<n>.<attempt>.pick`, `.group`, or `.fill`.
|
|
36
34
|
- A resumed run re-executing an in-flight request passes the same `callKey` as the original attempt.
|
|
37
35
|
- A fork mints its own lineage id (see [Fork](event-log.md#fork)), so none of its calls shares a key with its parent's.
|
|
38
|
-
- It is `undefined` off the `
|
|
36
|
+
- It is `undefined` off the `runAgent` path (a bare `provideExecutors` bind) and on a run with no event log.
|
|
39
37
|
- Only model calls get one. A plain actor (`createAsyncLogic`, a tool) in flight at a crash runs again on resume with no key. Derive an idempotency key from the domain (an order id, a booking key) and dedupe inside the effect.
|
|
40
38
|
|
|
41
39
|
The key names the call _site_, not the request. A version bridge keeps the lineage id, so a migrated machine that asks something else at the same invoke site produces the same key for a different request. Cache on `callKey` **and** a fingerprint of the request, and reuse the cached result only when the request also matches. Pass `callKey` to a provider as its dedupe key for that identical request:
|
|
@@ -63,10 +61,7 @@ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
|
63
61
|
const models = { fast: openai("gpt-6-luna") };
|
|
64
62
|
const agent = setupAgent({ models /* schemas and requests */ });
|
|
65
63
|
|
|
66
|
-
await
|
|
67
|
-
createAgentRuntime(machine, { executors: createAiSdkExecutors({ models }) }),
|
|
68
|
-
{ input },
|
|
69
|
-
);
|
|
64
|
+
await runAgent(machine, { executors: createAiSdkExecutors({ models }), input });
|
|
70
65
|
```
|
|
71
66
|
|
|
72
67
|
Passing the same `models` map to `setupAgent({ models })` types the machine's model refs, so a request naming a model the host does not have is a compile error. Executors are always passed explicitly. Core does not import or require the AI SDK at runtime.
|
|
@@ -97,7 +92,7 @@ const executors = createOpenAiExecutors({
|
|
|
97
92
|
},
|
|
98
93
|
});
|
|
99
94
|
|
|
100
|
-
await
|
|
95
|
+
await runAgent(machine, { executors, input });
|
|
101
96
|
```
|
|
102
97
|
|
|
103
98
|
`client` is injected, so the API key, base URL, and transport stay with the host. `openai` 5 or newer is required. It is an optional peer dependency with no version range, so an app on `openai` 4 still installs the core, and it is imported for types only. A client wrapper must forward both `responses.create` and `chat.completions.create` unless `api` pins one of them.
|
|
@@ -131,7 +126,7 @@ Decisions follow `decideMode`:
|
|
|
131
126
|
- `'tool'`: one function tool per candidate event, with `tool_choice: 'required'` and `parallel_tool_calls: false`. Function tools are sent with `strict: false`, since the Responses API defaults strict mode on and arbitrary JSON Schema may fall outside it.
|
|
132
127
|
- An answer the adapter cannot read as one event comes back as `rejected`, and the runtime retries it. See [Coercion](decisions.md#coercion).
|
|
133
128
|
|
|
134
|
-
`generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early
|
|
129
|
+
`generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early when the model calls a client-side tool (one with no `execute`). The call is handed back with `finishReason: 'tool-calls'` and the raw response. Every step's `usage` is summed onto the one result the run aggregates. `modelCalls` reports the steps, and a loop that throws after a step records them on the error, so the run's budget counts them.
|
|
135
130
|
|
|
136
131
|
`toolChoice` maps onto `tool_choice`: `'auto'`, `'none'`, and `'required'` pass through, and `{ type: 'tool', name }` becomes `{ type: 'function', name }`. It is sent on the first step only, so a forced choice cannot re-fire every step and burn the step budget.
|
|
137
132
|
|
|
@@ -164,7 +159,7 @@ const executors = createTanStackAiExecutors({
|
|
|
164
159
|
},
|
|
165
160
|
});
|
|
166
161
|
|
|
167
|
-
await
|
|
162
|
+
await runAgent(machine, { executors, input });
|
|
168
163
|
```
|
|
169
164
|
|
|
170
165
|
The options mirror `createAiSdkExecutors`:
|
|
@@ -197,7 +192,7 @@ The rest of the contract matches the other adapters:
|
|
|
197
192
|
|
|
198
193
|
## Finish reasons and truncation
|
|
199
194
|
|
|
200
|
-
An executor result may report `finishReason`, normalized to `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. Map the provider's own vocabulary onto those five and leave the raw value on `raw`. `
|
|
195
|
+
An executor result may report `finishReason`, normalized to `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. Map the provider's own vocabulary onto those five and leave the raw value on `raw`. `runAgent` lifts the normalized reason onto the `request.end` trace event, beside `usage`.
|
|
201
196
|
|
|
202
197
|
A `'length'` finish is the host's to interpret, because only the host sees it:
|
|
203
198
|
|
|
@@ -255,7 +250,7 @@ Tool-bearing calls are not retried here because tools may have side effects. Use
|
|
|
255
250
|
|
|
256
251
|
## Resume events off the wire
|
|
257
252
|
|
|
258
|
-
A host that resumes a run from an HTTP request or a socket frame parses the payload at the boundary, then hands the parsed event to `
|
|
253
|
+
A host that resumes a run from an HTTP request or a socket frame parses the payload at the boundary, then hands the parsed event to `runAgent`:
|
|
259
254
|
|
|
260
255
|
```ts no-check
|
|
261
256
|
let event;
|
|
@@ -265,9 +260,7 @@ try {
|
|
|
265
260
|
return Response.json({ error: String(error) }, { status: 400 });
|
|
266
261
|
}
|
|
267
262
|
|
|
268
|
-
const result = await
|
|
269
|
-
event,
|
|
270
|
-
});
|
|
263
|
+
const result = await runAgent(machine, { store, threadId, executors, event });
|
|
271
264
|
|
|
272
265
|
if (result.ignored) {
|
|
273
266
|
return Response.json(
|
|
@@ -279,7 +272,7 @@ if (result.ignored) {
|
|
|
279
272
|
|
|
280
273
|
- `parseAgentEvent(machineOrSnapshot, payload)` takes `unknown` and returns the event typed as the machine's event union. Give it the machine to read the event schemas `setupAgent` registered, or any snapshot of it.
|
|
281
274
|
- It throws `AgentInvalidEventPayloadError` (code `invalid-event-payload`) for a payload that is not an object with a string `type`, a reserved `@agent.*` type, or fields that fail the schema. That is the 400.
|
|
282
|
-
- It does not ask whether the current state handles the event, and `
|
|
275
|
+
- It does not ask whether the current state handles the event, and `runAgent` adds no check of its own.
|
|
283
276
|
- An event the resumed state has no transition for is ignored: the run settles normally and `result.ignored` holds the event. Answer 409 if the client should know nothing happened.
|
|
284
277
|
|
|
285
278
|
See [Persistence](persistence.md#resume-with-an-event-off-the-wire).
|
|
@@ -411,4 +404,4 @@ const result = await run;
|
|
|
411
404
|
|
|
412
405
|
`provideExecutors(machine, executors)` binds the executors onto the machine so a plain `createActor` runs it, for an application that owns the actor or embeds the agent machine in a larger XState system. See [Advanced](advanced.md).
|
|
413
406
|
|
|
414
|
-
Framework-owned concerns
|
|
407
|
+
Framework-owned concerns (storage, durable execution, retries, queues, and tool-loop interruption recovery) remain with the framework.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Human in the loop
|
|
2
2
|
|
|
3
3
|
A human wait is an ordinary XState state with accepted events. Once no child,
|
|
4
|
-
request, or in-process timer remains active, `
|
|
4
|
+
request, or in-process timer remains active, `runAgent` settles as
|
|
5
5
|
`idle`. Use `isAgentIdle(snapshot)` afterward to distinguish an intentional
|
|
6
6
|
human wait from a stuck machine.
|
|
7
7
|
|
|
@@ -126,7 +126,7 @@ asking: {
|
|
|
126
126
|
## Render and validate
|
|
127
127
|
|
|
128
128
|
```ts no-check
|
|
129
|
-
const paused = await
|
|
129
|
+
const paused = await runAgent(machine, { executors, input });
|
|
130
130
|
|
|
131
131
|
if (paused.status === "idle") {
|
|
132
132
|
const interaction = getInteraction(paused.snapshot);
|
|
@@ -151,10 +151,7 @@ Both functions are typed off the snapshot, so `eventFromInteraction` returns the
|
|
|
151
151
|
|
|
152
152
|
```ts no-check
|
|
153
153
|
const event = eventFromInteraction(paused.snapshot, { type: "APPROVE" });
|
|
154
|
-
await
|
|
155
|
-
snapshot: paused.persist(),
|
|
156
|
-
event,
|
|
157
|
-
});
|
|
154
|
+
await runAgent(machine, { executors, snapshot: paused.persist(), event });
|
|
158
155
|
```
|
|
159
156
|
|
|
160
157
|
When the answer arrives over the wire instead of from your own code, parse it at the boundary with `parseAgentEvent(machine, await request.json())` and pass the result as `event`. A bad payload throws, which is a 400; an event the paused state has no transition for is ignored and comes back as `result.ignored`. See [Persistence](persistence.md#resume-with-an-event-off-the-wire).
|
|
@@ -162,13 +159,13 @@ When the answer arrives over the wire instead of from your own code, parse it at
|
|
|
162
159
|
## Drive several turns
|
|
163
160
|
|
|
164
161
|
```ts no-check
|
|
165
|
-
let result = await
|
|
162
|
+
let result = await runAgent(machine, { executors, input });
|
|
166
163
|
|
|
167
164
|
while (result.status === "idle") {
|
|
168
165
|
const snapshot = result.persist();
|
|
169
166
|
await storage.put(id, snapshot);
|
|
170
167
|
const event = await promptUser(getInteraction(result.snapshot));
|
|
171
|
-
result = await
|
|
168
|
+
result = await runAgent(machine, { executors, snapshot, event });
|
|
172
169
|
}
|
|
173
170
|
```
|
|
174
171
|
|