@statelyai/agent 0.0.4 → 0.0.6

package/.vscode/launch.json

@@ -1,17 +1,17 @@
 {
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
     {
       "type": "node",
       "request": "launch",
-      "name": "Launch Program",
-      "skipFiles": ["<node_internals>/**"],
-      "program": "${file}",
-      "preLaunchTask": "tsc: build - tsconfig.json",
-      "outFiles": ["${workspaceFolder}/**/*.js"]
+      "name": "Debug Current Test File",
+      "autoAttachChildProcesses": true,
+      "skipFiles": ["<node_internals>/**", "**/node_modules/**"],
+      "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
+      "args": ["run", "${relativeFile}"],
+      "smartStep": true,
+      "console": "integratedTerminal"
     }
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @statelyai/agent
 
+## 0.0.6
+
+### Patch Changes
+
+- [#16](https://github.com/statelyai/agent/pull/16) [`3ba5fb2`](https://github.com/statelyai/agent/commit/3ba5fb2392b51dee71f2585ed662b4ee9ecd6c41) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Update to XState 5.8.0
+
+## 0.0.5
+
+### Patch Changes
+
+- [#9](https://github.com/statelyai/agent/pull/9) [`d8e7b67`](https://github.com/statelyai/agent/commit/d8e7b673f6d265f37b2096b25d75310845860271) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Add `adapter.fromTool(…)`, which creates an actor that chooses agent logic based on a input.
+
+  ```ts
+  const actor = adapter.fromTool(() => "Draw me a picture of a donut", {
+    // tools
+    makeIllustration: {
+      description: "Makes an illustration",
+      run: async (input) => {
+        /* ... */
+      },
+      inputSchema: {
+        /* ... */
+      },
+    },
+    getWeather: {
+      description: "Gets the weather",
+      run: async (input) => {
+        /* ... */
+      },
+      inputSchema: {
+        /* ... */
+      },
+    },
+  });
+
+  //...
+  ```
+
 ## 0.0.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { Prop, Values, AnyStateMachine, createActor, PromiseActorLogic, AnyEvent
 import { JSONSchema7 } from 'json-schema-to-ts/lib/types/definitions';
 import { FromSchema } from 'json-schema-to-ts';
 import OpenAI from 'openai';
-import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
-import { ChatCompletionCreateParamsBase, ChatCompletionCreateParamsStreaming } from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from 'openai/resources';
 
 type EventSchemas = {
     [key: string]: {
@@ -14,67 +14,80 @@ type EventSchemas = {
         };
     };
 };
-interface ContextSchema {
-    [key: string]: JSONSchema7;
-}
+type ContextSchema = JSONSchema7 & {
+    type: 'object';
+};
 type ConvertToJSONSchemas<T> = {
     [K in keyof T]: {
         properties: {
             type: {
                 const: K;
             };
-        };
+        } & Prop<T[K], 'properties'>;
         type: 'object';
-        required: Array<keyof Prop<T[K], 'properties'> | 'type'>;
+        required: Array<(keyof Prop<T[K], 'properties'> & string) | 'type'>;
         additionalProperties: false;
-    } & T[K];
+    };
 } & {};
-type ConvertContextToJSONSchema<T extends ContextSchema> = {
-    type: 'object';
-    properties: T;
-    readonly required: Array<keyof T & string>;
-    additionalProperties: false;
-};
 
-declare function createSchemas<TContextSchema extends ContextSchema, TEventSchemas extends EventSchemas>({ context, events, }: {
+declare function createSchemas<const TContextSchema extends ContextSchema, const TEventSchemas extends EventSchemas>({ context, events, }: {
+    /**
+     * The JSON schema for the context object.
+     *
+     * Must be of `{ type: 'object' }`.
+     */
     context: TContextSchema;
+    /**
+     * An object mapping event types to each event object's JSON Schema.
+     */
     events: TEventSchemas;
 }): {
-    context: ConvertContextToJSONSchema<TContextSchema>;
+    context: TContextSchema;
     events: ConvertToJSONSchemas<TEventSchemas>;
     types: {
-        context: FromSchema<ConvertContextToJSONSchema<TContextSchema>>;
+        context: FromSchema<TContextSchema>;
         events: FromSchema<Values<ConvertToJSONSchemas<TEventSchemas>>>;
     };
 };
 
 declare function createAgent<T extends AnyStateMachine>(...args: Parameters<typeof createActor<T>>): xstate.Actor<T>;
 
-interface OpenAIAdapterOutput<T extends {
-    model: ChatCompletionCreateParamsBase['model'];
-}> {
-    model: T['model'];
+interface StatelyAgentAdapter {
+    model: string;
     /**
-     * Determines which event to send to the parent state machine actor based on the prompt.
+     * Creates actor logic that chooses an event from all of the
+     * possible next events of the parent state machine
+     * and sends it to the parent actor.
      */
-    fromEventChoice: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, options?: {
-        /**
-         * Immediately execute sending the event to the parent actor.
-         * @default true
-         */
-        execute?: boolean;
-    }) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+    fromEvent: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
     /**
-     * Creates promise actor logic that resolves with a chat completion.
+     * Creates actor logic that resolves with a chat completion.
      */
     fromChat: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
     /**
-     * Creates observable actor logic that emits a chat completion stream.
+     * Creates actor logic that emits a chat completion stream.
      */
     fromChatStream: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming) => ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
+    /**
+     * Creates actor logic that chooses a tool from the provided
+     * tools and runs that tool.
+     */
+    fromTool: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, tools: {
+        [key: string]: Tool<any, any>;
+    }) => PromiseActorLogic<{
+        result: any;
+        tool: string;
+        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+    } | undefined, TInput>;
 }
+interface Tool<TInput, TOutput> {
+    description: string;
+    inputSchema: any;
+    run: (input: TInput) => TOutput;
+}
+
 declare function createOpenAIAdapter<T extends {
     model: ChatCompletionCreateParamsBase['model'];
-}>(openai: OpenAI, settings: T): OpenAIAdapterOutput<T>;
+}>(openai: OpenAI, settings: T): StatelyAgentAdapter;
 
 export { createAgent, createOpenAIAdapter, createSchemas };

