@statelyai/agent 2.0.0-next.1 → 2.0.0-next.2

package/.changeset/grumpy-dolphins-think.md

@@ -0,0 +1,17 @@
+---
+'@statelyai/agent': minor
+---
+
+planner -> strategy
+agent.addPlan -> agent.addDecision
+agent.getPlans -> agent.getDecisions
+
+The word "strategy" is now used instead of "planner" to make it more clear what the agent is doing: it uses a strategy to make decisions. The method `agent.addPlan(…)` has been renamed to `agent.addDecision(…)` and `agent.getPlans(…)` has been renamed to `agent.getDecisions(…)` to reflect this change. Additionally, you specify the `strategy` instead of the `planner` when creating an agent:
+
+```diff
+const agent = createAgent({
+- planner: createSimplePlanner(),
++ strategy: createSimpleStrategy(),
+  ...
+});
+```

package/.changeset/old-teachers-tap.md

@@ -0,0 +1,5 @@
+---
+'@statelyai/agent': minor
+---
+
+For feedback, the `goal`, `observationId`, and `attributes` are now required, and `feedback` and `reward` are removed since they are redundant.

package/.changeset/pre.json

@@ -7,7 +7,10 @@
   "changesets": [
     "cyan-carpets-perform",
     "fast-donkeys-argue",
+    "grumpy-dolphins-think",
     "light-hats-drive",
-    "old-jobs-check"
+    "old-jobs-check",
+    "old-teachers-tap",
+    "smart-yaks-pull"
   ]
 }

package/.changeset/smart-yaks-pull.md

@@ -0,0 +1,23 @@
+---
+'@statelyai/agent': minor
+---
+
+You can specify `allowedEvents` in `agent.decide(...)` to allow from a list of specific events to be sent to the agent. This is useful when using `agent.decide(...)` without a state machine.
+
+```ts
+const agent = createAgent({
+  // ...
+  events: {
+    PLAY: z.object({}).describe('Play a move'),
+    SKIP: z.object({}).describe('Skip a move'),
+    FORFEIT: z.object({}).describe('Forfeit the game'),
+  },
+});
+
+// ...
+const decision = await agent.decide({
+  // Don't allow the agent to send `FORFEIT` or other events
+  allowedEvents: ['PLAY', 'SKIP'],
+  // ...
+});
+```

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @statelyai/agent
 
