@convex-dev/agent 0.0.16 → 0.0.17-alpha.2

package/README.md

@@ -7,6 +7,7 @@
 AI Agent framework built on Convex.
 
 - Automatic storage of chat history, per-user or per-thread, that can span multiple agents.
+- Playground UI for testing, debugging, and development. See [playground/README.md](playground/README.md) for more.
 - RAG for chat context, via hybrid text & vector search, with configuration options.
   Use the API to query the history yourself and do it your way.
 - Opt-in search for messages from other threads (for the same specified user).
@@ -111,7 +112,7 @@ export default app;
 
 ## Usage
 
-### Configuring the agent
+### Creating the agent
 
 ```ts
 import { tool } from "ai";
@@ -124,8 +125,6 @@ import { components } from "./_generated/api";
 const supportAgent = new Agent(components.agent, {
   // The chat completions model to use for the agent.
   chat: openai.chat("gpt-4o-mini"),
-  // Embedding model to power vector search of message history (RAG).
-  textEmbedding: openai.embedding("text-embedding-3-small"),
   // The default system prompt if not overriden.
   instructions: "You are a helpful assistant.",
   tools: {
@@ -135,57 +134,26 @@ const supportAgent = new Agent(components.agent, {
     myConvexTool: createTool({
       description: "My Convex tool",
       args: z.object({...}),
-      handler: async (ctx, args) => {
+      // Note: annotate the return type of the handler to avoid type cycles.
+      handler: async (ctx, args): Promise<string> => {
         return "Hello, world!";
       },
     }),
   },
-  // Used for fetching context messages. Values shown are the defaults.
-  contextOptions: {
-    // Whether to include tool messages in the context.
-    includeToolCalls: false,
-    // How many recent messages to include. These are added after the search
-    // messages, and do not count against the search limit.
-    recentMessages: 100,
-    // Options for searching messages via text and/or vector search.
-    searchOptions: {
-      limit: 10, // The maximum number of messages to fetch.
-      textSearch: false, // Whether to use text search to find messages.
-      vectorSearch: false, // Whether to use vector search to find messages.
-      // Note, this is after the limit is applied.
-      // E.g. this will quadruple the number of messages fetched.
-      // (two before, and one after each message found in the search)
-      messageRange: { before: 2, after: 1 },
-    },
-    // Whether to search across other threads for relevant messages.
-    // By default, only the current thread is searched.
-    searchOtherThreads: false,
-  },
-  // Used for storing messages.
-  storageOptions: {
-    // When false, allows you to pass in arbitrary context that will
-    // be in addition to automatically fetched content.
-    // Pass true to have all input messages saved to the thread history.
-    saveAllInputMessages: false,
-    // By default it saves the input message, or the last message if multiple are provided.
-    saveAnyInputMessages: true,
-    // Save the generated messages to the thread history.
-    saveOutputMessages: true,
-  },
+  // Embedding model to power vector search of message history (RAG).
+  textEmbedding: openai.embedding("text-embedding-3-small"),
+  // Used for fetching context messages. See [below](#configuring-the-context-of-messages)
+  contextOptions,
+  // Used for storing messages. See [below](#configuring-the-storage-of-messages)
+  storageOptions,
   // Used for limiting the number of steps when tool calls are involved.
+  // NOTE: if you want tool calls to happen automatically with a single call,
+  // you need to set this to something greater than 1 (the default).
   maxSteps: 1,
-  // Used for limiting the number of retries when a tool call fails.
+  // Used for limiting the number of retries when a tool call fails. Default: 3.
   maxRetries: 3,
-  // Used for tracking token usage.
-  usageHandler: async (ctx, args) => {
-    const {
-      // Who used the tokens
-      userId, threadId, agentName,
-      // What LLM was used
-      model, provider,
-      // How many tokens were used (extra info is available in providerMetadata)
-      usage, providerMetadata
-    } = args;
+  // Used for tracking token usage. See [below](#tracking-token-usage)
+  usageHandler: async (ctx, { model, usage }) => {
     // ... log, save usage to your database, etc.
   },
 });
@@ -230,28 +198,87 @@ export const continueThread = action({
 });
 ```
 