package/dist/index.js

@@ -57,12 +57,7 @@ function createSchemas({
   events
 }) {
   return {
-    context: {
-      type: "object",
-      properties: context,
-      additionalProperties: false,
-      required: Object.keys(context)
-    },
+    context,
     events: createEventSchemas(events),
     types: {}
   };
@@ -134,7 +129,7 @@ function fromChatStream(openai, agentSettings, inputFn) {
     }
   );
 }
-function fromEventChoice(openai, agentSettings, inputFn, options) {
+function fromEvent(openai, agentSettings, inputFn) {
   return (0, import_xstate2.fromPromise)(
     async ({ input, self, system }) => {
       const parentSnapshot = self._parent?.getSnapshot();
@@ -177,32 +172,70 @@ function fromEventChoice(openai, agentSettings, inputFn, options) {
         tools
       });
       const toolCalls = completion.choices[0]?.message.tool_calls;
-      if (toolCalls) {
+      if (toolCalls?.length) {
         const events = toolCalls.map((tc) => {
           return {
             type: functionNameMapping[tc.function.name],
             ...JSON.parse(tc.function.arguments)
           };
         });
-        if (options?.execute) {
-          events.forEach((event) => {
-            system._relay(self, self._parent, event);
-          });
-        }
+        const event = events[0];
+        system._relay(self, self._parent, event);
       }
       return void 0;
     }
   );
 }
+function fromTool(openai, agentSettings, tools, inputFn) {
+  return (0, import_xstate2.fromPromise)(async ({ input }) => {
+    const resolvedTools = Object.entries(tools).map(([key, value]) => {
+      return {
+        type: "function",
+        function: {
+          name: key,
+          description: value.description,
+          parameters: value.inputSchema
+        }
+      };
+    });
+    const openAiInput = inputFn(input);
+    const completionParams = typeof openAiInput === "string" ? {
+      model: agentSettings.model,
+      messages: [
+        {
+          role: "user",
+          content: openAiInput
+        }
+      ]
+    } : openAiInput;
+    const completion = await openai.chat.completions.create({
+      ...completionParams,
+      tools: resolvedTools
+    });
+    const toolCalls = completion.choices[0]?.message.tool_calls;
+    if (toolCalls?.length) {
+      const toolCall = toolCalls[0];
+      const tool = tools[toolCall.function.name];
+      const args = JSON.parse(toolCall.function.arguments);
+      if (tool) {
+        const result = await tool.run(args);
+        return {
+          toolCall,
+          tool: toolCall.function.name,
+          result
+        };
+      }
+    }
+    return void 0;
+  });
+}
 function createOpenAIAdapter(openai, settings) {
   const agentSettings = {
     model: settings.model,
-    fromEventChoice: (input) => (
-      // @ts-ignore infinitely deep
-      fromEventChoice(openai, agentSettings, input, { execute: true })
-    ),
+    fromEvent: (input) => fromEvent(openai, agentSettings, input),
     fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
-    fromChatStream: (input) => fromChatStream(openai, agentSettings, input)
+    fromChatStream: (input) => fromChatStream(openai, agentSettings, input),
+    fromTool: (input, tools) => fromTool(openai, agentSettings, tools, input)
   };
   return agentSettings;
 }

package/examples/joke.ts

@@ -9,15 +9,19 @@ const openai = new OpenAI({
 
 const schemas = createSchemas({
   context: {
-    topic: { type: 'string' },
-    jokes: {
-      type: 'array',
-      items: {
-        type: 'string',
+    type: 'object',
+    properties: {
+      topic: { type: 'string' },
+      jokes: {
+        type: 'array',
+        items: {
+          type: 'string',
+        },
       },
+      desire: { type: ['string', 'null'] },
+      lastRating: { type: ['string', 'null'] },
     },
-    desire: { type: ['string', 'null'] as const },
-    lastRating: { type: ['string', 'null'] as const },
+    required: ['topic', 'jokes', 'desire', 'lastRating'],
   },
   events: {
     askForTopic: {
@@ -61,7 +65,7 @@ const getTopic = fromPromise(async () => {
   return topic;
 });
 
-const decide = adapter.fromEventChoice(
+const decide = adapter.fromEvent(
   (lastRating: string) =>
     `Choose what to do next, given the previous rating of the joke: ${lastRating}`
 );

package/examples/numberGuesser.ts

@@ -0,0 +1,128 @@
+import OpenAI from 'openai';
+import { createAgent, createOpenAIAdapter, createSchemas } from '../src';
+import { assign, setup } from 'xstate';
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const adapter = createOpenAIAdapter(openai, {
+  model: 'gpt-3.5-turbo-1106',
+});
+
+const guessLogic = adapter.fromEvent(
+  ({
+    previousGuesses,
+    lastResult,
+  }: {
+    previousGuesses: number[];
+    lastResult: string;
+  }) => `
+  Guess the number between 1 and 10. The previous guesses were ${
+    previousGuesses.length ? previousGuesses.join(', ') : 'not made yet'
+  } and the last result was ${lastResult}.
+`
+);
+
+const schemas = createSchemas({
+  context: {
+    type: 'object',
+    properties: {
+      lastGuess: {
+        type: ['number', 'null'],
+        description: 'The last guess',
+      },
+      previousGuesses: {
+        type: 'array',
+        items: {
+          type: 'number',
+        },
+        description: 'The previous guesses',
+      },
+      answer: {
+        type: 'number',
+        description: 'The answer',
+      },
+    },
+  },
+  events: {
+    guess: {
+      properties: {
+        number: {
+          // integer
+          type: 'number',
+          minimum: 1,
+          maximum: 10,
+        },
+      },
+      required: ['number'],
+    },
+  },
+});
+
+const machine = setup({
+  types: {
+    context: {} as {
+      previousGuesses: number[];
+      answer: number;
+    },
+    input: {} as { answer: number },
+    events: schemas.types.events,
+  },
+  schemas,
+  actors: {
+    guessLogic,
+  },
+}).createMachine({
+  context: ({ input }) => ({
+    answer: input.answer,
+    previousGuesses: [],
+  }),
+  initial: 'guessing',
+  states: {
+    guessing: {
+      always: {
+        guard: ({ context }) =>
+          context.answer === context.previousGuesses.at(-1),
+        target: 'winner',
+      },
+      invoke: {
+        src: 'guessLogic',
+        input: ({ context }) => ({
+          previousGuesses: context.previousGuesses,
+          lastResult:
+            context.previousGuesses.length === 0
+              ? 'not given yet'
+              : context.previousGuesses.at(-1)! - context.answer > 0
+              ? 'too high'
+              : 'too low',
+        }),
+      },
+      on: {
+        guess: {
+          actions: assign({
+            previousGuesses: ({ context, event }) => [
+              ...context.previousGuesses,
+              event.number,
+            ],
+          }),
+          target: 'guessing',
+          reenter: true,
+        },
+      },
+    },
+    winner: {
+      type: 'final',
+    },
+  },
+});
+
+const agent = createAgent(machine, {
+  input: { answer: 4 },
+  inspect: (ev) => {
+    if (ev.type === '@xstate.event') {
+      console.log(ev.event);
+    }
+  },
+});
+
+agent.start();

package/examples/ticTacToe.ts

@@ -10,36 +10,40 @@ type Player = 'x' | 'o';
 
 const schemas = createSchemas({
   context: {
-    board: {
-      type: 'array',
-      items: {
-        type: ['null', 'string'],
-        enum: [null, 'x', 'o'],
+    type: 'object',
+    properties: {
+      board: {
+        type: 'array',
+        items: {
+          type: ['null', 'string'],
+          enum: [null, 'x', 'o'],
+        },
+        minItems: 9,
+        maxItems: 9,
+        description: 'The board of the tic-tac-toe game',
       },
-      minItems: 9,
-      maxItems: 9,
-      description: 'The board of the tic-tac-toe game',
-    },
-    moves: {
-      type: 'number',
-      description: 'The number of moves that have been played',
-    },
-    player: {
-      type: 'string',
-      enum: ['x', 'o'],
-      description: 'The player whose turn it is',
-    },
-    gameReport: {
-      type: 'string',
-      description: 'The game report',
-    },
-    events: {
-      type: 'array',
-      items: {
+      moves: {
+        type: 'number',
+        description: 'The number of moves that have been played',
+      },
+      player: {
         type: 'string',
+        enum: ['x', 'o'],
+        description: 'The player whose turn it is',
+      },
+      gameReport: {
+        type: 'string',
+        description: 'The game report',
+      },
+      events: {
+        type: 'array',
+        items: {
+          type: 'string',
+        },
       },
     },
-  } as const,
+    required: ['board', 'moves', 'player', 'gameReport', 'events'],
+  },
   events: {
     'x.play': {
       properties: {
@@ -80,7 +84,7 @@ const initialContext = {
   events: [],
 } satisfies typeof schemas.types.context;
 
-const bot = adapter.fromEventChoice(
+const bot = adapter.fromEvent(
   ({ context }: { context: typeof schemas.types.context }) => `
 You are playing a game of tic tac toe. This is the current game state. The 3x3 board is represented by a 9-element array. The first element is the top-left cell, the second element is the top-middle cell, the third element is the top-right cell, the fourth element is the middle-left cell, and so on. The value of each cell is either null, x, or o. The value of null means that the cell is empty. The value of x means that the cell is occupied by an x. The value of o means that the cell is occupied by an o.
 

package/examples/weather.ts

@@ -84,7 +84,7 @@ const machine = setup({
   types: schemas.types,
   actors: {
     getWeather,
-    decide: adapter.fromEventChoice(
+    decide: adapter.fromEvent(
       (input: string) =>
         `Decide what to do based on the given input, which may or may not be a location: ${input}`
     ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -17,19 +17,20 @@
     "openai": "^4.24.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "xstate": "^5.6.0"
+    "xstate": "^5.8.0"
   },
   "packageManager": "pnpm@8.11.0",
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc",
-    "test": "vitest run",
+    "test": "vitest",
     "example": "ts-node examples/helpers/runner.ts",
     "changeset": "changeset",
     "release": "changeset publish",

package/readme.md

@@ -1,13 +1,14 @@
 # Stately Agent (alpha)
 
-🚧 Documentation in progress! Please see [the examples directory](https://github.com/statelyai/agent/tree/main/examples) for working examples.
+- Read [the documentation](https://stately.ai/docs/agents)
+- See [the examples directory](https://github.com/statelyai/agent/tree/main/examples) for working examples.
 
 ## Installation
 
 Install `openai`, and `@statelyai/agent`:
 
 ```bash
-npm install openai @statelyai/agent
+pnpm install openai @statelyai/agent
 ```
 
 ## Usage
@@ -35,7 +36,7 @@ OPENAI_API_KEY="your-openai-api-key"
 Then, install the dependencies (`npm install`) and run the examples:
 
 ```bash
-npm run example joke
+pnpm run example joke
 # or:
-# npm run example ticTacToe
+# pnpm run example ticTacToe
 ```

package/src/adapter.test.ts

@@ -0,0 +1,217 @@
+import { test, expect } from 'vitest';
+import { createOpenAIAdapter, createTool } from './adapters/openai';
+import OpenAI from 'openai';
+import { createActor, toPromise } from 'xstate';
+
+test('fromTool - weather or illustration', async () => {
+  const openAi = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  const adapter = createOpenAIAdapter(openAi, {
+    model: 'gpt-3.5-turbo',
+  });
+
+  const toolChoice = adapter.fromTool(() => 'Create an image of a donut', {
+    makeIllustration: {
+      description: 'Make an illustration',
+      run: async () => 'Illustration',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'The name of the illustration',
+          },
+        },
+        required: ['name'],
+      },
+    },
+    getWeather: {
+      description: 'Get the weather for a location',
+      run: async () => 'Weather',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'object',
+            properties: {
+              city: {
+                type: 'string',
+                description: 'The name of the city',
+              },
+              state: {
+                type: 'string',
+                description: 'The name of the state',
+              },
+            },
+            required: ['city', 'state'],
+          },
+        },
+        required: ['location'],
+      },
+    },
+  });
+
+  const actor = createActor(toolChoice);
+
+  actor.start();
+
+  const res = await toPromise(actor);
+
+  expect(res?.result).toBe('Illustration');
+});
+
+test('fromTool - GitHub PR description inserter', async () => {
+  const openAi = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  const adapter = createOpenAIAdapter(openAi, {
+    model: 'gpt-3.5-turbo-16k-0613',
+  });
+
+  const toolChoice = adapter.fromTool(
+    (input: string) =>
+      `Create a GitHub PR description for the following: ${input}`,
+    {
+      fetchGitHubPR: {
+        description: 'Fetch a GitHub PR',
+        run: async (input: string) => {
+          return {
+            title: 'Title',
+            body: input,
+          };
+        },
+        inputSchema: {
+          type: 'object',
+          properties: {
+            repo: {
+              type: 'string',
+              description: 'The name of the repo',
+            },
+            number: {
+              type: 'number',
+              description: 'The number of the PR',
+            },
+          },
+          required: ['repo', 'number'],
+        },
+      },
+      createPullRequestDescription: {
+        description: 'Create a GitHub PR description',
+        run: () => 'Description',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: {
+              type: 'string',
+              description: 'The title of the PR',
+            },
+            body: {
+              type: 'string',
+              description: 'The body of the PR',
+            },
+          },
+          required: ['title', 'body'],
+        },
+      },
+    }
+  );
+
+  const actor = createActor(toolChoice, {
+    input:
+      // 'Get the details from this: https://github.com/microsoft/TypeScript/pull/47198',
+      'Make a summary of this PR: (some code here)',
+  });
+
+  actor.start();
+
+  const res = await toPromise(actor);
+
+  expect(res?.tool).toEqual('createPullRequestDescription');
+  expect(res?.result).toEqual('Description');
+});
+
+test('fromTool - joke creator or rater', async () => {
+  const openAi = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  const adapter = createOpenAIAdapter(openAi, {
+    model: 'gpt-4-1106-preview',
+  });
+
+  const rateJoke = createTool({
+    description: 'Rate a joke',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        joke: {
+          type: 'string',
+          description: 'The joke to rate',
+        },
+      },
+    },
+    run: async ({ topic }: { topic: string }) => {
+      return `Here is a joke about ${topic}`;
+    },
+  });
+
+  const createJoke = createTool({
+    description: 'Create a joke',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: {
+          type: 'string',
+          description: 'The category of the joke',
+        },
+      },
+      required: ['category'],
+    },
+    run: async () => {
+      return 'Some joke';
+    },
+  });
+
+  const toolChoice = adapter.fromTool(
+    (input: string) => `
+The user provided this input:
+
+<input>
+${input}
+</input>
+
+Determine what to do:
+- If the input is asking for a joke, create a joke,
+- But if the input is providing a joke, then rate the joke.
+    `,
+    {
+      rateJoke,
+      createJoke,
+    }
+  );
+
+  const actor = createActor(toolChoice, {
+    // input: 'Why did the chicken cross the road? To get to the other side!',
+    input: 'Tell me a joke about chickens',
+  });
+
+  actor.start();
+
+  const res = await toPromise(actor);
+
+  expect(res?.tool).toEqual('createJoke');
+  expect(res?.result).toEqual('Some joke');
+
+  const actor2 = createActor(toolChoice, {
+    input:
+      'Check this joke out: Why did the chicken cross the road? To get to the other side!',
+  });
+
+  actor2.start();
+
+  const res2 = await toPromise(actor2);
+  expect(res2?.tool).toEqual('rateJoke');
+});

package/src/adapters/openai.ts

@@ -1,9 +1,7 @@
 import type OpenAI from 'openai';
 import {
   AnyEventObject,
-  ObservableActorLogic,
   Observer,
-  PromiseActorLogic,
   fromObservable,
   fromPromise,
   isMachineSnapshot,
@@ -11,10 +9,8 @@ import {
 } from 'xstate';
 import { getAllTransitions } from '../utils';
 import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
-import {
-  ChatCompletionCreateParamsBase,
-  ChatCompletionCreateParamsStreaming,
-} from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
+import { StatelyAgentAdapter, Tool } from '../types';
 
 /**
  * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that uses the OpenAI API to generate a completion.
@@ -25,7 +21,7 @@ import {
  */
 export function fromChatCompletion<TInput>(
   openai: OpenAI,
-  agentSettings: OpenAIAdapterOutput<any>,
+  agentSettings: StatelyAgentAdapter,
   inputFn: (
     input: TInput
   ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
@@ -60,7 +56,7 @@ export function fromChatCompletion<TInput>(
  */
 export function fromChatStream<TInput>(
   openai: OpenAI,
-  agentSettings: OpenAIAdapterOutput<any>,
+  agentSettings: StatelyAgentAdapter,
   inputFn: (
     input: TInput
   ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming
@@ -117,19 +113,12 @@ export function fromChatStream<TInput>(
  * @param openai The OpenAI instance to use.
  * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
  */
-export function fromEventChoice<TInput>(
+export function fromEvent<TInput>(
   openai: OpenAI,
-  agentSettings: OpenAIAdapterOutput<any>,
+  agentSettings: StatelyAgentAdapter,
   inputFn: (
     input: TInput
-  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming,
-  options?: {
-    /**
-     * Immediately execute sending the event to the parent actor.
-     * @default false
-     */
-    execute?: boolean;
-  }
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
 ) {
   return fromPromise<AnyEventObject[] | undefined, TInput>(
     async ({ input, self, system }) => {
@@ -185,7 +174,7 @@ export function fromEventChoice<TInput>(
 
       const toolCalls = completion.choices[0]?.message.tool_calls;
 
-      if (toolCalls) {
+      if (toolCalls?.length) {
         const events = toolCalls.map((tc) => {
           return {
             type: functionNameMapping[tc.function.name],
@@ -193,12 +182,10 @@ export function fromEventChoice<TInput>(
           };
         });
 
-        if (options?.execute) {
-          events.forEach((event) => {
-            // @ts-ignore
-            system._relay(self, self._parent, event);
-          });
-        }
+        const event = events[0]!;
+
+        // @ts-ignore
+        system._relay(self, self._parent, event);
       }
 
       return undefined;
@@ -206,54 +193,105 @@ export function fromEventChoice<TInput>(
   );
 }
 
-interface OpenAIAdapterOutput<
-  T extends {
-    model: ChatCompletionCreateParamsBase['model'];
-  }
-> {
-  model: T['model'];
-  /**
-   * Determines which event to send to the parent state machine actor based on the prompt.
-   */
-  fromEventChoice: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
-    options?: {
-      /**
-       * Immediately execute sending the event to the parent actor.
-       * @default true
-       */
-      execute?: boolean;
-    }
-  ) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
-  /**
-   * Creates promise actor logic that resolves with a chat completion.
-   */
-  fromChat: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
-  ) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
-  /**
-   * Creates observable actor logic that emits a chat completion stream.
-   */
-  fromChatStream: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming
-  ) => ObservableActorLogic<
-    OpenAI.Chat.Completions.ChatCompletionChunk,
+export function createTool<TInput, T>({
+  description,
+  inputSchema,
+  run,
+}: Tool<TInput, T>): Tool<TInput, T> {
+  return {
+    description,
+    inputSchema,
+    run,
+  };
+}
+
+/**
+ * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that passes the next possible transitions as functions to [OpenAI tool calls](https://platform.openai.com/docs/guides/function-calling) and returns an array of potential next events.
+ *
+ * @param openai The OpenAI instance to use.
+ * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
+ */
+export function fromTool<TInput>(
+  openai: OpenAI,
+  agentSettings: StatelyAgentAdapter,
+  tools: {
+    [key: string]: Tool<any, any>;
+  },
+  inputFn: (
+    input: TInput
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
+) {
+  return fromPromise<
+    | {
+        result: any;
+        tool: string;
+        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+      }
+    | undefined,
     TInput
-  >;
+  >(async ({ input }) => {
+    const resolvedTools = Object.entries(tools).map(([key, value]) => {
+      return {
+        type: 'function',
+        function: {
+          name: key,
+          description: value.description,
+          parameters: value.inputSchema,
+        },
+      } as const;
+    });
+
+    const openAiInput = inputFn(input);
+    const completionParams: ChatCompletionCreateParamsNonStreaming =
+      typeof openAiInput === 'string'
+        ? {
+            model: agentSettings.model,
+            messages: [
+              {
+                role: 'user',
+                content: openAiInput,
+              },
+            ],
+          }
+        : openAiInput;
+    const completion = await openai.chat.completions.create({
+      ...completionParams,
+      tools: resolvedTools,
+    });
+
+    const toolCalls = completion.choices[0]?.message.tool_calls;
+
+    if (toolCalls?.length) {
+      const toolCall = toolCalls[0]!;
+      const tool = tools[toolCall.function.name];
+      const args = JSON.parse(toolCall.function.arguments);
+
+      if (tool) {
+        const result = await tool.run(args);
+
+        return {
+          toolCall,
+          tool: toolCall.function.name,
+          result,
+        };
+      }
+    }
+
+    return undefined;
+  });
 }
 
 export function createOpenAIAdapter<
   T extends {
     model: ChatCompletionCreateParamsBase['model'];
   }
->(openai: OpenAI, settings: T): OpenAIAdapterOutput<T> {
-  const agentSettings: OpenAIAdapterOutput<T> = {
+>(openai: OpenAI, settings: T): StatelyAgentAdapter {
+  const agentSettings: StatelyAgentAdapter = {
     model: settings.model,
-    fromEventChoice: (input) =>
-      // @ts-ignore infinitely deep
-      fromEventChoice(openai, agentSettings, input, { execute: true }) as any,
+    fromEvent: (input) => fromEvent(openai, agentSettings, input),
     fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
     fromChatStream: (input) => fromChatStream(openai, agentSettings, input),
+    fromTool: (input, tools) => fromTool(openai, agentSettings, tools, input),
   };
 
   return agentSettings;

package/src/schemas.ts

@@ -2,36 +2,38 @@ import { Values } from 'xstate';
 import {
   ContextSchema,
   EventSchemas,
-  ConvertContextToJSONSchema,
   ConvertToJSONSchemas,
   createEventSchemas,
 } from './utils';
 import { FromSchema } from 'json-schema-to-ts';
 
 export function createSchemas<
-  TContextSchema extends ContextSchema,
-  TEventSchemas extends EventSchemas
+  const TContextSchema extends ContextSchema,
+  const TEventSchemas extends EventSchemas
 >({
   context,
   events,
 }: {
+  /**
+   * The JSON schema for the context object.
+   *
+   * Must be of `{ type: 'object' }`.
+   */
   context: TContextSchema;
+  /**
+   * An object mapping event types to each event object's JSON Schema.
+   */
   events: TEventSchemas;
 }): {
-  context: ConvertContextToJSONSchema<TContextSchema>;
+  context: TContextSchema;
   events: ConvertToJSONSchemas<TEventSchemas>;
   types: {
-    context: FromSchema<ConvertContextToJSONSchema<TContextSchema>>;
+    context: FromSchema<TContextSchema>;
     events: FromSchema<Values<ConvertToJSONSchemas<TEventSchemas>>>;
   };
 } {
   return {
-    context: {
-      type: 'object',
-      properties: context,
-      additionalProperties: false,
-      required: Object.keys(context),
-    },
+    context,
     events: createEventSchemas(events),
     types: {} as any,
   };

package/src/types.ts

@@ -0,0 +1,61 @@
+import OpenAI from 'openai';
+import {
+  ChatCompletionCreateParamsNonStreaming,
+  ChatCompletionCreateParamsStreaming,
+} from 'openai/resources';
+import {
+  AnyEventObject,
+  ObservableActorLogic,
+  PromiseActorLogic,
+} from 'xstate';
+
+export interface StatelyAgentAdapter {
+  model: string;
+  /**
+   * Creates actor logic that chooses an event from all of the
+   * possible next events of the parent state machine
+   * and sends it to the parent actor.
+   */
+  fromEvent: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
+  ) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+  /**
+   * Creates actor logic that resolves with a chat completion.
+   */
+  fromChat: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
+  ) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
+  /**
+   * Creates actor logic that emits a chat completion stream.
+   */
+  fromChatStream: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming
+  ) => ObservableActorLogic<
+    OpenAI.Chat.Completions.ChatCompletionChunk,
+    TInput
+  >;
+  /**
+   * Creates actor logic that chooses a tool from the provided
+   * tools and runs that tool.
+   */
+  fromTool: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
+    tools: {
+      [key: string]: Tool<any, any>;
+    }
+  ) => PromiseActorLogic<
+    | {
+        result: any;
+        tool: string;
+        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+      }
+    | undefined,
+    TInput
+  >;
+}
+
+export interface Tool<TInput, TOutput> {
+  description: string;
+  inputSchema: any;
+  run: (input: TInput) => TOutput;
+}

package/src/utils.ts

@@ -20,26 +20,17 @@ export type EventSchemas = {
   };
 };
 
-export interface ContextSchema {
-  [key: string]: JSONSchema7;
-}
+export type ContextSchema = JSONSchema7 & { type: 'object' };
 
 export type ConvertToJSONSchemas<T> = {
   [K in keyof T]: {
-    properties: { type: { const: K } };
+    properties: { type: { const: K } } & Prop<T[K], 'properties'>;
     type: 'object';
-    required: Array<keyof Prop<T[K], 'properties'> | 'type'>;
+    required: Array<(keyof Prop<T[K], 'properties'> & string) | 'type'>;
     additionalProperties: false;
-  } & T[K];
+  };
 } & {};
 
-export type ConvertContextToJSONSchema<T extends ContextSchema> = {
-  type: 'object';
-  properties: T;
-  readonly required: Array<keyof T & string>;
-  additionalProperties: false;
-};
-
 export function createEventSchemas<T extends EventSchemas>(
   eventSchemaMap: T
 ): ConvertToJSONSchemas<T> {

package/vitest.config.ts

@@ -0,0 +1,9 @@
+// vitest.config.ts
+import dotenv from 'dotenv';
+dotenv.config();
+
+export default {
+  test: {
+    testTimeout: 10000, // Global timeout of 10000ms for all tests
+  },
+};