@statelyai/agent 1.1.6 → 2.0.0-next.0

package/examples/joke.ts

@@ -3,7 +3,7 @@ import { createAgent, fromDecision } from '../src';
 import { loadingAnimation } from './helpers/loader';
 import { z } from 'zod';
 import { openai } from '@ai-sdk/openai';
-import { getFromTerminal } from './helpers/helpers';
+import { fromTerminal } from './helpers/helpers';
 
 export function getRandomFunnyPhrase() {
   const funnyPhrases = [
@@ -46,26 +46,30 @@ const loader = fromCallback(({ input }: { input: string }) => {
 
 const agent = createAgent({
   name: 'joke-teller',
-  model: openai('gpt-4-turbo'),
+  model: openai('gpt-4o-mini'),
   events: {
-    askForTopic: z.object({
-      topic: z.string().describe('The topic for the joke'),
-    }),
+    askForTopic: z
+      .object({
+        topic: z.string().describe('The topic for the joke'),
+      })
+      .describe('Ask for a new topic, because the last joke rated 6 or lower'),
     'agent.tellJoke': z.object({
       joke: z.string().describe('The joke text'),
     }),
-    'agent.endJokes': z.object({}).describe('End the jokes'),
+    'agent.endJokes': z
+      .object({})
+      .describe('End the jokes, since the last joke rated 7 or higher'),
     'agent.rateJoke': z.object({
       rating: z.number().min(1).max(10),
       explanation: z.string(),
     }),
     'agent.continue': z.object({}).describe('Continue'),
-    'agent.markAsIrrelevant': z
-      .object({
-        explanation: z.string(),
-      })
-      .describe('Explains why the joke was irrelevant'),
-    'agent.markAsRelevant': z.object({}).describe('The joke was relevant'),
+    'agent.markRelevancy': z.object({
+      relevant: z.boolean().describe('Whether the joke was relevant'),
+      explanation: z
+        .string()
+        .describe('The explanation for why the joke was relevant or not'),
+    }),
   },
   context: {
     topic: z.string().describe('The topic for the joke'),
@@ -81,7 +85,7 @@ const jokeMachine = setup({
   actors: {
     agent: fromDecision(agent),
     loader,
-    getFromTerminal,
+    getFromTerminal: fromTerminal,
   },
 }).createMachine({
   id: 'joke',
@@ -107,72 +111,44 @@ const jokeMachine = setup({
       },
     },
     tellingJoke: {
-      invoke: [
-        {
-          src: 'agent',
-          input: ({ context }) => ({
-            context: {
-              topic: context.topic,
-            },
-            goal: `Tell me a joke about the topic. Do not make any joke that is not relevant to the topic.`,
-          }),
-        },
-        {
-          src: 'loader',
-          input: getRandomFunnyPhrase,
-        },
-      ],
+      invoke: {
+        src: 'loader',
+        input: getRandomFunnyPhrase,
+      },
+
       on: {
         'agent.tellJoke': {
           actions: [
             assign({
               jokes: ({ context, event }) => [...context.jokes, event.joke],
             }),
-            log((x) => x.event.joke),
+            log(({ event }) => event.joke),
           ],
           target: 'relevance',
         },
       },
     },
     relevance: {
-      invoke: {
-        src: 'agent',
-        input: (x) => ({
-          context: {
-            topic: x.context.topic,
-            lastJoke: x.context.jokes[x.context.jokes.length - 1],
-          },
-          goal: 'An irrelevant joke has no reference to the topic. If the last joke is completely irrelevant to the topic, ask for a new joke topic. Otherwise, continue.',
-        }),
-      },
       on: {
-        'agent.markAsIrrelevant': {
-          actions: log((x) => 'Irrelevant joke: ' + x.event.explanation),
-          target: 'waitingForTopic',
-          description: 'Continue',
-        },
-        'agent.markAsRelevant': {
-          actions: log('Joke was relevant'),
-          target: 'rateJoke',
-        },
+        'agent.markRelevancy': [
+          {
+            guard: ({ event }) => !event.relevant,
+            actions: log(
+              ({ event }) => 'Irrelevant joke: ' + event.explanation
+            ),
+            target: 'waitingForTopic',
+            description: 'Continue',
+          },
+          { target: 'rateJoke' },
+        ],
       },
     },
     rateJoke: {
-      invoke: [
-        {
-          src: 'agent',
-          input: ({ context }) => ({
-            context: {
-              jokes: context.jokes,
-            },
-            goal: `Rate the last joke on a scale of 1 to 10.`,
-          }),
-        },
-        {
-          src: 'loader',
-          input: getRandomRatingPhrase,
-        },
-      ],
+      invoke: {
+        src: 'loader',
+        input: getRandomRatingPhrase,
+      },
+
       on: {
         'agent.rateJoke': {
           actions: [
@@ -188,26 +164,14 @@ const jokeMachine = setup({
       },
     },
     decide: {
-      invoke: {
-        src: 'agent',
-        input: ({ context }) => ({
-          context: {
-            lastRating: context.lastRating,
-          },
-          goal: `Choose what to do next, given the previous rating of the joke.`,
-        }),
-      },
       on: {
         askForTopic: {
           target: 'waitingForTopic',
           actions: log("That joke wasn't good enough. Let's try again."),
-          description:
-            'Ask for a new topic, because the last joke rated 6 or lower',
         },
         'agent.endJokes': {
           target: 'end',
           actions: log('That joke was good enough. Goodbye!'),
-          description: 'End the jokes, since the last joke rated 7 or higher',
         },
       },
     },
@@ -222,4 +186,43 @@ const jokeMachine = setup({
 
 const actor = createActor(jokeMachine);
 
+agent.interact(actor, (observed) => {
+  if (observed.state.matches('tellingJoke')) {
+    return {
+      goal: 'Tell me a joke about the topic. Do not make any joke that is not relevant to the topic.',
+      context: {
+        topic: observed.state.context.topic,
+      },
+    };
+  }
+
+  if (observed.state.matches('relevance')) {
+    return {
+      goal: 'An irrelevant joke has no reference to the topic. If the last joke is completely irrelevant to the topic, ask for a new joke topic. Otherwise, continue.',
+      context: {
+        topic: observed.state.context.topic,
+        lastJoke: observed.state.context.jokes.at(-1),
+      },
+    };
+  }
+
+  if (observed.state.matches('rateJoke')) {
+    return {
+      goal: 'Rate the last joke on a scale of 1 to 10.',
+      context: {
+        lastJoke: observed.state.context.jokes.at(-1),
+      },
+    };
+  }
+
+  if (observed.state.matches('decide')) {
+    return {
+      goal: 'Choose what to do next, given the previous rating of the joke.',
+      context: {
+        lastRating: observed.state.context.lastRating,
+      },
+    };
+  }
+});
+
 actor.start();

package/examples/jugs.ts

@@ -0,0 +1,125 @@
+import { createAgent } from '../src';
+import { assign, createActor, setup } from 'xstate';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+import { shortestPathPlanner } from '../src/planners/shortestPathPlanner';
+
+const agent = createAgent({
+  name: 'die-hard-solver',
+  model: openai('gpt-4o'),
+  events: {
+    fill3: z.object({}).describe('Fill the 3-gallon jug'),
+    fill5: z.object({}).describe('Fill the 5-gallon jug'),
+    empty3: z.object({}).describe('Empty the 3-gallon jug'),
+    empty5: z.object({}).describe('Empty the 5-gallon jug'),
+    pour3to5: z
+      .object({
+        reasoning: z
+          .string()
+          .describe(
+            'Very brief reasoning for pouring 3-gallon jug into 5-gallon jug'
+          ),
+      })
+      .describe('Pour the 3-gallon jug into the 5-gallon jug'),
+    pour5to3: z
+      .object({
+        reasoning: z
+          .string()
+          .describe(
+            'Very brief reasoning for pouring 3-gallon jug into 5-gallon jug'
+          ),
+      })
+      .describe('Pour the 5-gallon jug into the 3-gallon jug'),
+  },
+  context: {
+    jug3: z.number().int().describe('Gallons of water in the 3-gallon jug'),
+    jug5: z.number().int().describe('Gallons of water in the 5-gallon jug'),
+  },
+});
+
+const waterJugMachine = setup({
+  types: {
+    context: agent.types.context,
+    events: agent.types.events,
+  },
+}).createMachine({
+  initial: 'solving',
+  context: { jug3: 0, jug5: 0 },
+  states: {
+    solving: {
+      always: {
+        guard: ({ context }) => context.jug5 === 4,
+        target: 'success',
+      },
+      on: {
+        fill3: {
+          actions: assign({ jug3: 3 }),
+        },
+        fill5: {
+          actions: assign({ jug5: 5 }),
+        },
+        empty3: {
+          actions: assign({ jug3: 0 }),
+        },
+        empty5: {
+          actions: assign({ jug5: 0 }),
+        },
+        pour3to5: {
+          actions: assign(({ context }) => {
+            const total = context.jug3 + context.jug5;
+            const newJug5 = Math.min(5, total);
+            return {
+              jug5: newJug5,
+              jug3: total - newJug5,
+            };
+          }),
+        },
+        pour5to3: {
+          actions: assign(({ context }) => {
+            const total = context.jug3 + context.jug5;
+            const newJug3 = Math.min(3, total);
+            return {
+              jug3: newJug3,
+              jug5: total - newJug3,
+            };
+          }),
+        },
+      },
+    },
+    success: {
+      type: 'final',
+    },
+  },
+});
+
+let maxTries = 0;
+async function main() {
+  const waterJugActor = createActor(waterJugMachine).start();
+
+  while (waterJugActor.getSnapshot().value !== 'success') {
+    maxTries++;
+    if (maxTries > 20) {
+      console.log('Max tries reached');
+      throw new Error('Max tries reached');
+    }
+    const decision = await agent.decide({
+      machine: waterJugMachine,
+      goal: 'Get exactly 4 gallons of water in the 5-gallon jug',
+      state: waterJugActor.getSnapshot(),
+      planner: shortestPathPlanner,
+    });
+
+    console.log(decision?.nextEvent);
+
+    if (decision?.nextEvent) {
+      waterJugActor.send(decision.nextEvent);
+      console.log(waterJugActor.getSnapshot().context);
+    } else {
+      console.log('No decision made');
+    }
+  }
+
+  console.log('Done');
+}
+
+main();

package/examples/multi.ts

@@ -1,12 +1,12 @@
 import { createAgent, fromDecision } from '../src';
 import { z } from 'zod';
 import { assign, createActor, log, setup } from 'xstate';
-import { getFromTerminal } from './helpers/helpers';
+import { fromTerminal } from './helpers/helpers';
 import { openai } from '@ai-sdk/openai';
 
 const agent = createAgent({
   name: 'multi',
-  model: openai('gpt-4-1106-preview'),
+  model: openai('gpt-4o-mini'),
   events: {
     'agent.respond': z.object({
       response: z.string().describe('The response from the agent'),
@@ -22,7 +22,7 @@ const machine = setup({
     },
   },
   actors: {
-    getFromTerminal,
+    getFromTerminal: fromTerminal,
     agent: fromDecision(agent),
   },
 }).createMachine({
@@ -69,7 +69,7 @@ const machine = setup({
       invoke: {
         src: 'agent',
         input: ({ context }) => ({
-          model: openai('gpt-3.5-turbo-16k-0613'),
+          model: openai('gpt-4-turbo'),
           context,
           goal: 'Debate the topic, and take the negative position. Respond directly to the last message of the discourse. Keep it short.',
         }),

package/examples/newspaper.ts

@@ -2,10 +2,13 @@
 // https://github.com/assafelovic/gpt-newspaper
 // https://gist.github.com/TheGreatBonnie/58dc21ebbeeb8cbb08df665db762738c
 
-import { TavilySearchAPIRetriever } from '@langchain/community/retrievers/tavily_search_api';
-import { ChatOpenAI } from '@langchain/openai';
-import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { tavily } from '@tavily/core';
+
 import { assign, createActor, fromPromise, setup } from 'xstate';
+import { createAgent } from '../src';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+import { generateObject, generateText } from 'ai';
 
 interface AgentState {
   topic: string;
@@ -15,58 +18,41 @@ interface AgentState {
   revisionCount: number;
 }
 
-function model() {
-  return new ChatOpenAI({
-    temperature: 0,
-    modelName: 'gpt-4-1106-preview',
-    openAIApiKey: process.env.OPENAI_API_KEY,
-  });
-}
+const agent = createAgent({
+  model: openai('gpt-4o-mini'),
+  events: {},
+});
 
-async function search({ topic }: Pick<AgentState, 'topic'>): Promise<string> {
-  const retriever = new TavilySearchAPIRetriever({
-    k: 10,
+async function search({
+  topic,
+}: Pick<AgentState, 'topic'>): Promise<string | undefined> {
+  const tvly = tavily({
     apiKey: process.env.TAVILY_API_KEY,
   });
-  // let topic = state.agentState.topic;
-  // must be at least 5 characters long
-  if (topic.length < 5) {
-    topic = 'topic: ' + topic;
-  }
-  const docs = await retriever.invoke(topic);
-  return JSON.stringify(docs);
+  const response = await tvly.search(topic, {});
+
+  return response.answer;
 }
 
 async function curate(
   input: Pick<AgentState, 'topic' | 'searchResults'>
 ): Promise<string> {
-  const response = await model().invoke(
-    [
-      new SystemMessage(
-        `You are a personal newspaper editor. 
-         Your sole task is to return a list of URLs of the 5 most relevant articles for the provided topic or query as a JSON list of strings
-         in this format:
-         {
-          urls: ["url1", "url2", "url3", "url4", "url5"]
-         }
-         .`.replace(/\s+/g, ' ')
-      ),
-      new HumanMessage(
-        `Today's date is ${new Date().toLocaleDateString('en-GB')}.
-       Topic or Query: ${input.topic}
-       
-       Here is a list of articles:
-       ${input.searchResults}`.replace(/\s+/g, ' ')
-      ),
-    ],
-    {
-      response_format: {
-        type: 'json_object',
-      },
-    }
-  );
-  const urls = JSON.parse(response.content as string).urls;
-  const searchResults = JSON.parse(input.searchResults!);
+  const response = await generateObject({
+    model: agent.model,
+    system: `
+You are a personal newspaper editor. 
+Your sole task is to return a list of URLs of the 5 most relevant articles for the provided topic or query as a JSON list of strings.`.trim(),
+    prompt: `Today's date is ${new Date().toLocaleDateString('en-GB')}
+Topic or Query: ${input.topic}
+
+Here is a list of articles:
+${input.searchResults}`.trim(),
+    schema: z.object({
+      urls: z.array(z.string()).describe('The URLs of the articles'),
+    }),
+  });
+  const urls = response.object.urls;
+  const searchResults = JSON.parse(input.searchResults ?? '[]');
   const newSearchResults = searchResults.filter((result: any) => {
     return urls.includes(result.metadata.source);
   });
@@ -78,29 +64,36 @@ async function critique(
 ): Promise<string | undefined> {
   let feedbackInstructions = '';
   if (input.critique) {
-    feedbackInstructions =
-      `The writer has revised the article based on your previous critique: ${input.critique}
-       The writer might have left feedback for you encoded between <FEEDBACK> tags.
-       The feedback is only for you to see and will be removed from the final article.
-    `.replace(/\s+/g, ' ');
+    feedbackInstructions = `
+        The writer has revised the article based on your previous critique: ${input.critique}
+        The writer might have left feedback for you encoded between <FEEDBACK> tags.
+        The feedback is only for you to see and will be removed from the final article.
+      `.trim();
   }
-  const response = await model().invoke([
-    new SystemMessage(
-      `You are a personal newspaper writing critique. Your sole purpose is to provide short feedback on a written 
-      article so the writer will know what to fix.       
-      Today's date is ${new Date().toLocaleDateString('en-GB')}
-      Your task is to provide a really short feedback on the article only if necessary.
-      if you think the article is good, please return [DONE].
-      you can provide feedback on the revised article or just
-      return [DONE] if you think the article is good.
-      Please return a string of your critique or [DONE].`.replace(/\s+/g, ' ')
-    ),
-    new HumanMessage(
-      `${feedbackInstructions}
-       This is the article: ${input.article}`
-    ),
-  ]);
-  const content = response.content as string;
+
+  const response = await generateObject({
+    model: agent.model,
+    system: `
+  You are a personal newspaper writing critique. 
+  Your sole purpose is to provide short feedback on a written article so the writer will know what to fix.
+  Today's date is ${new Date().toLocaleDateString('en-GB')}
+  Your task is to provide a really short feedback on the article only if necessary.
+  If you think the article is good, please return [DONE].
+  You can provide feedback on the revised article or just return [DONE] if you think the article is good.
+  Please return a string of your critique or [DONE].`.trim(),
+    prompt: `
+  ${feedbackInstructions}
+  This is the article: ${input.article}`.trim(),
+    schema: z.object({
+      critique: z
+        .string()
+        .describe(
+          'The critique of the article or [DONE] if no changes are needed'
+        ),
+    }),
+  });
+
+  const content = response.object.critique;
   console.log('critique:', content);
   return content.includes('[DONE]') ? undefined : content;
 }
@@ -108,48 +101,55 @@ async function critique(
 async function write(
   input: Pick<AgentState, 'searchResults' | 'topic'>
 ): Promise<string> {
-  const response = await model().invoke([
-    new SystemMessage(
+  const response = await generateObject({
+    model: agent.model,
+    system:
       `You are a personal newspaper writer. Your sole purpose is to write a well-written article about a 
-      topic using a list of articles. Write 5 paragraphs in markdown.`.replace(
-        /\s+/g,
-        ' '
-      )
-    ),
-    new HumanMessage(
-      `Today's date is ${new Date().toLocaleDateString('en-GB')}.
-      Your task is to write a critically acclaimed article for me about the provided query or 
-      topic based on the sources. 
-      Here is a list of articles: ${input.searchResults}
-      This is the topic: ${input.topic}
-      Please return a well-written article based on the provided information.`.replace(
+        topic using a list of articles. Write 5 paragraphs in markdown.`.replace(
         /\s+/g,
         ' '
-      )
+      ),
+    prompt: `Today's date is ${new Date().toLocaleDateString('en-GB')}.
+        Your task is to write a critically acclaimed article for me about the provided query or 
+        topic based on the sources. 
+        Here is a list of articles: ${input.searchResults}
+        This is the topic: ${input.topic}
+        Please return a well-written article based on the provided information.`.replace(
+      /\s+/g,
+      ' '
     ),
-  ]);
-  const content = response.content as string;
+    schema: z.object({
+      article: z
+        .string()
+        .describe('The well-written article based on the provided information'),
+    }),
+  });
+
+  const content = response.object.article;
   return content;
 }
-
 async function revise(
   input: Pick<AgentState, 'article' | 'critique'>
 ): Promise<string> {
-  const response = await model().invoke([
-    new SystemMessage(
+  const response = await generateObject({
+    model: agent.model,
+    system:
       `You are a personal newspaper editor. Your sole purpose is to edit a well-written article about a 
-      topic based on given critique.`.replace(/\s+/g, ' ')
-    ),
-    new HumanMessage(
-      `Your task is to edit the article based on the critique given.
+      topic based on given critique.`.replace(/\s+/g, ' '),
+    prompt: `Your task is to edit the article based on the critique given.
       This is the article: ${input.article}
       This is the critique: ${input.critique}
       Please return the edited article based on the critique given.
       You may leave feedback about the critique encoded between <FEEDBACK> tags like this:
-      <FEEDBACK> here goes the feedback ...</FEEDBACK>`.replace(/\s+/g, ' ')
-    ),
-  ]);
-  const content = response.content as string;
+      <FEEDBACK> here goes the feedback ...</FEEDBACK>`.replace(/\s+/g, ' '),
+    schema: z.object({
+      article: z
+        .string()
+        .describe('The edited article based on the critique given'),
+    }),
+  });
+
+  const content = response.object.article;
   return content;
 }
 
@@ -284,13 +284,7 @@ const machine = setup({
   output: ({ context }) => context.article,
 });
 
-const actor = createActor(machine, {
-  // inspect: (inspEv) => {
-  //   if (inspEv.type === '@xstate.event') {
-  //     console.log(JSON.stringify(inspEv.event, null, 2));
-  //   }
-  // },
-});
+const actor = createActor(machine);
 
 actor.subscribe({
   next: (s) => {

package/examples/number.ts

@@ -2,13 +2,14 @@ import { createAgent, fromDecision } from '../src';
 import { assign, createActor, log, setup } from 'xstate';
 import { z } from 'zod';
 import { openai } from '@ai-sdk/openai';
-import { getFromTerminal } from './helpers/helpers';
+import { fromTerminal } from './helpers/helpers';
 
 const agent = createAgent({
   name: 'number-guesser',
   model: openai('gpt-3.5-turbo-1106'),
   events: {
     'agent.guess': z.object({
+      reasoning: z.string().describe('The reasoning for the guess'),
       number: z.number().min(1).max(10).describe('The number guessed'),
     }),
   },
@@ -24,7 +25,7 @@ const machine = setup({
   },
   actors: {
     agent: fromDecision(agent),
-    getFromTerminal,
+    getFromTerminal: fromTerminal,
   },
 }).createMachine({
   context: {
@@ -39,7 +40,7 @@ const machine = setup({
         input: 'Enter a number between 1 and 10',
         onDone: {
           actions: assign({
-            answer: (x) => +x.event.output,
+            answer: ({ event }) => +event.output,
           }),
           target: 'guessing',
         },
@@ -78,7 +79,7 @@ const machine = setup({
                 event.number,
               ],
             }),
-            log((x) => x.event.number),
+            log(({ event }) => `${event.number} (${event.reasoning})`),
           ],
           target: 'guessing',
           reenter: true,