@convex-dev/agent 0.5.0-alpha.1 → 0.6.0-alpha.0

package/dist/client/index.js

@@ -1,32 +1,60 @@
-import { embedMany, generateObject, generateText, stepCountIs, streamObject, streamText, } from "ai";
+import { generateObject, generateText, stepCountIs, streamObject } from "ai";
+const MIGRATION_URL = "https://github.com/get-convex/agent/blob/main/MIGRATION.md";
+const warnedDeprecations = new Set();
+function warnDeprecation(key, message) {
+    if (!warnedDeprecations.has(key)) {
+        warnedDeprecations.add(key);
+        console.warn(`[@convex-dev/agent] ${message}\n  See: ${MIGRATION_URL}`);
+    }
+}
 import { assert, omit, pick } from "convex-helpers";
 import { internalActionGeneric, internalMutationGeneric, } from "convex/server";
-import { v } from "convex/values";
-import { validateVectorDimension, } from "../component/vector/tables.js";
-import { deserializeMessage, serializeMessage, serializeNewMessagesInStep, serializeObjectResult, } from "../mapping.js";
-import { extractText, isTool } from "../shared.js";
-import { vMessageWithMetadata, vSafeObjectArgs, vTextArgs, } from "../validators.js";
-import { createTool, wrapTools } from "./createTool.js";
-import { listMessages } from "./listMessages.js";
-import { fetchContextMessages } from "./search.js";
-import { DeltaStreamer, mergeTransforms, syncStreams, } from "./streaming.js";
+import { convexToJson, v } from "convex/values";
+import {} from "../component/vector/tables.js";
+import { toModelMessage, serializeMessage, serializeNewMessagesInStep, serializeObjectResult, } from "../mapping.js";
+import { getModelName, getProviderName } from "../shared.js";
+import { vMessageEmbeddings, vMessageWithMetadata, vSafeObjectArgs, vTextArgs, } from "../validators.js";
+import { listMessages, saveMessages, } from "./messages.js";
+import { embedMany, embedMessages, fetchContextMessages, generateAndSaveEmbeddings, } from "./search.js";
+import { startGeneration } from "./start.js";
+import { syncStreams } from "./streaming.js";
+import { createThread, getThreadMetadata } from "./threads.js";
+import { streamText } from "./streamText.js";
+import { errorToString, willContinue } from "./utils.js";
 export { stepCountIs } from "ai";
-export { vMessageDoc, vThreadDoc } from "../component/schema.js";
-export { serializeDataOrUrl, deserializeMessage, serializeMessage, } from "../mapping.js";
+export { docsToModelMessages, toModelMessage, 
+//** @deprecated use toModelMessage instead */
+toModelMessage as deserializeMessage, guessMimeType, serializeDataOrUrl, serializeMessage, toUIFilePart, } from "../mapping.js";
 // NOTE: these are also exported via @convex-dev/agent/validators
 // a future version may put them all here or move these over there
-export { vAssistantMessage, vContextOptions, vMessage, vPaginationResult, vProviderMetadata, vStorageOptions, vStreamArgs, vSystemMessage, vToolMessage, vUsage, vUserMessage, } from "../validators.js";
-export { getFile, storeFile } from "./files.js";
-export { filterOutOrphanedToolMessages, fetchContextMessages, } from "./search.js";
-export { abortStream, listStreams, syncStreams } from "./streaming.js";
-export { createTool, extractText, isTool, listMessages };
+export { extractText, isTool, sorted } from "../shared.js";
+export { vAssistantMessage, vContent, vContextOptions, vMessage, vMessageDoc, vPaginationResult, vProviderMetadata, vSource, vStorageOptions, vStreamArgs, vSystemMessage, vThreadDoc, vToolMessage, vUsage, vUserMessage, } from "../validators.js";
+export { createTool } from "./createTool.js";
 export { definePlaygroundAPI, } from "./definePlaygroundAPI.js";
