@statelyai/agent 1.0.0-beta.0 → 1.0.0

package/.changeset/heavy-moons-bake.md

@@ -0,0 +1,12 @@
+---
+'@statelyai/agent': minor
+---
+
+Added four new methods for easily retrieving agent messages, observations, feedback, and plans:
+
+- `agent.getMessages()`
+- `agent.getObservations()`
+- `agent.getFeedback()`
+- `agent.getPlans()`
+
+The `agent.select(…)` method is deprecated in favor of these methods.

package/.changeset/silly-berries-drop.md

@@ -0,0 +1,5 @@
+---
+'@statelyai/agent': patch
+---
+
+Messages are now properly included in `agent.decide(…)`, when specified.

package/.changeset/wild-bobcats-care.md

@@ -0,0 +1,26 @@
+---
+'@statelyai/agent': minor
+---
+
+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.
+
+Breaking: The `context` and `events` types are now in `agent.types` instead of ~~`agent.eventTypes`.
+
+```ts
+const agent = createAgent({
+  // ...
+  context: {
+    score: z.number().describe('The score of the game'),
+    // ...
+  },
+});
+
+const machine = setup({
+  types: agent.types,
+}).createMachine({
+  context: {
+    score: 0,
+  },
+  // ...
+});
+```

package/.env.template

@@ -1,6 +1,3 @@
 
 # Get your OpenAI API key from: https://platform.openai.com/signup/
 OPENAI_API_KEY="sk-..."
-
-# Get your Tavily API key from: https://app.tavily.com/
-TAVILY_API_KEY="tvly-..."

package/.github/workflows/release.yml

@@ -11,9 +11,9 @@ permissions: {}
 jobs:
   release:
     permissions:
-      contents: write  # to create release (changesets/action)
+      contents: write # to create release (changesets/action)
       issues: write # to post issue comments (changesets/action)
-      pull-requests: write  # to create pull request (changesets/action)
+      pull-requests: write # to create pull request (changesets/action)
 
     if: github.repository == 'statelyai/agent'
 
@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: ./.github/actions/ci-setup
 
       - name: Create Release Pull Request or Publish to npm

package/dist/index.d.mts

@@ -1,17 +1,38 @@
 import { EventObject, AnyStateMachine, AnyEventObject, AnyActorRef, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, ActorRefFrom, Subscription, StateValue, ObservableActorLogic } from 'xstate';
-import { TypeOf, SomeZodObject } from 'zod';
+import { SomeZodObject, ZodType, TypeOf } from 'zod';
 import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, StreamTextResult, CoreTool } from 'ai';
 
+type ZodEventMapping = {
+    [eventType: string]: SomeZodObject;
+};
+type ZodContextMapping = {
+    [contextKey: string]: ZodType;
+};
+
 type GenerateTextOptions = Parameters<typeof generateText>[0];
 type StreamTextOptions = Parameters<typeof streamText>[0];
-type AgentPlanInput<TEvent extends EventObject> = {
-    model: LanguageModel;
+type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'prompt' | 'messages' | 'tools'> & {
+    /**
+     * The currently observed state.
+     */
     state: ObservedState;
+    /**
+     * The goal for the agent to accomplish.
+     * The agent will create a plan based on this goal.
+     */
     goal: string;
+    /**
+     * The events that the agent can trigger. This is a mapping of
+     * event types to Zod event schemas.
+     */
     events: ZodEventMapping;
+    /**
+     * The state machine that represents the environment the agent
+     * is interacting with.
+     */
     machine?: AnyStateMachine;
     /**
-     * The previous plan
+     * The previous plan.
      */
     previousPlan?: AgentPlan<TEvent>;
 };
@@ -19,10 +40,11 @@ type AgentPlan<TEvent extends EventObject> = {
     goal: string;
     state: ObservedState;
     content?: string;
-    steps?: Array<{
-        event: TEvent;
-        state?: ObservedState;
-    }>;
+    /**
+     * Executes the plan based on the given `state` and resolves with
+     * a potential next `event` to trigger to achieve the `goal`.
+     */
+    execute: (state: ObservedState) => Promise<TEvent | undefined>;
     nextEvent: TEvent | undefined;
     sessionId: string;
     timestamp: number;
@@ -60,10 +82,10 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
      */
     observations?: AgentObservation<any>[];
     feedback?: AgentFeedback[];
-    messages?: AgentMessageHistory[];
+    messages?: AgentMessage[];
     plans?: AgentPlan<TEvents>[];
 }) => string;
