@convex-dev/agent 0.2.0-alpha.2 → 0.2.1

package/dist/client/index.d.ts

@@ -1,6 +1,7 @@
-import type { LanguageModelV2 } from "@ai-sdk/provider";
-import type { ModelMessage, DeepPartial, GenerateObjectResult, GenerateTextResult, StepResult, StreamObjectResult, StreamTextResult, ToolSet, StopCondition, Schema, LanguageModel, EmbeddingModel, CallSettings } from "ai";
-import { type GenericActionCtx, type GenericDataModel, type PaginationOptions, type PaginationResult } from "convex/server";
+import type { FlexibleSchema, IdGenerator, InferSchema, ProviderOptions } from "@ai-sdk/provider-utils";
+import type { CallSettings, EmbeddingModel, GenerateObjectResult, GenerateTextResult, LanguageModel, ModelMessage, StepResult, StopCondition, StreamTextResult, ToolSet } from "ai";
+import { generateObject, streamObject } from "ai";
+import { type GenericDataModel, type PaginationOptions, type PaginationResult } from "convex/server";
 import type { MessageDoc, ThreadDoc } from "../component/schema.js";
 import type { threadFieldsSupportingPatch } from "../component/threads.js";
 import { type VectorDimension } from "../component/vector/tables.js";