+export { getFile, storeFile } from "./files.js";
+export { listMessages, listUIMessages, saveMessage, saveMessages, } from "./messages.js";
+export { mockModel } from "./mockModel.js";
+export { fetchContextMessages, filterOutOrphanedToolMessages, fetchContextWithPrompt, generateAndSaveEmbeddings, embedMessages, embedMany, } from "./search.js";
+export { startGeneration } from "./start.js";
+export { DEFAULT_STREAMING_OPTIONS, DeltaStreamer, abortStream, compressUIMessageChunks, listStreams, syncStreams, vStreamMessagesReturnValue, } from "./streaming.js";
+export { createThread, getThreadMetadata, searchThreadTitles, updateThreadMetadata, } from "./threads.js";
+export { toUIMessages, fromUIMessages } from "../UIMessages.js";
 export class Agent {
     component;
     options;
     constructor(component, options) {
         this.component = component;
         this.options = options;
+        if (this.options.textEmbeddingModel && !this.options.embeddingModel) {
+            warnDeprecation("textEmbeddingModel", "textEmbeddingModel is deprecated. Use embeddingModel instead.");
+        }
+    }
+    /**
+     * Get the embedding model, prioritizing embeddingModel over textEmbeddingModel.
+     * @private
+     */
+    getEmbeddingModel() {
+        return this.options.embeddingModel ?? this.options.textEmbeddingModel;
     }
     async createThread(ctx, args) {
         const threadId = await createThread(ctx, this.component, args);
@@ -36,13 +64,8 @@ export class Agent {
         const { thread } = await this.continueThread(ctx, {
             threadId,
             userId: args?.userId,
-            usageHandler: args?.usageHandler,
-            tools: args?.tools,
         });
-        return {
-            threadId,
-            thread,
-        };
+        return { threadId, thread };
     }
     /**
      * Continues a thread using this agent. Note: threads can be continued
@@ -70,16 +93,25 @@ export class Agent {
             },
         };
     }
+    async start(ctx, 
     /**
-     * Search for threads by title, paginated.
-     * @param ctx The context passed from the query/mutation/action.
-     * @returns The threads matching the search, paginated.
+     * These are the arguments you'll pass to the LLM call such as
+     * `generateText` or `streamText`. This function will look up the context
+     * and provide functions to save the steps, abort the generation, and more.
+     * The type of the arguments returned infers from the type of the arguments
+     * you pass here.
      */
-    async searchThreadTitles(ctx, { userId, query, limit, }) {
-        return ctx.runQuery(this.component.threads.searchThreadTitles, {
-            userId,
-            query,
-            limit: limit ?? 10,
+    args, options) {
+        return startGeneration(ctx, this.component, {
+            ...args,
+            tools: (args.tools ?? this.options.tools),
+            system: args.system ?? this.options.instructions,
+            stopWhen: (args.stopWhen ?? this.options.stopWhen),
+        }, {
+            ...this.options,
+            ...options,
+            agentName: this.options.name,
+            agentForToolCtx: this,
         });
     }
     /**
@@ -89,80 +121,44 @@ export class Agent {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      * @param ctx The context passed from the action function calling this.
-     * @param { userId, threadId }: The user and thread to associate the message with
-     * @param args The arguments to the generateText function, along with extra controls
-     * for the {@link ContextOptions} and {@link StorageOptions}.
+     * @param scope: The user and thread to associate the message with
+     * @param generateTextArgs The arguments to the generateText function, along
+     * with {@link AgentPrompt} options, such as promptMessageId.
+     * @param options Extra controls for the {@link ContextOptions} and {@link StorageOptions}.
      * @returns The result of the generateText function.
      */
-    async generateText(ctx, { userId: argsUserId, threadId, usageHandler, tools: threadTools, }, args, options) {
-        const opts = { ...this.options, ...options, usageHandler };
-        const context = await this._saveMessagesAndFetchContext(ctx, args, {
-            userId: argsUserId ?? undefined,
-            threadId,
-            ...opts,
-        });
-        const { args: aiArgs, messageId, order, userId } = context;
-        const toolCtx = {
-            ...ctx,
-            userId,
-            threadId,
-            messageId,
-            agent: this,
-        };
-        const tools = wrapTools(toolCtx, args.tools ?? threadTools ?? this.options.tools);
-        const saveOutput = opts.storageOptions?.saveMessages !== "none";
+    async generateText(ctx, threadOpts, 
+    /**
+     * The arguments to the generateText function, similar to the ai sdk's
+     * {@link generateText} function, along with Agent prompt options.
+     */
+    generateTextArgs, options) {
+        const { args, promptMessageId, order, ...call } = await this.start(ctx, generateTextArgs, { ...threadOpts, ...options });
+        const steps = [];
         try {
             const result = (await generateText({
-                // Can be overridden
-                stopWhen: this.options.stopWhen,
-                ...aiArgs,
-                tools,
+                ...args,
+                prepareStep: async (options) => {
+                    const result = await generateTextArgs.prepareStep?.(options);
+                    call.updateModel(result?.model ?? options.model);
+                    return result;
+                },
                 onStepFinish: async (step) => {
-                    if (threadId && messageId && saveOutput) {
-                        await this.saveStep(ctx, {
-                            userId,
-                            threadId,
-                            promptMessageId: messageId,
-                            model: aiArgs.model.modelId,
-                            provider: aiArgs.model.provider,
-                            step,
-                        });
-                    }
-                    if (this.options.rawRequestResponseHandler) {
-                        await this.options.rawRequestResponseHandler(ctx, {
-                            userId,
-                            threadId,
-                            agentName: this.options.name,
-                            request: step.request,
-                            response: step.response,
-                        });
-                    }
-                    if (opts.usageHandler && step.usage) {
-                        await opts.usageHandler(ctx, {
-                            userId,
-                            threadId,
-                            agentName: this.options.name,
-                            model: aiArgs.model.modelId,
-                            provider: aiArgs.model.provider,
-                            usage: step.usage,
-                            providerMetadata: step.providerMetadata,
-                        });
-                    }
-                    return args.onStepFinish?.(step);
+                    steps.push(step);
+                    await call.save({ step }, await willContinue(steps, args.stopWhen));
+                    return generateTextArgs.onStepFinish?.(step);
                 },
             }));
-            result.messageId = messageId;
-            result.order = order;
-            return result;
+            const metadata = {
+                promptMessageId,
+                order,
+                savedMessages: call.getSavedMessages(),
+                messageId: promptMessageId,
+            };
+            return Object.assign(result, metadata);
         }
         catch (error) {
-            if (threadId && messageId) {
-                console.error("RollbackMessage", messageId);
-                await ctx.runMutation(this.component.messages.rollbackMessage, {
-                    messageId,
-                    error: error.message,
-                });
-            }
+            await call.fail(errorToString(error));
             throw error;
         }
     }
@@ -173,109 +169,30 @@ export class Agent {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    async streamText(ctx, { userId: argsUserId, threadId, usageHandler, 
-    /** Note: to get better type inference, pass tools in the next arg */
-    tools: threadTools, }, 
+    async streamText(ctx, threadOpts, 
     /**
-     * The arguments to the streamText function, similar to the ai `streamText` function.
+     * The arguments to the streamText function, similar to the ai sdk's
+     * {@link streamText} function, along with Agent prompt options.
      */
-    args, 
+    streamTextArgs, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
      */
     options) {
-        const opts = { ...this.options, ...options, usageHandler };
-        const context = await this._saveMessagesAndFetchContext(ctx, args, {
-            userId: argsUserId ?? undefined,
-            threadId,
-            ...opts,
-        });
-        const { args: aiArgs, messageId, order, stepOrder, userId } = context;
-        const toolCtx = {
-            ...ctx,
-            userId,
-            threadId,
-            messageId,
-            agent: this,
-        };
-        const tools = wrapTools(toolCtx, args.tools ?? threadTools ?? this.options.tools);
-        const saveOutput = opts.storageOptions?.saveMessages !== "none";
-        const streamer = threadId && opts.saveStreamDeltas
-            ? new DeltaStreamer(this.component, ctx, opts.saveStreamDeltas, {
-                threadId,
-                userId,
-                agentName: this.options.name,
-                model: aiArgs.model.modelId,
-                provider: aiArgs.model.provider,
-                providerOptions: aiArgs.providerOptions,
-                order,
-                stepOrder,
-                abortSignal: aiArgs.abortSignal,
-            })
-            : undefined;
-        const result = streamText({
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            stopWhen: this.options.stopWhen, // Can be overridden
-            ...aiArgs,
-            tools,
-            abortSignal: streamer?.abortController.signal ?? aiArgs.abortSignal,
-            experimental_transform: mergeTransforms(options?.saveStreamDeltas, args.experimental_transform),
-            onChunk: async (event) => {
-                await streamer?.addParts([event.chunk]);
-                // console.log("onChunk", chunk);
-                return args.onChunk?.(event);
-            },
-            onError: async (error) => {
-                console.error("onError", error);
-                if (threadId && messageId && saveOutput) {
-                    await ctx.runMutation(this.component.messages.rollbackMessage, {
-                        messageId,
-                        error: error.error.message,
-                    });
-                }
-                // TODO: update the streamer to error state
-                return args.onError?.(error);
-            },
-            onStepFinish: async (step) => {
-                // console.log("onStepFinish", step);
-                if (threadId && messageId && saveOutput) {
-                    const saved = await this.saveStep(ctx, {
-                        userId,
-                        threadId,
-                        model: aiArgs.model.modelId,
-                        provider: aiArgs.model.provider,
-                        promptMessageId: messageId,
-                        step,
-                    });
-                    await streamer?.finish(saved.messages);
-                }
-                if (this.options.rawRequestResponseHandler) {
-                    await this.options.rawRequestResponseHandler(ctx, {
-                        userId,
-                        threadId,
-                        agentName: this.options.name,
-                        request: step.request,
-                        response: step.response,
-                    });
-                }
-                if (opts.usageHandler && step.usage) {
-                    await opts.usageHandler(ctx, {
-                        userId,
-                        threadId,
-                        agentName: this.options.name,
-                        model: aiArgs.model.modelId,
-                        provider: aiArgs.model.provider,
-                        usage: step.usage,
-                        providerMetadata: step.providerMetadata,
-                    });
-                }
-                return args.onStepFinish?.(step);
-            },
+        return streamText(ctx, this.component, {
+            ...streamTextArgs,
+            model: streamTextArgs.model ?? this.options.languageModel,
+            tools: (streamTextArgs.tools ?? this.options.tools),
+            system: streamTextArgs.system ?? this.options.instructions,
+            stopWhen: (streamTextArgs.stopWhen ?? this.options.stopWhen),
+        }, {
+            ...threadOpts,
+            ...this.options,
+            agentName: this.options.name,
+            agentForToolCtx: this,
+            ...options,
         });
-        result.messageId = messageId;
-        result.order = order;
-        return result;
     }
     /**
      * This behaves like {@link generateObject} from the "ai" package except that
@@ -284,69 +201,31 @@ export class Agent {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    async generateObject(ctx, { userId: argsUserId, threadId, usageHandler, }, 
+    async generateObject(ctx, threadOpts, 
     /**
-     * The arguments to the generateObject function, similar to the ai.generateObject function.
+     * The arguments to the generateObject function, similar to the ai sdk's
+     * {@link generateObject} function, along with Agent prompt options.
      */
-    args, 
+    generateObjectArgs, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
      */
     options) {
-        const opts = { ...this.options, ...options, usageHandler };
-        const context = await this._saveMessagesAndFetchContext(ctx, args, {
-            userId: argsUserId ?? undefined,
-            threadId,
-            ...opts,
-        });
-        const { args: aiArgs, messageId, order, userId } = context;
-        const saveOutput = opts.storageOptions?.saveMessages !== "none";
+        const { args, promptMessageId, order, fail, save, getSavedMessages } = await this.start(ctx, generateObjectArgs, { ...threadOpts, ...options });
         try {
-            const result = (await generateObject(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            aiArgs));
-            if (threadId && messageId && saveOutput) {
-                await this.saveObject(ctx, {
-                    threadId,
-                    promptMessageId: messageId,
-                    result,
-                    userId,
-                    model: aiArgs.model.modelId,
-                    provider: aiArgs.model.provider,
-                });
-            }
-            result.messageId = messageId;
-            result.order = order;
-            if (this.options.rawRequestResponseHandler) {
-                await this.options.rawRequestResponseHandler(ctx, {
-                    userId,
-                    threadId,
-                    agentName: this.options.name,
-                    request: result.request,
-                    response: result.response,
-                });
-            }
-            if (opts.usageHandler && result.usage) {
-                await opts.usageHandler(ctx, {
-                    userId,
-                    threadId,
-                    agentName: this.options.name,
-                    model: aiArgs.model.modelId,
-                    provider: aiArgs.model.provider,
-                    usage: result.usage,
-                    providerMetadata: result.providerMetadata,
-                });
-            }
-            return result;
+            const result = (await generateObject(args));
+            await save({ object: result });
+            const metadata = {
+                promptMessageId,
+                order,
+                savedMessages: getSavedMessages(),
+                messageId: promptMessageId,
+            };
+            return Object.assign(result, metadata);
         }
         catch (error) {
-            if (threadId && messageId) {
-                await ctx.runMutation(this.component.messages.rollbackMessage, {
-                    messageId,
-                    error: error.message,
-                });
-            }
+            await fail(errorToString(error));
             throw error;
         }
     }
@@ -357,80 +236,51 @@ export class Agent {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    async streamObject(ctx, { userId: argsUserId, threadId, usageHandler, }, 
+    async streamObject(ctx, threadOpts, 
     /**
-     * The arguments to the streamObject function, similar to the ai `streamObject` function.
+     * The arguments to the streamObject function, similar to the ai sdk's
+     * {@link streamObject} function, along with Agent prompt options.
      */
-    args, 
+    streamObjectArgs, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
      */
     options) {
-        // TODO: unify all this shared code between all the generate* and stream* functions
-        const opts = { ...this.options, ...options, usageHandler };
-        const context = await this._saveMessagesAndFetchContext(ctx, args, {
-            userId: argsUserId ?? undefined,
-            threadId,
-            ...opts,
-        });
-        const { args: aiArgs, messageId, order, userId } = context;
-        const saveOutput = opts.storageOptions?.saveMessages !== "none";
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { args, promptMessageId, order, fail, save, getSavedMessages } = await this.start(ctx, streamObjectArgs, { ...threadOpts, ...options });
         const stream = streamObject({
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            ...aiArgs,
+            ...args,
             onError: async (error) => {
-                console.error("onError", error);
+                console.error(" streamObject onError", error);
+                // TODO: content that we have so far
+                // content: stream.fullStream.
+                await fail(errorToString(error.error));
                 return args.onError?.(error);
             },
             onFinish: async (result) => {
-                if (threadId && messageId && saveOutput) {
-                    await this.saveObject(ctx, {
-                        userId,
-                        threadId,
-                        promptMessageId: messageId,
-                        result: {
-                            object: result.object,
-                            finishReason: "stop",
-                            usage: result.usage,
-                            warnings: result.warnings,
-                            request: await stream.request,
-                            response: result.response,
-                            providerMetadata: result.providerMetadata,
-                            toJsonResponse: stream.toTextStreamResponse,
-                        },
-                        model: aiArgs.model.modelId,
-                        provider: aiArgs.model.provider,
-                    });
-                }
-                if (opts.usageHandler && result.usage) {
-                    await opts.usageHandler(ctx, {
-                        userId,
-                        threadId,
-                        agentName: this.options.name,
-                        model: aiArgs.model.modelId,
-                        provider: aiArgs.model.provider,
+                await save({
+                    object: {
+                        object: result.object,
+                        finishReason: result.error ? "error" : "stop",
                         usage: result.usage,
-                        providerMetadata: result.providerMetadata,
-                    });
-                }
-                if (this.options.rawRequestResponseHandler) {
-                    await this.options.rawRequestResponseHandler(ctx, {
-                        userId,
-                        threadId,
-                        agentName: this.options.name,
+                        warnings: result.warnings,
                         request: await stream.request,
                         response: result.response,
-                    });
-                }
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        providerMetadata: result.providerMetadata,
+                        toJsonResponse: stream.toTextStreamResponse,
+                        reasoning: undefined,
+                    },
+                });
                 return args.onFinish?.(result);
             },
         });
-        stream.messageId = messageId;
-        stream.order = order;
-        return stream;
+        const metadata = {
+            promptMessageId,
+            order,
+            savedMessages: getSavedMessages(),
+            messageId: promptMessageId,
+        };
+        return Object.assign(stream, metadata);
     }
     /**
      * Save a message to the thread.
@@ -440,22 +290,22 @@ export class Agent {
      * @returns The messageId of the saved message.
      */
     async saveMessage(ctx, args) {
-        const { lastMessageId, messages } = await this.saveMessages(ctx, {
+        const { messages } = await this.saveMessages(ctx, {
             threadId: args.threadId,
             userId: args.userId,
             embeddings: args.embedding
-                ? {
-                    model: args.embedding.model,
-                    vectors: [args.embedding.vector],
-                }
+                ? { model: args.embedding.model, vectors: [args.embedding.vector] }
                 : undefined,
             messages: args.prompt !== undefined
                 ? [{ role: "user", content: args.prompt }]
                 : [args.message],
             metadata: args.metadata ? [args.metadata] : undefined,
             skipEmbeddings: args.skipEmbeddings,
+            promptMessageId: args.promptMessageId,
+            pendingMessageId: args.pendingMessageId,
         });
-        return { messageId: lastMessageId, message: messages.at(-1) };
+        const message = messages.at(-1);
+        return { messageId: message._id, message };
     }
     /**
      * Explicitly save messages associated with the thread (& user if provided)
@@ -471,7 +321,7 @@ export class Agent {
         if (args.embeddings) {
             embeddings = args.embeddings;
         }
-        else if (!skipEmbeddings && this.options.textEmbedding) {
+        else if (!skipEmbeddings && this.getEmbeddingModel()) {
             if (!("runAction" in ctx)) {
                 console.warn("You're trying to save messages and generate embeddings, but you're in a mutation. " +
                     "Pass `skipEmbeddings: true` to skip generating embeddings in the mutation and skip this warning. " +
@@ -485,10 +335,7 @@ export class Agent {
                     "You can explicitly generate them asynchronously by using the scheduler to run an action later that calls `agent.generateAndSaveEmbeddings`.");
             }
             else {
-                embeddings = await this.generateEmbeddings(ctx, {
-                    userId: args.userId ?? undefined,
-                    threadId: args.threadId,
-                }, args.messages);
+                embeddings = await this.generateEmbeddings(ctx, { userId: args.userId ?? undefined, threadId: args.threadId }, args.messages);
             }
         }
         return saveMessages(ctx, this.component, {
@@ -540,14 +387,17 @@ export class Agent {
             contextOptions,
             getEmbedding: async (text) => {
                 assert("runAction" in ctx);
-                assert(this.options.textEmbedding, "A textEmbedding model is required to be set on the Agent that you're doing vector search with");
+                const embeddingModel = this.getEmbeddingModel();
+                assert(embeddingModel, "An embeddingModel (or textEmbeddingModel) is required to be set on the Agent that you're doing vector search with");
                 return {
-                    embedding: (await this.doEmbed(ctx, {
+                    embedding: (await embedMany(ctx, {
+                        ...this.options,
+                        agentName: this.options.name,
                         userId: args.userId,
                         threadId: args.threadId,
                         values: [text],
                     })).embeddings[0],
-                    embeddingModel: this.options.textEmbedding.modelId,
+                    embeddingModel: embeddingModel,
                 };
             },
         });
@@ -577,40 +427,8 @@ export class Agent {
      * @param messages The messages to get the embeddings for.
      * @returns The embeddings for the messages.
      */
-    async generateEmbeddings(ctx, { userId, threadId, }, messages) {
-        if (!this.options.textEmbedding) {
-            return undefined;
-        }
-        let embeddings;
-        const messageTexts = messages.map((m) => !isTool(m) && extractText(m));
-        // Find the indexes of the messages that have text.
-        const textIndexes = messageTexts
-            .map((t, i) => (t ? i : undefined))
-            .filter((i) => i !== undefined);
-        if (textIndexes.length === 0) {
-            return undefined;
-        }
-        // Then embed those messages.
-        const textEmbeddings = await this.doEmbed(ctx, {
-            userId,
-            threadId,
-            values: messageTexts,
-        });
-        // Then assemble the embeddings into a single array with nulls for the messages without text.
-        const embeddingsOrNull = Array(messages.length).fill(null);
-        textIndexes.forEach((i, j) => {
-            embeddingsOrNull[i] = textEmbeddings.embeddings[j];
-        });
-        if (textEmbeddings.embeddings.length > 0) {
-            const dimension = textEmbeddings.embeddings[0].length;
-            validateVectorDimension(dimension);
-            embeddings = {
-                vectors: embeddingsOrNull,
-                dimension,
-                model: this.options.textEmbedding.modelId,
-            };
-        }
-        return embeddings;
+    async generateEmbeddings(ctx, args, messages) {
+        return embedMessages(ctx, { ...args, ...this.options, agentName: this.options.name }, messages);
     }
     /**
      * Generate embeddings for a set of messages, and save them to the database.
@@ -629,9 +447,6 @@ export class Agent {
                     .filter((id) => !messages.some((m) => m?._id === id))
                     .join(", "));
         }
-        await this._generateAndSaveEmbeddings(ctx, messages);
-    }
-    async _generateAndSaveEmbeddings(ctx, messages) {
         if (messages.some((m) => !m.message)) {
             throw new Error("Some messages don't have a message: " +
                 messages
@@ -639,34 +454,17 @@ export class Agent {
                     .map((m) => m._id)
                     .join(", "));
         }
-        const messagesMissingEmbeddings = messages.filter((m) => !m.embeddingId);
-        if (messagesMissingEmbeddings.length === 0) {
-            return;
+        const embeddingModel = this.getEmbeddingModel();
+        if (!embeddingModel) {
+            throw new Error("No embeddings were generated for the messages. You must pass an embeddingModel (or textEmbeddingModel) to the agent constructor.");
         }
-        const embeddings = await this.generateEmbeddings(ctx, {
-            userId: messagesMissingEmbeddings[0].userId,
-            threadId: messagesMissingEmbeddings[0].threadId,
-        }, messagesMissingEmbeddings.map((m) => deserializeMessage(m.message)));
-        if (!embeddings) {
-            if (!this.options.textEmbedding) {
-                throw new Error("No embeddings were generated for the messages. You must pass a textEmbedding model to the agent constructor.");
-            }
-            throw new Error("No embeddings were generated for these messages: " +
-                messagesMissingEmbeddings.map((m) => m._id).join(", "));
-        }
-        await ctx.runMutation(this.component.vector.index.insertBatch, {
-            vectorDimension: embeddings.dimension,
-            vectors: messagesMissingEmbeddings
-                .map((m, i) => ({
-                messageId: m._id,
-                model: embeddings.model,
-                table: "messages",
-                userId: m.userId,
-                threadId: m.threadId,
-                vector: embeddings.vectors[i],
-            }))
-                .filter((v) => v.vector !== null),
-        });
+        await generateAndSaveEmbeddings(ctx, this.component, {
+            ...this.options,
+            agentName: this.options.name,
+            threadId: messages[0].threadId,
+            userId: messages[0].userId,
+            embeddingModel,
+        }, messages);
     }
     /**
      * Explicitly save a "step" created by the AI SDK.
@@ -674,12 +472,12 @@ export class Agent {
      * @param args The Step generated by the AI SDK.
      */
     async saveStep(ctx, args) {
-        const messages = await serializeNewMessagesInStep(ctx, this.component, args.step, {
-            provider: args.provider ?? this.options.chat.provider,
-            model: args.model ?? this.options.chat.modelId,
+        const { messages } = await serializeNewMessagesInStep(ctx, this.component, args.step, {
+            provider: args.provider ?? getProviderName(this.options.languageModel),
+            model: args.model ?? getModelName(this.options.languageModel),
         });
-        const embeddings = await this.generateEmbeddings(ctx, { userId: args.userId, threadId: args.threadId }, messages.map((m) => deserializeMessage(m.message)));
-        const saved = await ctx.runMutation(this.component.messages.addMessages, {
+        const embeddings = await this.generateEmbeddings(ctx, { userId: args.userId, threadId: args.threadId }, messages.map((m) => m.message));
+        return ctx.runMutation(this.component.messages.addMessages, {
             userId: args.userId,
             threadId: args.threadId,
             agentName: this.options.name,
@@ -688,7 +486,6 @@ export class Agent {
             embeddings,
             failPendingSteps: false,
         });
-        return saved;
     }
     /**
      * Manually save the result of a generateObject call to the thread.
@@ -699,11 +496,15 @@ export class Agent {
      */
     async saveObject(ctx, args) {
         const { messages } = await serializeObjectResult(ctx, this.component, args.result, {
-            model: args.model ?? this.options.chat.modelId,
-            provider: args.provider ?? this.options.chat.provider,
+            model: args.model ??
+                args.metadata?.model ??
+                getModelName(this.options.languageModel),
+            provider: args.provider ??
+                args.metadata?.provider ??
+                getProviderName(this.options.languageModel),
         });
-        const embeddings = await this.generateEmbeddings(ctx, { userId: args.userId, threadId: args.threadId }, messages.map((m) => deserializeMessage(m.message)));
-        await ctx.runMutation(this.component.messages.addMessages, {
+        const embeddings = await this.generateEmbeddings(ctx, { userId: args.userId, threadId: args.threadId }, messages.map((m) => m.message));
+        return ctx.runMutation(this.component.messages.addMessages, {
             userId: args.userId,
             threadId: args.threadId,
             promptMessageId: args.promptMessageId,
@@ -711,7 +512,6 @@ export class Agent {
             messages,
             embeddings,
             agentName: this.options.name,
-            pending: false,
         });
     }
     /**
@@ -722,19 +522,11 @@ export class Agent {
      * @param args What message to save. Generally the parent message sent into
      *   the generateText call.
      */
-    async completeMessage(ctx, args) {
-        const result = args.result;
-        if (result.kind === "success") {
-            await ctx.runMutation(this.component.messages.commitMessage, {
-                messageId: args.messageId,
-            });
-        }
-        else {
-            await ctx.runMutation(this.component.messages.rollbackMessage, {
-                messageId: args.messageId,
-                error: result.error,
-            });
-        }
+    async finalizeMessage(ctx, args) {
+        await ctx.runMutation(this.component.messages.finalizeMessage, {
+            messageId: args.messageId,
+            result: args.result,
+        });
     }
     /**
      * Update a message by its id.
@@ -847,206 +639,6 @@ export class Agent {
             limit: args.pageSize,
         });
     }
-    async _saveMessagesAndFetchContext(ctx, args, { userId: argsUserId, threadId, contextOptions, storageOptions, }) {
-        // If only a promptMessageId is provided, this will be empty.
-        const messages = args.messages ?? [];
-        const prompt = !args.prompt
-            ? []
-            : Array.isArray(args.prompt)
-                ? args.prompt
-                : [{ role: "user", content: args.prompt }];
-        const userId = argsUserId ??
-            (threadId &&
-                (await ctx.runQuery(this.component.threads.getThread, { threadId }))
-                    ?.userId);
-        // If only a messageId is provided, this will add that message to the end.
-        const contextMessages = await this.fetchContextMessages(ctx, {
-            userId,
-            threadId,
-            upToAndIncludingMessageId: args.promptMessageId,
-            messages,
-            contextOptions,
-        });
-        // If it was a promptMessageId, pop it off context messages
-        // and add to the end of messages.
-        const promptMessageIndex = args.promptMessageId
-            ? contextMessages.findIndex((m) => m._id === args.promptMessageId)
-            : -1;
-        const promptMessage = promptMessageIndex !== -1
-            ? contextMessages.splice(promptMessageIndex, 1)[0]
-            : undefined;
-        let messageId = promptMessage?._id;
-        let order = promptMessage?.order;
-        let stepOrder = promptMessage?.stepOrder;
-        if (threadId &&
-            messages.length + prompt.length &&
-            storageOptions?.saveMessages !== "none" &&
-            // If it was a promptMessageId, we don't want to save it again.
-            (!args.promptMessageId || storageOptions?.saveMessages === "all")) {
-            const saveAll = storageOptions?.saveMessages === "all";
-            const coreMessages = [...messages, ...prompt];
-            const toSave = saveAll ? coreMessages : coreMessages.slice(-1);
-            const metadata = Array.from({ length: toSave.length }, () => ({}));
-            metadata[metadata.length - 1] = { id: args.id };
-            const saved = await this.saveMessages(ctx, {
-                threadId,
-                userId,
-                messages: toSave,
-                metadata,
-                failPendingSteps: true,
-            });
-            messageId = saved.lastMessageId;
-            order = saved.messages.at(-1)?.order;
-            stepOrder = saved.messages.at(-1)?.stepOrder;
-        }
-        if (promptMessage?.message) {
-            if (!args.prompt) {
-                // If they override the prompt, we skip the existing prompt message.
-                messages.push(deserializeMessage(promptMessage.message));
-            }
-            // Lazily generate embeddings for the prompt message, if it doesn't have
-            // embeddings yet. This can happen if the message was saved in a mutation
-            // where the LLM is not available.
-            if (!promptMessage.embeddingId && this.options.textEmbedding) {
-                await this._generateAndSaveEmbeddings(ctx, [promptMessage]);
-            }
-        }
-        const prePrompt = contextMessages.map((m) => deserializeMessage(m.message));
-        let existingResponses = [];
-        if (promptMessageIndex !== -1) {
-            // pull any messages that already responded to the prompt off
-            // and add them after the prompt
-            existingResponses = prePrompt.splice(promptMessageIndex);
-        }
-        let processedMessages = [
-            ...prePrompt,
-            ...messages,
-            ...prompt,
-            ...existingResponses,
-        ];
-        if (promptMessageIndex === -1) {
-            processedMessages.push(...prompt);
-        }
-        else {
-            // We add the prompt where the prompt message was
-            processedMessages.splice(promptMessageIndex, 0, ...prompt);
-        }
-        // Process messages to inline localhost files (if not, file urls pointing to localhost will be sent to LLM providers)
-        if (process.env.CONVEX_CLOUD_URL?.startsWith("http://127.0.0.1")) {
-            processedMessages = await this._inlineMessagesFiles(processedMessages);
-        }
-        const { prompt: _, model, ...rest } = args;
-        return {
-            args: {
-                ...rest,
-                maxRetries: args.maxRetries ?? this.options.maxRetries,
-                model: model ?? this.options.chat,
-                system: args.system ?? this.options.instructions,
-                messages: processedMessages,
-            },
-            userId,
-            messageId,
-            order,
-            stepOrder,
-        };
-    }
-    async doEmbed(ctx, options) {
-        const embeddingModel = this.options.textEmbedding;
-        assert(embeddingModel, "a textEmbedding model is required to be set on the Agent that you're doing vector search with");
-        const result = await embedMany({
-            model: embeddingModel,
-            values: options.values,
-            abortSignal: options.abortSignal,
-            headers: options.headers,
-            maxRetries: this.options.maxRetries,
-        });
-        if (this.options.usageHandler && result.usage) {
-            await this.options.usageHandler(ctx, {
-                userId: options.userId,
-                threadId: options.threadId,
-                agentName: this.options.name,
-                model: embeddingModel.modelId,
-                provider: embeddingModel.provider,
-                providerMetadata: undefined,
-                usage: {
-                    inputTokens: result.usage.tokens,
-                    outputTokens: 0,
-                    totalTokens: result.usage.tokens,
-                },
-            });
-        }
-        return { embeddings: result.embeddings };
-    }
-    /**
-     * Process messages to inline file and image URLs that point to localhost
-     * by converting them to base64. This solves the problem of LLMs not being
-     * able to access localhost URLs.
-     */
-    async _inlineMessagesFiles(messages) {
-        // Process each message to convert localhost URLs to base64
-        return Promise.all(messages.map(async (message) => {
-            if ((message.role !== "user" && message.role !== "assistant") ||
-                typeof message.content === "string" ||
-                !Array.isArray(message.content)) {
-                return message;
-            }
-            const processedContent = await Promise.all(message.content.map(async (part) => {
-                if (part.type === "image" && part.image instanceof URL) {
-                    assert(message.role === "user", "Images can only be in user messages");
-                    if (this._isLocalhostUrl(part.image)) {
-                        const imageData = await this._downloadFile(part.image);
-                        return {
-                            ...part,
-                            image: imageData,
-                        };
-                    }
-                }
-                // Handle file parts
-                if (part.type === "file" && part.data instanceof URL) {
-                    if (this._isLocalhostUrl(part.data)) {
-                        const fileData = await this._downloadFile(part.data);
-                        return {
-                            ...part,
-                            data: fileData,
-                        };
-                    }
-                }
-                return part;
-            }));
-            if (message.role === "user") {
-                return {
-                    ...message,
-                    content: processedContent,
-                };
-            }
-            else {
-                return {
-                    ...message,
-                    content: processedContent,
-                };
-            }
-        }));
-    }
-    /**
-     * Check if a URL points to localhost
-     */
-    _isLocalhostUrl(url) {
-        return (url.hostname === "localhost" ||
-            url.hostname === "127.0.0.1" ||
-            url.hostname === "::1" ||
-            url.hostname === "0.0.0.0");
-    }
-    /**
-     * Download a file from a URL
-     */
-    async _downloadFile(url) {
-        // Fetch the file
-        const response = await fetch(url);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
-        }
-        return await response.arrayBuffer();
-    }
     /**
      * WORKFLOW UTILITIES
      */
@@ -1087,28 +679,26 @@ export class Agent {
      * @param spec Configuration for the agent acting as an action, including
      *   {@link ContextOptions}, {@link StorageOptions}, and {@link stopWhen}.
      */
-    asTextAction(spec) {
-        const stopWhen = spec?.stopWhen ?? this.options.stopWhen;
+    asTextAction(spec, overrides) {
         return internalActionGeneric({
             args: vTextArgs,
             handler: async (ctx_, args) => {
-                const stream = args.stream === true ? spec?.stream || true : spec?.stream ?? false;
-                const targetArgs = { userId: args.userId, threadId: args.threadId };
+                const stream = args.stream === true ? spec?.stream || true : (spec?.stream ?? false);
+                const { userId, threadId, prompt, messages, maxSteps, ...rest } = args;
+                const targetArgs = { userId, threadId };
                 const llmArgs = {
-                    stopWhen,
-                    ...omit(args, ["storageOptions", "contextOptions"]),
-                    messages: args.messages?.map(deserializeMessage),
-                    prompt: Array.isArray(args.prompt)
-                        ? args.prompt.map(deserializeMessage)
-                        : args.prompt,
+                    stopWhen: spec?.stopWhen,
+                    ...overrides,
+                    ...omit(rest, ["storageOptions", "contextOptions", "stream"]),
+                    messages: messages?.map(toModelMessage),
+                    prompt: Array.isArray(prompt) ? prompt.map(toModelMessage) : prompt,
                     toolChoice: args.toolChoice,
                 };
-                if (args.maxSteps) {
-                    llmArgs.stopWhen = stepCountIs(args.maxSteps);
+                if (maxSteps) {
+                    llmArgs.stopWhen = stepCountIs(maxSteps);
                 }
                 const opts = {
-                    ...this.options,
-                    ...(spec && pick(spec, ["contextOptions", "storageOptions"])),
+                    ...pick(spec, ["contextOptions", "storageOptions"]),
                     ...pick(args, ["contextOptions", "storageOptions"]),
                     saveStreamDeltas: stream,
                 };
@@ -1116,26 +706,26 @@ export class Agent {
                     ? { ...ctx_, ...spec.customCtx(ctx_, targetArgs, llmArgs) }
                     : ctx_);
                 if (stream) {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const result = await this.streamText(ctx, targetArgs, llmArgs, opts);
                     await result.consumeStream();
                     return {
                         text: await result.text,
-                        messageId: result.messageId,
+                        promptMessageId: result.promptMessageId,
                         order: result.order,
                         finishReason: await result.finishReason,
-                        warnings: result.warnings,
+                        warnings: await result.warnings,
+                        savedMessageIds: result.savedMessages?.map((m) => m._id) ?? [],
                     };
                 }
                 else {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const res = await this.generateText(ctx, targetArgs, llmArgs, opts);
                     return {
                         text: res.text,
-                        messageId: res.messageId,
+                        promptMessageId: res.promptMessageId,
                         order: res.order,
                         finishReason: res.finishReason,
                         warnings: res.warnings,
+                        savedMessageIds: res.savedMessages?.map((m) => m._id) ?? [],
                     };
                 }
             },
@@ -1148,45 +738,43 @@ export class Agent {
      * the normal parameters to {@link generateObject}, plus {@link ContextOptions}
      * and stopWhen.
      */
-    asObjectAction(spec, options) {
+    asObjectAction(objectArgs, options) {
         return internalActionGeneric({
             args: vSafeObjectArgs,
-            handler: async (ctx, args) => {
-                const { userId, threadId, ...rest } = args;
+            handler: async (ctx_, args) => {
+                const { userId, threadId, callSettings, ...rest } = args;
                 const overrides = pick(rest, ["contextOptions", "storageOptions"]);
-                const value = await this.generateObject(ctx, { userId, threadId }, {
-                    ...spec,
-                    ...omit(rest, ["contextOptions", "storageOptions"]),
-                }, { ...this.options, ...options, ...overrides });
+                const targetArgs = { userId, threadId };
+                const llmArgs = {
+                    ...objectArgs,
+                    ...callSettings,
+                    ...omit(rest, ["storageOptions", "contextOptions"]),
+                    messages: args.messages?.map(toModelMessage),
+                    prompt: Array.isArray(args.prompt)
+                        ? args.prompt.map(toModelMessage)
+                        : args.prompt,
+                };
+                const ctx = (options?.customCtx
+                    ? { ...ctx_, ...options.customCtx(ctx_, targetArgs, llmArgs) }
+                    : ctx_);
+                const value = await this.generateObject(ctx, targetArgs, llmArgs, {
+                    ...this.options,
+                    ...options,
+                    ...overrides,
+                });
                 return {
-                    object: value.object,
-                    messageId: value.messageId,
+                    object: convexToJson(value.object),
+                    promptMessageId: value.promptMessageId,
                     order: value.order,
                     finishReason: value.finishReason,
                     warnings: value.warnings,
+                    savedMessageIds: value.savedMessages?.map((m) => m._id) ?? [],
                 };
             },
         });
     }
     /**
-     * Save messages to the thread.
-     * Useful as a step in Workflows, e.g.
-     * ```ts
-     * const saveMessages = agent.asSaveMessagesMutation();
-     *
-     * const myWorkflow = workflow.define({
-     *   args: {...},
-     *   handler: async (step, args) => {
-     *     // do things to create (but not save)messages
-     *     const { messageIds } = await step.runMutation(internal.foo.saveMessages, {
-     *       threadId: args.threadId,
-     *       messages: args.messages,
-     *     });
-     *     // ...
-     *   },
-     * })
-     * ```
-     * @returns A mutation that can be used to save messages to the thread.
+     * @deprecated Use {@link saveMessages} directly instead.
      */
     asSaveMessagesMutation() {
         return internalMutationGeneric({
@@ -1195,116 +783,22 @@ export class Agent {
                 userId: v.optional(v.string()),
                 promptMessageId: v.optional(v.string()),
                 messages: v.array(vMessageWithMetadata),
-                pending: v.optional(v.boolean()),
                 failPendingSteps: v.optional(v.boolean()),
+                embeddings: v.optional(vMessageEmbeddings),
             },
             handler: async (ctx, args) => {
-                const { lastMessageId, messages } = await this.saveMessages(ctx, {
+                const { messages } = await this.saveMessages(ctx, {
                     ...args,
-                    messages: args.messages.map((m) => deserializeMessage(m.message)),
+                    messages: args.messages.map((m) => toModelMessage(m.message)),
                     metadata: args.messages.map(({ message: _, ...m }) => m),
+                    skipEmbeddings: true,
                 });
                 return {
-                    lastMessageId,
-                    messageIds: messages.map((m) => m._id),
+                    lastMessageId: messages.at(-1)._id,
+                    messages: messages.map((m) => pick(m, ["_id", "order", "stepOrder"])),
                 };
             },
         });
     }
 }
-/**
- * Create a thread to store messages with an Agent.
- * @param ctx The context from a mutation or action.
- * @param component The Agent component, usually `components.agent`.
- * @param args The associated thread metadata.
- * @returns The id of the created thread.
- */
-export async function createThread(ctx, component, args) {
-    const { _id: threadId } = await ctx.runMutation(component.threads.createThread, {
-        userId: args?.userId ?? undefined,
-        title: args?.title,
-        summary: args?.summary,
-    });
-    return threadId;
-}
-/**
- * Get the metadata for a thread.
- * @param ctx A ctx object from a query, mutation, or action.
- * @param args.threadId The thread to get the metadata for.
- * @returns The metadata for the thread.
- */
-export async function getThreadMetadata(ctx, component, args) {
-    const thread = await ctx.runQuery(component.threads.getThread, {
-        threadId: args.threadId,
-    });
-    if (!thread) {
-        throw new Error("Thread not found");
-    }
-    return thread;
-}
-/**
- * Explicitly save messages associated with the thread (& user if provided)
- */
-export async function saveMessages(ctx, component, args) {
-    let embeddings;
-    if (args.embeddings) {
-        const dimension = args.embeddings.vectors.find((v) => v !== null)?.length;
-        if (dimension) {
-            validateVectorDimension(dimension);
-            embeddings = {
-                model: args.embeddings.model,
-                dimension,
-                vectors: args.embeddings.vectors,
-            };
-        }
-    }
-    const result = await ctx.runMutation(component.messages.addMessages, {
-        threadId: args.threadId,
-        userId: args.userId ?? undefined,
-        agentName: args.agentName,
-        promptMessageId: args.promptMessageId,
-        embeddings,
-        messages: await Promise.all(args.messages.map(async (m, i) => {
-            const { message, fileIds } = await serializeMessage(ctx, component, m);
-            return {
-                ...args.metadata?.[i],
-                message,
-                fileIds,
-            };
-        })),
-        failPendingSteps: args.failPendingSteps ?? false,
-        pending: args.pending ?? false,
-    });
-    return {
-        lastMessageId: result.messages.at(-1)._id,
-        messages: result.messages,
-    };
-}
-/**
- * Save a message to the thread.
- * @param ctx A ctx object from a mutation or action.
- * @param args The message and what to associate it with (user / thread)
- * You can pass extra metadata alongside the message, e.g. associated fileIds.
- * @returns The messageId of the saved message.
- */
-export async function saveMessage(ctx, component, args) {
-    let embeddings;
-    if (args.embedding && args.embedding.vector) {
-        embeddings = {
-            model: args.embedding.model,
-            vectors: [args.embedding.vector],
-        };
-    }
-    const { lastMessageId, messages } = await saveMessages(ctx, component, {
-        threadId: args.threadId,
-        userId: args.userId ?? undefined,
-        agentName: args.agentName,
-        messages: args.prompt !== undefined
-            ? [{ role: "user", content: args.prompt }]
-            : [args.message],
-        metadata: args.metadata ? [args.metadata] : undefined,
-        embeddings,
-    });
-    return { messageId: lastMessageId, message: messages.at(-1) };
-}
 //# sourceMappingURL=index.js.map