@statelyai/agent 1.1.5 → 2.0.0-next.0

package/src/types.ts

@@ -1,7 +1,6 @@
 import {
   ActorLogic,
-  ActorRefFrom,
-  AnyActorRef,
+  ActorRefLike,
   AnyEventObject,
   AnyStateMachine,
   EventFrom,
@@ -9,29 +8,32 @@ import {
   PromiseActorLogic,
   SnapshotFrom,
   StateValue,
-  Subscription,
   TransitionSnapshot,
   Values,
 } from 'xstate';
 import {
   CoreMessage,
-  CoreTool,
+  GenerateObjectResult,
   generateText,
   GenerateTextResult,
   LanguageModel,
   streamText,
-  StreamTextResult,
 } from 'ai';
 import { ZodContextMapping, ZodEventMapping } from './schemas';
 import { TypeOf } from 'zod';
+import { Agent } from './agent';
 
 export type GenerateTextOptions = Parameters<typeof generateText>[0];
 
 export type StreamTextOptions = Parameters<typeof streamText>[0];
 
+export type CostFunction<TEvent extends EventObject> = (
+  path: AgentPath<TEvent>
+) => number;
+
 export type AgentPlanInput<TEvent extends EventObject> = Omit<
   GenerateTextOptions,
-  'prompt' | 'messages' | 'tools'
+  'prompt' | 'tools'
 > & {
   /**
    * The currently observed state.
@@ -56,20 +58,51 @@ export type AgentPlanInput<TEvent extends EventObject> = Omit<
    * The previous plan.
    */
   previousPlan?: AgentPlan<TEvent>;
+
+  /**
+   * The total cost of the path to the goal state.
+   */
+  costFunction?: CostFunction<TEvent>;
+};
+
+export type AgentStep<TEvent extends EventObject> = {
+  /** The event to take */
+  event: TEvent;
+  /** The next expected state after taking the event */
+  state: ObservedState | undefined;
+};
+
+export type AgentPath<TEvent extends EventObject> = {
+  /** The expected ending state of the path */
+  state: ObservedState | undefined;
+  /** The steps to reach the ending state */
+  steps: Array<AgentStep<TEvent>>;
+  weight?: number;
 };
 
 export type AgentPlan<TEvent extends EventObject> = {
+  /**
+   * The planner used to generate the plan
+   */
+  planner: string;
   goal: string;
-  state: ObservedState;
-  content?: string;
   /**
-   * Executes the plan based on the given `state` and resolves with
-   * a potential next `event` to trigger to achieve the `goal`.
+   * The ending state of the plan.
+   */
+  goalState: ObservedState | undefined;
+  /**
+   * The next event that the agent decided needs to occur to achieve the `goal`.
+   *
+   * This next event is chosen from the
    */
-  execute: (state: ObservedState) => Promise<TEvent | undefined>;
   nextEvent: TEvent | undefined;
-  sessionId: string;
+  /**
+   * The paths that the agent can take to achieve the goal.
+   */
+  paths: AgentPath<TEvent>[];
+  episodeId: string;
   timestamp: number;
+  // result: GenerateObjectResult<any>;
 };
 
 export interface TransitionData {
@@ -116,16 +149,12 @@ export type AgentPlanner<T extends AnyAgent> = (
 export type AgentDecideOptions = {
   goal: string;
   model?: LanguageModel;
-  context?: any;
   state: ObservedState;
-  machine: AnyStateMachine;
+  machine?: AnyStateMachine;
   execute?: (event: AnyEventObject) => Promise<void>;
   planner?: AgentPlanner<any>;
   events?: ZodEventMapping;
-} & Omit<
-  Parameters<typeof generateText>[0],
-  'model' | 'tools' | 'prompt' | 'messages'
->;
+} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 
 export interface AgentFeedback {
   goal?: string;
@@ -137,7 +166,7 @@ export interface AgentFeedback {
   attributes: Record<string, any>;
   reward: number;
   timestamp: number;
-  sessionId: string;
+  episodeId: string;
 }
 
 export interface AgentFeedbackInput {
@@ -158,9 +187,122 @@ export type AgentMessage = CoreMessage & {
    */
   responseId?: string;
   result?: GenerateTextResult<any>;
-  sessionId: string;
-  correlationId: string;
-  parentCorrelationId?: string;
+  episodeId: string;
+};
+
+type JSONObject = {
+  [key: string]: JSONValue;
+};
+type JSONArray = JSONValue[];
+type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+
+type LanguageModelV1ProviderMetadata = Record<
+  string,
+  Record<string, JSONValue>
+>;
+
+interface LanguageModelV1ImagePart {
+  type: 'image';
+  /**
+Image data as a Uint8Array (e.g. from a Blob or Buffer) or a URL.
+   */
+  image: Uint8Array | URL;
+  /**
+Optional mime type of the image.
+   */
+  mimeType?: string;
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: LanguageModelV1ProviderMetadata;
+}
+
+export interface LanguageModelV1TextPart {
+  type: 'text';
+  /**
+The text content.
+   */
+  text: string;
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: LanguageModelV1ProviderMetadata;
+}
+
+export interface LanguageModelV1ToolCallPart {
+  type: 'tool-call';
+  /**
+ID of the tool call. This ID is used to match the tool call with the tool result.
+ */
+  toolCallId: string;
+  /**
+Name of the tool that is being called.
+ */
+  toolName: string;
+  /**
+Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+   */
+  args: unknown;
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: LanguageModelV1ProviderMetadata;
+}
+interface LanguageModelV1ToolResultPart {
+  type: 'tool-result';
+  /**
+ID of the tool call that this result is associated with.
+ */
+  toolCallId: string;
+  /**
+Name of the tool that generated this result.
+  */
+  toolName: string;
+  /**
+Result of the tool call. This is a JSON-serializable object.
+   */
+  result: unknown;
+  /**
+Optional flag if the result is an error or an error message.
+   */
+  isError?: boolean;
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: LanguageModelV1ProviderMetadata;
+}
+type LanguageModelV1Message = (
+  | {
+      role: 'system';
+      content: string;
+    }
+  | {
+      role: 'user';
+      content: Array<LanguageModelV1TextPart | LanguageModelV1ImagePart>;
+    }
+  | {
+      role: 'assistant';
+      content: Array<LanguageModelV1TextPart | LanguageModelV1ToolCallPart>;
+    }
+  | {
+      role: 'tool';
+      content: Array<LanguageModelV1ToolResultPart>;
+    }
+) & {
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: LanguageModelV1ProviderMetadata;
 };
 
 export type AgentMessageInput = CoreMessage & {
@@ -176,20 +318,20 @@ export type AgentMessageInput = CoreMessage & {
   result?: GenerateTextResult<any>;
 };
 
-export interface AgentObservation<TActor extends AnyActorRef> {
+export interface AgentObservation<TActor extends ActorRefLike> {
   id: string;
   prevState: SnapshotFrom<TActor> | undefined;
-  event: EventFrom<TActor>;
+  event: EventFrom<TActor> | undefined;
   state: SnapshotFrom<TActor>;
   machineHash: string | undefined;
-  sessionId: string;
+  episodeId: string;
   timestamp: number;
 }
 
 export interface AgentObservationInput {
   id?: string;
-  prevState: ObservedState | undefined;
-  event: AnyEventObject;
+  prevState?: ObservedState;
+  event?: AnyEventObject;
   state: ObservedState;
   machine?: AnyStateMachine;
   timestamp?: number;
@@ -198,7 +340,7 @@ export interface AgentObservationInput {
 export type AgentDecisionInput = {
   goal: string;
   model?: LanguageModel;
-  context?: any;
+  context?: Record<string, any>;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 
 export type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<
@@ -260,150 +402,6 @@ export type ContextFromZodContextMapping<
   [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
 
-export type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<
-  AgentLogic<TEvents>
-> & {
-  /**
-   * 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;
-  /**
-   * The unique identifier for the agent.
-   */
-  id?: string;
-  description?: string;
-  events: ZodEventMapping;
-  types: {
-    events: TEvents;
-    context: Compute<TContext>;
-  };
-  model: LanguageModel;
-  defaultOptions: GenerateTextOptions;
-  memory: AgentLongTermMemory | undefined;
-  /**
-   * The adapter used to perform LLM actions such as
-   * `.generateText(…)` and `.streamText(…)`.
-   *
-   * Defaults to the Vercel AI SDK.
-   */
-  adapter: AIAdapter;
-
-  /**
-   * Resolves with an `AgentPlan` 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: (
-    options: AgentDecideOptions
-  ) => Promise<AgentPlan<TEvents> | undefined>;
-
-  // Generate text
-  generateText: (
-    options: AgentGenerateTextOptions
-  ) => Promise<AgentGenerateTextResult>;
-
-  // Stream text
-  streamText: (
-    options: AgentStreamTextOptions
-  ) => Promise<AgentStreamTextResult>;
-
-  addObservation: (
-    observationInput: AgentObservationInput
-  ) => AgentObservation<any>; // TODO
-  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: 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;
-
-  /**
-   * Retrieves messages from the agent's short-term (local) memory.
-   */
-  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;
-};
-
 export type AnyAgent = Agent<any, any>;
 
 export type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
@@ -414,13 +412,6 @@ export type CommonTextOptions = {
   context?: Record<string, any>;
   messages?: FromAgent<CoreMessage[]>;
   template?: PromptTemplate<any>;
-  correlationId?: string;
-  parentCorrelationId?: string;
-};
-
-export type TextResultMeta = {
-  correlationId: string;
-  parentCorrelationId?: string;
 };
 
 export type AgentGenerateTextOptions = Omit<
@@ -429,16 +420,12 @@ export type AgentGenerateTextOptions = Omit<
 > &
   CommonTextOptions;
 
-export type AgentGenerateTextResult = GenerateTextResult<any> & TextResultMeta;
-
 export type AgentStreamTextOptions = Omit<
   StreamTextOptions,
   'model' | 'prompt' | 'messages'
 > &
   CommonTextOptions;
 
-export type AgentStreamTextResult = StreamTextResult<any> & TextResultMeta;
-
 export interface ObservedState {
   /**
    * The current state value of the state machine, e.g.
@@ -448,10 +435,10 @@ export interface ObservedState {
   /**
    * Additional contextual data related to the current state
    */
-  context: Record<string, unknown>;
+  context?: Record<string, unknown>;
 }
 
-export type ObservedStateFrom<TActor extends AnyActorRef> = Pick<
+export type ObservedStateFrom<TActor extends ActorRefLike> = Pick<
   SnapshotFrom<TActor>,
   'value' | 'context'
 >;
@@ -463,20 +450,6 @@ export type AgentMemoryContext = {
   feedback: AgentFeedback[];
 };
 
-export type AgentMemory = AppendOnlyStorage<AgentMemoryContext>;
-
-export interface AppendOnlyStorage<T extends Record<string, any[]>> {
-  append<K extends keyof T>(
-    sessionId: string,
-    key: K,
-    item: T[K][0]
-  ): Promise<void>;
-  getAll<K extends keyof T>(
-    sessionId: string,
-    key: K
-  ): Promise<T[K] | undefined>;
-}
-
 export interface AgentLongTermMemory {
   get<K extends keyof AgentMemoryContext>(
     key: K
@@ -491,9 +464,4 @@ export interface AgentLongTermMemory {
   ): Promise<void>;
 }
 
-export interface AIAdapter {
-  generateText: typeof generateText;
-  streamText: typeof streamText;
-}
-
 export type Compute<A extends any> = { [K in keyof A]: A[K] } & unknown;

package/src/utils.ts

@@ -1,6 +1,12 @@
-import { AnyMachineSnapshot, AnyStateMachine, AnyStateNode } from 'xstate';
+import {
+  ActorRefLike,
+  AnyActorRef,
+  AnyMachineSnapshot,
+  AnyStateMachine,
+  AnyStateNode,
+} from 'xstate';
 import hash from 'object-hash';
-import { TransitionData } from './types';
+import { ObservedState, TransitionData } from './types';
 
 export function getAllTransitions(state: AnyMachineSnapshot): TransitionData[] {
   const nodes = state._nodes;
@@ -53,10 +59,11 @@ export function wrapInXml(tagName: string, content: string): string {
   return `<${tagName}>${content}</${tagName}>`;
 }
 
-export function randomId() {
+export function randomId(prefix?: string): string {
   const timestamp = Date.now().toString(36);
   const random = Math.random().toString(36).substring(2, 9);
-  return timestamp + random;
+  // return timestamp + random;
+  return `${prefix || ''}${timestamp}${random}`;
 }
 
 const machineHashes: WeakMap<AnyStateMachine, string> = new WeakMap();
@@ -70,3 +77,29 @@ export function getMachineHash(machine: AnyStateMachine): string {
   machineHashes.set(machine, machineHash);
   return machineHash;
 }
+
+export function isActorRef(
+  actorRefLike: ActorRefLike
+): actorRefLike is AnyActorRef {
+  return (
+    'src' in actorRefLike &&
+    'system' in actorRefLike &&
+    'sessionId' in actorRefLike
+  );
+}
+
+export function getTransitions(
+  state: ObservedState,
+  machine: AnyStateMachine
+): TransitionData[] {
+  if (!machine) {
+    return [];
+  }
+
+  const resolvedState = machine.resolveState({
+    ...state,
+    // Need this property defined to make TS happy
+    context: state.context,
+  });
+  return getAllTransitions(resolvedState);
+}

package/src/adapters/vercel.ts

@@ -1,7 +0,0 @@
-import { generateText, streamText } from 'ai';
-import { AIAdapter } from '../types';
-
-export const vercelAdapter: AIAdapter = {
-  generateText,
-  streamText,
-};

package/src/decision.ts

@@ -1,84 +0,0 @@
-import { AnyActor, AnyMachineSnapshot, fromPromise } from 'xstate';
-import {
-  AnyAgent,
-  AgentDecideOptions,
-  AgentDecisionLogic,
-  AgentDecisionInput,
-  AgentPlanner,
-  AgentPlan,
-} from './types';
-import { simplePlanner } from './planners/simplePlanner';
-
-export async function agentDecide<T extends AnyAgent>(
-  agent: T,
-  options: AgentDecideOptions
-): Promise<AgentPlan<any> | undefined> {
-  const resolvedOptions = {
-    ...agent.defaultOptions,
-    ...options,
-  };
-  const {
-    planner = simplePlanner as AgentPlanner<any>,
-    goal,
-    events = agent.events,
-    state,
-    machine,
-    model = agent.model,
-    ...otherPlanInput
-  } = resolvedOptions;
-
-  const plan = await planner(agent, {
-    model,
-    goal,
-    events,
-    state,
-    machine,
-    ...otherPlanInput,
-  });
-
-  if (plan?.nextEvent) {
-    agent.addPlan(plan);
-    await resolvedOptions.execute?.(plan.nextEvent);
-  }
-
-  return plan;
-}
-
-export function fromDecision(
-  agent: AnyAgent,
-  defaultInput?: AgentDecisionInput
-): AgentDecisionLogic<any> {
-  return fromPromise(async ({ input, self }) => {
-    const parentRef = self._parent;
-    if (!parentRef) {
-      return;
-    }
-
-    const snapshot = parentRef.getSnapshot() as AnyMachineSnapshot;
-    const inputObject = typeof input === 'string' ? { goal: input } : input;
-    const resolvedInput = {
-      ...defaultInput,
-      ...inputObject,
-    };
-    const contextToInclude =
-      resolvedInput.context === true
-        ? // include entire context
-          parentRef.getSnapshot().context
-        : resolvedInput.context;
-    const state = {
-      value: snapshot.value,
-      context: contextToInclude,
-    };
-
-    const plan = await agentDecide(agent, {
-      machine: (parentRef as AnyActor).logic,
-      state,
-      execute: async (event) => {
-        parentRef.send(event);
-      },
-      ...resolvedInput,
-    });
-
-    return plan;
-  }) as AgentDecisionLogic<any>;
-}

package/src/memory.ts

@@ -1,25 +0,0 @@
-import { AgentMemory, AgentMemoryContext } from './types';
-
-export function createAgentMemory(): AgentMemory {
-  const storage = {
-    sessions: {} as Record<string, AgentMemoryContext>,
-  };
-
-  return {
-    append: async (sessionId, key, item) => {
-      storage.sessions[sessionId] =
-        storage.sessions[sessionId] ||
-        ({
-          observations: [],
-          messages: [],
-          plans: [],
-          feedback: [],
-        } satisfies AgentMemoryContext);
-
-      storage.sessions[sessionId]![key].push(item as any);
-    },
-    getAll: async (sessionId, key) => {
-      return storage.sessions[sessionId]?.[key];
-    },
-  };
-}