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

package/.changeset/cyan-carpets-perform.md

@@ -0,0 +1,5 @@
+---
+'@statelyai/agent': patch
+---
+
+The `name` field in `createAgent({ name: '...' })` has been renamed to `id`.

package/.changeset/fast-donkeys-argue.md

@@ -0,0 +1,5 @@
+---
+"@statelyai/agent": patch
+---
+
+The `description` field in `createAgent({ description: '...' })` is now used for the `system` prompt in agent decision making when a `system` prompt is not provided.

package/.changeset/old-jobs-check.md

@@ -0,0 +1,5 @@
+---
+'@statelyai/agent': minor
+---
+
+You can specify `maxAttempts` in `agent.decide({ maxAttempts: 5 })`. This will allow the agent to attempt to make a decision up to the specified number of `maxAttempts` before giving up. The default value is `2`.

package/.changeset/pre.json

@@ -5,6 +5,9 @@
     "@statelyai/agent": "1.1.6"
   },
   "changesets": [
-    "light-hats-drive"
+    "cyan-carpets-perform",
+    "fast-donkeys-argue",
+    "light-hats-drive",
+    "old-jobs-check"
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @statelyai/agent
 
+## 2.0.0-next.1
+
+### Minor Changes
+
+- [`6a9861d`](https://github.com/statelyai/agent/commit/6a9861d959ce295114f53c95c5bdaa097348bacb) Thanks [@davidkpiano](https://github.com/davidkpiano)! - You can specify `maxAttempts` in `agent.decide({ maxAttempts: 5 })`. This will allow the agent to attempt to make a decision up to the specified number of `maxAttempts` before giving up. The default value is `2`.
+
+### Patch Changes
+
+- [`8c3eab8`](https://github.com/statelyai/agent/commit/8c3eab8950cb85e662c6afb5d8cefb1d5ef54dd8) Thanks [@davidkpiano](https://github.com/davidkpiano)! - The `name` field in `createAgent({ name: '...' })` has been renamed to `id`.
+
+- [`8c3eab8`](https://github.com/statelyai/agent/commit/8c3eab8950cb85e662c6afb5d8cefb1d5ef54dd8) Thanks [@davidkpiano](https://github.com/davidkpiano)! - The `description` field in `createAgent({ description: '...' })` is now used for the `system` prompt in agent decision making when a `system` prompt is not provided.
+
 ## 2.0.0-next.0
 
 ### Major Changes

package/dist/index.d.mts

@@ -13,7 +13,7 @@ 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<GenerateTextOptions, 'prompt' | 'tools'> & {
+type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
     /**
      * The currently observed state.
      */
@@ -41,6 +41,11 @@ type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'pro
      * The total cost of the path to the goal state.
      */
     costFunction?: CostFunction<TEvent>;
+    /**
+     * The maximum number of attempts to generate a plan.
+     * Defaults to 2.
+     */
+    maxAttempts?: number;
 };
 type AgentStep<TEvent extends EventObject> = {
     /** The event to take */
@@ -115,14 +120,19 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
     plans?: AgentPlan<TEvents>[];
 }) => string;
 type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
-type AgentDecideOptions = {
+type AgentDecideOptions<T extends AnyAgent> = {
     goal: string;
     model?: LanguageModel;
     state: ObservedState;
     machine?: AnyStateMachine;
     execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<any>;
+    planner?: AgentPlanner<T>;
     events?: ZodEventMapping;
+    /**
+     * The maximum number of times the agent will attempt to make a decision.
+     * Defaults to 2.
+     */
+    maxAttempts?: number;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 interface AgentFeedback {
     goal?: string;
@@ -130,7 +140,6 @@ interface AgentFeedback {
     /**
      * The message correlation that the feedback is relevant for
      */
-    correlationId?: string;
     attributes: Record<string, any>;
     reward: number;
     timestamp: number;
@@ -139,7 +148,6 @@ interface AgentFeedback {
 interface AgentFeedbackInput {
     goal?: string;
     observationId?: string;
-    correlationId?: string;
     attributes?: Record<string, any>;
     timestamp?: number;
     reward?: number;
@@ -203,8 +211,6 @@ type AgentMessageInput = CoreMessage & {
      * which message this message is responding to, if any.
      */
     responseId?: string;
-    correlationId?: string;
-    parentCorrelationId?: string;
     result?: GenerateTextResult<any>;
 };
 interface AgentObservation<TActor extends ActorRefLike> {
@@ -265,7 +271,7 @@ type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
 type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
     [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
-type AnyAgent = Agent<any, any>;
+type AnyAgent = Agent<any, any, any, any>;
 type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
 type CommonTextOptions = {
     prompt: FromAgent<string>;
@@ -303,12 +309,12 @@ type Compute<A extends any> = {
     [K in keyof A]: A[K];
 } & unknown;
 
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ id, name, description, model, events, context, planner, stringify, getMemory, logic, ...generateTextOptions }: {
+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, }: {
     /**
      * 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.
+     * used to retrieve memory for previous episodes of this agent.
      *
      * @example
      * ```ts
@@ -319,10 +325,6 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      * ```
      */
     id?: string;
-    /**
-     * The name of the agent
-     */
-    name?: string;
     /**
      * A description of the role of the agent
      */
@@ -343,6 +345,7 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      * Agent logic
      */
     logic?: AgentLogic<TEvents>;
+    model: LanguageModel;
 } & GenerateTextOptions): 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>> {
     /**
@@ -364,7 +367,7 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     };
     model: LanguageModel;
     memory: AgentLongTermMemory | undefined;
-    defaultOptions: any;
+    defaultOptions: AgentDecideOptions<AnyAgent> | undefined;
     constructor({ logic, id, name, description, model, events, context, planner, }: {
         logic: AgentLogic<TEvents>;
         id?: string;
@@ -390,8 +393,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: ai.AssistantContent;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     } | {
         id: string;
@@ -401,8 +402,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: ai.ToolContent;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     } | {
         id: string;
@@ -412,8 +411,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: string;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     } | {
         id: string;
@@ -423,8 +420,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: ai.UserContent;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     };
     getMessages(): AgentMessage[];
@@ -437,7 +432,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         episodeId: string;
         goal?: string;
         observationId?: string;
-        correlationId?: string;
     };
     /**
      * Retrieves feedback from the agent's short-term (local) memory.
@@ -508,7 +502,7 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
      * - The `machine` (e.g. a state machine) that specifies what can happen next
      * - Additional `context`
      */
-    decide(opts: AgentDecideOptions): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
+    decide(opts: AgentDecideOptions<this>): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
 }
 
 declare function fromTextStream<T extends AnyAgent>(agent: T, options?: AgentStreamTextOptions): ObservableActorLogic<{

package/dist/index.d.ts

@@ -13,7 +13,7 @@ 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<GenerateTextOptions, 'prompt' | 'tools'> & {
+type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
     /**
      * The currently observed state.
      */
@@ -41,6 +41,11 @@ type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'pro
      * The total cost of the path to the goal state.
      */
     costFunction?: CostFunction<TEvent>;
+    /**
+     * The maximum number of attempts to generate a plan.
+     * Defaults to 2.
+     */
+    maxAttempts?: number;
 };
 type AgentStep<TEvent extends EventObject> = {
     /** The event to take */
@@ -115,14 +120,19 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
     plans?: AgentPlan<TEvents>[];
 }) => string;
 type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
-type AgentDecideOptions = {
+type AgentDecideOptions<T extends AnyAgent> = {
     goal: string;
     model?: LanguageModel;
     state: ObservedState;
     machine?: AnyStateMachine;
     execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<any>;
+    planner?: AgentPlanner<T>;
     events?: ZodEventMapping;
+    /**
+     * The maximum number of times the agent will attempt to make a decision.
+     * Defaults to 2.
+     */
+    maxAttempts?: number;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 interface AgentFeedback {
     goal?: string;
@@ -130,7 +140,6 @@ interface AgentFeedback {
     /**
      * The message correlation that the feedback is relevant for
      */
-    correlationId?: string;
     attributes: Record<string, any>;
     reward: number;
     timestamp: number;
@@ -139,7 +148,6 @@ interface AgentFeedback {
 interface AgentFeedbackInput {
     goal?: string;
     observationId?: string;
-    correlationId?: string;
     attributes?: Record<string, any>;
     timestamp?: number;
     reward?: number;
@@ -203,8 +211,6 @@ type AgentMessageInput = CoreMessage & {
      * which message this message is responding to, if any.
      */
     responseId?: string;
-    correlationId?: string;
-    parentCorrelationId?: string;
     result?: GenerateTextResult<any>;
 };
 interface AgentObservation<TActor extends ActorRefLike> {
@@ -265,7 +271,7 @@ type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
 type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
     [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
-type AnyAgent = Agent<any, any>;
+type AnyAgent = Agent<any, any, any, any>;
 type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
 type CommonTextOptions = {
     prompt: FromAgent<string>;
@@ -303,12 +309,12 @@ type Compute<A extends any> = {
     [K in keyof A]: A[K];
 } & unknown;
 
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ id, name, description, model, events, context, planner, stringify, getMemory, logic, ...generateTextOptions }: {
+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, }: {
     /**
      * 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.
+     * used to retrieve memory for previous episodes of this agent.
      *
      * @example
      * ```ts
@@ -319,10 +325,6 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      * ```
      */
     id?: string;
-    /**
-     * The name of the agent
-     */
-    name?: string;
     /**
      * A description of the role of the agent
      */
@@ -343,6 +345,7 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      * Agent logic
      */
     logic?: AgentLogic<TEvents>;
+    model: LanguageModel;
 } & GenerateTextOptions): 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>> {
     /**
@@ -364,7 +367,7 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     };
     model: LanguageModel;
     memory: AgentLongTermMemory | undefined;
-    defaultOptions: any;
+    defaultOptions: AgentDecideOptions<AnyAgent> | undefined;
     constructor({ logic, id, name, description, model, events, context, planner, }: {
         logic: AgentLogic<TEvents>;
         id?: string;
@@ -390,8 +393,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: ai.AssistantContent;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     } | {
         id: string;
@@ -401,8 +402,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: ai.ToolContent;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     } | {
         id: string;
@@ -412,8 +411,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: string;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     } | {
         id: string;
@@ -423,8 +420,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         content: ai.UserContent;
         experimental_providerMetadata?: ai.ProviderMetadata;
         responseId?: string;
-        correlationId?: string;
-        parentCorrelationId?: string;
         result?: ai.GenerateTextResult<any>;
     };
     getMessages(): AgentMessage[];
@@ -437,7 +432,6 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
         episodeId: string;
         goal?: string;
         observationId?: string;
-        correlationId?: string;
     };
     /**
      * Retrieves feedback from the agent's short-term (local) memory.
@@ -508,7 +502,7 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
      * - The `machine` (e.g. a state machine) that specifies what can happen next
      * - Additional `context`
      */
-    decide(opts: AgentDecideOptions): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
+    decide(opts: AgentDecideOptions<this>): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
 }
 
 declare function fromTextStream<T extends AnyAgent>(agent: T, options?: AgentStreamTextOptions): ObservableActorLogic<{

package/dist/index.js

@@ -40,7 +40,7 @@ module.exports = __toCommonJS(src_exports);
 // src/agent.ts
 var import_xstate4 = require("xstate");
 
-// src/planners/simplePlanner.ts
+// src/planners/simple.ts
 var import_ai3 = require("ai");
 
 // src/utils.ts
@@ -106,8 +106,11 @@ function getTransitions(state, machine) {
   });
   return getAllTransitions(resolvedState);
 }
+function isMachineActor(actor) {
+  return "src" in actor && typeof actor.src === "object" && actor.src !== null && "definition" in actor.src;
+}
 
-// src/planners/simplePlanner.ts
+// src/planners/simple.ts
 var import_xstate3 = require("xstate");
 
 // src/templates/defaultText.ts
@@ -218,19 +221,27 @@ async function agentDecide(agent, options) {
     state,
     machine,
     model = agent.model,
+    messages,
     ...otherPlanInput
   } = resolvedOptions;
-  const plan = await planner(agent, {
-    model,
-    goal,
-    events,
-    state,
-    machine,
-    ...otherPlanInput
-  });
-  if (plan?.nextEvent) {
-    agent.addPlan(plan);
-    await resolvedOptions.execute?.(plan.nextEvent);
+  let attempts = 0;
+  const maxAttempts = resolvedOptions.maxAttempts ?? 2;
+  let plan;
+  while (attempts++ < maxAttempts) {
+    plan = await planner(agent, {
+      model,
+      goal,
+      events,
+      state,
+      machine,
+      messages,
+      // TODO: fix UIMessage thing
+      ...otherPlanInput
+    });
+    if (plan?.nextEvent) {
+      agent.addPlan(plan);
+      await resolvedOptions.execute?.(plan.nextEvent);
+    }
   }
   return plan;
 }
@@ -304,7 +315,7 @@ function getToolMap(_agent, input) {
   return toolMap;
 }
 
-// src/planners/simplePlanner.ts
+// src/planners/simple.ts
 var simplePlannerPromptTemplate = (data) => {
   return `
 ${defaultTextTemplate(data)}
@@ -338,12 +349,13 @@ async function simplePlanner(agent, input) {
   }) : void 0;
   const result = await (0, import_ai3.generateText)({
     ...rest,
+    system: input.system ?? agent.description,
     model,
     messages,
     tools: toolMap,
     toolChoice: input.toolChoice ?? "required"
   });
-  result.responseMessages.forEach((m) => {
+  result.response.messages.forEach((m) => {
     const message = m;
     agent.addMessage({
       ...message,
@@ -388,13 +400,11 @@ function createAgentMiddleware(agent) {
     },
     wrapGenerate: async ({ doGenerate, params }) => {
       const id = randomId();
-      params.prompt.forEach((p) => {
+      params.prompt.forEach((message) => {
         agent.addMessage({
           id,
-          ...p,
-          timestamp: Date.now(),
-          correlationId: params.providerMetadata?.correlationId,
-          parentCorrelationId: params.providerMetadata?.parentCorrelationId
+          ...message,
+          timestamp: Date.now()
         });
       });
       const result = await doGenerate();
@@ -407,9 +417,7 @@ function createAgentMiddleware(agent) {
         agent.addMessage({
           id,
           ...message,
-          timestamp: Date.now(),
-          correlationId: params.providerMetadata?.correlationId,
-          parentCorrelationId: params.providerMetadata?.parentCorrelationId
+          timestamp: Date.now()
         });
       });
       const { stream, ...rest } = await doStream();
@@ -434,9 +442,7 @@ function createAgentMiddleware(agent) {
             timestamp: Date.now(),
             role: "assistant",
             content,
-            responseId: id,
-            correlationId: params.providerMetadata?.correlationId,
-            parentCorrelationId: params.providerMetadata?.parentCorrelationId
+            responseId: id
           });
         }
       });
@@ -489,8 +495,10 @@ var agentLogic = (0, import_xstate4.fromTransition)(
         });
         break;
       }
-      default:
+      default: {
+        console.warn("Unrecognized event", event);
         break;
+      }
     }
     return state;
   },
@@ -503,22 +511,17 @@ var agentLogic = (0, import_xstate4.fromTransition)(
 );
 function createAgent({
   id,
-  name,
   description,
   model,
   events,
   context,
   planner = simplePlanner,
-  stringify = JSON.stringify,
-  getMemory,
-  logic = agentLogic,
-  ...generateTextOptions
+  logic = agentLogic
 }) {
   return new Agent({
     id,
     context,
     events,
-    name,
     description,
     planner,
     model,
@@ -629,7 +632,8 @@ var Agent = class extends import_xstate4.Actor {
     return this.getSnapshot().context.plans;
   }
   interact(actorRef, getInput) {
-    const actorRefCheck = isActorRef(actorRef);
+    const actorRefCheck = isActorRef(actorRef) && actorRef.src;
+    const machine = isMachineActor(actorRef) ? actorRef.src : void 0;
     let prevState = void 0;
     let subscribed = true;
     const agent = this;
@@ -637,14 +641,14 @@ var Agent = class extends import_xstate4.Actor {
       const observation = agent.addObservation(observationInput);
       const input = getInput?.(observation);
       if (input) {
-        await agentDecide(agent, {
-          machine: actorRefCheck ? actorRef.src : void 0,
+        const res = await agentDecide(agent, {
+          machine,
           state: observation.state,
-          execute: async (event) => {
-            actorRef.send(event);
-          },
           ...input
         });
+        if (res?.nextEvent) {
+          actorRef.send(res.nextEvent);
+        }
       }
       prevState = observationInput.state;
     }