@statelyai/agent 2.0.0-next.4 → 2.0.0-next.5

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/dist/index.d.mts CHANGED
@@ -1,7 +1,6 @@
1
- import * as ai from 'ai';
2
- import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, LanguageModelV1, CoreTool } from 'ai';
3
- import { AnyStateMachine, ActorRefLike, SnapshotFrom, EventFrom, AnyEventObject, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, StateValue, EventObject, Actor, Subscription, ObservableActorLogic } from 'xstate';
1
+ import { AnyStateMachine, ActorRefLike, SnapshotFrom, EventFrom, AnyEventObject, ActorLogic, TransitionSnapshot, Values, StateValue, Actor, Subscription, ObservableActorLogic, PromiseActorLogic } from 'xstate';
4
2
  import { SomeZodObject, ZodType, TypeOf } from 'zod';
3
+ import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, LanguageModelV1, CoreTool } from 'ai';
5
4
 
6
5
  type ZodEventMapping = {
7
6
  [eventType: string]: SomeZodObject;
@@ -13,8 +12,11 @@ type ZodContextMapping = {
13
12
  type GenerateTextOptions = Parameters<typeof generateText>[0];
14
13
  type StreamTextOptions = Parameters<typeof streamText>[0];
15
14
  type CostFunction<TAgent extends AnyAgent> = (path: AgentPath<TAgent>) => number;
16
- type AgentDecideInput<TAgent extends AnyAgent> = Omit<AgentGenerateTextOptions<TAgent>, 'model' | 'prompt' | 'tools'> & {
17
- episodeId?: string;
15
+ type AgentDecideInput<TAgent extends AnyAgent> = Omit<AgentGenerateTextOptions, 'model' | 'prompt' | 'tools' | 'toolChoice'> & {
16
+ /**
17
+ * The parent decision that this decision is a part of.
18
+ */
19
+ decisionId?: string;
18
20
  /**
19
21
  * The currently observed state.
20
22
  */
@@ -40,7 +42,7 @@ type AgentDecideInput<TAgent extends AnyAgent> = Omit<AgentGenerateTextOptions<T
40
42
  */
41
43
  machine?: AnyStateMachine;
42
44
  /**
43
- * The total cost of the path to the goal state.
45
+ * A function that calculates the total cost of the path to the goal state.
44
46
  */
45
47
  costFunction?: CostFunction<TAgent>;
46
48
  /**
@@ -48,46 +50,75 @@ type AgentDecideInput<TAgent extends AnyAgent> = Omit<AgentGenerateTextOptions<T
48
50
  * Defaults to 2.
49
51
  */
50
52
  maxAttempts?: number;
51
- strategy?: AgentStrategy<TAgent>;
53
+ /**
54
+ * The policy to use for making a decision.
55
+ */
56
+ policy?: AgentPolicy<TAgent>;
52
57
  model?: LanguageModel;
53
- };
58
+ /**
59
+ * The previous relevant feedback from the agent.
60
+ */
61
+ feedback?: AgentFeedback[];
62
+ /**
63
+ * The previous relevant observations from the agent.
64
+ */
65
+ observations?: AgentObservation<any>[];
66
+ /**
67
+ * The previous relevant decisions from the agent.
68
+ */
69
+ decisions?: AgentDecision<TAgent>[];
70
+ /**
71
+ * The previous relevant insights from the agent.
72
+ */
73
+ insights?: AgentInsight[];
74
+ toolChoice?: 'auto' | 'none' | 'required';
75
+ } & BaseInput;
54
76
  type AgentStep<TAgent extends AnyAgent> = {
55
77
  /** The event to take */
56
78
  event: EventFromAgent<TAgent>;
57
79
  /** The next expected state after taking the event */
58
- state: ObservedState<TAgent> | undefined;
80
+ state: ObservedState<TAgent> | null;
59
81
  };
60
82
  type AgentPath<TAgent extends AnyAgent> = {
61
83
  /** The expected ending state of the path */
62
- state: ObservedState<TAgent> | undefined;
84
+ state: ObservedState<TAgent> | null;
63
85
  /** The steps to reach the ending state */
64
86
  steps: Array<AgentStep<TAgent>>;
65
87
  weight?: number;
66
88
  };
67
- type AgentDecision<TAgent extends AnyAgent> = {
68
- id: string;
89
+ interface AgentDecisionInput<TAgent extends AnyAgent> extends BaseInput {
90
+ goal: string;
91
+ decisionId?: string | null;
92
+ policy?: string | null;
93
+ goalState?: ObservedState<TAgent> | null;
94
+ nextEvent?: EventFromAgent<TAgent> | null;
95
+ paths?: AgentPath<TAgent>[];
96
+ }
97
+ interface AgentDecision<TAgent extends AnyAgent = AnyAgent> extends BaseProperties {
69
98
  /**
70
- * The strategy used to generate the decision
99
+ * The parent decision that this decision is a part of.
71
100
  */
72
- strategy: string;
101
+ decisionId: string | null;
102
+ /**
103
+ * The policy used to generate the decision
104
+ */
105
+ policy: string | null;
73
106
  goal: string;
74
107
  /**
75
108
  * The ending state of the decision.
76
109
  */
77
- goalState: ObservedState<TAgent> | undefined;
110
+ goalState: ObservedState<TAgent> | null;
78
111
  /**
79
112
  * The next event that the agent decided needs to occur to achieve the `goal`.
80
113
  *
81
114
  * This next event is chosen from the
82
115
  */
83
- nextEvent: EventFromAgent<TAgent> | undefined;
116
+ nextEvent: EventFromAgent<TAgent> | null;
84
117
  /**
85
118
  * The paths that the agent can take to achieve the goal.
86
119
  */
87
120
  paths: AgentPath<TAgent>[];
88
- episodeId: string;
89
- timestamp: number;
90
- };
121
+ }
91
122
  interface TransitionData {
92
123
  eventType: string;
93
124
  description?: string;
@@ -113,53 +144,62 @@ type PromptTemplate<TAgent extends AnyAgent> = (data: {
113
144
  */
114
145
  transitions?: TransitionData[];
115
146
  /**
116
- * Past observations
147
+ * Relevant past observations
117
148
  */
118
149
  observations?: AgentObservation<any>[];
150
+ /**
151
+ * Relevant feedback
152
+ */
119
153
  feedback?: AgentFeedback[];
154
+ /**
155
+ * Relevant messages
156
+ */
120
157
  messages?: AgentMessage[];
158
+ /**
159
+ * Relevant past decisions
160
+ */
121
161
  decisions?: AgentDecision<TAgent>[];
162
+ /**
163
+ * Relevant past insights
164
+ */
165
+ insights?: AgentInsight[];
122
166
  }) => string;
123
- type AgentStrategy<TAgent extends AnyAgent> = (agent: TAgent, input: AgentDecideInput<EventFromAgent<TAgent>>) => Promise<AgentDecision<TAgent> | undefined>;
167
+ type AgentPolicy<TAgent extends AnyAgent = AnyAgent> = (agent: TAgent, input: AgentDecideInput<TAgent>) => Promise<AgentDecision<TAgent> | undefined>;
124
168
  type AgentInteractInput<T extends AnyAgent> = Omit<AgentDecideInput<T>, 'state'> & {
125
169
  state?: never;
126
170
  };
127
- type AgentFeedback = {
128
- score: number;
171
+ interface AgentFeedback extends BaseProperties {
172
+ decisionId: string;
173
+ reward: number;
129
174
  comment: string | undefined;
130
175
  attributes: Record<string, any>;
131
- timestamp: number;
176
+ }
177
+ interface BaseProperties {
178
+ id: string;
132
179
  episodeId: string;
133
- } & ({
134
- observationId: string;
135
- decisionId?: never;
136
- } | {
180
+ timestamp: number;
181
+ }
182
+ type BaseInput = Partial<BaseProperties>;
183
+ interface AgentFeedbackInput extends BaseInput {
184
+ /**
185
+ * The decision ID that this feedback is relevant for.
186
+ */
137
187
  decisionId: string;
138
- observationId?: never;
139
- });
140
- type AgentFeedbackInput = {
141
- episodeId?: string;
142
- score: number;
188
+ reward: number;
143
189
  comment?: string;
144
190
  attributes?: Record<string, any>;
145
- timestamp?: number;
146
- } & ({
147
- observationId: string;
148
- decisionId?: never;
149
- } | {
150
- decisionId: string;
151
- observationId?: never;
152
- });
153
- type AgentMessage = CoreMessage & {
154
- timestamp: number;
155
- id: string;
191
+ }
192
+ type AgentMessage = BaseProperties & CoreMessage & {
193
+ /**
194
+ * The parent decision that this message is a part of.
195
+ */
196
+ decisionId?: string;
156
197
  /**
157
198
  * The response ID of the message, which references
158
199
  * which message this message is responding to, if any.
159
200
  */
160
201
  responseId?: string;
161
- result?: GenerateTextResult<any>;
162
- episodeId: string;
202
+ result?: GenerateTextResult<any, any>;
163
203
  };
164
204
  type JSONObject = {
165
205
  [key: string]: JSONValue;
@@ -209,37 +249,31 @@ type AgentMessageInput = CoreMessage & {
209
249
  * which message this message is responding to, if any.
210
250
  */
211
251
  responseId?: string;
212
- result?: GenerateTextResult<any>;
252
+ result?: GenerateTextResult<any, any>;
213
253
  };
214
254
  interface AgentObservation<TActor extends ActorRefLike> {
215
255
  id: string;
256
+ episodeId: string;
257
+ /**
258
+ * The decision that this observation is relevant for
259
+ */
216
260
  decisionId?: string | undefined;
217
261
  goal?: string;
218
262
  prevState: SnapshotFrom<TActor> | undefined;
219
263
  event: EventFrom<TActor> | undefined;
220
264
  state: SnapshotFrom<TActor>;
221
- episodeId: string;
222
265
  timestamp: number;
223
266
  }
224
- interface AgentObservationInput<TAgent extends AnyAgent> {
225
- id?: string;
226
- episodeId?: string;
267
+ interface AgentObservationInput<TAgent extends AnyAgent> extends BaseInput {
268
+ state: ObservedState<TAgent>;
227
269
  /**
228
270
  * The agent decision that the observation is relevant for
229
271
  */
230
272
  decisionId?: string | undefined;
231
273
  prevState?: ObservedState<TAgent>;
232
274
  event?: AnyEventObject;
233
- state: ObservedState<TAgent>;
234
- timestamp?: number;
235
275
  goal?: string | undefined;
236
276
  }
237
- type AgentDecisionInput = {
238
- goal: string;
239
- model?: LanguageModel;
240
- context?: Record<string, any>;
241
- } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
242
- type AgentDecisionLogic<TAgent extends AnyAgent> = PromiseActorLogic<AgentDecision<TAgent> | undefined, AgentDecisionInput | string>;
243
277
  type AgentEmitted<TAgent extends AnyAgent> = {
244
278
  type: 'feedback';
245
279
  feedback: AgentFeedback;
@@ -252,6 +286,9 @@ type AgentEmitted<TAgent extends AnyAgent> = {
252
286
  } | {
253
287
  type: 'decision';
254
288
  decision: AgentDecision<TAgent>;
289
+ } | {
290
+ type: 'insight';
291
+ insight: AgentInsight;
255
292
  };
256
293
  type AgentLogic<TAgent extends AnyAgent> = ActorLogic<TransitionSnapshot<AgentMemoryContext<TAgent>>, {
257
294
  type: 'agent.feedback';
@@ -265,6 +302,9 @@ type AgentLogic<TAgent extends AnyAgent> = ActorLogic<TransitionSnapshot<AgentMe
265
302
  } | {
266
303
  type: 'agent.decision';
267
304
  decision: AgentDecision<TAgent>;
305
+ } | {
306
+ type: 'agent.insight';
307
+ insight: AgentInsight;
268
308
  }, any, // TODO: input
269
309
  any, AgentEmitted<TAgent>>;
270
310
  type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Compute<Values<{
@@ -275,17 +315,17 @@ type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Compute<
275
315
  type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
276
316
  [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
277
317
  };
278
- type AnyAgent = Agent<any, any, any, any>;
318
+ type AnyAgent = Agent<any, any>;
279
319
  type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
280
- type CommonTextOptions<TAgent extends AnyAgent> = {
320
+ type CommonTextOptions = {
281
321
  prompt: FromAgent<string>;
282
322
  model?: LanguageModel;
283
- messages?: FromAgent<CoreMessage[]>;
323
+ messages?: CoreMessage[];
284
324
  template?: PromptTemplate<any>;
285
325
  context?: Record<string, any>;
286
326
  };
287
- type AgentGenerateTextOptions<TAgent extends AnyAgent> = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions<TAgent>;
288
- type AgentStreamTextOptions<TAgent extends AnyAgent> = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions<TAgent>;
327
+ type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
328
+ type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
289
329
  interface ObservedState<TAgent extends AnyAgent> {
290
330
  /**
291
331
  * The current state value of the state machine, e.g.
@@ -299,10 +339,11 @@ interface ObservedState<TAgent extends AnyAgent> {
299
339
  }
300
340
  type ObservedStateFrom<TActor extends ActorRefLike> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
301
341
  type AgentMemoryContext<TAgent extends AnyAgent> = {
302
- observations: AgentObservation<TAgent>[];
342
+ observations: AgentObservation<any>[];
303
343
  messages: AgentMessage[];
304
344
  decisions: AgentDecision<TAgent>[];
305
345
  feedback: AgentFeedback[];
346
+ insights: AgentInsight[];
306
347
  };
307
348
  interface AgentLongTermMemory<TAgent extends AnyAgent> {
308
349
  get<K extends keyof AgentMemoryContext<TAgent>>(key: K): Promise<AgentMemoryContext<TAgent>[K]>;
@@ -313,18 +354,37 @@ type Compute<A extends any> = {
313
354
  [K in keyof A]: A[K];
314
355
  } & unknown;
315
356
  type MaybePromise<T> = T | Promise<T>;
316
- type EventFromAgent<T extends AnyAgent> = T extends Agent<infer _, infer __, infer TEvents, infer ___> ? TEvents : never;
357
+ type EventFromAgent<T extends AnyAgent> = T extends Agent<infer _, infer TEventSchemas> ? EventsFromZodEventMapping<TEventSchemas> : never;
317
358
  type TypesFromAgent<T extends AnyAgent> = T extends Agent<infer TContextSchema, infer TEventSchema> ? {
318
359
  context: ContextFromZodContextMapping<TContextSchema>;
319
360
  events: EventsFromZodEventMapping<TEventSchema>;
320
361
  } : never;
321
362
  type ContextFromAgent<T extends AnyAgent> = T extends Agent<infer TContextSchema, infer _TEventSchema> ? ContextFromZodContextMapping<TContextSchema> : never;
363
+ interface StorageAdapter<TAgent extends AnyAgent, TQuery> {
364
+ addObservation(observationInput: AgentObservationInput<TAgent>): Promise<AgentObservation<any>>;
365
+ getObservations(queryObject?: TQuery): Promise<AgentObservation<any>[]>;
366
+ addFeedback(feedbackInput: AgentFeedbackInput): Promise<AgentFeedback>;
367
+ getFeedback(queryObject?: TQuery): Promise<AgentFeedback[]>;
368
+ addMessage(messageInput: AgentMessageInput): Promise<AgentMessage>;
369
+ getMessages(queryObject?: TQuery): Promise<AgentMessage[]>;
370
+ addDecision(decisionInput: AgentDecideInput<TAgent>): Promise<AgentDecision<TAgent>>;
371
+ getDecisions(queryObject?: TQuery): Promise<AgentDecision<TAgent>[]>;
372
+ }
373
+ type StorageAdapterQuery<T extends StorageAdapter<any, any>> = T extends StorageAdapter<infer _, infer TQuery> ? TQuery : never;
374
+ interface AgentInsightInput extends BaseInput {
375
+ observationId: string;
376
+ attributes: Record<string, any>;
377
+ }
378
+ interface AgentInsight extends BaseProperties {
379
+ observationId: string;
380
+ attributes: Record<string, any>;
381
+ }
322
382
 
323
- declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>, TAgent extends AnyAgent = Agent<TContextSchema, TEventSchemas>>({ id, description: description, model, events, context, episodeId, strategy, logic, }: {
383
+ declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TAgent extends AnyAgent = Agent<TContextSchema, TEventSchemas>>({ id, description, model, events, context, episodeId, policy, logic, }: {
324
384
  /**
325
385
  * The unique identifier for the agent.
326
386
  *
327
- * This should be the same across all sessions of a specific agent, as it can be
387
+ * This should be the same across all episodes of a specific agent, as it can be
328
388
  * used to retrieve memory for previous episodes of this agent.
329
389
  *
330
390
  * @example
@@ -337,29 +397,44 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
337
397
  */
338
398
  id?: string;
339
399
  /**
340
- * A description of the role of the agent
400
+ * A description of the role of the agent.
341
401
  */
342
402
  description?: string;
343
403
  /**
344
- * Events that the agent can cause (send) in an environment
345
- * that the agent knows about.
404
+ * Event schemas for events that the agent can trigger in an environment.
346
405
  */
347
406
  events: TEventSchemas;
407
+ /**
408
+ * The state context schema for the states that the agent can observe.
409
+ */
348
410
  context?: TContextSchema;
349
- strategy?: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
350
- stringify?: typeof JSON.stringify;
411
+ /**
412
+ * The default policy to use for `agent.decide(…)`.
413
+ *
414
+ * A policy is a strategy that the agent uses to decide which event to trigger next.
415
+ */
416
+ policy?: AgentPolicy<Agent<TContextSchema, TEventSchemas>>;
351
417
  /**
352
418
  * A function that retrieves the agent's long term memory
353
419
  */
354
420
  getMemory?: (agent: Agent<TContextSchema, TEventSchemas>) => AgentLongTermMemory<TAgent>;
355
421
  /**
356
- * Agent logic
422
+ * Custom agent logic, which receives events for handling feedback,
423
+ * observations, messages, decisions, and insights.
357
424
  */
358
425
  logic?: AgentLogic<TAgent>;
426
+ /**
427
+ * The default language model for the agent to use in `agent.decide(…)`.
428
+ */
359
429
  model: LanguageModel;
430
+ /**
431
+ * The unique episode ID that this agent will run on.
432
+ *
433
+ * An episode is an instance of an agent interacting with an environment.
434
+ */
360
435
  episodeId?: string;
361
436
  }): Agent<TContextSchema, TEventSchemas>;
362
- declare class Agent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>> extends Actor<AgentLogic<any>> {
437
+ declare class Agent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping> extends Actor<AgentLogic<any>> {
363
438
  /**
364
439
  * The name of the agent. All agents with the same name are related and
365
440
  * able to share experiences (observations, feedback) with each other.
@@ -372,10 +447,10 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
372
447
  description?: string;
373
448
  events: TEventSchemas;
374
449
  context?: TContextSchema;
375
- strategy: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
450
+ policy: AgentPolicy<Agent<TContextSchema, TEventSchemas>>;
376
451
  model: LanguageModel;
377
452
  memory: AgentLongTermMemory<this> | undefined;
378
- constructor({ logic, id, name, description, model, events, context, episodeId, strategy, }: {
453
+ constructor({ logic, id, name, description, model, events, context, episodeId, policy, }: {
379
454
  logic: AgentLogic<any>;
380
455
  id?: string;
381
456
  name?: string;
@@ -383,78 +458,40 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
383
458
  model: GenerateTextOptions['model'];
384
459
  events: TEventSchemas;
385
460
  context?: TContextSchema;
386
- strategy?: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
461
+ policy?: AgentPolicy<Agent<TContextSchema, TEventSchemas>>;
387
462
  episodeId?: string;
388
463
  });
389
464
  /**
390
- * Called whenever the agent (LLM assistant) receives or sends a message.
465
+ * Called whenever the agent detects that a message was sent from the human, assistant, or system.
391
466
  */
392
467
  onMessage(fn: (message: AgentMessage) => void): Subscription;
393
468
  /**
394
- * Called whenever the agent (LLM assistant) receives some feedback.
469
+ * Called whenever the agent receives some feedback.
395
470
  */
396
471
  onFeedback(fn: (feedback: AgentFeedback) => void): Subscription;
397
472
  /**
398
- * Retrieves messages from the agent's short-term (local) memory.
473
+ * Called whenever the agent receives an observation.
399
474
  */
400
- addMessage(messageInput: AgentMessageInput): {
401
- id: string;
402
- timestamp: number;
403
- episodeId: string;
404
- role: "assistant";
405
- content: ai.AssistantContent;
406
- experimental_providerMetadata?: ai.ProviderMetadata;
407
- responseId?: string;
408
- result?: ai.GenerateTextResult<any>;
409
- } | {
410
- id: string;
411
- timestamp: number;
412
- episodeId: string;
413
- role: "tool";
414
- content: ai.ToolContent;
415
- experimental_providerMetadata?: ai.ProviderMetadata;
416
- responseId?: string;
417
- result?: ai.GenerateTextResult<any>;
418
- } | {
419
- id: string;
420
- timestamp: number;
421
- episodeId: string;
422
- role: "system";
423
- content: string;
424
- experimental_providerMetadata?: ai.ProviderMetadata;
425
- responseId?: string;
426
- result?: ai.GenerateTextResult<any>;
427
- } | {
428
- id: string;
429
- timestamp: number;
430
- episodeId: string;
431
- role: "user";
432
- content: ai.UserContent;
433
- experimental_providerMetadata?: ai.ProviderMetadata;
434
- responseId?: string;
435
- result?: ai.GenerateTextResult<any>;
436
- };
475
+ onObservation(fn: (observation: AgentObservation<this>) => void): Subscription;
476
+ /**
477
+ * Called whenever the agent makes a decision.
478
+ */
479
+ onDecision(fn: (decision: AgentDecision<this>) => void): Subscription;
480
+ /**
481
+ * Adds a message to the agent's short-term (local) memory.
482
+ */
483
+ addMessage(messageInput: AgentMessageInput): AgentMessage;
437
484
  getMessages(): AgentMessage[];
438
485
  addFeedback(feedbackInput: AgentFeedbackInput): {
486
+ id: string;
439
487
  comment: string | undefined;
440
488
  attributes: {
441
489
  [x: string]: any;
442
490
  };
443
491
  timestamp: number;
444
492
  episodeId: string;
445
- score: number;
446
- observationId: string;
447
- decisionId?: never;
448
- } | {
449
- comment: string | undefined;
450
- attributes: {
451
- [x: string]: any;
452
- };
453
- timestamp: number;
454
- episodeId: string;
455
- score: number;
456
493
  decisionId: string;
457
- observationId?: never;
494
+ reward: number;
458
495
  };
459
496
  /**
460
497
  * Retrieves feedback from the agent's short-term (local) memory.
@@ -465,7 +502,9 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
465
502
  * Retrieves observations from the agent's short-term (local) memory.
466
503
  */
467
504
  getObservations(): AgentObservation<any>[];
468
- addDecision(decision: AgentDecision<this>): void;
505
+ addInsight(insightInput: AgentInsightInput): AgentInsight;
506
+ getInsights(): AgentInsight[];
507
+ addDecision(input: AgentDecisionInput<this>): void;
469
508
  /**
470
509
  * Retrieves strategies from the agent's short-term (local) memory.
471
510
  */
@@ -528,15 +567,27 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
528
567
  decide(input: AgentDecideInput<this>): Promise<AgentDecision<this> | undefined>;
529
568
  }
530
569
 
531
- declare function fromTextStream<TAgent extends AnyAgent>(agent: TAgent, options?: AgentStreamTextOptions<TAgent>): ObservableActorLogic<{
570
+ declare function fromTextStream<TAgent extends AnyAgent>(agent: TAgent, options?: AgentStreamTextOptions): ObservableActorLogic<{
532
571
  textDelta: string;
533
- }, Omit<AgentStreamTextOptions<TAgent>, 'context'> & {
572
+ }, Omit<AgentStreamTextOptions, 'context'> & {
534
573
  context?: Record<string, any>;
535
574
  }>;
536
- declare function fromText<TAgent extends AnyAgent>(agent: TAgent, options?: AgentGenerateTextOptions<TAgent>): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions<TAgent>, 'context'> & {
575
+ declare function fromText<TAgent extends AnyAgent>(agent: TAgent, options?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>, any>, Omit<AgentGenerateTextOptions, 'context'> & {
537
576
  context?: Record<string, any>;
538
577
  }>;
539
578
 
540
- declare function fromDecision<T extends AnyAgent>(agent: T, defaultInput?: AgentDecideInput<EventFromAgent<T>>): AgentDecisionLogic<any>;
579
+ type AgentDecideLogicInput = {
580
+ goal: string;
581
+ model?: LanguageModel;
582
+ context?: Record<string, any>;
583
+ } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
584
+ type MachineDecisionLogic<TAgent extends AnyAgent> = PromiseActorLogic<AgentDecision<TAgent> | undefined, AgentDecideLogicInput | string>;
585
+ declare function fromDecision<TAgent extends AnyAgent>(agent: TAgent, defaultInput?: AgentDecideInput<TAgent>): MachineDecisionLogic<any>;
586
+
587
+ declare function chainOfThoughtPolicy<T extends AnyAgent>(agent: T, input: AgentDecideInput<any>): Promise<AgentDecision<any> | undefined>;
588
+
589
+ declare function experimental_shortestPathPolicy<T extends AnyAgent>(agent: T, input: AgentDecideInput<any>): Promise<AgentDecision<any> | undefined>;
590
+
591
+ declare function toolPolicy<TAgent extends AnyAgent>(agent: TAgent, input: AgentDecideInput<TAgent>): Promise<AgentDecision<TAgent> | undefined>;
541
592
 
542
- export { type AgentDecideInput, type AgentDecision, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentInteractInput, type AgentLogic, type AgentLongTermMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPath, type AgentStep, type AgentStrategy, type AgentStreamTextOptions, type AnyAgent, type CommonTextOptions, type Compute, type ContextFromAgent, type ContextFromZodContextMapping, type CostFunction, type EventFromAgent, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type LanguageModelV1TextPart, type LanguageModelV1ToolCallPart, type MaybePromise, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, type TypesFromAgent, createAgent, fromDecision, fromText, fromTextStream };
593
+ export { type AgentDecideInput, type AgentDecision, type AgentDecisionInput, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentInsight, type AgentInsightInput, type AgentInteractInput, type AgentLogic, type AgentLongTermMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPath, type AgentPolicy, type AgentStep, type AgentStreamTextOptions, type AnyAgent, type CommonTextOptions, type Compute, type ContextFromAgent, type ContextFromZodContextMapping, type CostFunction, type EventFromAgent, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type LanguageModelV1TextPart, type LanguageModelV1ToolCallPart, type MaybePromise, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StorageAdapter, type StorageAdapterQuery, type StreamTextOptions, type TransitionData, type TypesFromAgent, chainOfThoughtPolicy, createAgent, experimental_shortestPathPolicy, fromDecision, fromText, fromTextStream, toolPolicy };