+## 2.0.0-next.2
+
+### Minor Changes
+
+- [`4d870fe`](https://github.com/statelyai/agent/commit/4d870fe38ad0c906bafb2e0f6b2dabb745900ad3) Thanks [@davidkpiano](https://github.com/davidkpiano)! - planner -> strategy
+  agent.addPlan -> agent.addDecision
+  agent.getPlans -> agent.getDecisions
+
+  The word "strategy" is now used instead of "planner" to make it more clear what the agent is doing: it uses a strategy to make decisions. The method `agent.addPlan(…)` has been renamed to `agent.addDecision(…)` and `agent.getPlans(…)` has been renamed to `agent.getDecisions(…)` to reflect this change. Additionally, you specify the `strategy` instead of the `planner` when creating an agent:
+
+  ```diff
+  const agent = createAgent({
+  - planner: createSimplePlanner(),
+  + strategy: createSimpleStrategy(),
+    ...
+  });
+  ```
+
+- [`f1189cb`](https://github.com/statelyai/agent/commit/f1189cb980e52fa909888d27d3300dcd913ea47f) Thanks [@davidkpiano](https://github.com/davidkpiano)! - For feedback, the `goal`, `observationId`, and `attributes` are now required, and `feedback` and `reward` are removed since they are redundant.
+
+- [`7b16326`](https://github.com/statelyai/agent/commit/7b163266c61bfc8125ed4d00924680d932001e27) Thanks [@davidkpiano](https://github.com/davidkpiano)! - You can specify `allowedEvents` in `agent.decide(...)` to allow from a list of specific events to be sent to the agent. This is useful when using `agent.decide(...)` without a state machine.
+
+  ```ts
+  const agent = createAgent({
+    // ...
+    events: {
+      PLAY: z.object({}).describe("Play a move"),
+      SKIP: z.object({}).describe("Skip a move"),
+      FORFEIT: z.object({}).describe("Forfeit the game"),
+    },
+  });
+
+  // ...
+  const decision = await agent.decide({
+    // Don't allow the agent to send `FORFEIT` or other events
+    allowedEvents: ["PLAY", "SKIP"],
+    // ...
+  });
+  ```
+
 ## 2.0.0-next.1
 
 ### Minor Changes

package/dist/index.d.mts

@@ -13,14 +13,14 @@ type ZodContextMapping = {
 type GenerateTextOptions = Parameters<typeof generateText>[0];
 type StreamTextOptions = Parameters<typeof streamText>[0];
 type CostFunction<TEvent extends EventObject> = (path: AgentPath<TEvent>) => number;
-type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
+type AgentDecideInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
     /**
      * The currently observed state.
      */
     state: ObservedState;
     /**
      * The goal for the agent to accomplish.
-     * The agent will create a plan based on this goal.
+     * The agent will make a decision based on this goal.
      */
     goal: string;
     /**
@@ -34,15 +34,15 @@ type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions,
      */
     machine?: AnyStateMachine;
     /**
-     * The previous plan.
+     * The previous decision made by the agent.
      */
-    previousPlan?: AgentPlan<TEvent>;
+    prevDecision?: AgentDecision<TEvent>;
     /**
      * The total cost of the path to the goal state.
      */
     costFunction?: CostFunction<TEvent>;
     /**
-     * The maximum number of attempts to generate a plan.
+     * The maximum number of attempts to make a decision.
      * Defaults to 2.
      */
     maxAttempts?: number;
@@ -60,14 +60,14 @@ type AgentPath<TEvent extends EventObject> = {
     steps: Array<AgentStep<TEvent>>;
     weight?: number;
 };
-type AgentPlan<TEvent extends EventObject> = {
+type AgentDecision<TEvent extends EventObject> = {
     /**
-     * The planner used to generate the plan
+     * The strategy used to generate the decision
      */
-    planner: string;
+    strategy: string;
     goal: string;
     /**
-     * The ending state of the plan.
+     * The ending state of the decision.
      */
     goalState: ObservedState | undefined;
     /**
@@ -117,17 +117,20 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
     observations?: AgentObservation<any>[];
     feedback?: AgentFeedback[];
     messages?: AgentMessage[];
-    plans?: AgentPlan<TEvents>[];
+    decisions?: AgentDecision<TEvents>[];
 }) => string;
-type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
+type AgentStrategy<T extends AnyAgent> = (agent: T, input: AgentDecideInput<EventsFromAgent<T>>) => Promise<AgentDecision<EventsFromAgent<T>> | undefined>;
+type AgentInteractInput<T extends AnyAgent> = Omit<AgentDecideOptions<T>, 'state'>;
 type AgentDecideOptions<T extends AnyAgent> = {
     goal: string;
-    model?: LanguageModel;
     state: ObservedState;
+    context?: Record<string, any>;
     machine?: AnyStateMachine;
+    model?: LanguageModel;
     execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<T>;
+    strategy?: AgentStrategy<T>;
     events?: ZodEventMapping;
+    allowedEvents?: Array<EventsFromAgent<T>['type']>;
     /**
      * The maximum number of times the agent will attempt to make a decision.
      * Defaults to 2.
@@ -135,22 +138,20 @@ type AgentDecideOptions<T extends AnyAgent> = {
     maxAttempts?: number;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 interface AgentFeedback {
-    goal?: string;
-    observationId?: string;
+    goal: string;
+    observationId: string;
     /**
      * The message correlation that the feedback is relevant for
      */
     attributes: Record<string, any>;
-    reward: number;
     timestamp: number;
     episodeId: string;
 }
 interface AgentFeedbackInput {
-    goal?: string;
-    observationId?: string;
-    attributes?: Record<string, any>;
+    goal: string;
+    observationId: string;
+    attributes: Record<string, any>;
     timestamp?: number;
-    reward?: number;
 }
 type AgentMessage = CoreMessage & {
     timestamp: number;
@@ -235,7 +236,7 @@ type AgentDecisionInput = {
     model?: LanguageModel;
     context?: Record<string, any>;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
-type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<AgentPlan<TEvents> | undefined, AgentDecisionInput | string>;
+type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<AgentDecision<TEvents> | undefined, AgentDecisionInput | string>;
 type AgentEmitted<TEvents extends EventObject> = {
     type: 'feedback';
     feedback: AgentFeedback;
@@ -246,8 +247,8 @@ type AgentEmitted<TEvents extends EventObject> = {
     type: 'message';
     message: AgentMessage;
 } | {
-    type: 'plan';
-    plan: AgentPlan<TEvents>;
+    type: 'decision';
+    decision: AgentDecision<TEvents>;
 };
 type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<AgentMemoryContext>, {
     type: 'agent.feedback';
@@ -259,8 +260,8 @@ type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<Age
     type: 'agent.message';
     message: AgentMessage;
 } | {
-    type: 'agent.plan';
-    plan: AgentPlan<TEvents>;
+    type: 'agent.decision';
+    decision: AgentDecision<TEvents>;
 }, any, // TODO: input
 any, AgentEmitted<TEvents>>;
 type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
@@ -297,7 +298,7 @@ type ObservedStateFrom<TActor extends ActorRefLike> = Pick<SnapshotFrom<TActor>,
 type AgentMemoryContext = {
     observations: AgentObservation<any>[];
     messages: AgentMessage[];
-    plans: AgentPlan<any>[];
+    decisions: AgentDecision<any>[];
     feedback: AgentFeedback[];
 };
 interface AgentLongTermMemory {
@@ -308,8 +309,15 @@ interface AgentLongTermMemory {
 type Compute<A extends any> = {
     [K in keyof A]: A[K];
 } & unknown;
+type MaybePromise<T> = T | Promise<T>;
+type EventsFromAgent<T extends AnyAgent> = T extends Agent<infer _, infer __, infer TEvents, infer ___> ? TEvents : never;
+type TypesFromAgent<T extends AnyAgent> = T extends Agent<infer TContextSchema, infer TEventSchema> ? {
+    context: ContextFromZodContextMapping<TContextSchema>;
+    events: EventsFromZodEventMapping<TEventSchema>;
+} : never;
+type ContextFromAgent<T extends AnyAgent> = T extends Agent<infer TContextSchema, infer _TEventSchema> ? ContextFromZodContextMapping<TContextSchema> : never;
 
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ id, description: description, model, events, context, planner, logic, }: {
+declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ id, description: description, model, events, context, episodeId, strategy, logic, }: {
     /**
      * The unique identifier for the agent.
      *
@@ -335,7 +343,7 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      */
     events: TEventSchemas;
     context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
+    strategy?: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
     stringify?: typeof JSON.stringify;
     /**
      * A function that retrieves the agent's long term memory
@@ -346,7 +354,8 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      */
     logic?: AgentLogic<TEvents>;
     model: LanguageModel;
-} & GenerateTextOptions): Agent<TContextSchema, TEventSchemas>;
+    episodeId?: string;
+}): Agent<TContextSchema, TEventSchemas>;
 declare class Agent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>> extends Actor<AgentLogic<TEvents>> {
     /**
      * The name of the agent. All agents with the same name are related and
@@ -360,15 +369,11 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     description?: string;
     events: TEventSchemas;
     context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
-    types: {
-        events: TEvents;
-        context: Compute<TContext>;
-    };
+    strategy: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
     model: LanguageModel;
     memory: AgentLongTermMemory | undefined;
     defaultOptions: AgentDecideOptions<AnyAgent> | undefined;
-    constructor({ logic, id, name, description, model, events, context, planner, }: {
+    constructor({ logic, id, name, description, model, events, context, episodeId, strategy, }: {
         logic: AgentLogic<TEvents>;
         id?: string;
         name?: string;
@@ -376,12 +381,17 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         model: GenerateTextOptions['model'];
         events: TEventSchemas;
         context?: TContextSchema;
-        planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
+        strategy?: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
+        episodeId?: string;
     });
     /**
      * Called whenever the agent (LLM assistant) receives or sends a message.
      */
     onMessage(fn: (message: AgentMessage) => void): Subscription;
+    /**
+     * Called whenever the agent (LLM assistant) receives some feedback.
+     */
+    onFeedback(fn: (feedback: AgentFeedback) => void): Subscription;
     /**
      * Retrieves messages from the agent's short-term (local) memory.
      */
@@ -427,11 +437,10 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         attributes: {
             [x: string]: any;
         };
-        reward: number;
         timestamp: number;
         episodeId: string;
-        goal?: string;
-        observationId?: string;
+        goal: string;
+        observationId: string;
     };
     /**
      * Retrieves feedback from the agent's short-term (local) memory.
@@ -442,11 +451,11 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
      * Retrieves observations from the agent's short-term (local) memory.
      */
     getObservations(): AgentObservation<any>[];
-    addPlan(plan: AgentPlan<TEvents>): void;
+    addDecision(decision: AgentDecision<TEvents>): void;
     /**
      * Retrieves strategies from the agent's short-term (local) memory.
      */
-    getPlans(): AgentPlan<any>[];
+    getDecisions(): AgentDecision<any>[];
     /**
      * Interacts with this state machine actor by inspecting state transitions and storing them as observations.
      *
@@ -491,18 +500,18 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
      * actor.start();
      * ```
      */
-    interact<TActor extends ActorRefLike>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
+    interact<TActor extends ActorRefLike>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentInteractInput<this> | void): Subscription;
     observe<TActor extends ActorRefLike>(actorRef: TActor): Subscription;
     wrap(modelToWrap: LanguageModelV1): LanguageModelV1;
     /**
-     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
+     * Resolves with an `AgentDecision` based on the information provided in the `options`, including:
      *
      * - The `goal` for the agent to achieve
      * - The observed current `state`
      * - The `machine` (e.g. a state machine) that specifies what can happen next
      * - Additional `context`
      */
-    decide(opts: AgentDecideOptions<this>): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
+    decide(opts: AgentDecideOptions<this>): Promise<AgentDecision<EventsFromAgent<this>> | undefined>;
 }
 
 declare function fromTextStream<T extends AnyAgent>(agent: T, options?: AgentStreamTextOptions): ObservableActorLogic<{
@@ -514,6 +523,6 @@ declare function fromText<T extends AnyAgent>(agent: T, options?: AgentGenerateT
     context?: AgentGenerateTextOptions['context'];
 }>;
 
-declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
+declare function fromDecision<T extends AnyAgent>(agent: T, defaultInput?: AgentDecideInput<EventsFromAgent<T>>): AgentDecisionLogic<any>;
 
-export { type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentLogic, type AgentLongTermMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPath, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStep, type AgentStreamTextOptions, type AnyAgent, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type CostFunction, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type LanguageModelV1TextPart, type LanguageModelV1ToolCallPart, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };
+export { type AgentDecideInput, type AgentDecideOptions, 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 EventsFromAgent, 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 };