-type AgentPlanner<T extends Agent<any>> = (agent: T['eventTypes'], options: AgentPlanInput<T['eventTypes']>) => Promise<AgentPlan<T['eventTypes']> | undefined>;
+type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
 type AgentDecideOptions = {
     goal: string;
     model?: LanguageModel;
@@ -87,7 +109,7 @@ interface AgentFeedbackInput {
     attributes: Record<string, any>;
     timestamp?: number;
 }
-type AgentMessageHistory = CoreMessage & {
+type AgentMessage = CoreMessage & {
     timestamp: number;
     id: string;
     /**
@@ -98,7 +120,7 @@ type AgentMessageHistory = CoreMessage & {
     result?: GenerateTextResult<any>;
     sessionId: string;
 };
-type AgentMessageHistoryInput = CoreMessage & {
+type AgentMessageInput = CoreMessage & {
     timestamp?: number;
     id?: string;
     /**
@@ -113,6 +135,7 @@ interface AgentObservation<TActor extends AnyActorRef> {
     prevState: SnapshotFrom<TActor> | undefined;
     event: EventFrom<TActor>;
     state: SnapshotFrom<TActor>;
+    machineHash: string | undefined;
     sessionId: string;
     timestamp: number;
 }
@@ -121,6 +144,7 @@ interface AgentObservationInput {
     prevState: ObservedState | undefined;
     event: AnyEventObject;
     state: ObservedState;
+    machine?: AnyStateMachine;
     timestamp?: number;
 }
 type AgentDecisionInput = {
@@ -137,7 +161,7 @@ type AgentEmitted<TEvents extends EventObject> = {
     observation: AgentObservation<any>;
 } | {
     type: 'message';
-    message: AgentMessageHistory;
+    message: AgentMessage;
 } | {
     type: 'plan';
     plan: AgentPlan<TEvents>;
@@ -150,7 +174,7 @@ type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<Age
     observation: AgentObservation<any>;
 } | {
     type: 'agent.message';
-    message: AgentMessageHistory;
+    message: AgentMessage;
 } | {
     type: 'agent.plan';
     plan: AgentPlan<TEvents>;
@@ -161,19 +185,25 @@ type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
         type: K;
     } & TypeOf<TEventSchemas[K]>;
 }>;
-type Agent<TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
+type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
+    [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
+};
+type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
     /**
-     * The general name of the agent. All agents with the same name are related and
+     * The name of the agent. All agents with the same name are related and
      * able to share experiences (observations, feedback) with each other.
      */
-    name: string;
+    name?: string;
     /**
-     * The unique id of the agent. This is used to partition message history.
+     * The unique identifier for the agent.
      */
     id?: string;
     description?: string;
     events: ZodEventMapping;
-    eventTypes: TEvents;
+    types: {
+        events: TEvents;
+        context: Compute<TContext>;
+    };
     model: LanguageModel;
     defaultOptions: GenerateTextOptions;
     memory: AgentLongTermMemory | undefined;
@@ -189,37 +219,99 @@ type Agent<TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
      *
      * - The `goal` for the agent to achieve
      * - The observed current `state`
-     * - The `logic` (e.g. a state machine) that specifies what can happen next
+     * - The `machine` (e.g. a state machine) that specifies what can happen next
      * - Additional `context`
      */
     decide: (options: AgentDecideOptions) => Promise<AgentPlan<TEvents> | undefined>;
     generateText: (options: AgentGenerateTextOptions) => Promise<GenerateTextResult<Record<string, any>>>;
     streamText: (options: AgentStreamTextOptions) => Promise<StreamTextResult<Record<string, CoreTool<any, any>>>>;
-    addObservation: (observation: AgentObservationInput) => AgentObservation<any>;
-    addMessage: (history: AgentMessageHistoryInput) => AgentMessageHistory;
-    addFeedback: (feedbackItem: AgentFeedbackInput) => AgentFeedback;
+    addObservation: (observationInput: AgentObservationInput) => AgentObservation<any>;
+    addMessage: (messageInput: AgentMessageInput) => AgentMessage;
+    addFeedback: (feedbackInput: AgentFeedbackInput) => AgentFeedback;
     addPlan: (plan: AgentPlan<TEvents>) => void;
     /**
      * Called whenever the agent (LLM assistant) receives or sends a message.
      */
-    onMessage: (callback: (message: AgentMessageHistory) => void) => void;
+    onMessage: (callback: (message: AgentMessage) => void) => void;
     /**
      * Selects agent data from its context.
+     *
+     * @deprecated Select from `agent.getSnapshot().context` directly or:
+     * - `agent.getMessages()`
+     * - `agent.getObservations()`
+     * - `agent.getFeedback()`
+     * - `agent.getPlans()`
      */
     select: <T>(selector: (context: AgentMemoryContext) => T) => T;
     /**
-     * Inspects state machine actor transitions and automatically observes
-     * (prevState, event, state) tuples.
+     * Retrieves messages from the agent's short-term (local) memory.
      */
-    interact: <TActor extends AnyActorRef>(actorRef: TActor, getInput?: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined) => Subscription;
+    getMessages: () => AgentMessage[];
+    /**
+     * Retrieves observations from the agent's short-term (local) memory.
+     */
+    getObservations: () => AgentObservation<Agent<TContext, TEvents>>[];
+    /**
+     * Retrieves feedback from the agent's short-term (local) memory.
+     */
+    getFeedback: () => AgentFeedback[];
+    /**
+     * Retrieves strategies from the agent's short-term (local) memory.
+     */
+    getPlans: () => AgentPlan<TEvents>[];
+    /**
+     * Interacts with this state machine actor by inspecting state transitions and storing them as observations.
+     *
+     * Observations contain the `prevState`, `event`, and current `state` of this
+     * actor, as well as other properties that are useful when recalled.
+     * These observations are stored in the `agent`'s short-term (local) memory
+     * and can be retrieved via `agent.getObservations()`.
+     *
+     * @example
+     * ```ts
+     * // Only observes the actor's state transitions
+     * agent.interact(actor);
+     *
+     * actor.start();
+     * ```
+     */
+    interact<TActor extends AnyActorRef>(actorRef: TActor): Subscription;
+    /**
+     * Interacts with this state machine actor by:
+     * 1. Inspecting state transitions and storing them as observations
+     * 2. Deciding what to do next (which event to send the actor) based on
+     * the agent input returned from `getInput(observation)`, if `getInput(…)` is provided as the 2nd argument.
+     *
+     * Observations contain the `prevState`, `event`, and current `state` of this
+     * actor, as well as other properties that are useful when recalled.
+     * These observations are stored in the `agent`'s short-term (local) memory
+     * and can be retrieved via `agent.getObservations()`.
+     *
+     * @example
+     * ```ts
+     * // Observes the actor's state transitions and
+     * // makes a decision if on the "summarize" state
+     * agent.interact(actor, observed => {
+     *   if (observed.state.matches('summarize')) {
+     *     return {
+     *       context: observed.state.context,
+     *       goal: 'Summarize the message'
+     *     }
+     *   }
+     * });
+     *
+     * actor.start();
+     * ```
+     */
+    interact<TActor extends AnyActorRef>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
 };
-type AnyAgent = Agent<any>;
+type AnyAgent = Agent<any, any>;
 type FromAgent<T> = T | ((self: AnyAgent) => T | Promise<T>);
 interface CommonTextOptions {
     prompt: FromAgent<string>;
     model?: LanguageModel;
     context?: Record<string, any>;
-    messages?: FromAgent<CoreMessage[]> | true;
+    messages?: FromAgent<CoreMessage[]>;
     template?: PromptTemplate<any>;
 }
 type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
@@ -238,7 +330,7 @@ interface ObservedState {
 type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
 type AgentMemoryContext = {
     observations: AgentObservation<any>[];
-    messages: AgentMessageHistory[];
+    messages: AgentMessage[];
     plans: AgentPlan<any>[];
     feedback: AgentFeedback[];
 };
@@ -256,16 +348,30 @@ interface AIAdapter {
     generateText: typeof generateText;
     streamText: typeof streamText;
 }
+type Compute<A extends any> = {
+    [K in keyof A]: A[K];
+} & unknown;
 
-type ZodEventMapping = {
-    [eventType: string]: SomeZodObject;
-};
-
-declare function createAgent<const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>>({ name, description, model, events, planner, stringify, getMemory, logic, adapter, ...generateTextOptions }: {
+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 }: {
+    /**
+     * The unique identifier for the agent.
+     *
+     * This should be the same across all sessions of a specific agent, as it can be
+     * used to retrieve memory for this agent.
+     *
+     * @example
+     * ```ts
+     * const agent = createAgent({
+     *  id: 'recipe-assistant',
+     *  // ...
+     * });
+     * ```
+     */
+    id?: string;
     /**
      * The name of the agent
      */
-    name: string;
+    name?: string;
     /**
      * A description of the role of the agent
      */
@@ -275,30 +381,29 @@ declare function createAgent<const TEventSchemas extends ZodEventMapping, TEvent
      * that the agent knows about.
      */
     events: TEventSchemas;
-    planner?: AgentPlanner<Agent<TEvents>>;
+    context?: TContextSchema;
+    planner?: AgentPlanner<Agent<TContext, TEvents>>;
     stringify?: typeof JSON.stringify;
     /**
      * A function that retrieves the agent's long term memory
      */
-    getMemory?: (agent: Agent<any>) => AgentLongTermMemory;
+    getMemory?: (agent: Agent<TContext, TEvents>) => AgentLongTermMemory;
     /**
      * Agent logic
      */
     logic?: AgentLogic<TEvents>;
     adapter?: AIAdapter;
-} & GenerateTextOptions): Agent<TEvents>;
+} & GenerateTextOptions): Agent<TContext, TEvents>;
 
-declare function agentGenerateText<T extends Agent<any>>(agent: T, options: AgentGenerateTextOptions): Promise<GenerateTextResult<Record<string, CoreTool<any, any>>>>;
-declare function fromTextStream<T extends Agent<any>>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
+declare function fromTextStream<T extends AnyAgent>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
     textDelta: string;
 }, Omit<AgentStreamTextOptions, 'context'> & {
-    context?: AgentStreamTextOptions['context'] | boolean;
+    context?: AgentStreamTextOptions['context'];
 }>;
-declare function fromText<T extends Agent<any>>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
-    context?: AgentGenerateTextOptions['context'] | boolean;
+declare function fromText<T extends AnyAgent>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
+    context?: AgentGenerateTextOptions['context'];
 }>;
 
-declare function agentDecide<T extends Agent<any>>(agent: T, options: AgentDecideOptions): Promise<AgentPlan<any> | undefined>;
-declare function fromDecision(agent: Agent<any>, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
+declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
 
-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 AgentMessageHistory, type AgentMessageHistoryInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, type AnyAgent, type AppendOnlyStorage, type CommonTextOptions, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, agentDecide, agentGenerateText, createAgent, fromDecision, fromText, fromTextStream };
+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 AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, 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 TransitionData, createAgent, fromDecision, fromText, fromTextStream };