@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +138 -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-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
- package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
- 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-30mH2moE.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.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-BaNyz6Q3.d.cts} +4 -4
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- 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 +2493 -1502
- package/dist/testing.d.cts +360 -256
- package/dist/testing.d.mts +360 -256
- package/dist/testing.mjs +2489 -1503
- 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-Bm5nvpow.d.cts} +6 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -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-ChyX6jq0.mjs +2306 -0
- package/dist/verify-CwlombbC.cjs +2359 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
- 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 +312 -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 +207 -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 +56 -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 +518 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +492 -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 +84 -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,62 @@
|
|
|
1
|
+
# Use in any stack
|
|
2
|
+
|
|
3
|
+
The machine is framework-independent. Adapters only supply executors and transport events/snapshots.
|
|
4
|
+
|
|
5
|
+
## Server request
|
|
6
|
+
|
|
7
|
+
```ts no-check
|
|
8
|
+
const result = await runAgent(machine, {
|
|
9
|
+
input: await request.json(),
|
|
10
|
+
executors,
|
|
11
|
+
});
|
|
12
|
+
|
|
13
|
+
if (result.status === "idle") {
|
|
14
|
+
await frameworkStore.put(id, result.persist());
|
|
15
|
+
}
|
|
16
|
+
return Response.json(result);
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Resume request
|
|
20
|
+
|
|
21
|
+
```ts no-check
|
|
22
|
+
const snapshot = await frameworkStore.get(id);
|
|
23
|
+
|
|
24
|
+
let event;
|
|
25
|
+
try {
|
|
26
|
+
event = parseAgentEvent(machine, await request.json());
|
|
27
|
+
} catch (error) {
|
|
28
|
+
return Response.json({ error: String(error) }, { status: 400 });
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const result = await runAgent(machine, { executors, snapshot, event });
|
|
32
|
+
|
|
33
|
+
if (result.ignored) {
|
|
34
|
+
return Response.json(
|
|
35
|
+
{ error: `'${result.ignored.type}' does not apply right now` },
|
|
36
|
+
{ status: 409 },
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Parse at the boundary; `runAgent` adds no validation of its own. An event the restored state does not handle is ignored, not an error.
|
|
42
|
+
|
|
43
|
+
## Long-lived UI actor
|
|
44
|
+
|
|
45
|
+
Bind executors with `provideExecutors`, create a normal XState actor, and connect it using the framework's XState integration.
|
|
46
|
+
|
|
47
|
+
## Durable or event-pushing host
|
|
48
|
+
|
|
49
|
+
A host that cannot block on a run, such as a Durable Object woken by alarms, drives the transition loop itself. See [Write your own host loop](hosts.md#write-your-own-host-loop).
|
|
50
|
+
|
|
51
|
+
## Examples
|
|
52
|
+
|
|
53
|
+
- Next.js: [next-host](https://github.com/statelyai/agent/blob/next/examples/next-host)
|
|
54
|
+
- Cloudflare: [cloudflare-agent-host](https://github.com/statelyai/agent/blob/next/examples/cloudflare-agent-host), [cloudflare-workers-ai-host](https://github.com/statelyai/agent/blob/next/examples/cloudflare-workers-ai-host)
|
|
55
|
+
- Mastra, LangChain: [mastra-host](https://github.com/statelyai/agent/blob/next/examples/mastra-host), [langchain-host](https://github.com/statelyai/agent/blob/next/examples/langchain-host)
|
|
56
|
+
- AI SDK and AG-UI streaming: [ai-sdk-ui-stream](https://github.com/statelyai/agent/blob/next/examples/ai-sdk-ui-stream), [tanstack-ai-stream](https://github.com/statelyai/agent/blob/next/examples/tanstack-ai-stream)
|
|
57
|
+
|
|
58
|
+
Use each framework's own storage, retry, queue, and interruption semantics.
|
|
59
|
+
|
|
60
|
+
## Related
|
|
61
|
+
|
|
62
|
+
- [Use in an XState 4 or 5 app](xstate-4-and-5-apps.md): isolating the agent when the app's own XState version cannot change.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Choosing a run mode
|
|
2
|
+
|
|
3
|
+
The machine is the artifact. Runners only decide how one host executes its XState effects.
|
|
4
|
+
|
|
5
|
+
| Need | Use |
|
|
6
|
+
| -------------------------------- | ---------------------------------------------------------------------- |
|
|
7
|
+
| One request/response run | `runToQuiescence(createAgentRuntime(...), init)` |
|
|
8
|
+
| Several idle/resume turns | `runToQuiescence` in a loop over `result.persist()` |
|
|
9
|
+
| Transition-by-transition control | The explicit `AgentRuntime` loop |
|
|
10
|
+
| A long-lived actor | `provideExecutors` + XState `createActor`, see [Advanced](advanced.md) |
|
|
11
|
+
|
|
12
|
+
## Managed run
|
|
13
|
+
|
|
14
|
+
```ts no-check
|
|
15
|
+
const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
16
|
+
|
|
17
|
+
if (result.status === "idle") {
|
|
18
|
+
await storage.save(result.persist());
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`createAgentRuntime` binds request executors. `runToQuiescence` drives its durable
|
|
23
|
+
transition loop until the run is done, idle, or errors. Storage remains host-owned.
|
|
24
|
+
|
|
25
|
+
## Idle/resume loop
|
|
26
|
+
|
|
27
|
+
```ts no-check
|
|
28
|
+
let result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
29
|
+
|
|
30
|
+
while (result.status === "idle") {
|
|
31
|
+
const snapshot = result.persist();
|
|
32
|
+
await storage.save(snapshot);
|
|
33
|
+
const event = await nextExternalEvent(result.snapshot);
|
|
34
|
+
result = await runToQuiescence(createAgentRuntime(machine, { executors }), { snapshot, event });
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The continuation is always the native persisted XState snapshot, so the loop can span processes: persist after one call, resume in another.
|
|
39
|
+
|
|
40
|
+
## Long-lived actor
|
|
41
|
+
|
|
42
|
+
When your application owns the actor, or the agent machine is a child in a larger XState system, bind the executors with `provideExecutors` and run a plain `createActor`. See [Advanced](advanced.md).
|
|
43
|
+
|
|
44
|
+
## The portable loop
|
|
45
|
+
|
|
46
|
+
Any host can drive `AgentRuntime` one transition at a time. Effects only start
|
|
47
|
+
when the host calls `execute`; completions and child messages arrive through
|
|
48
|
+
`nextEvent`. See [The runtime loop](steps.md).
|
|
49
|
+
|
|
50
|
+
[`portable-xstate-loop`](https://github.com/statelyai/agent/blob/next/examples/portable-xstate-loop) expands this sketch
|
|
51
|
+
into a runnable `createDurable` host. Its extra mailbox and wake-up plumbing is
|
|
52
|
+
host implementation, while the Agent machine artifact stays unchanged.
|
|
53
|
+
|
|
54
|
+
A durable host owns persistence, retries, messaging, timers, and child execution.
|
|
55
|
+
Stately Agent does not wrap those framework responsibilities.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Debugging
|
|
2
|
+
|
|
3
|
+
Use the XState inspection protocol for framework behavior and Agent traces for request behavior.
|
|
4
|
+
|
|
5
|
+
```ts no-check
|
|
6
|
+
const result = await runToQuiescence(
|
|
7
|
+
createAgentRuntime(machine, {
|
|
8
|
+
executors,
|
|
9
|
+
inspect: (event) => inspector.next(event),
|
|
10
|
+
onTrace: (event) => logger.write(serializeTraceEvent(event)),
|
|
11
|
+
}),
|
|
12
|
+
{ input },
|
|
13
|
+
);
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`inspect` is the raw XState stream. `onTrace` adds Agent request start/end/error, chunks, usage, emitted events, transitions, and the terminal run result.
|
|
17
|
+
|
|
18
|
+
Common errors:
|
|
19
|
+
|
|
20
|
+
| Error | Meaning |
|
|
21
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| `AgentInvalidEventPayloadError` | A payload passed to `parseAgentEvent` was not `{ type, ... }`, used a reserved `@agent.*` type, or failed the machine's event schema. |
|
|
23
|
+
| `AgentDecisionExhaustedError` | Every proposed decision was unknown, invalid, or guard-rejected. |
|
|
24
|
+
| `AgentMaxModelCallsExceededError` | The run exceeded its configured model-call budget. |
|
|
25
|
+
| XState version error | The persisted snapshot version needs the machine's native `migrate` function. |
|
|
26
|
+
|
|
27
|
+
An event the active state has no transition for is not an error: the run settles normally and the event comes back as `result.ignored`. Its `machine.transition` trace event carries `ignored: true`.
|
|
28
|
+
|
|
29
|
+
`lintAgentMachine` reports only Agent-specific mistakes: decisions with no candidate events, decisions that list an event only a person sends, direct object request sources that a host cannot bind, and invokes with no error path. General state-machine lint belongs in XState tooling.
|
|
@@ -0,0 +1,473 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Decisions
|
|
3
|
+
description: Let the model choose one currently-legal machine event, validated and retried by the machine before it is taken.
|
|
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
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
A **decision** lets the model choose one event to send to the running machine. The machine declares the candidate events, guards determine which of them are legal in the current state, and the model picks one of the remaining candidates. The model does not produce free text or an arbitrary tool call. The machine rejects any event that is not legal in the current state.
|
|
11
|
+
|
|
12
|
+
The snippets below come from [Twenty Questions](https://github.com/statelyai/agent/blob/next/examples/twenty-questions/index.ts), where the model chooses `ASK` or `GUESS` each turn.
|
|
13
|
+
|
|
14
|
+
<!-- viz: sequence diagram for one decision: machine invokes agent.decide -> host coerces the model to one candidate event -> validation (unknown-event / invalid-payload / rejected-by-guard) -> retry or send the event to the machine -->
|
|
15
|
+
|
|
16
|
+
## Invoking an agent decision
|
|
17
|
+
|
|
18
|
+
<!-- agent.decide builtin from src/setup-agent.ts and src/decision.ts -->
|
|
19
|
+
|
|
20
|
+
Author a decision inline on the invoke that needs one, using the builtin `agent.decide` actor source. Its input takes:
|
|
21
|
+
|
|
22
|
+
- `model`: which model to use (a key from your models map).
|
|
23
|
+
- `name` (optional): the request's semantic name. It identifies the decision in traces, host mocks, and eval scripts. Without it the name falls back to the invoke `id`, then to the invoke's state path. See [Plain-function executors](evals.md#plain-function-executors).
|
|
24
|
+
- `system` (optional): system prompt.
|
|
25
|
+
- `prompt` (optional): user prompt, usually built from `context`.
|
|
26
|
+
- `allowedEvents` (optional): the candidate events (exact types or [patterns](#allowedevents-patterns)). Defaults to all currently-legal events.
|
|
27
|
+
- `maxRetries` (optional): retries after an invalid choice. Default 2.
|
|
28
|
+
|
|
29
|
+
```ts no-check
|
|
30
|
+
// ...
|
|
31
|
+
deciding: {
|
|
32
|
+
invoke: {
|
|
33
|
+
src: 'agent.decide',
|
|
34
|
+
input: ({ context }) => ({
|
|
35
|
+
model: 'quick',
|
|
36
|
+
name: 'chooseAction',
|
|
37
|
+
system: 'Ask one yes/no question at a time, but guess on the final turn.',
|
|
38
|
+
prompt: `Questions remaining: ${context.questionsRemaining}`,
|
|
39
|
+
allowedEvents: ['ASK', 'GUESS'],
|
|
40
|
+
}),
|
|
41
|
+
// Reached when retries are exhausted.
|
|
42
|
+
onError: { target: 'failed' },
|
|
43
|
+
},
|
|
44
|
+
on: {
|
|
45
|
+
ASK: ({ context, event }) =>
|
|
46
|
+
context.questionsRemaining > 1 ? { target: 'awaitingAnswer', context: { /* ... */ } } : undefined,
|
|
47
|
+
GUESS: ({ context, event }) => ({ target: 'revealing', context: { guess: event.guess } }),
|
|
48
|
+
},
|
|
49
|
+
}
|
|
50
|
+
// ...
|
|
51
|
+
```
|
|
52
|
+
|
|
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
|
+
|
|
55
|
+
> **Note:** `agent.decide` needs a snapshot-aware host such as `runToQuiescence` 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
|
+
|
|
57
|
+
### `allowedEvents` patterns
|
|
58
|
+
|
|
59
|
+
The `allowedEvents` option accepts a single string or an array. Entries are exact event types or wildcard patterns, and the two can mix, as in `['todo.*', 'reset']`.
|
|
60
|
+
|
|
61
|
+
| Value | Meaning |
|
|
62
|
+
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
63
|
+
| `['ASK', 'GUESS']` | Exact event types, typed against the event-schema keys. A typo is a compile error. |
|
|
64
|
+
| `'ASK'` | A single string, shorthand for a one-entry array. |
|
|
65
|
+
| `'*'` | Every currently-legal event. |
|
|
66
|
+
| `'todo.*'` | Every declared event under the `todo.` namespace, such as `todo.add` and `todo.toggle`. Typed against declared dotted types, so a pattern matching nothing, such as `'nope.*'`, is a compile error. |
|
|
67
|
+
|
|
68
|
+
### Reusable decision logic
|
|
69
|
+
|
|
70
|
+
<!-- createDecisionLogic public API from src/decision.ts and src/index.ts -->
|
|
71
|
+
|
|
72
|
+
For a decision used by more than one state or machine, `createDecisionLogic` builds the same decision as standalone actor logic, exported from `@statelyai/agent`. Register the result under `actors:` and invoke it by name. It takes the same fields as the `agent.decide` input, each a static value or an `({ input }) => value` resolver, plus an optional `schemas.input` to type and validate the input.
|
|
73
|
+
|
|
74
|
+
```ts no-check
|
|
75
|
+
import { createDecisionLogic } from "@statelyai/agent";
|
|
76
|
+
import { z } from "zod";
|
|
77
|
+
|
|
78
|
+
export const chooseAction = createDecisionLogic({
|
|
79
|
+
schemas: { input: z.object({ questionsRemaining: z.number() }) },
|
|
80
|
+
model: "quick",
|
|
81
|
+
system: "Ask one yes/no question at a time, but guess on the final turn.",
|
|
82
|
+
prompt: ({ input }) => `Questions remaining: ${input.questionsRemaining}`,
|
|
83
|
+
allowedEvents: ["ASK", "GUESS"],
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Prefer the `agent.decide` builtin for a one-off, state-local decision: it needs no separate declaration and types `allowedEvents` against the machine's own event schemas.
|
|
88
|
+
|
|
89
|
+
## Delivering the chosen event
|
|
90
|
+
|
|
91
|
+
Delivery is automatic. When the decision resolves, the `agent.decide` actor sends the chosen event to the machine, and the matching `on:` transition runs. You handle the outcome with ordinary transitions.
|
|
92
|
+
|
|
93
|
+
### When `onDone` fires
|
|
94
|
+
|
|
95
|
+
The chosen event's transition usually exits the invoking state, which cancels the invoke, so `onDone` normally never fires. Declare `onDone` only when the chosen event's transition stays in the same state. The invoke then completes with the chosen event as its output. `onError` is unaffected and still fires when retries are exhausted with `AgentDecisionExhaustedError`.
|
|
96
|
+
|
|
97
|
+
## Guard enforcement
|
|
98
|
+
|
|
99
|
+
Guards are transition functions that return `undefined`. See [Transitions](machines.md#transitions). A guard may read the event payload, so candidates cannot be filtered before the model picks.
|
|
100
|
+
|
|
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
|
+
|
|
103
|
+
`runToQuiescence` 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
|
+
|
|
105
|
+
```ts
|
|
106
|
+
import { resolveDecision } from "@statelyai/agent";
|
|
107
|
+
|
|
108
|
+
const event = await resolveDecision(request, executors, {
|
|
109
|
+
canTake: (e) => snapshot.can(e),
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Build the request with `createDecisionRequest` rather than by hand. It fills in `kind`, an `id`, an empty `attempts` list, and each candidate event's `toolName`, and accepts either bare event types or the descriptors `getAcceptedEvents` returns:
|
|
114
|
+
|
|
115
|
+
```ts no-check
|
|
116
|
+
const request = createDecisionRequest({
|
|
117
|
+
name: "judge",
|
|
118
|
+
model: "reviewer",
|
|
119
|
+
prompt: `Judge this draft.\n\n${snapshot.context.draft}`,
|
|
120
|
+
events: getAcceptedEvents(snapshot),
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Events a person sends
|
|
125
|
+
|
|
126
|
+
Tag a transition with `meta: { actor: "human" }` when only a person may send its event, such as an approval. No model-facing decision offers that event in a state that handles it this way.
|
|
127
|
+
|
|
128
|
+
```ts no-check
|
|
129
|
+
reviewing: {
|
|
130
|
+
invoke: {
|
|
131
|
+
src: "agent.decide",
|
|
132
|
+
input: { model: "quick", allowedEvents: ["revise"] },
|
|
133
|
+
},
|
|
134
|
+
on: {
|
|
135
|
+
approve: { target: "approved", meta: { actor: "human" } },
|
|
136
|
+
revise: { target: "revising" },
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- `agent.decide` and `decideNext` drop the event from the candidates. A closed choice lists its options in `withheld`, and a choice of it anyway is retried.
|
|
142
|
+
- `getAcceptedEvents(snapshot, { actor: "agent" })` returns the same model-facing list, for a host that offers events itself.
|
|
143
|
+
- `describeMachine` marks the transition `(human)`.
|
|
144
|
+
- `lintAgentMachine` reports `decide-allows-human-event` when a decision's literal `allowedEvents` names a tagged event. `verifyAgentConfig` fails its `lint` gate on it.
|
|
145
|
+
- Only object transitions can be tagged. A transition written as a function has no static `meta`.
|
|
146
|
+
- A plain `createMachine` declares `schemas: { meta: interactionMetaSchema }` to type the tag; `setupAgent` machines have it by default.
|
|
147
|
+
|
|
148
|
+
The tag does not change what the machine accepts. A host still sends the event when a person answers, and `parseAgentEvent` still parses it.
|
|
149
|
+
|
|
150
|
+
## Validation and retries
|
|
151
|
+
|
|
152
|
+
<!-- decision validation checks and retry behavior from src/decision.ts -->
|
|
153
|
+
|
|
154
|
+
Each attempt runs three checks in order. Each failure is typed and fed back to the model on the next attempt:
|
|
155
|
+
|
|
156
|
+
| Failure | Cause |
|
|
157
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
158
|
+
| `unknown-event` | The event type is not among the candidate events. |
|
|
159
|
+
| `invalid-payload` | The payload does not match that event's schema. |
|
|
160
|
+
| `rejected-by-guard` | The type and payload are valid, but `snapshot.can(event)` returned `false`, or the event matches none of a [closed choice](#closed-choices)'s options. |
|
|
161
|
+
|
|
162
|
+
Retry behavior:
|
|
163
|
+
|
|
164
|
+
- The default is 2 retries, so up to 3 attempts. Set `maxRetries` on the decide input to change it.
|
|
165
|
+
- Prior failed attempts are carried on `request.attempts`, so the host can render the previous failure into the next call. Core does not rewrite the prompt itself. See [Hosts](hosts.md).
|
|
166
|
+
- Exhausting retries throws `AgentDecisionExhaustedError`, which carries the attempts list and is caught by the invoke's `onError`.
|
|
167
|
+
- The run's [event log](event-log.md) keeps the failed attempts on the entry they explain. `getDecisionAttempts` reads them back. See [Decision attempts](event-log.md#decision-attempts).
|
|
168
|
+
|
|
169
|
+
## Coercion
|
|
170
|
+
|
|
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
|
+
|
|
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 answer holds one event by construction.
|
|
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
|
+
- 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
|
+
|
|
177
|
+
```ts no-check
|
|
178
|
+
createAiSdkExecutors({ models, decideMode: "tool" });
|
|
179
|
+
createOpenAiExecutors({ client, decideMode: (request) => (request.options ? "object" : "tool") });
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
An executor returns an answer it cannot read as an event as `rejected: { failure, reason }` instead of `event`. Core records it as a failed attempt, feeds `reason` back to the model as written, and asks again. The shipped executors reject:
|
|
183
|
+
|
|
184
|
+
- An object answer that is not valid JSON: an `invalid-payload` attempt.
|
|
185
|
+
- An object answer that names no event, or an event that is not a candidate: an `unknown-event` attempt whose reason lists the valid events.
|
|
186
|
+
- A closed-choice id that was not offered: an `unknown-event` attempt whose reason lists the valid ids.
|
|
187
|
+
- In tool mode, no tool call, a call to a tool that was not offered, or more than one call: an `unknown-event` attempt whose reason lists the tools to call.
|
|
188
|
+
- In tool mode, tool arguments that are not valid JSON: an `invalid-payload` attempt whose reason names the tool.
|
|
189
|
+
|
|
190
|
+
Decision models such as Jev are not affected by `decideMode`. See [Decision models](#decision-models).
|
|
191
|
+
|
|
192
|
+
> **Note:** Decisions are state-local, so prefer authoring one-off decisions inline on the invoke.
|
|
193
|
+
|
|
194
|
+
## The decide loop for multi-event commands
|
|
195
|
+
|
|
196
|
+
A decision produces one event. When one command needs several events, such as "add X and Y" producing two `ADD_TODO` events, loop the decision in the machine. The loop, its exit, and the trail of applied events stay visible in the statechart.
|
|
197
|
+
|
|
198
|
+
- A `planning` state invokes `agent.decide` for one event.
|
|
199
|
+
- Applying that event targets a turnaround state that immediately re-enters `planning` and starts the next step.
|
|
200
|
+
- An explicit machine event, such as `DONE`, is among `allowedEvents` and targets a state outside the loop, so the model can end the loop.
|
|
201
|
+
- The trail of applied events lives in context and is appended to each step's prompt.
|
|
202
|
+
|
|
203
|
+
<!-- viz: state diagram of the decide loop: planning (invoke agent.decide) -> applying (always -> planning) for ADD_TODO/TOGGLE_TODO, and DONE -> awaitingCommand -->
|
|
204
|
+
|
|
205
|
+
```ts no-check
|
|
206
|
+
planning: {
|
|
207
|
+
invoke: {
|
|
208
|
+
src: 'agent.decide',
|
|
209
|
+
input: ({ context }) => ({
|
|
210
|
+
model: 'quick',
|
|
211
|
+
prompt: `${context.command}\n\nAlready applied: ${context.applied.join(', ')}`,
|
|
212
|
+
allowedEvents: ['ADD_TODO', 'TOGGLE_TODO', 'DONE'],
|
|
213
|
+
}),
|
|
214
|
+
},
|
|
215
|
+
on: {
|
|
216
|
+
ADD_TODO: ({ context, event }) => ({
|
|
217
|
+
target: 'applying',
|
|
218
|
+
context: { applied: [...context.applied, `ADD_TODO ${event.title}`] },
|
|
219
|
+
}),
|
|
220
|
+
DONE: { target: 'awaitingCommand' },
|
|
221
|
+
},
|
|
222
|
+
},
|
|
223
|
+
applying: { always: { target: 'planning' } },
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Every step runs the validation and retry loop described above. For the full example, see [examples/todo-nl/index.ts](https://github.com/statelyai/agent/blob/next/examples/todo-nl/index.ts).
|
|
227
|
+
|
|
228
|
+
To let the model send several events in one tool loop instead, invoke `agent.act`. See [Acting on events](act.md).
|
|
229
|
+
|
|
230
|
+
## Closed choices
|
|
231
|
+
|
|
232
|
+
By default the model writes the event payload. A **closed choice** lists the concrete events instead, and the model picks one.
|
|
233
|
+
|
|
234
|
+
- Pass `payloads` on the `agent.decide` input: one payload list per event type, without `type`.
|
|
235
|
+
- Each payload becomes one option on `request.options`.
|
|
236
|
+
- An event type in `allowedEvents` with no `payloads` key is offered bare, as `{ type }`. An empty list offers nothing for that type. To withhold a type, give it `[]`: `payloads: { refund: [{ amount: 20 }], escalate: [] }`.
|
|
237
|
+
- The runtime keeps only the options `snapshot.can(event)` accepts right now.
|
|
238
|
+
- The chosen event must equal one offered option, type and payload. Any other choice is retried as a `rejected-by-guard` attempt.
|
|
239
|
+
- When the snapshot accepts none of the options, the decision fails at once with `AgentDecisionExhaustedError` and no model call. Handle it with the invoke's `onError`.
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
import { createAgentSchemas, setupAgent } from "@statelyai/agent";
|
|
243
|
+
import { z } from "zod";
|
|
244
|
+
|
|
245
|
+
const agent = setupAgent({
|
|
246
|
+
schemas: createAgentSchemas({
|
|
247
|
+
context: z.object({ limit: z.number() }),
|
|
248
|
+
events: { refund: z.object({ amount: z.number() }), escalate: z.object({}) },
|
|
249
|
+
}),
|
|
250
|
+
});
|
|
251
|
+
|
|
252
|
+
agent.createMachine({
|
|
253
|
+
context: { limit: 50 },
|
|
254
|
+
initial: "deciding",
|
|
255
|
+
states: {
|
|
256
|
+
deciding: {
|
|
257
|
+
invoke: {
|
|
258
|
+
src: "agent.decide",
|
|
259
|
+
input: {
|
|
260
|
+
model: "quick",
|
|
261
|
+
allowedEvents: ["refund", "escalate"],
|
|
262
|
+
// The model sees refund 20 and escalate. The machine does not accept refund 80.
|
|
263
|
+
payloads: { refund: [{ amount: 20 }, { amount: 80 }] },
|
|
264
|
+
},
|
|
265
|
+
},
|
|
266
|
+
on: {
|
|
267
|
+
refund: ({ context, event }) =>
|
|
268
|
+
event.amount <= context.limit ? { target: "refunded" } : undefined,
|
|
269
|
+
escalate: { target: "escalated" },
|
|
270
|
+
},
|
|
271
|
+
},
|
|
272
|
+
refunded: {},
|
|
273
|
+
escalated: {},
|
|
274
|
+
},
|
|
275
|
+
});
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
### Closed choices in the shipped adapters
|
|
279
|
+
|
|
280
|
+
- In object mode, the answer is `{ choice }`, an enum of option ids such as `refund:20` and `escalate`. The schema description lists each id with its description.
|
|
281
|
+
- In tool mode, `createAiSdkExecutors` presents a closed choice as ONE tool, `choose_option`, whose input is `{ option }` over the same ids.
|
|
282
|
+
- The chosen id maps back to that option's event.
|
|
283
|
+
- An id that is not offered, or a call to another tool, is retried as an `unknown-event` attempt. Its reason names the answer and lists the valid ids.
|
|
284
|
+
|
|
285
|
+
### Decision models
|
|
286
|
+
|
|
287
|
+
An AI SDK decision model, such as TypeSafe's Jev, goes in the same `createAiSdkExecutors` models map as the language models. A decide request whose model ref names it is answered through `experimental_decide`.
|
|
288
|
+
|
|
289
|
+
- The request must be a closed choice: `payloads` on `agent.decide`, `decideNext`, or the pick step of a [decision strategy](#decision-strategies). A request without options throws.
|
|
290
|
+
- It 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.
|
|
291
|
+
- A label that is not an option is retried as an `unknown-event` attempt, like any failed choice.
|
|
292
|
+
- The result carries `confidence` when the model reports it. Branch on it in your own code.
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
296
|
+
import { openai } from "@ai-sdk/openai";
|
|
297
|
+
import { typeSafeAi } from "@ai-sdk/typesafe-ai";
|
|
298
|
+
|
|
299
|
+
const { decide } = createAiSdkExecutors({
|
|
300
|
+
models: { desk: openai("gpt-6-luna"), judge: typeSafeAi.decisionModel("jev-latest") },
|
|
301
|
+
});
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
See [Decision models](models-and-providers.md#decision-models).
|
|
305
|
+
|
|
306
|
+
## Decision strategies
|
|
307
|
+
|
|
308
|
+
A **decision strategy** splits one decision into several model calls. Set `strategy` on the `agent.decide` input (or on `createDecisionLogic`). Core runs the strategy around the `decide` executor, so validation and retries apply to the combined answer, and any adapter works.
|
|
309
|
+
|
|
310
|
+
| Strategy | Model calls |
|
|
311
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
|
|
312
|
+
| `'direct'` | One decide call over every candidate event. |
|
|
313
|
+
| `'pick-then-fill'` | Pick the event type as a closed choice over bare `{ type }` options, then fill its payload. |
|
|
314
|
+
| `'grouped'` | Pick a group of event types as a closed choice, then one decide call within that group. |
|
|
315
|
+
| `'auto'` (default) | `'pick-then-fill'` when `fillModel` is set; `'grouped'` over more than 24 events in two or more groups; else `'direct'`. |
|
|
316
|
+
|
|
317
|
+
Filling a payload under `'pick-then-fill'`:
|
|
318
|
+
|
|
319
|
+
- An event with no payload fields: no fill call.
|
|
320
|
+
- Every payload field finite (an `enum`, a `const`, a boolean, or a union of those), with at most 32 combinations (`MAX_FINITE_PAYLOADS`): a closed choice over the enumerated payloads, on the same model.
|
|
321
|
+
- Any open field: a structured `generateText` call on `fillModel`, with the event's payload schema as its output schema and `type` fixed. This needs a `generateText` executor.
|
|
322
|
+
- Open fields with no `fillModel` throw `missing-fill-model` at runtime. `verifyAgentConfig` reports it at setup when `strategy: 'pick-then-fill'` is literal.
|
|
323
|
+
|
|
324
|
+
Groups under `'grouped'`:
|
|
325
|
+
|
|
326
|
+
- `groups` maps a group name to its event types: `groups: { cart: ["cart.add", "cart.clear"] }`.
|
|
327
|
+
- An event type in no group is grouped by its prefix before the first `.`. `cart.add` and `cart.clear` group as `cart`.
|
|
328
|
+
- Each group option's description lists its member types. A request with fewer than two groups makes one direct call.
|
|
329
|
+
|
|
330
|
+
Every sub-call counts against the model-call budget, emits its own trace events, and receives the decision's prior `attempts`. Its `info.callKey` adds the role to the attempt key: `<key>.<attempt>.pick`, `.group`, or `.fill`. See [Idempotency keys](hosts.md#idempotency-keys).
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
import { createAgentSchemas, setupAgent } from "@statelyai/agent";
|
|
334
|
+
import { z } from "zod";
|
|
335
|
+
|
|
336
|
+
const agent = setupAgent({
|
|
337
|
+
schemas: createAgentSchemas({
|
|
338
|
+
context: z.object({}),
|
|
339
|
+
events: {
|
|
340
|
+
refund: z.object({ amount: z.number(), reason: z.string() }),
|
|
341
|
+
escalate: z.object({ queue: z.enum(["billing", "tech"]) }),
|
|
342
|
+
},
|
|
343
|
+
}),
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
agent.createMachine({
|
|
347
|
+
context: {},
|
|
348
|
+
initial: "triaging",
|
|
349
|
+
states: {
|
|
350
|
+
triaging: {
|
|
351
|
+
invoke: {
|
|
352
|
+
src: "agent.decide",
|
|
353
|
+
input: {
|
|
354
|
+
model: "judge",
|
|
355
|
+
fillModel: "writer",
|
|
356
|
+
allowedEvents: ["refund", "escalate"],
|
|
357
|
+
},
|
|
358
|
+
},
|
|
359
|
+
on: { refund: { target: "refunded" }, escalate: { target: "escalated" } },
|
|
360
|
+
},
|
|
361
|
+
refunded: {},
|
|
362
|
+
escalated: {},
|
|
363
|
+
},
|
|
364
|
+
});
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
`fillModel` is set, so `'auto'` resolves to `'pick-then-fill'`. `judge` picks `refund` or `escalate`. `escalate` has one finite field, so `judge` also picks its `queue`. `refund` has open fields, so `writer` writes `amount` and `reason`.
|
|
368
|
+
|
|
369
|
+
### Decision models with `fillModel`
|
|
370
|
+
|
|
371
|
+
A decision model such as Jev answers only closed choices. `'pick-then-fill'` turns an open choice into closed ones, so a decision model can pick the event type while `fillModel` names a language model that writes the open payload. In the example above, `judge` can be `typeSafeAi.decisionModel("jev-latest")` and `writer` a language model in the same models map.
|
|
372
|
+
|
|
373
|
+
## A policy as the decider
|
|
374
|
+
|
|
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
|
+
|
|
377
|
+
```ts no-check
|
|
378
|
+
import { createPolicyDecider, runAgent } from "@statelyai/agent";
|
|
379
|
+
|
|
380
|
+
const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
|
|
381
|
+
|
|
382
|
+
await runAgent(deskMachine, { input, executors: { ...modelExecutors, decide } });
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
- Each decision request starts one run of the policy. Its output, an event, is the choice. The environment still judges it: an event it does not accept is retried like any decider's.
|
|
386
|
+
- The policy's input defaults to `{ facts, options, system, prompt }`: the request's `metadata.facts`, the offered events, and its prompt. The policy's input schema validates it. Pass `input: (request) => ...` to build it another way.
|
|
387
|
+
- The policy's own `agent.decide` invokes are answered by `executors`. Pass the environment's `metadata` on to them, so the model sees what it would without the policy.
|
|
388
|
+
- The result carries the policy's token usage, and none when it decided with a rule.
|
|
389
|
+
- A run that does not end `done` with an event throws `AgentError` with code `policy-not-done`. Give each of the policy's decisions an `onError` that falls back to an event the environment always accepts.
|
|
390
|
+
- Every other `runAgent` option passes through: `store` and `metadata` to journal the policy's runs, `onTrace` to trace them.
|
|
391
|
+
- Each decision's policy run gets its own `store` thread, `policy:${info.callKey}:${hash}` by default, where `hash` is the SHA-256 of the policy input: a thread that already has entries is resumed, so a shared one would return an earlier choice. The hash keeps a machine that asks something else at the same call site after a version bridge, which keeps the call key, off the earlier thread. Pass `threadId: (request, info) => ...` to name them yourself; it is required with a `store` when the decider is called without a `callKey`.
|
|
392
|
+
- The policy's input must be JSON, since it opens the run's event log. The default drops keys whose value is `undefined`; any other value that is not JSON throws before the run.
|
|
393
|
+
|
|
394
|
+
To route by request name, wrap it: `decide: (request, info) => (request.name === "chooseResolution" ? policyDecide(request, info) : modelExecutors.decide!(request, info))`, where `policyDecide` is the executor `createPolicyDecider` returned.
|
|
395
|
+
|
|
396
|
+
## Decisions at the boundary of a plain machine
|
|
397
|
+
|
|
398
|
+
A machine does not have to know about AI. `decideNext` asks a model to pick one event that a plain XState machine accepts right now, built with `createMachine` or `setup`, with no `agent.*` invoke anywhere.
|
|
399
|
+
|
|
400
|
+
- `allowedEvents`: exact types or wildcards such as `'desk.*'`. Candidates are the matching events an active state handles.
|
|
401
|
+
- `payloads` (optional): a function of the snapshot returning payloads per event type, as in a closed choice. A candidate type with no key is offered bare, as `{ type }`. An empty list offers nothing for that type, so `{ "desk.escalate": [] }` withholds it.
|
|
402
|
+
- Options are kept only where `snapshot.can(event)` is true. Each one is described by its transition's `description`, else its event schema's description.
|
|
403
|
+
- `lookahead` (optional): appends what each option changes, computed with xstate's pure `transition()`: the state value and the changed top-level context keys.
|
|
404
|
+
- `true` reports every changed key.
|
|
405
|
+
- An array of context keys reports only those keys. A state value change is always reported.
|
|
406
|
+
- Each reported value is cut at 120 characters.
|
|
407
|
+
- With no options, it returns `{ event: null }` without calling the executor.
|
|
408
|
+
- 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
|
+
```ts
|
|
411
|
+
import { decideNext } from "@statelyai/agent";
|
|
412
|
+
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
413
|
+
import { openai } from "@ai-sdk/openai";
|
|
414
|
+
import { createActor, createMachine } from "xstate";
|
|
415
|
+
import { z } from "zod";
|
|
416
|
+
|
|
417
|
+
const desk = createMachine({
|
|
418
|
+
schemas: {
|
|
419
|
+
context: z.object({ requested: z.number(), limit: z.number() }),
|
|
420
|
+
events: {
|
|
421
|
+
"desk.refund": z.object({ amount: z.number() }),
|
|
422
|
+
"desk.escalate": z.object({}).describe("Hand the case to a person"),
|
|
423
|
+
},
|
|
424
|
+
},
|
|
425
|
+
context: { requested: 20, limit: 50 },
|
|
426
|
+
initial: "reviewing",
|
|
427
|
+
states: {
|
|
428
|
+
reviewing: {
|
|
429
|
+
on: {
|
|
430
|
+
"desk.refund": {
|
|
431
|
+
description: "Refund the customer",
|
|
432
|
+
to: ({ context, event }) =>
|
|
433
|
+
event.amount <= context.limit ? { target: "refunded" } : undefined,
|
|
434
|
+
},
|
|
435
|
+
"desk.escalate": { target: "escalated" },
|
|
436
|
+
},
|
|
437
|
+
},
|
|
438
|
+
refunded: {},
|
|
439
|
+
escalated: {},
|
|
440
|
+
},
|
|
441
|
+
});
|
|
442
|
+
|
|
443
|
+
const { decide } = createAiSdkExecutors({ models: { quick: openai("gpt-6-luna") } });
|
|
444
|
+
const actor = createActor(desk);
|
|
445
|
+
|
|
446
|
+
let busy = false;
|
|
447
|
+
actor.subscribe(async (snapshot) => {
|
|
448
|
+
if (busy || !snapshot.matches("reviewing")) return;
|
|
449
|
+
busy = true;
|
|
450
|
+
try {
|
|
451
|
+
const { event } = await decideNext(snapshot, {
|
|
452
|
+
decide,
|
|
453
|
+
model: "quick",
|
|
454
|
+
allowedEvents: "desk.*",
|
|
455
|
+
payloads: (s) => ({ "desk.refund": [{ amount: s.context.requested }] }),
|
|
456
|
+
lookahead: true,
|
|
457
|
+
});
|
|
458
|
+
if (event && actor.getSnapshot().can(event)) actor.send(event);
|
|
459
|
+
} finally {
|
|
460
|
+
busy = false;
|
|
461
|
+
}
|
|
462
|
+
});
|
|
463
|
+
actor.start();
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
The result also carries `attempts`, the failed choices before the one that landed, and the `request` the executor saw. `withheld` lists the candidates the snapshot rejected: each `allowedEvents` type and payload, built like the options, where `snapshot.can(event)` was false. The model never sees them; `request.withheld` holds the same list. A closed choice under the runtime sets `request.withheld` the same way, and traces it even when every option is withheld and no model call is made. Exhausting retries throws `AgentDecisionExhaustedError`. To journal `attempts`, pass them with the event to the run that delivers it. See [Boundary decisions](event-log.md#boundary-decisions).
|
|
467
|
+
|
|
468
|
+
## Related
|
|
469
|
+
|
|
470
|
+
- Read more about [Agent machines](machines.md), including transitions, guards, and event schemas.
|
|
471
|
+
- Read more about [Acting on events](act.md), for several events in one tool loop.
|
|
472
|
+
- Read more about [Hosts](hosts.md), including the decide executor and how the model is coerced into one event.
|
|
473
|
+
- Read more about [Machines as data](machines-as-data.md), including authoring decisions from JSON.
|