@statelyai/agent 1.0.0-beta.1 → 1.1.2
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/.env.template +0 -3
- package/.github/actions/ci-setup/action.yml +11 -11
- package/.github/workflows/release.yml +19 -7
- package/CHANGELOG.md +85 -0
- package/dist/index.d.mts +164 -54
- package/dist/index.d.ts +164 -54
- package/dist/index.js +190 -117
- package/dist/index.mjs +181 -117
- package/examples/chatbot.ts +9 -17
- package/examples/cot.ts +5 -7
- package/examples/email.ts +2 -2
- package/examples/example.ts +7 -7
- package/examples/goal.ts +1 -1
- package/examples/joke.ts +8 -10
- package/examples/number.ts +1 -1
- package/examples/raffle.ts +1 -1
- package/examples/sandbox.ts +28 -0
- package/examples/support.ts +1 -1
- package/examples/ticTacToe.ts +18 -21
- package/examples/todo.ts +3 -1
- package/examples/tutor.ts +1 -1
- package/examples/verify.ts +1 -1
- package/examples/weather.ts +1 -1
- package/examples/wiki.ts +1 -1
- package/examples/word.ts +1 -1
- package/package.json +22 -22
- package/readme.md +1 -4
- package/src/agent.test.ts +324 -5
- package/src/agent.ts +64 -26
- package/src/decision.ts +6 -5
- package/src/index.ts +2 -2
- package/src/planners/shortestPathPlanner.ts +2 -2
- package/src/planners/simplePlanner.ts +22 -12
- package/src/schemas.ts +4 -8
- package/src/strategies/chain-of-note.ts +3 -3
- package/src/text.ts +42 -37
- package/src/types.ts +146 -42
- package/src/utils.ts +53 -9
- package/.changeset/shaggy-buttons-itch.md +0 -5
- package/src/templates/defaultToolCall.ts +0 -10
package/.env.template
CHANGED
|
@@ -7,18 +7,18 @@ runs:
|
|
|
7
7
|
- uses: actions/setup-node@v4
|
|
8
8
|
with:
|
|
9
9
|
node-version: 20.x
|
|
10
|
+
|
|
11
|
+
- name: install pnpm
|
|
12
|
+
run: npm i pnpm@latest -g
|
|
13
|
+
shell: bash
|
|
10
14
|
|
|
11
|
-
- name:
|
|
15
|
+
- name: Setup npmrc
|
|
16
|
+
run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
|
|
12
17
|
shell: bash
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
with:
|
|
19
|
-
path: ${{ steps.pnpm-cache.outputs.pnpm_cache_dir }}
|
|
20
|
-
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
|
|
21
|
-
restore-keys: |
|
|
22
|
-
${{ runner.os }}-pnpm-store-
|
|
18
|
+
|
|
19
|
+
- name: setup pnpm config
|
|
20
|
+
run: pnpm config set store-dir $PNPM_CACHE_FOLDER
|
|
21
|
+
shell: bash
|
|
22
|
+
|
|
23
23
|
- run: pnpm install
|
|
24
24
|
shell: bash
|
|
@@ -11,9 +11,9 @@ permissions: {}
|
|
|
11
11
|
jobs:
|
|
12
12
|
release:
|
|
13
13
|
permissions:
|
|
14
|
-
contents: write
|
|
14
|
+
contents: write # to create release (changesets/action)
|
|
15
15
|
issues: write # to post issue comments (changesets/action)
|
|
16
|
-
pull-requests: write
|
|
16
|
+
pull-requests: write # to create pull request (changesets/action)
|
|
17
17
|
|
|
18
18
|
if: github.repository == 'statelyai/agent'
|
|
19
19
|
|
|
@@ -22,14 +22,26 @@ jobs:
|
|
|
22
22
|
runs-on: ubuntu-latest
|
|
23
23
|
|
|
24
24
|
steps:
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
25
|
+
- name: checkout code repository
|
|
26
|
+
uses: actions/checkout@v3
|
|
27
|
+
with:
|
|
28
|
+
fetch-depth: 0
|
|
29
|
+
- name: setup node.js
|
|
30
|
+
uses: actions/setup-node@v3
|
|
31
|
+
with:
|
|
32
|
+
node-version: 20
|
|
33
|
+
- name: install pnpm
|
|
34
|
+
run: npm i pnpm@latest -g
|
|
35
|
+
- name: Setup npmrc
|
|
36
|
+
run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
|
|
37
|
+
- name: setup pnpm config
|
|
38
|
+
run: pnpm config set store-dir $PNPM_CACHE_FOLDER
|
|
39
|
+
- name: install dependencies
|
|
40
|
+
run: pnpm install
|
|
41
|
+
- name: create and publish versions
|
|
29
42
|
uses: changesets/action@v1
|
|
30
43
|
with:
|
|
31
44
|
publish: pnpm run release
|
|
32
45
|
version: pnpm run version
|
|
33
46
|
env:
|
|
34
47
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
35
|
-
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,90 @@
|
|
|
1
1
|
# @statelyai/agent
|
|
2
2
|
|
|
3
|
+
## 1.1.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#43](https://github.com/statelyai/agent/pull/43) [`8e7629c`](https://github.com/statelyai/agent/commit/8e7629c347b29b704ae9576aa1af97e6cd693bc7) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Update dependencies
|
|
8
|
+
|
|
9
|
+
## 1.1.1
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- [#41](https://github.com/statelyai/agent/pull/41) [`b2f2b73`](https://github.com/statelyai/agent/commit/b2f2b7307e96d7722968769aae9db2572ede8ce7) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Update dependencies
|
|
14
|
+
|
|
15
|
+
## 1.1.0
|
|
16
|
+
|
|
17
|
+
### Minor Changes
|
|
18
|
+
|
|
19
|
+
- [#39](https://github.com/statelyai/agent/pull/39) [`3cce30f`](https://github.com/statelyai/agent/commit/3cce30fc77d36dbed0abad805248de9f64bf8086) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Added four new methods for easily retrieving agent messages, observations, feedback, and plans:
|
|
20
|
+
|
|
21
|
+
- `agent.getMessages()`
|
|
22
|
+
- `agent.getObservations()`
|
|
23
|
+
- `agent.getFeedback()`
|
|
24
|
+
- `agent.getPlans()`
|
|
25
|
+
|
|
26
|
+
The `agent.select(…)` method is deprecated in favor of these methods.
|
|
27
|
+
|
|
28
|
+
- [#40](https://github.com/statelyai/agent/pull/40) [`8b7c374`](https://github.com/statelyai/agent/commit/8b7c37482d5c35b2b3addc2f88e198526f203da7) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Correlation IDs are now provided as part of the result from `agent.generateText(…)` and `agent.streamText(…)`:
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
const result = await agent.generateText({
|
|
32
|
+
prompt: "Write me a song",
|
|
33
|
+
correlationId: "my-correlation-id",
|
|
34
|
+
// ...
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
result.correlationId; // 'my-correlation-id'
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
These correlation IDs can be passed to feedback:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
// ...
|
|
44
|
+
|
|
45
|
+
agent.addFeedback({
|
|
46
|
+
reward: -1,
|
|
47
|
+
correlationId: result.correlationId,
|
|
48
|
+
});
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- [#40](https://github.com/statelyai/agent/pull/40) [`8b7c374`](https://github.com/statelyai/agent/commit/8b7c37482d5c35b2b3addc2f88e198526f203da7) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Changes to agent feedback (the `AgentFeedback` interface):
|
|
52
|
+
|
|
53
|
+
- `goal` is now optional
|
|
54
|
+
- `observationId` is now optional
|
|
55
|
+
- `correlationId` has been added (optional)
|
|
56
|
+
- `reward` has been added (optional)
|
|
57
|
+
- `attributes` are now optional
|
|
58
|
+
|
|
59
|
+
- [#38](https://github.com/statelyai/agent/pull/38) [`21fb17c`](https://github.com/statelyai/agent/commit/21fb17c65fac1cbb4a8b08a04a58480a6930a0a9) Thanks [@davidkpiano](https://github.com/davidkpiano)! - You can now add `context` Zod schema to your agent. For now, this is meant to be passed directly to the state machine, but in the future, the schema can be shared with the LLM agent to better understand the state machine and its context for decision making.
|
|
60
|
+
|
|
61
|
+
Breaking: The `context` and `events` types are now in `agent.types` instead of ~~`agent.eventTypes`.
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
const agent = createAgent({
|
|
65
|
+
// ...
|
|
66
|
+
context: {
|
|
67
|
+
score: z.number().describe("The score of the game"),
|
|
68
|
+
// ...
|
|
69
|
+
},
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
const machine = setup({
|
|
73
|
+
types: agent.types,
|
|
74
|
+
}).createMachine({
|
|
75
|
+
context: {
|
|
76
|
+
score: 0,
|
|
77
|
+
},
|
|
78
|
+
// ...
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Patch Changes
|
|
83
|
+
|
|
84
|
+
- [`5f863bb`](https://github.com/statelyai/agent/commit/5f863bb0d89d90f30d0a9aa1f0dd2a35f0eeb45b) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Use nanoid
|
|
85
|
+
|
|
86
|
+
- [#37](https://github.com/statelyai/agent/pull/37) [`dafa815`](https://github.com/statelyai/agent/commit/dafa8157cc1b5adbfb222c146dbc84ab2eed8894) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Messages are now properly included in `agent.decide(…)`, when specified.
|
|
87
|
+
|
|
3
88
|
## 0.1.0
|
|
4
89
|
|
|
5
90
|
### Minor Changes
|
package/dist/index.d.mts
CHANGED
|
@@ -1,7 +1,14 @@
|
|
|
1
1
|
import { EventObject, AnyStateMachine, AnyEventObject, AnyActorRef, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, ActorRefFrom, Subscription, StateValue, ObservableActorLogic } from 'xstate';
|
|
2
|
-
import {
|
|
2
|
+
import { SomeZodObject, ZodType, TypeOf } from 'zod';
|
|
3
3
|
import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, StreamTextResult, CoreTool } from 'ai';
|
|
4
4
|
|
|
5
|
+
type ZodEventMapping = {
|
|
6
|
+
[eventType: string]: SomeZodObject;
|
|
7
|
+
};
|
|
8
|
+
type ZodContextMapping = {
|
|
9
|
+
[contextKey: string]: ZodType;
|
|
10
|
+
};
|
|
11
|
+
|
|
5
12
|
type GenerateTextOptions = Parameters<typeof generateText>[0];
|
|
6
13
|
type StreamTextOptions = Parameters<typeof streamText>[0];
|
|
7
14
|
type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'prompt' | 'messages' | 'tools'> & {
|
|
@@ -33,10 +40,11 @@ type AgentPlan<TEvent extends EventObject> = {
|
|
|
33
40
|
goal: string;
|
|
34
41
|
state: ObservedState;
|
|
35
42
|
content?: string;
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
43
|
+
/**
|
|
44
|
+
* Executes the plan based on the given `state` and resolves with
|
|
45
|
+
* a potential next `event` to trigger to achieve the `goal`.
|
|
46
|
+
*/
|
|
47
|
+
execute: (state: ObservedState) => Promise<TEvent | undefined>;
|
|
40
48
|
nextEvent: TEvent | undefined;
|
|
41
49
|
sessionId: string;
|
|
42
50
|
timestamp: number;
|
|
@@ -74,10 +82,10 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
|
|
|
74
82
|
*/
|
|
75
83
|
observations?: AgentObservation<any>[];
|
|
76
84
|
feedback?: AgentFeedback[];
|
|
77
|
-
messages?:
|
|
85
|
+
messages?: AgentMessage[];
|
|
78
86
|
plans?: AgentPlan<TEvents>[];
|
|
79
87
|
}) => string;
|
|
80
|
-
type AgentPlanner<T extends
|
|
88
|
+
type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
|
|
81
89
|
type AgentDecideOptions = {
|
|
82
90
|
goal: string;
|
|
83
91
|
model?: LanguageModel;
|
|
@@ -89,19 +97,26 @@ type AgentDecideOptions = {
|
|
|
89
97
|
events?: ZodEventMapping;
|
|
90
98
|
} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt' | 'messages'>;
|
|
91
99
|
interface AgentFeedback {
|
|
92
|
-
goal
|
|
93
|
-
observationId
|
|
100
|
+
goal?: string;
|
|
101
|
+
observationId?: string;
|
|
102
|
+
/**
|
|
103
|
+
* The message correlation that the feedback is relevant for
|
|
104
|
+
*/
|
|
105
|
+
correlationId?: string;
|
|
94
106
|
attributes: Record<string, any>;
|
|
107
|
+
reward: number;
|
|
95
108
|
timestamp: number;
|
|
96
109
|
sessionId: string;
|
|
97
110
|
}
|
|
98
111
|
interface AgentFeedbackInput {
|
|
99
|
-
goal
|
|
100
|
-
observationId
|
|
101
|
-
|
|
112
|
+
goal?: string;
|
|
113
|
+
observationId?: string;
|
|
114
|
+
correlationId?: string;
|
|
115
|
+
attributes?: Record<string, any>;
|
|
102
116
|
timestamp?: number;
|
|
117
|
+
reward?: number;
|
|
103
118
|
}
|
|
104
|
-
type
|
|
119
|
+
type AgentMessage = CoreMessage & {
|
|
105
120
|
timestamp: number;
|
|
106
121
|
id: string;
|
|
107
122
|
/**
|
|
@@ -111,8 +126,10 @@ type AgentMessageHistory = CoreMessage & {
|
|
|
111
126
|
responseId?: string;
|
|
112
127
|
result?: GenerateTextResult<any>;
|
|
113
128
|
sessionId: string;
|
|
129
|
+
correlationId: string;
|
|
130
|
+
parentCorrelationId?: string;
|
|
114
131
|
};
|
|
115
|
-
type
|
|
132
|
+
type AgentMessageInput = CoreMessage & {
|
|
116
133
|
timestamp?: number;
|
|
117
134
|
id?: string;
|
|
118
135
|
/**
|
|
@@ -120,6 +137,8 @@ type AgentMessageHistoryInput = CoreMessage & {
|
|
|
120
137
|
* which message this message is responding to, if any.
|
|
121
138
|
*/
|
|
122
139
|
responseId?: string;
|
|
140
|
+
correlationId?: string;
|
|
141
|
+
parentCorrelationId?: string;
|
|
123
142
|
result?: GenerateTextResult<any>;
|
|
124
143
|
};
|
|
125
144
|
interface AgentObservation<TActor extends AnyActorRef> {
|
|
@@ -127,6 +146,7 @@ interface AgentObservation<TActor extends AnyActorRef> {
|
|
|
127
146
|
prevState: SnapshotFrom<TActor> | undefined;
|
|
128
147
|
event: EventFrom<TActor>;
|
|
129
148
|
state: SnapshotFrom<TActor>;
|
|
149
|
+
machineHash: string | undefined;
|
|
130
150
|
sessionId: string;
|
|
131
151
|
timestamp: number;
|
|
132
152
|
}
|
|
@@ -135,6 +155,7 @@ interface AgentObservationInput {
|
|
|
135
155
|
prevState: ObservedState | undefined;
|
|
136
156
|
event: AnyEventObject;
|
|
137
157
|
state: ObservedState;
|
|
158
|
+
machine?: AnyStateMachine;
|
|
138
159
|
timestamp?: number;
|
|
139
160
|
}
|
|
140
161
|
type AgentDecisionInput = {
|
|
@@ -151,7 +172,7 @@ type AgentEmitted<TEvents extends EventObject> = {
|
|
|
151
172
|
observation: AgentObservation<any>;
|
|
152
173
|
} | {
|
|
153
174
|
type: 'message';
|
|
154
|
-
message:
|
|
175
|
+
message: AgentMessage;
|
|
155
176
|
} | {
|
|
156
177
|
type: 'plan';
|
|
157
178
|
plan: AgentPlan<TEvents>;
|
|
@@ -164,7 +185,7 @@ type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<Age
|
|
|
164
185
|
observation: AgentObservation<any>;
|
|
165
186
|
} | {
|
|
166
187
|
type: 'agent.message';
|
|
167
|
-
message:
|
|
188
|
+
message: AgentMessage;
|
|
168
189
|
} | {
|
|
169
190
|
type: 'agent.plan';
|
|
170
191
|
plan: AgentPlan<TEvents>;
|
|
@@ -175,19 +196,25 @@ type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
|
|
|
175
196
|
type: K;
|
|
176
197
|
} & TypeOf<TEventSchemas[K]>;
|
|
177
198
|
}>;
|
|
178
|
-
type
|
|
199
|
+
type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
|
|
200
|
+
[K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
|
|
201
|
+
};
|
|
202
|
+
type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
|
|
179
203
|
/**
|
|
180
|
-
* The
|
|
204
|
+
* The name of the agent. All agents with the same name are related and
|
|
181
205
|
* able to share experiences (observations, feedback) with each other.
|
|
182
206
|
*/
|
|
183
|
-
name
|
|
207
|
+
name?: string;
|
|
184
208
|
/**
|
|
185
|
-
* The unique
|
|
209
|
+
* The unique identifier for the agent.
|
|
186
210
|
*/
|
|
187
211
|
id?: string;
|
|
188
212
|
description?: string;
|
|
189
213
|
events: ZodEventMapping;
|
|
190
|
-
|
|
214
|
+
types: {
|
|
215
|
+
events: TEvents;
|
|
216
|
+
context: Compute<TContext>;
|
|
217
|
+
};
|
|
191
218
|
model: LanguageModel;
|
|
192
219
|
defaultOptions: GenerateTextOptions;
|
|
193
220
|
memory: AgentLongTermMemory | undefined;
|
|
@@ -203,41 +230,111 @@ type Agent<TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
|
|
|
203
230
|
*
|
|
204
231
|
* - The `goal` for the agent to achieve
|
|
205
232
|
* - The observed current `state`
|
|
206
|
-
* - The `
|
|
233
|
+
* - The `machine` (e.g. a state machine) that specifies what can happen next
|
|
207
234
|
* - Additional `context`
|
|
208
235
|
*/
|
|
209
236
|
decide: (options: AgentDecideOptions) => Promise<AgentPlan<TEvents> | undefined>;
|
|
210
|
-
generateText: (options: AgentGenerateTextOptions) => Promise<
|
|
211
|
-
streamText: (options: AgentStreamTextOptions) => Promise<
|
|
212
|
-
addObservation: (
|
|
213
|
-
addMessage: (
|
|
214
|
-
addFeedback: (
|
|
237
|
+
generateText: (options: AgentGenerateTextOptions) => Promise<AgentGenerateTextResult>;
|
|
238
|
+
streamText: (options: AgentStreamTextOptions) => Promise<AgentStreamTextResult>;
|
|
239
|
+
addObservation: (observationInput: AgentObservationInput) => AgentObservation<any>;
|
|
240
|
+
addMessage: (messageInput: AgentMessageInput) => AgentMessage;
|
|
241
|
+
addFeedback: (feedbackInput: AgentFeedbackInput) => AgentFeedback;
|
|
215
242
|
addPlan: (plan: AgentPlan<TEvents>) => void;
|
|
216
243
|
/**
|
|
217
244
|
* Called whenever the agent (LLM assistant) receives or sends a message.
|
|
218
245
|
*/
|
|
219
|
-
onMessage: (callback: (message:
|
|
246
|
+
onMessage: (callback: (message: AgentMessage) => void) => void;
|
|
220
247
|
/**
|
|
221
248
|
* Selects agent data from its context.
|
|
249
|
+
*
|
|
250
|
+
* @deprecated Select from `agent.getSnapshot().context` directly or:
|
|
251
|
+
* - `agent.getMessages()`
|
|
252
|
+
* - `agent.getObservations()`
|
|
253
|
+
* - `agent.getFeedback()`
|
|
254
|
+
* - `agent.getPlans()`
|
|
222
255
|
*/
|
|
223
256
|
select: <T>(selector: (context: AgentMemoryContext) => T) => T;
|
|
224
257
|
/**
|
|
225
|
-
*
|
|
226
|
-
|
|
258
|
+
* Retrieves messages from the agent's short-term (local) memory.
|
|
259
|
+
*/
|
|
260
|
+
getMessages: () => AgentMessage[];
|
|
261
|
+
/**
|
|
262
|
+
* Retrieves observations from the agent's short-term (local) memory.
|
|
263
|
+
*/
|
|
264
|
+
getObservations: () => AgentObservation<Agent<TContext, TEvents>>[];
|
|
265
|
+
/**
|
|
266
|
+
* Retrieves feedback from the agent's short-term (local) memory.
|
|
267
|
+
*/
|
|
268
|
+
getFeedback: () => AgentFeedback[];
|
|
269
|
+
/**
|
|
270
|
+
* Retrieves strategies from the agent's short-term (local) memory.
|
|
227
271
|
*/
|
|
228
|
-
|
|
272
|
+
getPlans: () => AgentPlan<TEvents>[];
|
|
273
|
+
/**
|
|
274
|
+
* Interacts with this state machine actor by inspecting state transitions and storing them as observations.
|
|
275
|
+
*
|
|
276
|
+
* Observations contain the `prevState`, `event`, and current `state` of this
|
|
277
|
+
* actor, as well as other properties that are useful when recalled.
|
|
278
|
+
* These observations are stored in the `agent`'s short-term (local) memory
|
|
279
|
+
* and can be retrieved via `agent.getObservations()`.
|
|
280
|
+
*
|
|
281
|
+
* @example
|
|
282
|
+
* ```ts
|
|
283
|
+
* // Only observes the actor's state transitions
|
|
284
|
+
* agent.interact(actor);
|
|
285
|
+
*
|
|
286
|
+
* actor.start();
|
|
287
|
+
* ```
|
|
288
|
+
*/
|
|
289
|
+
interact<TActor extends AnyActorRef>(actorRef: TActor): Subscription;
|
|
290
|
+
/**
|
|
291
|
+
* Interacts with this state machine actor by:
|
|
292
|
+
* 1. Inspecting state transitions and storing them as observations
|
|
293
|
+
* 2. Deciding what to do next (which event to send the actor) based on
|
|
294
|
+
* the agent input returned from `getInput(observation)`, if `getInput(…)` is provided as the 2nd argument.
|
|
295
|
+
*
|
|
296
|
+
* Observations contain the `prevState`, `event`, and current `state` of this
|
|
297
|
+
* actor, as well as other properties that are useful when recalled.
|
|
298
|
+
* These observations are stored in the `agent`'s short-term (local) memory
|
|
299
|
+
* and can be retrieved via `agent.getObservations()`.
|
|
300
|
+
*
|
|
301
|
+
* @example
|
|
302
|
+
* ```ts
|
|
303
|
+
* // Observes the actor's state transitions and
|
|
304
|
+
* // makes a decision if on the "summarize" state
|
|
305
|
+
* agent.interact(actor, observed => {
|
|
306
|
+
* if (observed.state.matches('summarize')) {
|
|
307
|
+
* return {
|
|
308
|
+
* context: observed.state.context,
|
|
309
|
+
* goal: 'Summarize the message'
|
|
310
|
+
* }
|
|
311
|
+
* }
|
|
312
|
+
* });
|
|
313
|
+
*
|
|
314
|
+
* actor.start();
|
|
315
|
+
* ```
|
|
316
|
+
*/
|
|
317
|
+
interact<TActor extends AnyActorRef>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
|
|
229
318
|
};
|
|
230
|
-
type AnyAgent = Agent<any>;
|
|
231
|
-
type FromAgent<T> = T | ((
|
|
232
|
-
|
|
319
|
+
type AnyAgent = Agent<any, any>;
|
|
320
|
+
type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
|
|
321
|
+
type CommonTextOptions = {
|
|
233
322
|
prompt: FromAgent<string>;
|
|
234
323
|
model?: LanguageModel;
|
|
235
324
|
context?: Record<string, any>;
|
|
236
|
-
messages?: FromAgent<CoreMessage[]
|
|
325
|
+
messages?: FromAgent<CoreMessage[]>;
|
|
237
326
|
template?: PromptTemplate<any>;
|
|
238
|
-
|
|
327
|
+
correlationId?: string;
|
|
328
|
+
parentCorrelationId?: string;
|
|
329
|
+
};
|
|
330
|
+
type TextResultMeta = {
|
|
331
|
+
correlationId: string;
|
|
332
|
+
parentCorrelationId?: string;
|
|
333
|
+
};
|
|
239
334
|
type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
|
|
335
|
+
type AgentGenerateTextResult = GenerateTextResult<any> & TextResultMeta;
|
|
240
336
|
type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
|
|
337
|
+
type AgentStreamTextResult = StreamTextResult<any> & TextResultMeta;
|
|
241
338
|
interface ObservedState {
|
|
242
339
|
/**
|
|
243
340
|
* The current state value of the state machine, e.g.
|
|
@@ -252,7 +349,7 @@ interface ObservedState {
|
|
|
252
349
|
type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
|
|
253
350
|
type AgentMemoryContext = {
|
|
254
351
|
observations: AgentObservation<any>[];
|
|
255
|
-
messages:
|
|
352
|
+
messages: AgentMessage[];
|
|
256
353
|
plans: AgentPlan<any>[];
|
|
257
354
|
feedback: AgentFeedback[];
|
|
258
355
|
};
|
|
@@ -270,16 +367,30 @@ interface AIAdapter {
|
|
|
270
367
|
generateText: typeof generateText;
|
|
271
368
|
streamText: typeof streamText;
|
|
272
369
|
}
|
|
370
|
+
type Compute<A extends any> = {
|
|
371
|
+
[K in keyof A]: A[K];
|
|
372
|
+
} & unknown;
|
|
273
373
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
374
|
+
declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ name, description, model, events, context, planner, stringify, getMemory, logic, adapter, ...generateTextOptions }: {
|
|
375
|
+
/**
|
|
376
|
+
* The unique identifier for the agent.
|
|
377
|
+
*
|
|
378
|
+
* This should be the same across all sessions of a specific agent, as it can be
|
|
379
|
+
* used to retrieve memory for this agent.
|
|
380
|
+
*
|
|
381
|
+
* @example
|
|
382
|
+
* ```ts
|
|
383
|
+
* const agent = createAgent({
|
|
384
|
+
* id: 'recipe-assistant',
|
|
385
|
+
* // ...
|
|
386
|
+
* });
|
|
387
|
+
* ```
|
|
388
|
+
*/
|
|
389
|
+
id?: string;
|
|
279
390
|
/**
|
|
280
391
|
* The name of the agent
|
|
281
392
|
*/
|
|
282
|
-
name
|
|
393
|
+
name?: string;
|
|
283
394
|
/**
|
|
284
395
|
* A description of the role of the agent
|
|
285
396
|
*/
|
|
@@ -289,30 +400,29 @@ declare function createAgent<const TEventSchemas extends ZodEventMapping, TEvent
|
|
|
289
400
|
* that the agent knows about.
|
|
290
401
|
*/
|
|
291
402
|
events: TEventSchemas;
|
|
292
|
-
|
|
403
|
+
context?: TContextSchema;
|
|
404
|
+
planner?: AgentPlanner<Agent<TContext, TEvents>>;
|
|
293
405
|
stringify?: typeof JSON.stringify;
|
|
294
406
|
/**
|
|
295
407
|
* A function that retrieves the agent's long term memory
|
|
296
408
|
*/
|
|
297
|
-
getMemory?: (agent: Agent<
|
|
409
|
+
getMemory?: (agent: Agent<TContext, TEvents>) => AgentLongTermMemory;
|
|
298
410
|
/**
|
|
299
411
|
* Agent logic
|
|
300
412
|
*/
|
|
301
413
|
logic?: AgentLogic<TEvents>;
|
|
302
414
|
adapter?: AIAdapter;
|
|
303
|
-
} & GenerateTextOptions): Agent<TEvents>;
|
|
415
|
+
} & GenerateTextOptions): Agent<TContext, TEvents>;
|
|
304
416
|
|
|
305
|
-
declare function
|
|
306
|
-
declare function fromTextStream<T extends Agent<any>>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
|
|
417
|
+
declare function fromTextStream<T extends AnyAgent>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
|
|
307
418
|
textDelta: string;
|
|
308
419
|
}, Omit<AgentStreamTextOptions, 'context'> & {
|
|
309
|
-
context?: AgentStreamTextOptions['context']
|
|
420
|
+
context?: AgentStreamTextOptions['context'];
|
|
310
421
|
}>;
|
|
311
|
-
declare function fromText<T extends
|
|
312
|
-
context?: AgentGenerateTextOptions['context']
|
|
422
|
+
declare function fromText<T extends AnyAgent>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
|
|
423
|
+
context?: AgentGenerateTextOptions['context'];
|
|
313
424
|
}>;
|
|
314
425
|
|
|
315
|
-
declare function
|
|
316
|
-
declare function fromDecision(agent: Agent<any>, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
|
|
426
|
+
declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
|
|
317
427
|
|
|
318
|
-
export { type AIAdapter, type Agent, type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentLogic, type AgentLongTermMemory, type AgentMemory, type AgentMemoryContext, type
|
|
428
|
+
export { type AIAdapter, type Agent, type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentGenerateTextResult, type AgentLogic, type AgentLongTermMemory, type AgentMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, type AgentStreamTextResult, type AnyAgent, type AppendOnlyStorage, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TextResultMeta, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };
|