@convex-dev/agent 0.0.15-alpha.2 → 0.0.16-alpha.0

package/README.md

@@ -135,7 +135,8 @@ 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!";
       },
     }),
@@ -230,6 +231,30 @@ export const continueThread = action({
 });
 ```
 
+### Sending a message with configurable message history context
+
+You can customize what history is included per-message via `contextOptions`.
+See the [configuring the agent](#configuring-the-agent) section for details.
+
+```ts
+const result = await thread.generateText({ prompt }, { contextOptions });
+```
+
+### 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.
+
+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 });
+```
+
 ### Creating a tool with Convex context
 
 There are two ways to create a tool that has access to the Convex context.
@@ -275,6 +300,71 @@ 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 CoreMessages (e.g. `{ role, content }`) 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
+const coreMessages = 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 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.
@@ -334,14 +424,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
 
@@ -349,26 +432,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.