@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
package/docs/machines.md
ADDED
|
@@ -0,0 +1,497 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Agent machines
|
|
3
|
+
description: Author an agent machine as a typed XState state machine that decides what your agent can do, while the host executes model calls.
|
|
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
|
+
An **agent machine** is a typed XState state machine that describes what your agent can do. It declares the states, the legal transitions, the model calls, and the events the model may choose in each state. An agent machine never calls a model itself. The host executes model calls on its behalf.
|
|
11
|
+
|
|
12
|
+
<!-- viz: data-flow figure of the machine/host boundary: machine invokes a request -> host executor calls the model SDK -> output validated against the output schema -> onDone transition applied to the machine -->
|
|
13
|
+
|
|
14
|
+
Author a machine in three steps:
|
|
15
|
+
|
|
16
|
+
1. Declare a models registry and your `context`/`input`/`output`/`events` schema fields.
|
|
17
|
+
2. Pass them to `setupAgent` with your requests and actor sources.
|
|
18
|
+
3. Build with `agentSetup.createMachine`.
|
|
19
|
+
|
|
20
|
+
## Schema declarations
|
|
21
|
+
|
|
22
|
+
<!-- flat schema fields on setupAgent from src/setup-agent.ts -->
|
|
23
|
+
|
|
24
|
+
Pass schema fields directly to `setupAgent` to type your data. `context` is required. `input`, `output`, `events`, `emitted`, and `meta` are optional.
|
|
25
|
+
|
|
26
|
+
Every schema is a [Standard Schema](https://standardschema.dev). Zod, Valibot, ArkType, and hand-written validators all work. The agent retains the schemas, so context and events are typed without `{} as Type` casts.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { z } from "zod";
|
|
30
|
+
import { setupAgent } from "@statelyai/agent";
|
|
31
|
+
|
|
32
|
+
const agentSetup = setupAgent({
|
|
33
|
+
models,
|
|
34
|
+
context: z.object({ prompt: z.string(), answer: z.string().nullable() }),
|
|
35
|
+
input: z.object({ prompt: z.string() }),
|
|
36
|
+
output: z.object({ answer: z.string() }),
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
<!-- machine input validation from src/run-agent.ts and the input schema retained by src/setup-agent.ts -->
|
|
41
|
+
|
|
42
|
+
`runToQuiescence` validates supplied machine input before the
|
|
43
|
+
actor starts. Defaults and transforms from the input schema reach the context
|
|
44
|
+
factory and trace; invalid input throws `AgentError` with code
|
|
45
|
+
`invalid-machine-input`. Calling XState's `createActor` directly does not run
|
|
46
|
+
this validation.
|
|
47
|
+
|
|
48
|
+
To keep conversation history in context, add a `messages` field with the `z.custom<AgentMessage[]>` recipe. See [Messages](messages.md).
|
|
49
|
+
|
|
50
|
+
### Event schemas
|
|
51
|
+
|
|
52
|
+
Event schemas type event payloads. Declare one schema per event type under `events`:
|
|
53
|
+
|
|
54
|
+
```ts no-check
|
|
55
|
+
// setupAgent({ ... })
|
|
56
|
+
events: {
|
|
57
|
+
ATTACK: z.object({ target: z.string().default('goblin') }),
|
|
58
|
+
HEAL: z.object({ amount: z.number().min(1).max(8).default(4) }),
|
|
59
|
+
FLEE: {},
|
|
60
|
+
},
|
|
61
|
+
// ...
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
In a `HEAL` transition, `event.amount` is a `number`. Reading a field the event does not carry is a compile error. Write `{}` for a payload-less event.
|
|
65
|
+
|
|
66
|
+
### Emitted event schemas
|
|
67
|
+
|
|
68
|
+
Emitted event schemas type the progress events a machine emits with `enq.emit(...)`. Hosts receive them through `runToQuiescence`'s `on` handlers. Declare them under `emitted`:
|
|
69
|
+
|
|
70
|
+
```ts no-check
|
|
71
|
+
// setupAgent({ ... })
|
|
72
|
+
emitted: {
|
|
73
|
+
EVALUATED: z.object({ qualityScore: z.number(), iteration: z.number() }),
|
|
74
|
+
},
|
|
75
|
+
// ...
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Both `enq.emit({ type: 'EVALUATED', ... })` and the host-side `on: { EVALUATED: handler }` are then typed. An undeclared type or a wrong payload is a compile error. See [Observability](observability.md).
|
|
79
|
+
|
|
80
|
+
> **Note:** To reuse one schema set across machines or the step helpers, declare it once with `createAgentSchemas({ context, input, output, events })` and pass it as `setupAgent({ schemas })`. This is equivalent to the inline form. See [Authoring forms](#authoring-forms).
|
|
81
|
+
|
|
82
|
+
<!-- getAgentSchemas registration and lookup from src/setup-agent.ts -->
|
|
83
|
+
|
|
84
|
+
When a generic host receives only a machine, call `getAgentSchemas(machine)` to
|
|
85
|
+
recover its schema pack for validation or form generation. It returns
|
|
86
|
+
`undefined` for plain XState machines. Read it before `machine.provide(...)`;
|
|
87
|
+
the provided machine is a new object and does not carry the registration.
|
|
88
|
+
|
|
89
|
+
### Type extraction
|
|
90
|
+
|
|
91
|
+
<!-- public type helpers from src/type-helpers.ts and src/index.ts -->
|
|
92
|
+
|
|
93
|
+
Use the exported `ContextOf`, `InputOf`, `OutputOf`, and `EventOf` helpers with
|
|
94
|
+
either an Agent setup or a machine. Machine-only helpers are `SnapshotOf` and
|
|
95
|
+
`StateValueOf`; `MetaOf` extracts declared metadata, and `RequestNamesOf`
|
|
96
|
+
extracts a setup's registered request-name union.
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
import type { ContextOf, EventOf, RequestNamesOf, SnapshotOf } from "@statelyai/agent";
|
|
100
|
+
|
|
101
|
+
type AgentContext = ContextOf<typeof agentSetup>;
|
|
102
|
+
type AgentEvent = EventOf<typeof machine>;
|
|
103
|
+
type AgentSnapshot = SnapshotOf<typeof machine>;
|
|
104
|
+
type RequestName = RequestNamesOf<typeof agentSetup>;
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Agent setup
|
|
108
|
+
|
|
109
|
+
<!-- setupAgent config surface (models, requests, actors, builtins) from src/setup-agent.ts -->
|
|
110
|
+
|
|
111
|
+
Beyond schemas, `setupAgent` takes your models plus optional `requests`, `actors`, `actions`, `guards`, `states`, and `delays`. `states` narrows context per state. See [Per-state context narrowing](#per-state-context-narrowing). `delays` names the durations that [delayed transitions](#delayed-transitions) reference. It returns a **setup** whose `createMachine` method builds the machine. Like XState's `setup()`, the return value is a typed foundation, not a running agent. Name it accordingly, for example `agentSetup` or `gameSetup`.
|
|
112
|
+
|
|
113
|
+
The builtins `agent.generateText`, `agent.streamText`, and `agent.decide` are registered automatically. Invoke them by name.
|
|
114
|
+
|
|
115
|
+
The setup's type is `SetupAgentResult<…>`, exported from the root, so `export const agentSetup = setupAgent(...)` emits portable declarations under `declaration: true` or `composite: true` (TS 6 and 7) with no annotation.
|
|
116
|
+
|
|
117
|
+
### Models
|
|
118
|
+
|
|
119
|
+
The `models` map pairs a short alias with a resolved model. Request and decision `model:` values autocomplete against its keys. Pass the same map to the host adapter. See [Models and providers](models-and-providers.md).
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { openai } from "@ai-sdk/openai";
|
|
123
|
+
import {} from "@statelyai/agent/ai-sdk";
|
|
124
|
+
|
|
125
|
+
const models = {
|
|
126
|
+
quick: openai("gpt-6-luna"),
|
|
127
|
+
careful: openai("gpt-6.1-sol"),
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
const agentSetup = setupAgent({
|
|
131
|
+
models,
|
|
132
|
+
context,
|
|
133
|
+
input,
|
|
134
|
+
output,
|
|
135
|
+
requests: {
|
|
136
|
+
answerQuestion: {
|
|
137
|
+
schemas: { input: z.object({ prompt: z.string() }), output: answerSchema },
|
|
138
|
+
model: "quick", // typed as "quick" | "careful"
|
|
139
|
+
prompt: ({ input }) => input.prompt,
|
|
140
|
+
},
|
|
141
|
+
},
|
|
142
|
+
});
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Aliases are optional. A request can carry any `model:` string, such as `'openai/gpt-6-luna'`, that the host resolves at run time. See [Authoring forms](#authoring-forms).
|
|
146
|
+
|
|
147
|
+
### Requests
|
|
148
|
+
|
|
149
|
+
The `requests` map declares named text requests inline. Each entry carries its own input and output schemas, a model, and a `prompt` or `messages` value built from typed input. Each entry becomes an actor you invoke by its key.
|
|
150
|
+
|
|
151
|
+
```ts no-check
|
|
152
|
+
// setupAgent({ ... })
|
|
153
|
+
requests: {
|
|
154
|
+
classifyAnswer: {
|
|
155
|
+
schemas: {
|
|
156
|
+
input: z.object({ question: z.string(), rawAnswer: z.string() }),
|
|
157
|
+
output: z.object({ answer: z.enum(["yes", "no"]) }),
|
|
158
|
+
},
|
|
159
|
+
model: "quick",
|
|
160
|
+
system: "Classify a natural-language answer as yes or no.",
|
|
161
|
+
prompt: ({ input }) => `Q: ${input.question}\nA: ${input.rawAnswer}`,
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
// ...
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
See [Text requests](text-requests.md) for the full request surface, including streaming and structured output.
|
|
168
|
+
|
|
169
|
+
### Actors
|
|
170
|
+
|
|
171
|
+
The `actors` map registers reusable actor logic. This can be text logic from `createTextLogic` or any XState actor. Register logic here when it is reusable, exported, or worth testing on its own.
|
|
172
|
+
|
|
173
|
+
Non-model work is an ordinary XState actor. `createAsyncLogic({ schemas, run })` is the usual form: `run` receives the validated `input` and resolves the actor's output. Annotate `run`'s return type when it resolves an array or another literal, because the schema type parameters are `const` and an unannotated array literal infers as a readonly tuple.
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
import { createAsyncLogic } from "xstate";
|
|
177
|
+
|
|
178
|
+
const fetchOrder = createAsyncLogic({
|
|
179
|
+
schemas: { input: z.object({ orderId: z.string() }), output: z.object({ total: z.number() }) },
|
|
180
|
+
run: async ({ input }) => ({ total: input.orderId.length }),
|
|
181
|
+
});
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Decisions are state-local. They use `src: 'agent.decide'` and are not actor sources. To reuse a decision, share its input builder.
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { createTextLogic } from "@statelyai/agent";
|
|
188
|
+
|
|
189
|
+
const summarizeTurn = createTextLogic({
|
|
190
|
+
schemas: { input: z.object({ log: z.string() }), output: z.string() },
|
|
191
|
+
model: "quick",
|
|
192
|
+
prompt: ({ input }) => `Summarize this turn:\n${input.log}`,
|
|
193
|
+
});
|
|
194
|
+
|
|
195
|
+
const agentSetup = setupAgent({
|
|
196
|
+
models,
|
|
197
|
+
context: z.object({ log: z.string(), summary: z.string().nullable() }),
|
|
198
|
+
input: z.object({ log: z.string() }),
|
|
199
|
+
actors: { summarizeTurn },
|
|
200
|
+
});
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
> **Warning:** Actor source keys must be unique across `actors` and `requests`. `setupAgent` throws at setup time on a collision.
|
|
204
|
+
|
|
205
|
+
### Built-in actor sources
|
|
206
|
+
|
|
207
|
+
<!-- builtin src reference, from src/setup-agent.ts -->
|
|
208
|
+
|
|
209
|
+
`setupAgent` registers reserved `src` strings on every machine. Use them for ad-hoc model work that does not warrant a named request. The invoke's `input` shapes each call:
|
|
210
|
+
|
|
211
|
+
| `src` | Invoke `input` | `onDone` output | Reference |
|
|
212
|
+
| -------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- |
|
|
213
|
+
| `agent.generateText` | `model`, `prompt` or `messages`, optional `system`, `outputSchema`, `tools` | `{ result, messages }`: text or the value parsed from `outputSchema`, plus response messages | [Text requests](text-requests.md) |
|
|
214
|
+
| `agent.streamText` | same as `agent.generateText` | same, with chunks delivered to the host as they arrive | [Text requests](text-requests.md) |
|
|
215
|
+
| `agent.decide` | `model`, `prompt`, optional `system`, `allowedEvents` | the one chosen event, applied to the machine | [Decisions](decisions.md) |
|
|
216
|
+
|
|
217
|
+
A human's turn is not a builtin: it is an idle state with accepted events. See [Human in the loop](human-in-the-loop.md).
|
|
218
|
+
|
|
219
|
+
Named `requests` are the default form because they are typed, reusable, and testable. The builtins are the inline alternative. The host executes both, so neither form names a model SDK in the machine.
|
|
220
|
+
|
|
221
|
+
## Authoring forms
|
|
222
|
+
|
|
223
|
+
<!-- canonical form vs the supported escape hatches -->
|
|
224
|
+
|
|
225
|
+
The canonical form covers most machines: a `models` registry, flat schema fields on `setupAgent`, `model: 'quick'` alias keys, and a host with `createAiSdkExecutors({ models })`. Use it whenever the models are known at author time.
|
|
226
|
+
|
|
227
|
+
Each alternate form handles one specific need:
|
|
228
|
+
|
|
229
|
+
| Form | Use it when |
|
|
230
|
+
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
|
+
| `createAgentSchemas` pack, passed as `setupAgent({ schemas })` | You share one schema set across several machines or the [step helpers](steps.md). |
|
|
232
|
+
| String model refs with `resolveModel` (`model: 'openai/gpt-6-luna'`, `createAiSdkExecutors({ resolveModel })`) | The machine must not name concrete models, for portability or for refs loaded from JSON [config](machines-as-data.md). |
|
|
233
|
+
| `createTextLogic`, a standalone request value | A request is exported, reused across states or machines, or unit-tested on its own. See [Text requests](text-requests.md#reusable-request-logic-with-createtextlogic). |
|
|
234
|
+
| `logic.withExecutor(...)` | You bind execution onto one logic instead of the whole host, so a plain `createActor` runs it without [`runToQuiescence`](hosts.md#write-your-own-host-loop)'s executor slots. Registered dynamic spawns inherit through `actors`. See [Multi-agent composition](multi-agent.md#collecting-dynamic-children). |
|
|
235
|
+
|
|
236
|
+
## Machine creation
|
|
237
|
+
|
|
238
|
+
`agentSetup.createMachine` is XState's `createMachine` with the agent's schemas and actors already bound. It registers the machine, so the step helpers and [`runToQuiescence`](hosts.md) resolve its schemas and actors without you passing them again.
|
|
239
|
+
|
|
240
|
+
<!-- viz: state diagram for the answering machine below: initial state `answering` invoking the `answerQuestion` request, onDone -> final state `done` producing { answer } -->
|
|
241
|
+
|
|
242
|
+
```ts no-check
|
|
243
|
+
const machine = agentSetup.createMachine({
|
|
244
|
+
context: ({ input }) => ({ prompt: input.prompt, answer: null }),
|
|
245
|
+
initial: "answering",
|
|
246
|
+
states: {
|
|
247
|
+
answering: {
|
|
248
|
+
invoke: {
|
|
249
|
+
id: "answer",
|
|
250
|
+
src: "answerQuestion",
|
|
251
|
+
input: ({ context }) => ({ prompt: context.prompt }),
|
|
252
|
+
onDone: ({ output }) => ({
|
|
253
|
+
target: "done",
|
|
254
|
+
context: { answer: output.result.answer },
|
|
255
|
+
}),
|
|
256
|
+
},
|
|
257
|
+
},
|
|
258
|
+
done: {
|
|
259
|
+
type: "final",
|
|
260
|
+
output: ({ context }) => ({ answer: context.answer ?? "" }),
|
|
261
|
+
},
|
|
262
|
+
},
|
|
263
|
+
});
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## Per-state context narrowing
|
|
267
|
+
|
|
268
|
+
A context field that starts `null` and is assigned mid-run forces a `?? fallback` at every later read. When a state is reachable only after that field is set, narrow it with XState's native per-state context schema under `setupAgent({ states })`. The narrowed type flows into that state's invoke `input`, transition functions, and `output`, so the fallback is no longer needed:
|
|
269
|
+
|
|
270
|
+
```ts
|
|
271
|
+
const context = z.object({ question: z.string(), plan: planSchema.nullable() });
|
|
272
|
+
|
|
273
|
+
const agentSetup = setupAgent({
|
|
274
|
+
context,
|
|
275
|
+
// `planning` assigns `plan` before `executing` and `done` run, so narrow it there.
|
|
276
|
+
states: {
|
|
277
|
+
executing: { schemas: { context: context.extend({ plan: planSchema }) } },
|
|
278
|
+
done: { schemas: { context: context.extend({ plan: planSchema }) } },
|
|
279
|
+
},
|
|
280
|
+
});
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
> **Note:** Narrow only where every path into the state has assigned the field. A state that is also reachable on an error or refusal route, where the field is still `null`, must keep its nullable handling. Narrowing changes the type only. Runtime behavior is unchanged.
|
|
284
|
+
|
|
285
|
+
See [examples/sql-agent/index.ts](https://github.com/statelyai/agent/blob/next/examples/sql-agent/index.ts).
|
|
286
|
+
|
|
287
|
+
## Transitions
|
|
288
|
+
|
|
289
|
+
<!-- transition-function authoring style from src/setup-agent.ts and examples/twenty-questions -->
|
|
290
|
+
|
|
291
|
+
A **transition** is a function of `{ context, event }` that returns the next `target` and a `context` update. The update is partial: omitted fields keep their values. You return updates instead of assigning them with `assign()`. The `event` is typed from the event schema.
|
|
292
|
+
|
|
293
|
+
```ts no-check
|
|
294
|
+
// inside a state
|
|
295
|
+
on: {
|
|
296
|
+
ATTACK: ({ context, event }) => ({
|
|
297
|
+
target: 'summarizing',
|
|
298
|
+
context: { enemyHp: Math.max(0, context.enemyHp - 6), defended: false },
|
|
299
|
+
}),
|
|
300
|
+
}
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
> **Note:** Guards are a return value, not a `guard:` field. Returning `undefined` from a transition function makes that transition illegal for the current snapshot. The condition and the transition live in the same function, so they cannot disagree. `snapshot.can(event)`, which determines [decision](decisions.md) legality, derives from the same code path. If you know XState's `guard:`, read "returns `undefined`" wherever you would expect one.
|
|
304
|
+
|
|
305
|
+
```ts no-check
|
|
306
|
+
// inside a state
|
|
307
|
+
on: {
|
|
308
|
+
// ASK is only legal before the final turn.
|
|
309
|
+
ASK: ({ context }) =>
|
|
310
|
+
context.questionsRemaining > 1
|
|
311
|
+
? { target: 'awaitingAnswer', context: { questionsRemaining: context.questionsRemaining - 1 } }
|
|
312
|
+
: undefined,
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
This affects [decisions](decisions.md). If the model chooses an event whose transition returns `undefined`, the choice is rejected before the transition is taken.
|
|
317
|
+
|
|
318
|
+
A transition can also be a plain object. Its `context` is a static patch, or a mapper function that receives the same arguments. On `onDone`, those arguments include `output` (for a text request, `{ result, messages }`):
|
|
319
|
+
|
|
320
|
+
```ts no-check
|
|
321
|
+
// inside a state
|
|
322
|
+
on: {
|
|
323
|
+
SEND: { target: 'sending' },
|
|
324
|
+
DEFEND: { target: 'summarizing', context: { defended: true } },
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
// on an invoke
|
|
328
|
+
onDone: {
|
|
329
|
+
target: 'revising',
|
|
330
|
+
context: ({ output }) => ({ feedback: output.result.feedback }),
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
Use the function form when the `target` is conditional or when you need `enq` to enqueue effects. Use the object form otherwise.
|
|
335
|
+
|
|
336
|
+
Keep conditional targets visible in the transition expression, as in the
|
|
337
|
+
`ASK` example above. Do not hide target selection in a helper call or an
|
|
338
|
+
arbitrary block body: the machine may run, but static graph tools cannot
|
|
339
|
+
reliably discover those targets.
|
|
340
|
+
|
|
341
|
+
## Choice states
|
|
342
|
+
|
|
343
|
+
<!-- choice state node type from xstate v6 (StateMachine formatChoiceTransitions) and src/machines/loop.ts -->
|
|
344
|
+
|
|
345
|
+
A **choice state** routes to one of several targets without waiting for an event. Set `type: 'choice'` and give the state a `choice` function of `{ context, event }` that returns the transition to take. The machine enters the state, runs the function, and leaves immediately.
|
|
346
|
+
|
|
347
|
+
```ts no-check
|
|
348
|
+
// inside states: { ... }
|
|
349
|
+
checking: {
|
|
350
|
+
type: 'choice',
|
|
351
|
+
choice: ({ context }) =>
|
|
352
|
+
context.iterations >= context.maxTurns || context.done
|
|
353
|
+
? { target: 'done' }
|
|
354
|
+
: { target: 'running' },
|
|
355
|
+
},
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
The returned object takes `target`, and optionally `description`, `reenter`, and `meta`. It cannot update `context`; a choice only routes. The function must return a target. A choice state whose function returns no target throws at run time.
|
|
359
|
+
|
|
360
|
+
A choice state has no other behavior. `on`, `always`, `after`, `entry`, `exit`, `invoke`, and `states` are not allowed on it. Put the work in the target states.
|
|
361
|
+
|
|
362
|
+
A choice function receives the same first argument as a transition function (`context`, `event`, `self`, `system`, `guards`, `actors`), but no `enq` argument, so it cannot emit, spawn, raise, or send. Routing that must also do one of those uses an `always` transition on a normal state, whose function takes `enq` like any transition function:
|
|
363
|
+
|
|
364
|
+
```ts no-check
|
|
365
|
+
// Routes only.
|
|
366
|
+
checking: {
|
|
367
|
+
type: 'choice',
|
|
368
|
+
choice: ({ context }) =>
|
|
369
|
+
context.score >= 0.8 ? { target: 'accepted' } : { target: 'rejected' },
|
|
370
|
+
},
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
```ts no-check
|
|
374
|
+
// Routes and emits.
|
|
375
|
+
routing: {
|
|
376
|
+
always: ({ context }, enq) => {
|
|
377
|
+
enq.emit({ type: 'SCORED', score: context.score });
|
|
378
|
+
return { target: context.score >= 0.8 ? 'accepted' : 'rejected' };
|
|
379
|
+
},
|
|
380
|
+
},
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
Use a choice state when the branch is a pure routing decision the machine makes on its own, such as a loop bound or a score threshold. Use a [decision](decisions.md) when the model picks the branch.
|
|
384
|
+
|
|
385
|
+
In a JSON [machine config](machines-as-data.md), `choice` is an array of branches instead of a function. Each branch carries an optional `guard` and a `target`, and the first branch whose guard passes wins. A branch with no guard is the fallback.
|
|
386
|
+
|
|
387
|
+
## Request and actor invokes
|
|
388
|
+
|
|
389
|
+
A state invokes an actor by `src`. The `src` is a request key, a registered actor, or a builtin such as `agent.decide`. The state passes typed `input` and handles `onDone` and `onError`.
|
|
390
|
+
|
|
391
|
+
```ts no-check
|
|
392
|
+
// inside states: { ... }
|
|
393
|
+
drafting: {
|
|
394
|
+
invoke: {
|
|
395
|
+
src: 'draftEmail',
|
|
396
|
+
input: ({ context }) => ({ prompt: context.prompt, messages: context.messages }),
|
|
397
|
+
onDone: ({ output }) => ({ target: 'reviewing', context: { draft: output.result } }),
|
|
398
|
+
onError: { target: 'failed' },
|
|
399
|
+
},
|
|
400
|
+
}
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
The `onDone` handler receives the actor's `output`. For a text request that is `{ result, messages }`: `result` is typed from the request's output schema, and `messages` is the executor's response messages (see [Messages](messages.md)). Any other actor's `output` is whatever its logic resolves. Both `onDone` and `onError` are transition functions.
|
|
404
|
+
|
|
405
|
+
`runAgent` runs only what a state invokes. It does not read descriptions or metadata as hidden requests. A machine that keeps its prompts in state metadata or an external map still needs an explicit invoke for each model call, so execution stays visible to XState tooling, persistence, inspection, and tests.
|
|
406
|
+
|
|
407
|
+
### Inline text requests
|
|
408
|
+
|
|
409
|
+
<!-- inline agent.generateText + runToQuiescence, from src/setup-agent.ts and src/index.ts -->
|
|
410
|
+
|
|
411
|
+
For a one-off text call, invoke `agent.generateText` inline. Move it to a named [request](text-requests.md) once it is reused or worth testing:
|
|
412
|
+
|
|
413
|
+
```ts no-check
|
|
414
|
+
import { createAgentRuntime, parseOutput, runToQuiescence } from "@statelyai/agent";
|
|
415
|
+
|
|
416
|
+
// ...
|
|
417
|
+
generating: {
|
|
418
|
+
invoke: {
|
|
419
|
+
id: "draft",
|
|
420
|
+
src: "agent.generateText",
|
|
421
|
+
input: ({ context }) => ({
|
|
422
|
+
model: "openai/gpt-6-luna",
|
|
423
|
+
prompt: context.prompt,
|
|
424
|
+
outputSchema: resultSchema,
|
|
425
|
+
}),
|
|
426
|
+
onDone: ({ output }) => ({
|
|
427
|
+
target: "done",
|
|
428
|
+
context: { result: parseOutput(resultSchema, output.result) },
|
|
429
|
+
}),
|
|
430
|
+
},
|
|
431
|
+
},
|
|
432
|
+
|
|
433
|
+
// ...
|
|
434
|
+
await runToQuiescence(createAgentRuntime(machine, { executors: createAiSdkExecutors({ models }) }), { input });
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
Give an invoke an explicit `id` when the host needs a stable occurrence identity. XState owns invoke identity and snapshot restoration.
|
|
438
|
+
|
|
439
|
+
## Final states and output
|
|
440
|
+
|
|
441
|
+
A final state ends the machine or a region of it. Its `output` is typed against the machine's output schema:
|
|
442
|
+
|
|
443
|
+
```ts no-check
|
|
444
|
+
done: {
|
|
445
|
+
type: 'final',
|
|
446
|
+
output: ({ context }) => ({ answer: context.answer ?? '' }),
|
|
447
|
+
}
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
When the root declares no `output` and exactly one final state does, `createMachine` promotes that final state's output to the root. `snapshot.output` is then set without you declaring the output twice.
|
|
451
|
+
|
|
452
|
+
> **Note:** Read durable domain data from `context` in a final `output` function. Capture entering-event data into context when the transition needs it later.
|
|
453
|
+
|
|
454
|
+
## State and transition meta
|
|
455
|
+
|
|
456
|
+
<!-- typed meta protocol from examples/email-drafter/agent-logic.ts -->
|
|
457
|
+
|
|
458
|
+
The `meta` field attaches typed data to a state or transition. By default `setupAgent` types it as the shipped interaction protocol, keyed by the machine's declared events, and hosts read it through `getInteraction(snapshot)` instead of `Record<string, unknown>`. A `label` names the wait, `events` maps choice events to labels, and `textEvent` names the free-text event, whose text fills a `text` field by default:
|
|
459
|
+
|
|
460
|
+
```ts no-check
|
|
461
|
+
// inside states: { ... }
|
|
462
|
+
prompting: {
|
|
463
|
+
meta: {
|
|
464
|
+
interaction: {
|
|
465
|
+
label: 'Email draft request',
|
|
466
|
+
textEvent: 'PROMPT_SUBMITTED',
|
|
467
|
+
},
|
|
468
|
+
},
|
|
469
|
+
on: {
|
|
470
|
+
PROMPT_SUBMITTED: ({ event }) => ({ target: 'evaluating', context: { prompt: event.text } }),
|
|
471
|
+
},
|
|
472
|
+
}
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
A choice or `textEvent` naming an event the machine never declared is a compile error. `textEvent: { type, field }` names another field, and `choices` (an array, or a context path) offers one button per payload. See [Human in the loop](human-in-the-loop.md#payload-choices). A machine with other metadata declares its own `meta` schema on `setupAgent`, which replaces the default. See [examples/email-drafter/agent-logic.ts](https://github.com/statelyai/agent/blob/next/examples/email-drafter/agent-logic.ts).
|
|
476
|
+
|
|
477
|
+
## Delayed transitions
|
|
478
|
+
|
|
479
|
+
A delayed transition (`after`) fires after a delay, with no external event. Key it by milliseconds or by a named delay from `setupAgent`'s `delays`:
|
|
480
|
+
|
|
481
|
+
```ts no-check
|
|
482
|
+
// inside states: { ... }
|
|
483
|
+
waiting: {
|
|
484
|
+
after: { 20: { target: 'done' } },
|
|
485
|
+
}
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
How `after` runs depends on the host:
|
|
489
|
+
|
|
490
|
+
- Under [`runToQuiescence`](hosts.md), the timer runs live. A pending `after` does not count as idle, so `runToQuiescence` waits for it and continues.
|
|
491
|
+
- Under a custom or durable XState host, timers follow that framework's runtime adapter. See [the runtime loop](steps.md).
|
|
492
|
+
|
|
493
|
+
## Related
|
|
494
|
+
|
|
495
|
+
- Read more about [Decisions](decisions.md), where the model chooses one currently-legal event.
|
|
496
|
+
- Read more about [Text requests](text-requests.md), including streaming and structured output.
|
|
497
|
+
- Read more about [Human in the loop](human-in-the-loop.md), including idle states, resuming from a snapshot, and inline user input.
|
package/docs/messages.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Messages
|
|
2
|
+
|
|
3
|
+
Messages are explicit machine context. Stately Agent does not keep a transcript sidecar or translate framework-native message objects. A text request resolves with the messages the executor returned, and the machine decides where they go.
|
|
4
|
+
|
|
5
|
+
Declare the schema from the framework you use:
|
|
6
|
+
|
|
7
|
+
```ts no-check
|
|
8
|
+
import type { ModelMessage } from "ai";
|
|
9
|
+
|
|
10
|
+
const agent = setupAgent({
|
|
11
|
+
context: z.object({
|
|
12
|
+
messages: z.custom<ModelMessage[]>(),
|
|
13
|
+
}),
|
|
14
|
+
// ...
|
|
15
|
+
});
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Reading messages off a request
|
|
19
|
+
|
|
20
|
+
<!-- AgentTextResult from src/text-logic.ts and src/index.ts -->
|
|
21
|
+
|
|
22
|
+
Every text request's invoke resolves to `{ result, messages }` (`AgentTextResult`, exported from `@statelyai/agent`). `result` is the validated output, typed from the request's output schema or `string` for plain text. `messages` is the executor's framework-native response messages, exactly as returned, and an empty array when the executor returned none. Append them to context in `onDone`:
|
|
23
|
+
|
|
24
|
+
```ts no-check
|
|
25
|
+
const machine = agent.createMachine({
|
|
26
|
+
context: { messages: [], draft: null },
|
|
27
|
+
initial: "drafting",
|
|
28
|
+
states: {
|
|
29
|
+
drafting: {
|
|
30
|
+
invoke: {
|
|
31
|
+
src: "writeDraft",
|
|
32
|
+
input: ({ context }) => ({ messages: context.messages }),
|
|
33
|
+
onDone: ({ context, output }) => ({
|
|
34
|
+
target: "reviewing",
|
|
35
|
+
context: {
|
|
36
|
+
draft: output.result,
|
|
37
|
+
messages: [...context.messages, ...output.messages],
|
|
38
|
+
},
|
|
39
|
+
}),
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
// ...
|
|
43
|
+
},
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
There is no separate event or helper. A machine that ignores `output.messages` keeps no transcript, and one that appends them owns exactly what it retained. The same shape arrives through `simulateAgent` scripts (with `messages: []`) and the [runtime loop](steps.md).
|
|
48
|
+
|
|
49
|
+
## Validating and reading messages
|
|
50
|
+
|
|
51
|
+
<!-- messagesSchema, isAgentMessages from src/messages.ts and getMessageText from src/utils.ts, all via src/index.ts -->
|
|
52
|
+
|
|
53
|
+
`getMessageText(message)` returns the readable string content and joins text parts, including textual tool-result output, while ignoring non-text content.
|
|
54
|
+
|
|
55
|
+
To validate the field at runtime, use the `isAgentMessages` guard. A zod object cannot nest a Standard Schema directly, so wrap it:
|
|
56
|
+
|
|
57
|
+
```ts no-check
|
|
58
|
+
context: z.object({
|
|
59
|
+
messages: z.custom<AgentMessage[]>(isAgentMessages),
|
|
60
|
+
}),
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`messagesSchema` is the same validator as a Standard Schema, for `fromConfig` and `createAgentSchemas`.
|
|
64
|
+
|
|
65
|
+
This is deliberately transparent: the AI SDK executor returns AI SDK messages, another framework returns its own messages, and the machine stores those values unchanged. Tool calls and tool results remain part of that framework-native chat log.
|
|
66
|
+
|
|
67
|
+
See the runnable [`review-tool-calls`](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls) example, where each proposed tool call becomes an explicit, persistable machine decision, and [Tools](tools.md#tool-results-in-messages) for a host-run tool loop whose native response messages are retained this way.
|
package/docs/meta.json
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "Agents",
|
|
3
|
+
"pages": [
|
|
4
|
+
"---Get started---",
|
|
5
|
+
"index",
|
|
6
|
+
"quickstart",
|
|
7
|
+
"thinking-in-state-machines",
|
|
8
|
+
"from-a-loop",
|
|
9
|
+
"strangler-fig",
|
|
10
|
+
"scope",
|
|
11
|
+
"---Core concepts---",
|
|
12
|
+
"machines",
|
|
13
|
+
"decisions",
|
|
14
|
+
"act",
|
|
15
|
+
"environment-and-policy",
|
|
16
|
+
"text-requests",
|
|
17
|
+
"tools",
|
|
18
|
+
"judgments",
|
|
19
|
+
"messages",
|
|
20
|
+
"machines-presets",
|
|
21
|
+
"---Running agents---",
|
|
22
|
+
"choosing-a-run-mode",
|
|
23
|
+
"hosts",
|
|
24
|
+
"any-stack",
|
|
25
|
+
"xstate-4-and-5-apps",
|
|
26
|
+
"upgrading",
|
|
27
|
+
"steps",
|
|
28
|
+
"advanced",
|
|
29
|
+
"---State & durability---",
|
|
30
|
+
"event-log",
|
|
31
|
+
"persistence",
|
|
32
|
+
"human-in-the-loop",
|
|
33
|
+
"---Production---",
|
|
34
|
+
"models-and-providers",
|
|
35
|
+
"observability",
|
|
36
|
+
"usage-and-budgets",
|
|
37
|
+
"debugging",
|
|
38
|
+
"multi-agent",
|
|
39
|
+
"---Machines as data---",
|
|
40
|
+
"machines-as-data",
|
|
41
|
+
"generate-machines",
|
|
42
|
+
"---Testing---",
|
|
43
|
+
"verify",
|
|
44
|
+
"evals",
|
|
45
|
+
"---Resources---",
|
|
46
|
+
"patterns",
|
|
47
|
+
"statechart-policy-examples",
|
|
48
|
+
"validate-and-repair",
|
|
49
|
+
"langgraph-comparison",
|
|
50
|
+
"roadmap"
|
|
51
|
+
]
|
|
52
|
+
}
|