@@ -9,21 +10,75 @@ import { type Message, type MessageStatus, type MessageWithMetadata, type Provid
 import { createTool } from "./createTool.js";
 import { type SaveMessageArgs, type SaveMessagesArgs } from "./messages.js";
 import { type StreamingOptions } from "./streaming.js";
-import type { ActionCtx, AgentComponent, ContextOptions, GenerationOutputMetadata, Options, OurObjectArgs, OurStreamObjectArgs, RawRequestResponseHandler, RunActionCtx, RunMutationCtx, RunQueryCtx, StorageOptions, StreamingTextArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler } from "./types.js";
-import type z from "zod/v3";
+import type { ActionCtx, AgentComponent, ContextOptions, DefaultObjectSchema, GenerationOutputMetadata, MaybeCustomCtx, GenerateObjectArgs, ObjectMode, ObjectSchema, Options, RawRequestResponseHandler, RunActionCtx, RunMutationCtx, RunQueryCtx, StorageOptions, StreamingTextArgs, StreamObjectArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler } from "./types.js";
+import type { DataModel } from "../component/_generated/dataModel.js";
 export { stepCountIs } from "ai";
 export { vMessageDoc, vThreadDoc } from "../component/schema.js";
-export { serializeDataOrUrl, deserializeMessage, serializeMessage, } from "../mapping.js";
+export { deserializeMessage, serializeDataOrUrl, serializeMessage, } from "../mapping.js";
 export { vAssistantMessage, vContextOptions, vMessage, vPaginationResult, vProviderMetadata, vStorageOptions, vStreamArgs, vSystemMessage, vToolMessage, vUsage, vUserMessage, } from "../validators.js";
 export type { ToolCtx } from "./createTool.js";
+export { definePlaygroundAPI, type AgentsFn, type PlaygroundAPI, } from "./definePlaygroundAPI.js";
 export { getFile, storeFile } from "./files.js";
-export { filterOutOrphanedToolMessages, fetchContextMessages, } from "./search.js";
-export { abortStream, listStreams, syncStreams } from "./streaming.js";
 export { listMessages, saveMessage, saveMessages, type SaveMessageArgs, type SaveMessagesArgs, } from "./messages.js";
-export { createThread, getThreadMetadata } from "./threads.js";
+export { fetchContextMessages, filterOutOrphanedToolMessages, } from "./search.js";
+export { abortStream, listStreams, syncStreams } from "./streaming.js";
+export { createThread, getThreadMetadata, updateThreadMetadata, searchThreadTitles, } from "./threads.js";
 export { createTool, extractText, isTool };
-export { definePlaygroundAPI, type PlaygroundAPI, type AgentsFn, } from "./definePlaygroundAPI.js";
 export type { AgentComponent, ContextOptions, MessageDoc, ProviderMetadata, RawRequestResponseHandler, StorageOptions, StreamArgs, SyncStreamsReturnValue, Thread, ThreadDoc, Usage, UsageHandler, };
+export type Config = {
+    /**
+     * The LLM model to use for generating / streaming text and objects.
+     * e.g.
+     * import { openai } from "@ai-sdk/openai"
+     * const myAgent = new Agent(components.agent, {
+     *   languageModel: openai.chat("gpt-4o-mini"),
+     */
+    languageModel?: LanguageModel;
+    /**
+     * The model to use for text embeddings. Optional.
+     * If specified, it will use this for generating vector embeddings
+     * of chats, and can opt-in to doing vector search for automatic context
+     * on generateText, etc.
+     * e.g.
+     * import { openai } from "@ai-sdk/openai"
+     * const myAgent = new Agent(components.agent, {
+     *   ...
+     *   textEmbeddingModel: openai.embedding("text-embedding-3-small")
+     */
+    textEmbeddingModel?: EmbeddingModel<string>;
+    /**
+     * Options to determine what messages are included as context in message
+     * generation. To disable any messages automatically being added, pass:
+     * { recentMessages: 0 }
+     */
+    contextOptions?: ContextOptions;
+    /**
+     * Determines whether messages are automatically stored when passed as
+     * arguments or generated.
+     */
+    storageOptions?: StorageOptions;
+    /**
+     * The usage handler to use for this agent.
+     */
+    usageHandler?: UsageHandler;
+    /**
+     * Called for each LLM request/response, so you can do things like
+     * log the raw request body or response headers to a table, or logs.
+     */
+    rawRequestResponseHandler?: RawRequestResponseHandler;
+    /**
+     * Default provider options to pass for the LLM calls.
+     * This can be overridden at each generate/stream callsite on a per-field
+     * basis. To clear a default setting, you'll need to pass `undefined`.
+     */
+    providerOptions?: ProviderOptions;
+    /**
+     * The default settings to use for the LLM calls.
+     * This can be overridden at each generate/stream callsite on a per-field
+     * basis. To clear a default setting, you'll need to pass `undefined`.
+     */
+    callSettings?: CallSettings;
+};
 export declare class Agent<
 /**
  * You can require that all `ctx` args to generateText & streamText
@@ -46,31 +101,20 @@ export declare class Agent<
  */
 CustomCtx extends object = object, AgentTools extends ToolSet = any> {
     component: AgentComponent;
-    options: {
+    options: Config & {
         /**
          * The name for the agent. This will be attributed on each message
          * created by this agent.
          */
-        name?: string;
+        name: string;
         /**
          * The LLM model to use for generating / streaming text and objects.
          * e.g.
          * import { openai } from "@ai-sdk/openai"
          * const myAgent = new Agent(components.agent, {
-         *   chat: openai.chat("gpt-4o-mini"),
+         *   languageModel: openai.chat("gpt-4o-mini"),
          */
-        chat: LanguageModel;
-        /**
-         * The model to use for text embeddings. Optional.
-         * If specified, it will use this for generating vector embeddings
-         * of chats, and can opt-in to doing vector search for automatic context
-         * on generateText, etc.
-         * e.g.
-         * import { openai } from "@ai-sdk/openai"
-         * const myAgent = new Agent(components.agent, {
-         *   textEmbedding: openai.embedding("text-embedding-3-small")
-         */
-        textEmbedding?: EmbeddingModel<string>;
+        languageModel: LanguageModel;
         /**
          * The default system prompt to put in each request.
          * Override per-prompt by passing the "system" parameter.
@@ -83,63 +127,30 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * (import { createTool } from "@convex-dev/agent")
          */
         tools?: AgentTools;
-        /**
-         * Options to determine what messages are included as context in message
-         * generation. To disable any messages automatically being added, pass:
-         * { recentMessages: 0 }
-         */
-        contextOptions?: ContextOptions;
-        /**
-         * Determines whether messages are automatically stored when passed as
-         * arguments or generated.
-         */
-        storageOptions?: StorageOptions;
         /**
          * When generating or streaming text with tools available, this
          * determines when to stop. Defaults to stepCountIs(1).
          */
         stopWhen?: StopCondition<AgentTools> | Array<StopCondition<AgentTools>>;
         /**
-         * The default settings to use for the LLM calls.
-         * This can be overridden at each generate/stream callsite on a per-field
-         * basis. To clear a default setting, you'll need to pass `undefined`.
-         */
-        callSettings?: CallSettings;
-        /**
-         * The usage handler to use for this agent.
+         * @deprecated Use `languageEmbeddingModel` instead.
          */
-        usageHandler?: UsageHandler;
-        /**
-         * Called for each LLM request/response, so you can do things like
-         * log the raw request body or response headers to a table, or logs.
-         */
-        rawRequestResponseHandler?: RawRequestResponseHandler;
+        chat?: LanguageModel;
     };
-    constructor(component: AgentComponent, options: {
+    constructor(component: AgentComponent, options: Config & {
         /**
          * The name for the agent. This will be attributed on each message
          * created by this agent.
          */
-        name?: string;
+        name: string;
         /**
          * The LLM model to use for generating / streaming text and objects.
          * e.g.
          * import { openai } from "@ai-sdk/openai"
          * const myAgent = new Agent(components.agent, {
-         *   chat: openai.chat("gpt-4o-mini"),
-         */
-        chat: LanguageModel;
-        /**
-         * The model to use for text embeddings. Optional.
-         * If specified, it will use this for generating vector embeddings
-         * of chats, and can opt-in to doing vector search for automatic context
-         * on generateText, etc.
-         * e.g.
-         * import { openai } from "@ai-sdk/openai"
-         * const myAgent = new Agent(components.agent, {
-         *   textEmbedding: openai.embedding("text-embedding-3-small")
+         *   languageModel: openai.chat("gpt-4o-mini"),
          */
-        textEmbedding?: EmbeddingModel<string>;
+        languageModel: LanguageModel;
         /**
          * The default system prompt to put in each request.
          * Override per-prompt by passing the "system" parameter.
@@ -152,37 +163,15 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * (import { createTool } from "@convex-dev/agent")
          */
         tools?: AgentTools;
-        /**
-         * Options to determine what messages are included as context in message
-         * generation. To disable any messages automatically being added, pass:
-         * { recentMessages: 0 }
-         */
-        contextOptions?: ContextOptions;
-        /**
-         * Determines whether messages are automatically stored when passed as
-         * arguments or generated.
-         */
-        storageOptions?: StorageOptions;
         /**
          * When generating or streaming text with tools available, this
          * determines when to stop. Defaults to stepCountIs(1).
          */
         stopWhen?: StopCondition<AgentTools> | Array<StopCondition<AgentTools>>;
         /**
-         * The default settings to use for the LLM calls.
-         * This can be overridden at each generate/stream callsite on a per-field
-         * basis. To clear a default setting, you'll need to pass `undefined`.
-         */
-        callSettings?: CallSettings;
-        /**
-         * The usage handler to use for this agent.
+         * @deprecated Use `languageEmbeddingModel` instead.
          */
-        usageHandler?: UsageHandler;
-        /**
-         * Called for each LLM request/response, so you can do things like
-         * log the raw request body or response headers to a table, or logs.
-         */
-        rawRequestResponseHandler?: RawRequestResponseHandler;
+        chat?: LanguageModel;
     });
     /**
      * Start a new thread with the agent. This will have a fresh history, though if
@@ -194,7 +183,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * @param args The thread metadata.
      * @returns The threadId of the new thread and the thread object.
      */
-    createThread<ThreadTools extends ToolSet | undefined = undefined>(ctx: RunActionCtx & CustomCtx, args?: {
+    createThread(ctx: RunActionCtx & CustomCtx, args?: {
         /**
          * The userId to associate with the thread. If not provided, the thread will be
          * anonymous.
@@ -208,19 +197,9 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * The summary of the thread. Not currently used for anything.
          */
         summary?: string;
-        /**
-         * The usage handler to use for this thread. Overrides any handler
-         * set in the agent constructor.
-         */
-        usageHandler?: UsageHandler;
-        /**
-         * The tools to use for this thread.
-         * Overrides any tools passed in the agent constructor.
-         */
-        tools?: ThreadTools;
     }): Promise<{
         threadId: string;
-        thread: Thread<ThreadTools extends undefined ? AgentTools : ThreadTools>;
+        thread: Thread<AgentTools>;
     }>;
     /**
      * Start a new thread with the agent. This will have a fresh history, though if
@@ -231,7 +210,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * @param args The thread metadata.
      * @returns The threadId of the new thread.
      */
-    createThread<ThreadTools extends ToolSet | undefined = undefined>(ctx: RunMutationCtx, args?: {
+    createThread(ctx: RunMutationCtx, args?: {
         /**
          * The userId to associate with the thread. If not provided, the thread will be
          * anonymous.
@@ -245,16 +224,6 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * The summary of the thread. Not currently used for anything.
          */
         summary?: string;
-        /**
-         * The usage handler to use for this thread. Overrides any handler
-         * set in the agent constructor.
-         */
-        usageHandler?: UsageHandler;
-        /**
-         * The tools to use for this thread.
-         * Overrides any tools passed in the agent constructor.
-         */
-        tools?: ThreadTools;
     }): Promise<{
         threadId: string;
     }>;
@@ -266,7 +235,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * @param { threadId, userId }: the thread and user to associate the messages with.
      * @returns Functions bound to the userId and threadId on a `{thread}` object.
      */
-    continueThread<ThreadTools extends ToolSet | undefined = undefined>(ctx: ActionCtx & CustomCtx, args: {
+    continueThread(ctx: ActionCtx & CustomCtx, args: {
         /**
          * The associated thread created by {@link createThread}
          */
@@ -276,18 +245,86 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * relevant messages from the same user as context for the LLM calls.
          */
         userId?: string | null;
+    }): Promise<{
+        thread: Thread<AgentTools>;
+    }>;
+    start<TOOLS extends ToolSet | undefined, T>(ctx: ActionCtx & CustomCtx, 
+    /**
+     * 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.
+     */
+    args: T & {
         /**
-         * The usage handler to use for this thread. Overrides any handler
-         * set in the agent constructor.
+         * If provided, this message will be used as the "prompt" for the LLM call,
+         * instead of the prompt or messages.
+         * This is useful if you want to first save a user message, then use it as
+         * the prompt for the LLM call in another call.
          */
-        usageHandler?: UsageHandler;
+        promptMessageId?: string;
         /**
-         * The tools to use for this thread.
-         * Overrides any tools passed in the agent constructor.
+         * The model to use for the LLM calls. This will override the model specified
+         * in the Agent constructor.
          */
-        tools?: ThreadTools;
+        model?: LanguageModel;
+        /**
+         * The tools to use for the tool calls. This will override tools specified
+         * in the Agent constructor or createThread / continueThread.
+         */
+        tools?: TOOLS;
+        /**
+         * The single prompt message to use for the LLM call. This will be the
+         * last message in the context. If it's a string, it will be a user role.
+         */
+        prompt?: string | (ModelMessage | Message)[];
+        /**
+         * If provided alongside prompt, the ordering will be:
+         * 1. system prompt
+         * 2. search context
+         * 3. recent messages
+         * 4. these messages
+         * 5. prompt messages, including those already on the same `order` as
+         *   the promptMessageId message, if provided.
+         */
+        messages?: (ModelMessage | Message)[];
+        /**
+         * This will be the first message in the context, and overrides the
+         * agent's instructions.
+         */
+        system?: string;
+        /**
+         * The abort signal to be passed to the LLM call. If triggered, it will
+         * mark the pending message as failed. If the generation is asynchronously
+         * aborted, it will trigger this signal when detected.
+         */
+        abortSignal?: AbortSignal;
+        _internal?: {
+            generateId?: IdGenerator;
+        };
+    }, options?: Options & {
+        userId?: string | null;
+        threadId?: string;
     }): Promise<{
-        thread: Thread<ThreadTools extends undefined ? AgentTools : ThreadTools>;
+        args: T & {
+            system?: string;
+            model: LanguageModel;
+            messages: ModelMessage[];
+            tools?: TOOLS extends undefined ? AgentTools : TOOLS;
+        } & CallSettings;
+        order: number;
+        stepOrder: number;
+        userId: string | undefined;
+        promptMessageId: string | undefined;
+        updateModel: (model: LanguageModel | undefined) => void;
+        save: <TOOLS extends ToolSet>(toSave: {
+            step: StepResult<TOOLS>;
+        } | {
+            object: GenerateObjectResult<unknown>;
+        }, createPendingMessage?: boolean) => Promise<void>;
+        fail: (reason: string) => Promise<void>;
+        getSavedMessages: () => MessageDoc[];
     }>;
     /**
      * This behaves like {@link generateText} from the "ai" package except that
@@ -297,21 +334,14 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * 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
+     * @param generateTextArgs The arguments to the generateText function, along with extra controls
      * for the {@link ContextOptions} and {@link StorageOptions}.
      * @returns The result of the generateText function.
      */
-    generateText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, OUTPUT_PARTIAL = never>(ctx: ActionCtx & CustomCtx, { userId: argsUserId, threadId, tools: threadTools, ...usageHandler }: {
+    generateText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, OUTPUT_PARTIAL = never>(ctx: ActionCtx & CustomCtx, threadOpts: {
         userId?: string | null;
         threadId?: string;
-        /**
-         * The usage handler to use for this thread. Overrides any handler
-         * set in the agent constructor.
-         */
-        usageHandler?: UsageHandler;
-        /** Note: to get better type inference, pass tools in the next arg */
-        tools?: ToolSet;
-    }, args: TextArgs<AgentTools, TOOLS, OUTPUT, OUTPUT_PARTIAL>, options?: Options): Promise<GenerateTextResult<TOOLS extends undefined ? AgentTools : TOOLS, OUTPUT> & GenerationOutputMetadata>;
+    }, generateTextArgs: TextArgs<AgentTools, TOOLS, OUTPUT, OUTPUT_PARTIAL>, options?: Options): Promise<GenerateTextResult<TOOLS extends undefined ? AgentTools : TOOLS, OUTPUT> & GenerationOutputMetadata>;
     /**
      * This behaves like {@link streamText} from the "ai" package except that
      * it add context based on the userId and threadId and saves the input and
@@ -319,18 +349,14 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    streamText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, PARTIAL_OUTPUT = never>(ctx: ActionCtx & CustomCtx, { userId: argsUserId, threadId, 
-    /** Note: to get better type inference, pass tools in the next arg */
-    tools: threadTools, ...usageHandler }: {
+    streamText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, PARTIAL_OUTPUT = never>(ctx: ActionCtx & CustomCtx, threadOpts: {
         userId?: string | null;
         threadId?: string;
-        usageHandler?: UsageHandler;
-        tools?: ToolSet;
     }, 
     /**
      * The arguments to the streamText function, similar to the ai `streamText` function.
      */
-    args: StreamingTextArgs<AgentTools, TOOLS, OUTPUT, PARTIAL_OUTPUT>, 
+    streamTextArgs: StreamingTextArgs<AgentTools, TOOLS, OUTPUT, PARTIAL_OUTPUT>, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
@@ -355,20 +381,19 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    generateObject<T>(ctx: ActionCtx, { userId: argsUserId, threadId, ...usageHandler }: {
+    generateObject<SCHEMA extends ObjectSchema = DefaultObjectSchema, OUTPUT extends ObjectMode = InferSchema<SCHEMA> extends string ? "enum" : "object", RESULT = OUTPUT extends "array" ? Array<InferSchema<SCHEMA>> : InferSchema<SCHEMA>>(ctx: ActionCtx & CustomCtx, threadOpts: {
         userId?: string | null;
         threadId?: string;
-        usageHandler?: UsageHandler;
     }, 
     /**
      * The arguments to the generateObject function, similar to the ai.generateObject function.
      */
-    args: OurObjectArgs<T>, 
+    generateObjectArgs: GenerateObjectArgs<SCHEMA, OUTPUT, RESULT>, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
      */
-    options?: Options): Promise<GenerateObjectResult<T> & GenerationOutputMetadata>;
+    options?: Options): Promise<GenerateObjectResult<RESULT> & GenerationOutputMetadata>;
     /**
      * This behaves like `streamObject` from the "ai" package except that
      * it add context based on the userId and threadId and saves the input and
@@ -376,20 +401,32 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * Use {@link continueThread} to get a version of this function already scoped
      * to a thread (and optionally userId).
      */
-    streamObject<T extends z.Schema | Schema>(ctx: ActionCtx, { userId: argsUserId, threadId, ...usageHandler }: {
+    streamObject<SCHEMA extends ObjectSchema = DefaultObjectSchema, OUTPUT extends ObjectMode = InferSchema<SCHEMA> extends string ? "enum" : "object", RESULT = OUTPUT extends "array" ? Array<InferSchema<SCHEMA>> : InferSchema<SCHEMA>>(ctx: ActionCtx & CustomCtx, threadOpts: {
         userId?: string | null;
         threadId?: string;
-        usageHandler?: UsageHandler;
     }, 
     /**
      * The arguments to the streamObject function, similar to the ai `streamObject` function.
      */
-    args: OurStreamObjectArgs<T>, 
+    streamObjectArgs: StreamObjectArgs<SCHEMA, OUTPUT, RESULT> & {
+        /**
+         * If provided, this message will be used as the "prompt" for the LLM call,
+         * instead of the prompt or messages.
+         * This is useful if you want to first save a user message, then use it as
+         * the prompt for the LLM call in another call.
+         */
+        promptMessageId?: string;
+        /**
+         * The model to use for the LLM calls. This will override the model specified
+         * in the Agent constructor.
+         */
+        model?: LanguageModel;
+    }, 
     /**
      * The {@link ContextOptions} and {@link StorageOptions}
      * options to use for fetching contextual messages and saving input/output messages.
      */
-    options?: Options): Promise<StreamObjectResult<DeepPartial<T>, T, never> & GenerationOutputMetadata>;
+    options?: Options): Promise<ReturnType<typeof streamObject<SCHEMA, OUTPUT, RESULT>> & GenerationOutputMetadata>;
     /**
      * Save a message to the thread.
      * @param ctx A ctx object from a mutation or action.
@@ -507,9 +544,9 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 title?: string | undefined;
                 type?: "source" | undefined;
                 providerOptions?: Record<string, Record<string, any>> | undefined;
-                url?: string | undefined;
                 id: string;
                 sourceType: "url";
+                url: string;
             } | {
                 filename?: string | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -519,6 +556,19 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 sourceType: "document";
                 mediaType: string;
             })[] | undefined;
+            warnings?: ({
+                details?: string | undefined;
+                type: "unsupported-setting";
+                setting: string;
+            } | {
+                details?: string | undefined;
+                type: "unsupported-tool";
+                tool: any;
+            } | {
+                type: "other";
+                message: string;
+            })[] | undefined;
+            finishReason?: "length" | "error" | "other" | "stop" | "content-filter" | "tool-calls" | "unknown" | undefined;
             reasoningDetails?: ({
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 signature?: string | undefined;
@@ -533,19 +583,6 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 type: "redacted";
                 data: string;
             })[] | undefined;
-            warnings?: ({
-                details?: string | undefined;
-                type: "unsupported-setting";
-                setting: string;
-            } | {
-                details?: string | undefined;
-                type: "unsupported-tool";
-                tool: any;
-            } | {
-                type: "other";
-                message: string;
-            })[] | undefined;
-            finishReason?: "length" | "error" | "other" | "stop" | "content-filter" | "tool-calls" | "unknown" | undefined;
             _id: string;
             _creationTime: number;
             status: "pending" | "success" | "failed";
@@ -722,14 +759,13 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * @param args What message to save. Generally the parent message sent into
      *   the generateText call.
      */
-    completeMessage(ctx: RunMutationCtx, args: {
-        threadId: string;
+    finalizeMessage(ctx: RunMutationCtx, args: {
         messageId: string;
         result: {
-            kind: "error";
+            status: "failed";
             error: string;
         } | {
-            kind: "success";
+            status: "success";
         };
     }): Promise<void>;
     /**
@@ -849,21 +885,23 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
         pageSize?: number;
     }): Promise<void>;
     _saveMessagesAndFetchContext<T extends {
-        id?: string;
         prompt?: string | (ModelMessage | Message)[];
         messages?: (ModelMessage | Message)[];
         system?: string;
         promptMessageId?: string;
-        model?: LanguageModelV2;
+        pendingMessageId?: string;
+        model?: LanguageModel;
     }>(ctx: RunActionCtx, args: T, { userId: argsUserId, threadId, contextOptions, storageOptions, }: {
-        userId: string | undefined;
+        userId: string | null | undefined;
         threadId: string | undefined;
     } & Options): Promise<{
-        args: T & {
-            model: LanguageModelV2;
-        };
+        args: Extract<T, {
+            model: LanguageModel;
+            messages: ModelMessage[];
+        }> & CallSettings;
         userId: string | undefined;
-        messageId: string | undefined;
+        promptMessageId: string | undefined;
+        pendingMessageId: string | undefined;
         order: number | undefined;
         stepOrder: number | undefined;
         savedMessages: MessageDoc[] | undefined;
@@ -877,20 +915,6 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
     }): Promise<{
         embeddings: number[][];
     }>;
-    /**
-     * 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.
-     */
-    private _inlineMessagesFiles;
-    /**
-     * Check if a URL points to localhost
-     */
-    private _isLocalhostUrl;
-    /**
-     * Download a file from a URL
-     */
-    private _downloadFile;
     /**
      * WORKFLOW UTILITIES
      */
@@ -925,23 +949,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * @param spec Configuration for the agent acting as an action, including
      *   {@link ContextOptions}, {@link StorageOptions}, and {@link stopWhen}.
      */
-    asTextAction<DataModel extends GenericDataModel>(spec?: {
-        /**
-         * When to stop generating text.
-         * Defaults to the {@link Agent["options"].stopWhen} option.
-         */
-        stopWhen?: StopCondition<AgentTools> | Array<StopCondition<AgentTools>>;
-        /**
-         * The {@link ContextOptions} to use for fetching contextual messages and
-         * saving input/output messages.
-         * Defaults to the {@link Agent.contextOptions} option.
-         */
-        contextOptions?: ContextOptions;
-        /**
-         * The {@link StorageOptions} to use for saving input/output messages.
-         * Defaults to the {@link Agent.storageOptions} option.
-         */
-        storageOptions?: StorageOptions;
+    asTextAction<DataModel extends GenericDataModel>(spec: MaybeCustomCtx<CustomCtx, DataModel, AgentTools> & {
         /**
          * Whether to stream the text.
          * If false, it will generate the text in a single call. (default)
@@ -950,30 +958,12 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
          * defaults if you pass true.
          */
         stream?: boolean | StreamingOptions;
-    } & (CustomCtx extends Record<string, unknown> ? {
         /**
-         * If you have a custom ctx that you use with the Agent
-         * (e.g. new Agent<{ orgId: string }>(...))
-         * you need to provide this function to add any extra fields.
-         * e.g.
-         * ```ts
-         * const myAgent = new Agent<{ orgId: string }>(...);
-         * const myAction = myAgent.asTextAction({
-         *   customCtx: (ctx: ActionCtx, target, llmArgs) => {
-         *     const orgId = await lookupOrgId(ctx, target.threadId);
-         *     return { orgId };
-         *   },
-         * });
-         * ```
-         * Then, in your tools, you can
+         * When to stop generating text.
+         * Defaults to the {@link Agent["options"].stopWhen} option.
          */
-        customCtx: (ctx: GenericActionCtx<DataModel>, target: {
-            userId?: string | undefined;
-            threadId?: string | undefined;
-        }, llmArgs: TextArgs<AgentTools>) => CustomCtx;
-    } : {
-        customCtx?: never;
-    })): import("convex/server").RegisteredAction<"internal", {
+        stopWhen?: StopCondition<AgentTools> | Array<StopCondition<AgentTools>>;
+    } & Options, overrides?: CallSettings): import("convex/server").RegisteredAction<"internal", {
         userId?: string | undefined;
         threadId?: string | undefined;
         providerOptions?: Record<string, Record<string, any>> | undefined;
@@ -1095,16 +1085,18 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
         } | undefined;
     }, Promise<{
         text: string;
-        messageId: string | undefined;
+        promptMessageId: string | undefined;
         order: number | undefined;
         finishReason: import("@ai-sdk/provider").LanguageModelV2FinishReason;
         warnings: Promise<import("@ai-sdk/provider").LanguageModelV2CallWarning[] | undefined>;
+        savedMessageIds: string[];
     } | {
         text: string;
-        messageId: string | undefined;
+        promptMessageId: string | undefined;
         order: number | undefined;
         finishReason: import("@ai-sdk/provider").LanguageModelV2FinishReason;
         warnings: import("@ai-sdk/provider").LanguageModelV2CallWarning[] | undefined;
+        savedMessageIds: string[];
     }>>;
     /**
      * Create an action that generates an object out of this agent so you can call
@@ -1113,10 +1105,7 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
      * the normal parameters to {@link generateObject}, plus {@link ContextOptions}
      * and stopWhen.
      */
-    asObjectAction<T>(spec: OurObjectArgs<T>, options?: {
-        contextOptions?: ContextOptions;
-        storageOptions?: StorageOptions;
-    }): import("convex/server").RegisteredAction<"internal", {
+    asObjectAction<T>(objectArgs: Omit<Parameters<typeof generateObject<FlexibleSchema<T>>>[0], "model">, options?: Options & MaybeCustomCtx<CustomCtx, DataModel, AgentTools>): import("convex/server").RegisteredAction<"internal", {
         userId?: string | undefined;
         threadId?: string | undefined;
         providerOptions?: Record<string, Record<string, any>> | undefined;
@@ -1231,10 +1220,11 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
         } | undefined;
     }, Promise<{
         object: T;
-        messageId: string | undefined;
+        promptMessageId: string | undefined;
         order: number | undefined;
         finishReason: import("@ai-sdk/provider").LanguageModelV2FinishReason;
         warnings: import("@ai-sdk/provider").LanguageModelV2CallWarning[] | undefined;
+        savedMessageIds: string[];
     }>>;
     /**
      * Save messages to the thread.
@@ -1285,9 +1275,9 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 title?: string | undefined;
                 type?: "source" | undefined;
                 providerOptions?: Record<string, Record<string, any>> | undefined;
-                url?: string | undefined;
                 id: string;
                 sourceType: "url";
+                url: string;
             } | {
                 filename?: string | undefined;
                 providerMetadata?: Record<string, Record<string, any>> | undefined;
@@ -1297,6 +1287,19 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 sourceType: "document";
                 mediaType: string;
             })[] | undefined;
+            warnings?: ({
+                details?: string | undefined;
+                type: "unsupported-setting";
+                setting: string;
+            } | {
+                details?: string | undefined;
+                type: "unsupported-tool";
+                tool: any;
+            } | {
+                type: "other";
+                message: string;
+            })[] | undefined;
+            finishReason?: "length" | "error" | "other" | "stop" | "content-filter" | "tool-calls" | "unknown" | undefined;
             reasoningDetails?: ({
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 signature?: string | undefined;
@@ -1311,19 +1314,6 @@ CustomCtx extends object = object, AgentTools extends ToolSet = any> {
                 type: "redacted";
                 data: string;
             })[] | undefined;
-            warnings?: ({
-                details?: string | undefined;
-                type: "unsupported-setting";
-                setting: string;
-            } | {
-                details?: string | undefined;
-                type: "unsupported-tool";
-                tool: any;
-            } | {
-                type: "other";
-                message: string;
-            })[] | undefined;
-            finishReason?: "length" | "error" | "other" | "stop" | "content-filter" | "tool-calls" | "unknown" | undefined;
             message: {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 role: "user";