@convex-dev/agent 0.0.1-alpha.1 → 0.0.1-alpha.2

package/dist/esm/client/index.d.ts

@@ -1,25 +1,51 @@
 import type { EmbeddingModelV1, LanguageModelV1 } from "@ai-sdk/provider";
-import type { CoreMessage, DeepPartial, GenerateObjectResult, GenerateTextResult, StepResult, StreamObjectResult, StreamTextResult, Tool, ToolChoice, ToolExecutionOptions, ToolSet, Message as UIMessage } from "ai";
+import type { CoreMessage, DeepPartial, GenerateObjectResult, GenerateTextResult, StepResult, StreamObjectResult, StreamTextResult, Tool, ToolChoice, ToolExecutionOptions, ToolSet } from "ai";
 import { generateObject, generateText, streamObject, streamText } from "ai";
-import type { ZodType } from "zod";
 import { api } from "../component/_generated/api";
-import { Message, MessageStatus, SearchOptions } from "../validators";
+import { SearchOptions } from "../validators";
 import { RunActionCtx, RunMutationCtx, RunQueryCtx, UseApi } from "./types";
-import { GenericActionCtx, GenericDataModel } from "convex/server";
+import { ConvexToZod } from "convex-helpers/server/zod";
 import { Infer, Validator } from "convex/values";
 export type ContextOptions = {
-    parentMessageId?: string;
-    includeToolMessages?: boolean;
+    /**
+     * Whether to include tool messages in the context.
+     */
+    includeToolCalls?: boolean;
+    /**
+     * How many recent messages to include. These are added after the search
+     * messages, and do not count against the search limit.
+     */
     recentMessages?: number;
+    /**
+     * Options for searching messages.
+     */
     searchOptions?: {
+        /**
+         * The maximum number of messages to fetch.
+         */
         limit: number;
+        /**
+         * Whether to use text search to find messages.
+         */
         textSearch?: boolean;
+        /**
+         * Whether to use vector search to find messages.
+         */
         vectorSearch?: boolean;
-        messageRange: {
+        /**
+         * Note, this is after the limit is applied.
+         * By default this will quadruple the number of messages fetched.
+         * (two before, and one after each message found in the search)
+         */
+        messageRange?: {
             before: number;
             after: number;
         };
     };
+    /**
+     * Whether to search across other chats for relevant messages.
+     * By default, only the current chat is searched.
+     */
     searchOtherChats?: boolean;
 };
 export type StorageOptions = {
@@ -38,15 +64,19 @@ export declare class Agent<AgentTools extends ToolSet> {
         name?: string;
         chat: LanguageModelV1;
         textEmbedding?: EmbeddingModelV1<string>;
-        defaultSystemPrompt?: string;
+        instructions?: string;
         tools?: AgentTools;
+        contextOptions?: ContextOptions;
+        maxSteps?: number;
     };
     constructor(component: UseApi<typeof api>, options: {
         name?: string;
         chat: LanguageModelV1;
         textEmbedding?: EmbeddingModelV1<string>;
-        defaultSystemPrompt?: string;
+        instructions?: string;
         tools?: AgentTools;
+        contextOptions?: ContextOptions;
+        maxSteps?: number;
     });
     /**
      * Start a new chat with the agent. This will have a fresh history, though if
@@ -58,7 +88,7 @@ export declare class Agent<AgentTools extends ToolSet> {
      * @param args The chat metadata.
      * @returns The chatId of the new chat and the chat object.
      */
-    startChat(ctx: RunActionCtx, args: {
+    createChat(ctx: RunActionCtx, args: {
         /**
          * The userId to associate with the chat. If not provided, the chat will be
          * anonymous.
@@ -91,7 +121,7 @@ export declare class Agent<AgentTools extends ToolSet> {
      * @param args The chat metadata.
      * @returns The chatId of the new chat.
      */
-    startChat(ctx: RunMutationCtx, args: {
+    createChat(ctx: RunMutationCtx, args: {
         userId?: string;
         parentChatIds?: string[];
         title?: string;
@@ -101,6 +131,10 @@ export declare class Agent<AgentTools extends ToolSet> {
     }>;
     continueChat(ctx: RunActionCtx, { chatId, userId, }: {
         chatId: string;
+        /**
+         * If supplied, the userId can be used to search across other chats for
+         * relevant messages from the same user as context for the LLM calls.
+         */
         userId?: string;
     }): Promise<{
         chat: Chat<AgentTools>;
@@ -109,12 +143,15 @@ export declare class Agent<AgentTools extends ToolSet> {
         userId?: string;
         chatId?: string;
         messages: CoreMessage[];
+        parentMessageId?: string;
     } & ContextOptions): Promise<CoreMessage[]>;
     saveMessages(ctx: RunMutationCtx, args: {
-        chatId: string;
+        chatId?: string;
+        userId?: string;
         messages: CoreMessageMaybeWithId[];
         pending?: boolean;
         parentMessageId?: string;
+        failPendingSteps?: boolean;
     }): Promise<{
         lastMessageId: string;
         messageIds: string[];
@@ -148,51 +185,457 @@ export declare class Agent<AgentTools extends ToolSet> {
      */
     generateText<TOOLS extends ToolSet, OUTPUT = never, OUTPUT_PARTIAL = never>(ctx: RunActionCtx, { userId, chatId, }: {
         userId?: string;
-        chatId: string;
+        chatId?: string;
     }, args: TextArgs<AgentTools, TOOLS, Parameters<typeof generateText<TOOLS, OUTPUT, OUTPUT_PARTIAL>>[0]>): Promise<GenerateTextResult<TOOLS & AgentTools, OUTPUT> & GenerationOutputMetadata>;
     streamText<TOOLS extends ToolSet, OUTPUT = never, PARTIAL_OUTPUT = never>(ctx: RunActionCtx, { userId, chatId }: {
         userId?: string;
-        chatId: string;
-    }, args: Partial<Parameters<typeof streamText<TOOLS, OUTPUT, PARTIAL_OUTPUT>>[0]> & ContextOptions & StorageOptions): Promise<StreamTextResult<TOOLS, PARTIAL_OUTPUT> & GenerationOutputMetadata>;
+        chatId?: string;
+    }, args: TextArgs<AgentTools, TOOLS, Parameters<typeof streamText<TOOLS, OUTPUT, PARTIAL_OUTPUT>>[0]>): Promise<StreamTextResult<TOOLS, PARTIAL_OUTPUT> & GenerationOutputMetadata>;
     generateObject<T>(ctx: RunActionCtx, { userId, chatId }: {
         userId?: string;
-        chatId: string;
+        chatId?: string;
     }, args: Omit<Parameters<typeof generateObject>[0], "model"> & {
         model?: LanguageModelV1;
+    } & {
+        parentMessageId?: string;
     } & ContextOptions & StorageOptions): Promise<GenerateObjectResult<T> & GenerationOutputMetadata>;
     streamObject<T>(ctx: RunMutationCtx, { userId, chatId }: {
         userId?: string;
-        chatId: string;
+        chatId?: string;
     }, args: Omit<Parameters<typeof streamObject<T>>[0], "model"> & {
         model?: LanguageModelV1;
+    } & {
+        parentMessageId?: string;
     } & ContextOptions & StorageOptions): Promise<StreamObjectResult<DeepPartial<T>, T, never> & GenerationOutputMetadata>;
-    searchOptionsWithDefaults(searchArgs: ContextOptions, messages: CoreMessage[]): Promise<SearchOptions>;
-    getChatMessages(ctx: RunQueryCtx, args: {
-        chatId: string;
-        limit?: number;
-        statuses?: MessageStatus[];
-        cursor?: string;
-        includeToolMessages?: boolean;
-        order?: "asc" | "desc";
-    }): Promise<{
-        messages: (Message & {
-            id: string;
-        })[];
-        continueCursor?: string;
-        isDone: boolean;
-    }>;
+    mergedContextOptions(opts: ContextOptions): ContextOptions;
+    searchOptionsWithDefaults(contextOptions: ContextOptions, messages: CoreMessage[]): Promise<SearchOptions>;
+    /**
+     *
+     */
+    asAction(spec: {
+        contextOptions?: ContextOptions;
+        maxSteps?: number;
+    }): import("convex/server").RegisteredAction<"internal", {
+        userId?: string | undefined;
+        chatId?: string | undefined;
+        createChat?: {
+            title?: string | undefined;
+            summary?: string | undefined;
+            parentChatIds?: string[] | undefined;
+            userId: string;
+        } | undefined;
+        maxRetries?: number | undefined;
+        contextOptions?: {
+            includeToolCalls?: boolean | undefined;
+            recentMessages?: number | undefined;
+            searchOptions?: {
+                messageRange?: {
+                    before: number;
+                    after: number;
+                } | undefined;
+                textSearch?: boolean | undefined;
+                vectorSearch?: boolean | undefined;
+                limit: number;
+            } | undefined;
+            searchOtherChats?: boolean | undefined;
+        } | undefined;
+        storageOptions?: {
+            saveAllInputMessages?: boolean | undefined;
+            saveAllOutputMessages?: boolean | undefined;
+        } | undefined;
+        continueChat?: {
+            userId?: string | undefined;
+            chatId: string;
+        } | undefined;
+        generateText?: {
+            messages?: ({
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "user";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    mimeType?: string | undefined;
+                    type: "image";
+                    image: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "assistant";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "reasoning";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "redacted-reasoning";
+                    data: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "tool-call";
+                    toolCallId: string;
+                    toolName: string;
+                    args: any;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "tool";
+                content: {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    args?: any;
+                    experimental_content?: ({
+                        type: "text";
+                        text: string;
+                    } | {
+                        mimeType?: string | undefined;
+                        type: "image";
+                        data: string;
+                    })[] | undefined;
+                    isError?: boolean | undefined;
+                    type: "tool-result";
+                    toolCallId: string;
+                    toolName: string;
+                    result: any;
+                }[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "system";
+                content: string;
+            })[] | undefined;
+            maxSteps?: number | undefined;
+            prompt?: string | undefined;
+        } | undefined;
+        streamText?: {
+            messages?: ({
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "user";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    mimeType?: string | undefined;
+                    type: "image";
+                    image: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "assistant";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "reasoning";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "redacted-reasoning";
+                    data: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "tool-call";
+                    toolCallId: string;
+                    toolName: string;
+                    args: any;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "tool";
+                content: {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    args?: any;
+                    experimental_content?: ({
+                        type: "text";
+                        text: string;
+                    } | {
+                        mimeType?: string | undefined;
+                        type: "image";
+                        data: string;
+                    })[] | undefined;
+                    isError?: boolean | undefined;
+                    type: "tool-result";
+                    toolCallId: string;
+                    toolName: string;
+                    result: any;
+                }[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "system";
+                content: string;
+            })[] | undefined;
+            maxSteps?: number | undefined;
+            prompt?: string | undefined;
+        } | undefined;
+        generateObject?: {
+            messages?: ({
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "user";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    mimeType?: string | undefined;
+                    type: "image";
+                    image: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "assistant";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "reasoning";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "redacted-reasoning";
+                    data: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "tool-call";
+                    toolCallId: string;
+                    toolName: string;
+                    args: any;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "tool";
+                content: {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    args?: any;
+                    experimental_content?: ({
+                        type: "text";
+                        text: string;
+                    } | {
+                        mimeType?: string | undefined;
+                        type: "image";
+                        data: string;
+                    })[] | undefined;
+                    isError?: boolean | undefined;
+                    type: "tool-result";
+                    toolCallId: string;
+                    toolName: string;
+                    result: any;
+                }[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "system";
+                content: string;
+            })[] | undefined;
+            prompt?: string | undefined;
+            output?: any;
+            mode?: "json" | undefined;
+        } | undefined;
+        streamObject?: {
+            messages?: ({
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "user";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    mimeType?: string | undefined;
+                    type: "image";
+                    image: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "assistant";
+                content: string | ({
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "reasoning";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "redacted-reasoning";
+                    data: string;
+                } | {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    type: "tool-call";
+                    toolCallId: string;
+                    toolName: string;
+                    args: any;
+                })[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "tool";
+                content: {
+                    providerOptions?: Record<string, any> | undefined;
+                    experimental_providerMetadata?: Record<string, any> | undefined;
+                    args?: any;
+                    experimental_content?: ({
+                        type: "text";
+                        text: string;
+                    } | {
+                        mimeType?: string | undefined;
+                        type: "image";
+                        data: string;
+                    })[] | undefined;
+                    isError?: boolean | undefined;
+                    type: "tool-result";
+                    toolCallId: string;
+                    toolName: string;
+                    result: any;
+                }[];
+            } | {
+                providerOptions?: Record<string, any> | undefined;
+                experimental_providerMetadata?: Record<string, any> | undefined;
+                role: "system";
+                content: string;
+            })[] | undefined;
+            prompt?: string | undefined;
+            output?: any;
+            mode?: "json" | undefined;
+            schema: any;
+        } | undefined;
+    }, Promise<any>>;
+    /**
+     * Create a tool that can call this agent.
+     * @param spec The specification for the arguments to this agent.
+     *   They will be encoded as JSON and passed to the agent.
+     * @returns The agent as a tool that can be passed to other agents.
+     */
+    asTool(spec: {
+        description: string;
+        args: Validator<unknown, "required", string>;
+        contextOptions?: ContextOptions;
+        maxSteps?: number;
+    }): Tool<ConvexToZod<Validator<unknown, "required", string>>, string>;
 }
-export declare function promptOrMessagesToCoreMessages(args: {
-    system?: string;
-    prompt?: string;
-    messages?: CoreMessage[] | Omit<UIMessage, "id">[];
-}): CoreMessage[];
+export type ToolCtx = RunActionCtx & {
+    userId?: string;
+    chatId?: string;
+    messageId?: string;
+};
+/**
+ * This is a wrapper around the ai.tool function that adds support for
+ * userId and chatId to the tool, if they're called within a chat from an agent.
+ * @param tool The AI tool. See https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling
+ * @returns The same tool, but with userId and chatId args support added.
+ */
+export declare function createTool<V extends Validator<any, any, any>, RESULT>(convexTool: {
+    args: V;
+    description?: string;
+    handler: (ctx: ToolCtx, args: Infer<V>, options: ToolExecutionOptions) => PromiseLike<RESULT>;
+    ctx?: ToolCtx;
+}): Tool<ConvexToZod<V>, RESULT>;
 type TextArgs<AgentTools extends ToolSet, TOOLS extends ToolSet, T extends {
     toolChoice?: ToolChoice<TOOLS & AgentTools>;
     tools?: TOOLS;
     model: LanguageModelV1;
 }> = Omit<T, "toolChoice" | "tools" | "model"> & {
     model?: LanguageModelV1;
+    parentMessageId?: string;
 } & {
     tools?: TOOLS;
     toolChoice?: ToolChoice<{
@@ -210,24 +653,5 @@ interface Chat<AgentTools extends ToolSet> {
     generateObject<T>(args: ObjectArgs<Parameters<typeof generateObject>[0]>): Promise<GenerateObjectResult<T> & GenerationOutputMetadata>;
     streamObject<T>(args: ObjectArgs<Parameters<typeof streamObject<T>>[0]>): Promise<StreamObjectResult<DeepPartial<T>, T, never> & GenerationOutputMetadata>;
 }
-/**
- * This is a wrapper around the ai.tool function that adds support for
- * userId and chatId to the tool, if they're called within a chat from an agent.
- * @param tool The AI tool. See https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling
- * @returns The same tool, but with userId and chatId args support added.
- */
-export declare function tool<V extends Validator<any, any, any>, RESULT>(convexTool: {
-    args: V;
-    description?: string;
-    handler: (ctx: GenericActionCtx<GenericDataModel> & {
-        userId?: string;
-        chatId?: string;
-    }, args: Infer<V>, options: ToolExecutionOptions) => PromiseLike<RESULT>;
-    ctx?: GenericActionCtx<GenericDataModel> & {
-        userId?: string;
-        chatId?: string;
-    };
-}): Tool<ZodType<Infer<V>>, RESULT>;
-export declare function wrapTools(actionCtx: RunActionCtx, chatId: string, userId?: string, ...toolSets: (ToolSet | undefined)[]): ToolSet;
 export {};
 //# sourceMappingURL=index.d.ts.map