-### Sending a message with configurable message history context
+### Generating text
+
+The arguments to `generateText` are the same as the AI SDK, except you don't
+have to provide a model. By default it will use the agent's chat model.
+
+```ts
+const { thread } = await supportAgent.createThread(ctx, { userId });
+const result = await thread.generateText({ prompt });
+```
+
+### Generating an object
+
+Similar to the AI SDK, you can generate or streaman object.
+The same arguments apply, except you don't have to provide a model.
+It will use the agent's default chat model.
+
+```ts
+import { z } from "zod";
+
+const result = await thread.generateObject({
+  prompt: "Generate a plan based on the conversation so far",
+  schema: z.object({...}),
+});
+```
+
+
+### Configuring the context of messages
 
 You can customize what history is included per-message via `contextOptions`.
-See the [configuring the agent](#configuring-the-agent) section for details.
+These options can be provided to the Agent constructor, or per-message.
 
 ```ts
-const result = await thread.generateText({ prompt }, { contextOptions });
+const result = await thread.generateText({ prompt }, {
+  // Values shown are the defaults.
+  contextOptions: {
+    // Whether to include tool messages in the context.
+    includeToolCalls: false,
+    // How many recent messages to include. These are added after the search
+    // messages, and do not count against the search limit.
+    recentMessages: 100,
+    // Options for searching messages via text and/or vector search.
+    searchOptions: {
+      limit: 10, // The maximum number of messages to fetch.
+      textSearch: false, // Whether to use text search to find messages.
+      vectorSearch: false, // Whether to use vector search to find messages.
+      // Note, this is after the limit is applied.
+      // E.g. this will quadruple the number of messages fetched.
+      // (two before, and one after each message found in the search)
+      messageRange: { before: 2, after: 1 },
+    },
+    // Whether to search across other threads for relevant messages.
+    // By default, only the current thread is searched.
+    searchOtherThreads: false,
+  },
 ```
 
 ### Configuring the storage of messages
 
-See the [configuring the agent](#configuring-the-agent) section for details.
 Generally the defaults are fine, but if you want to pass in multiple messages
 and have them all saved (vs. just the last one), or avoid saving any input
-or output messages, you can pass in a `storageOptions` object.
+or output messages, you can pass in a `storageOptions` object, either to the
+Agent constructor or per-message.
 
 The usecase for passing multiple messages is if you want to include some extra
 messages for context to the LLM, but only the last message is the user's actual
 request. e.g. `messages = [...messagesFromRag, messageFromUser]`.
 
 ```ts
-const result = await thread.generateText({ messages }, { storageOptions });
+const result = await thread.generateText({ messages }, {
+  // The default values are shown below.
+  storageOptions: {
+    // When false, allows you to pass in arbitrary context that will
+    // be in addition to automatically fetched content.
+    // Pass true to have all input messages saved to the thread history.
+    saveAllInputMessages: false,
+    // By default it saves the input message, or the last message if multiple are provided.
+    saveAnyInputMessages: true,
+    // Save the generated messages to the thread history.
+    saveOutputMessages: true,
+  },
+});
 ```
 
 ### Creating a tool with Convex context
@@ -299,6 +326,82 @@ Specifying tools at each layer will overwrite the defaults.
 The tools will be `args.tools ?? thread.tools ?? agent.options.tools`.
 This allows you to create tools in a context that is convenient.
 
+### Fetching thread history
+
+Fetch the full messages directly. These will include things like usage, etc.
+
+```ts
+import type { MessageDoc } from "@convex-dev/agent";
+
+const messages: MessageDoc[] = await ctx.runQuery(
+  components.agent.messages.listMessagesByThreadId, {
+    threadId,
+    order: "desc",
+    paginationOpts: { cursor: null, numItems: 10 }
+});
+```
+
+### Search for messages
+
+This is what the agent does automatically, but it can be useful to do manually, e.g. to find custom context to include.
+
+Fetch Messages for a user and/or thread.
+Accepts ContextOptions, e.g. includeToolCalls, searchOptions, etc.
+If you provide a `beforeMessageId`, it will only fetch messages from before that message.
+
+```ts
+import type { MessageDoc } from "@convex-dev/agent";
+
+const messages: MessageDoc[] = await supportAgent.fetchContextMessages(ctx, {
+  threadId, messages: [{ role, content }], contextOptions
+});
+```
+
+### Get and update thread information
+
+List threads for a user:
+
+```ts
+const threads = await ctx.runQuery(components.agent.threads.listThreadsByUserId, {
+  userId,
+  order: "desc",
+  paginationOpts: { cursor: null, numItems: 10 }
+});
+```
+
+Get a thread by id:
+
+```ts
+const thread = await ctx.runQuery(components.agent.threads.getThread, {
+  threadId,
+});
+```
+
+Update a thread's metadata:
+
+```ts
+await ctx.runMutation(components.agent.threads.updateThread, {
+  threadId,
+  { title, summary, status }
+});
+```
+
+## Using the Playground UI
+
+The Playground UI is a simple way to test, debug, and develop with the agent.
+- First configure it with instructions [here](./playground/README.md).
+- Then you can use the [hosted version on GitHub pages](https://get-convex.github.io/agent/)
+or run it locally with `npx @convex-dev/agent-playground`.
+
+[Playground UI Screenshot](./playground/screenshot.png)
+
+## Using the Workflow component for long-lived durable workflows
+
+The [Workflow component](https://convex.dev/components/workflow) is a great way to build long-lived, durable workflows.
+It handles retries and guarantees of eventually completing, surviving server restarts, and more.
+Read more about durable workflows in [this Stack post](https://stack.convex.dev/durable-workflows-and-strong-guarantees).
+
+
 ### Exposing the agent as Convex actions
 
 You can expose the agent as a Convex internal action.
@@ -358,14 +461,7 @@ export const supportAgentWorkflow = workflow.define({
 
 See another example in [example.ts](./example/convex/example.ts#L120).
 
-### Fetching thread history
-
-```ts
-const messages = await ctx.runQuery(
-  components.agent.messages.getThreadMessages,
-  { threadId }
-);
-```
+## Extra control: how to do more things yourself
 
 ### Generating text for a user without an associated thread
 
@@ -373,26 +469,7 @@ const messages = await ctx.runQuery(
 const result = await supportAgent.generateText(ctx, { userId }, { prompt });
 ```
 
-### Manually managing messages
-
-Fetch the full messages directly. These will include things like usage, etc.
-
-```ts
-const messages = await ctx.runQuery(
-  components.agent.messages.getThreadMessages,
-  { threadId, order: "desc", paginationOpts: { cursor: null, numItems: 10 } }
-);
-```
-
-Fetch CoreMessages (e.g. `{ role, content }`) for a user and/or thread.
-Accepts ContextOptions, e.g. includeToolCalls, searchOptions, etc.
-If you provide a parentMessageId, it will only fetch messages from before that message.
-
-```ts
-const coreMessages = await supportAgent.fetchContextMessages(ctx, {
-  threadId, messages: [{ role, content }], contextOptions
-});
-```
+### Saving messages manually
 
 Save messages to the database.
 
@@ -468,27 +545,21 @@ See an example in
 [this demo](https://github.com/ianmacartney/ai-agent-chat/blob/main/convex/chat.ts)
 that captures usage to a table, then scans it to generate per-user invoices.
 
+You can provide a `usageHandler` to the agent, per-thread, or per-message.
+
 ```ts
 const supportAgent = new Agent(components.agent, {
   ...
   usageHandler: async (ctx, args) => {
-    const { userId, threadId, agentName } = args;
-    const { model, provider, usage, providerMetadata } = args;
-    // ... save usage to your database, etc.
-  },
-});
-// or when creating/continuing a thread:
-const { thread } = await supportAgent.createThread(ctx, {
-  ...
-  usageHandler: async (ctx, args) => {
-    // ...
-  },
-});
-// or when generating text:
-const result = await thread.generateText({
-  ...
-  usageHandler: async (ctx, args) => {
-    // ...
+    const {
+      // Who used the tokens
+      userId, threadId, agentName,
+      // What LLM was used
+      model, provider,
+      // How many tokens were used (extra info is available in providerMetadata)
+      usage, providerMetadata
+    } = args;
+    // ... log, save usage to your database, etc.
   },
 });
 ```