@convex-dev/agent 0.1.6 → 0.1.7-alpha.0

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

@@ -5,10 +5,12 @@ import type { MessageDoc, ThreadDoc } from "../component/schema.js";
 import { type VectorDimension } from "../component/vector/tables.js";
 import { type AIMessageWithoutId } from "../mapping.js";
 import { extractText, isTool } from "../shared.js";
-import { type MessageWithMetadata as InnerMessageWithMetadata, type MessageStatus, type ProviderMetadata, type SearchOptions, type StreamArgs, type Usage } from "../validators.js";
+import { type MessageWithMetadata, type MessageStatus, type ProviderMetadata, type SearchOptions, type StreamArgs, type Usage } from "../validators.js";
 import { createTool } from "./createTool.js";
 import { type StreamingOptions } from "./streaming.js";
-import type { AgentComponent, ContextOptions, GenerationOutputMetadata, OpaqueIds, Options, OurObjectArgs, OurStreamObjectArgs, RunActionCtx, RunMutationCtx, RunQueryCtx, StorageOptions, StreamingTextArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler } from "./types.js";
+import type { AgentComponent, ContextOptions, GenerationOutputMetadata, Options, OurObjectArgs, OurStreamObjectArgs, RawRequestResponseHandler, RunActionCtx, RunMutationCtx, RunQueryCtx, ActionCtx, StorageOptions, StreamingTextArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler } from "./types.js";
+export { storeFile, getFile } from "./files.js";
+export { serializeDataOrUrl } from "../mapping.js";
 export { vMessageDoc, vThreadDoc } from "../component/schema.js";
 export { vAssistantMessage, vContextOptions, vMessage, vPaginationResult, vProviderMetadata, vStorageOptions, vStreamArgs, vSystemMessage, vToolMessage, vUsage, vUserMessage, } from "../validators.js";
 export type { ToolCtx } from "./createTool.js";
@@ -78,6 +80,11 @@ export declare class Agent<AgentTools extends ToolSet> {
          * 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;
     };
     constructor(component: AgentComponent, options: {
         /**
@@ -141,6 +148,11 @@ export declare class Agent<AgentTools extends ToolSet> {
          * 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;
     });
     /**
      * Start a new thread with the agent. This will have a fresh history, though if
@@ -224,7 +236,7 @@ export declare class Agent<AgentTools extends ToolSet> {
      * @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: RunActionCtx, args: {
+    continueThread<ThreadTools extends ToolSet | undefined = undefined>(ctx: ActionCtx, args: {
         /**
          * The associated thread created by {@link createThread}
          */
@@ -248,93 +260,116 @@ export declare class Agent<AgentTools extends ToolSet> {
         thread: Thread<ThreadTools extends undefined ? AgentTools : ThreadTools>;
     }>;
     /**
-     * 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.
+     * This behaves like {@link generateText} from the "ai" package except that
+     * it add context based on the userId and threadId and saves the input and
+     * resulting messages to the thread, if specified.
+     * 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}.
+     * @returns The result of the generateText function.
      */
-    getThreadMetadata(ctx: RunQueryCtx, args: {
-        threadId: string;
-    }): Promise<ThreadDoc>;
+    generateText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, OUTPUT_PARTIAL = never>(ctx: ActionCtx, { userId: argsUserId, threadId, usageHandler, tools: threadTools, }: {
+        userId?: string;
+        threadId?: string;
+        /**
+         * The usage handler to use for this thread. Overrides any handler
+         * set in the agent constructor.
+         */
+        usageHandler?: UsageHandler;
+        /** @deprecated Pass `tools` in the next parameter instead. This is only intended to pass through thread-default tools.  */
+        tools?: ToolSet;
+    }, args: TextArgs<AgentTools, TOOLS, OUTPUT, OUTPUT_PARTIAL>, options?: Options): Promise<GenerateTextResult<TOOLS extends undefined ? AgentTools : TOOLS, OUTPUT> & GenerationOutputMetadata>;
     /**
-     * Update the metadata for a thread.
-     * @param ctx A ctx object from a mutation or action.
-     * @param args.threadId The thread to update the metadata for.
-     * @param args.patch The patch to apply to the thread.
-     * @returns The updated thread metadata.
+     * 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
+     * resulting messages to the thread, if specified.
+     * Use {@link continueThread} to get a version of this function already scoped
+     * to a thread (and optionally userId).
      */
-    updateThreadMetadata(ctx: RunMutationCtx, args: {
-        threadId: string;
-        patch: Partial<WithoutSystemFields<ThreadDoc>>;
-    }): Promise<ThreadDoc>;
+    streamText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, PARTIAL_OUTPUT = never>(ctx: ActionCtx, { userId: argsUserId, threadId, usageHandler, 
     /**
-     * List messages from a thread.
-     * @param ctx A ctx object from a query, mutation, or action.
-     * @param args.threadId The thread to list messages from.
-     * @param args.paginationOpts Pagination options (e.g. via usePaginatedQuery).
-     * @param args.excludeToolMessages Whether to exclude tool messages.
-     *   False by default.
-     * @param args.statuses What statuses to include. All by default.
-     * @returns The MessageDoc's in a format compatible with usePaginatedQuery.
+     * @deprecated Pass `tools` in the next parameter instead.
+     * This is only intended to pass through thread-default tools.
      */
-    listMessages(ctx: RunQueryCtx, args: {
-        threadId: string;
-        paginationOpts: PaginationOptions;
-        excludeToolMessages?: boolean;
-        statuses?: MessageStatus[];
-    }): Promise<PaginationResult<MessageDoc>>;
+    tools: threadTools, }: {
+        userId?: string;
+        threadId?: string;
+        usageHandler?: UsageHandler;
+        tools?: ToolSet;
+    }, 
     /**
-     * A function that handles fetching stream deltas, used with the React hooks
-     * `useThreadMessages` or `useStreamingThreadMessages`.
-     * @param ctx A ctx object from a query, mutation, or action.
-     * @param args.threadId The thread to sync streams for.
-     * @param args.streamArgs The stream arguments with per-stream cursors.
-     * @returns The deltas for each stream from their existing cursor.
+     * The arguments to the streamText function, similar to the ai `streamText` function.
      */
-    syncStreams(ctx: RunQueryCtx, args: {
-        threadId: string;
-        streamArgs: StreamArgs | undefined;
-    }): Promise<SyncStreamsReturnValue | undefined>;
+    args: StreamingTextArgs<AgentTools, TOOLS, OUTPUT, PARTIAL_OUTPUT>, 
     /**
-     * Fetch the context messages for a thread.
-     * @param ctx Either a query, mutation, or action ctx.
-     *   If it is not an action context, you can't do text or
-     *   vector search.
-     * @param args The associated thread, user, message
-     * @returns
+     * The {@link ContextOptions} and {@link StorageOptions}
+     * options to use for fetching contextual messages and saving input/output messages.
      */
-    fetchContextMessages(ctx: RunQueryCtx | RunActionCtx, args: {
-        userId: string | undefined;
-        threadId: string | undefined;
-        messages: CoreMessage[];
+    options?: Options & {
         /**
-         * If provided, it will search for messages up to and including this message.
-         * Note: if this is far in the past, text and vector search results may be more
-         * limited, as it's post-filtering the results.
+         * Whether to save incremental data (deltas) from streaming responses.
+         * Defaults to false.
+         * If false, it will not save any deltas to the database.
+         * If true, it will save deltas with {@link DEFAULT_STREAMING_OPTIONS}.
+         *
+         * Regardless of this option, when streaming you are able to use this
+         * `streamText` function as you would with the "ai" package's version:
+         * iterating over the text, streaming it over HTTP, etc.
          */
-        upToAndIncludingMessageId?: string;
-        contextOptions: ContextOptions | undefined;
-    }): Promise<MessageDoc[]>;
+        saveStreamDeltas?: boolean | StreamingOptions;
+    }): Promise<StreamTextResult<TOOLS extends undefined ? AgentTools : TOOLS, PARTIAL_OUTPUT> & GenerationOutputMetadata>;
     /**
-     * Get the embeddings for a set of messages.
-     * @param messages The messages to get the embeddings for.
-     * @returns The embeddings for the messages.
+     * This behaves like {@link generateObject} from the "ai" package except that
+     * it add context based on the userId and threadId and saves the input and
+     * resulting messages to the thread, if specified.
+     * Use {@link continueThread} to get a version of this function already scoped
+     * to a thread (and optionally userId).
      */
-    generateEmbeddings(messages: CoreMessage[]): Promise<{
-        vectors: (number[] | null)[];
-        dimension: VectorDimension;
-        model: string;
-    } | undefined>;
+    generateObject<T>(ctx: RunActionCtx, { userId: argsUserId, threadId, usageHandler, }: {
+        userId?: string;
+        threadId?: string;
+        usageHandler?: UsageHandler;
+    }, 
     /**
-     * Generate embeddings for a set of messages, and save them to the database.
-     * It will not generate or save embeddings for messages that already have an
-     * embedding.
-     * @param ctx The ctx parameter to an action.
-     * @param args The messageIds to generate embeddings for.
+     * The arguments to the generateObject function, similar to the ai.generateObject function.
+     */
+    args: OurObjectArgs<T>, 
+    /**
+     * The {@link ContextOptions} and {@link StorageOptions}
+     * options to use for fetching contextual messages and saving input/output messages.
+     */
+    options?: Options): Promise<GenerateObjectResult<T> & 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
+     * resulting messages to the thread, if specified.
+     * Use {@link continueThread} to get a version of this function already scoped
+     * to a thread (and optionally userId).
+     */
+    streamObject<T>(ctx: RunActionCtx, { userId: argsUserId, threadId, usageHandler, }: {
+        userId?: string;
+        threadId?: string;
+        usageHandler?: UsageHandler;
+    }, 
+    /**
+     * The arguments to the streamObject function, similar to the ai `streamObject` function.
+     */
+    args: OurStreamObjectArgs<T>, 
+    /**
+     * 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>;
+    /**
+     * 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.
      */
-    generateAndSaveEmbeddings(ctx: RunActionCtx, args: {
-        messageIds: string[];
-    }): Promise<void>;
     saveMessage(ctx: RunMutationCtx, args: {
         threadId: string;
         userId?: string;
@@ -361,116 +396,18 @@ export declare class Agent<AgentTools extends ToolSet> {
         message?: undefined;
     })): Promise<{
         messageId: string;
-    }>;
-    /**
-     * Explicitly save messages associated with the thread (& user if provided)
-     * @param ctx The ctx parameter to a mutation or action.
-     * @param args The messages and context to save
-     * @returns
-     */
-    saveMessages(ctx: RunMutationCtx, args: {
-        threadId: string;
-        userId?: string;
-        /**
-         * The message that these messages are in response to. They will be
-         * the same "order" as this message, at increasing stepOrder(s).
-         */
-        promptMessageId?: string;
-        /**
-         * The messages to save.
-         */
-        messages: CoreMessageMaybeWithId[];
-        /**
-         * Metadata to save with the messages. Each element corresponds to the
-         * message at the same index.
-         */
-        metadata?: Omit<MessageWithMetadata, "message">[];
-        /**
-         * If false, it will "commit" the messages immediately.
-         * If true, it will mark them as pending until the final step has finished.
-         * Defaults to false.
-         */
-        pending?: boolean;
-        /**
-         * If true, it will fail any pending steps.
-         * Defaults to false.
-         */
-        failPendingSteps?: boolean;
-        /**
-         * Skip generating embeddings for the messages. Useful if you're
-         * saving messages in a mutation where you can't run `fetch`.
-         * You can generate them asynchronously by using the scheduler to run an
-         * action later that calls `agent.generateAndSaveEmbeddings`.
-         */
-        skipEmbeddings?: boolean;
-    }): Promise<{
-        lastMessageId: string;
-        messages: MessageDoc[];
-    }>;
-    /**
-     * Save messages to the thread.
-     * Useful as a step in Workflows, e.g.
-     * ```ts
-     * const saveMessages = agent.asSaveMessagesMutation();
-     *
-     * const myWorkflow = workflow.define()
-     * ```
-     * @returns A mutation that can be used to save messages to the thread.
-     */
-    asSaveMessagesMutation(): import("convex/server").RegisteredMutation<"internal", {
-        userId?: string | undefined;
-        pending?: boolean | undefined;
-        promptMessageId?: string | undefined;
-        failPendingSteps?: boolean | undefined;
-        threadId: string;
-        messages: {
+        message: {
             id?: string | undefined;
+            userId?: string | undefined;
+            embeddingId?: string | undefined;
+            fileIds?: string[] | undefined;
+            files?: any[] | undefined;
             error?: string | undefined;
+            agentName?: string | undefined;
             model?: string | undefined;
             provider?: string | undefined;
-            text?: string | undefined;
-            reasoning?: string | undefined;
-            files?: {
-                data?: string | ArrayBuffer | undefined;
-                url?: string | undefined;
-                fileId?: import("convex/values").GenericId<"files"> | undefined;
-                mimeType: string;
-            }[] | undefined;
-            usage?: {
-                promptTokens: number;
-                completionTokens: number;
-                totalTokens: number;
-            } | undefined;
-            providerMetadata?: Record<string, Record<string, any>> | undefined;
-            sources?: {
-                title?: string | undefined;
-                providerOptions?: Record<string, Record<string, any>> | undefined;
-                id: string;
-                url: string;
-                sourceType: "url";
-            }[] | undefined;
-            reasoningDetails?: ({
-                signature?: string | undefined;
-                type: "text";
-                text: string;
-            } | {
-                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;
+            message?: {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 role: "user";
                 content: string | ({
@@ -542,18 +479,194 @@ export declare class Agent<AgentTools extends ToolSet> {
                 providerOptions?: Record<string, Record<string, any>> | undefined;
                 role: "system";
                 content: string;
-            };
-        }[];
-    }, Promise<{
+            } | undefined;
+            text?: string | undefined;
+            reasoning?: string | undefined;
+            usage?: {
+                promptTokens: number;
+                completionTokens: number;
+                totalTokens: number;
+            } | undefined;
+            providerMetadata?: Record<string, Record<string, any>> | undefined;
+            sources?: {
+                title?: string | undefined;
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                id: string;
+                sourceType: "url";
+                url: string;
+            }[] | undefined;
+            reasoningDetails?: ({
+                signature?: string | undefined;
+                type: "text";
+                text: string;
+            } | {
+                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";
+            order: number;
+            threadId: string;
+            stepOrder: number;
+            tool: boolean;
+        };
+    }>;
+    /**
+     * Explicitly save messages associated with the thread (& user if provided)
+     * @param ctx The ctx parameter to a mutation or action.
+     * @param args The messages and context to save
+     * @returns
+     */
+    saveMessages(ctx: RunMutationCtx | RunActionCtx, args: {
+        threadId: string;
+        userId?: string;
+        /**
+         * The message that these messages are in response to. They will be
+         * the same "order" as this message, at increasing stepOrder(s).
+         */
+        promptMessageId?: string;
+        /**
+         * The messages to save.
+         */
+        messages: CoreMessageMaybeWithId[];
+        /**
+         * Metadata to save with the messages. Each element corresponds to the
+         * message at the same index.
+         */
+        metadata?: Omit<MessageWithMetadata, "message">[];
+        /**
+         * If false, it will "commit" the messages immediately.
+         * If true, it will mark them as pending until the final step has finished.
+         * Defaults to false.
+         */
+        pending?: boolean;
+        /**
+         * If true, it will fail any pending steps.
+         * Defaults to false.
+         */
+        failPendingSteps?: boolean;
+        /**
+         * Skip generating embeddings for the messages. Useful if you're
+         * saving messages in a mutation where you can't run `fetch`.
+         * You can generate them asynchronously by using the scheduler to run an
+         * action later that calls `agent.generateAndSaveEmbeddings`.
+         */
+        skipEmbeddings?: boolean;
+    }): Promise<{
         lastMessageId: string;
+        messages: MessageDoc[];
+    }>;
+    /**
+     * List messages from a thread.
+     * @param ctx A ctx object from a query, mutation, or action.
+     * @param args.threadId The thread to list messages from.
+     * @param args.paginationOpts Pagination options (e.g. via usePaginatedQuery).
+     * @param args.excludeToolMessages Whether to exclude tool messages.
+     *   False by default.
+     * @param args.statuses What statuses to include. All by default.
+     * @returns The MessageDoc's in a format compatible with usePaginatedQuery.
+     */
+    listMessages(ctx: RunQueryCtx, args: {
+        threadId: string;
+        paginationOpts: PaginationOptions;
+        excludeToolMessages?: boolean;
+        statuses?: MessageStatus[];
+    }): Promise<PaginationResult<MessageDoc>>;
+    /**
+     * A function that handles fetching stream deltas, used with the React hooks
+     * `useThreadMessages` or `useStreamingThreadMessages`.
+     * @param ctx A ctx object from a query, mutation, or action.
+     * @param args.threadId The thread to sync streams for.
+     * @param args.streamArgs The stream arguments with per-stream cursors.
+     * @returns The deltas for each stream from their existing cursor.
+     */
+    syncStreams(ctx: RunQueryCtx, args: {
+        threadId: string;
+        streamArgs: StreamArgs | undefined;
+    }): Promise<SyncStreamsReturnValue | undefined>;
+    /**
+     * Fetch the context messages for a thread.
+     * @param ctx Either a query, mutation, or action ctx.
+     *   If it is not an action context, you can't do text or
+     *   vector search.
+     * @param args The associated thread, user, message
+     * @returns
+     */
+    fetchContextMessages(ctx: RunQueryCtx | RunActionCtx, args: {
+        userId: string | undefined;
+        threadId: string | undefined;
+        messages: CoreMessage[];
+        /**
+         * If provided, it will search for messages up to and including this message.
+         * Note: if this is far in the past, text and vector search results may be more
+         * limited, as it's post-filtering the results.
+         */
+        upToAndIncludingMessageId?: string;
+        contextOptions: ContextOptions | undefined;
+    }): Promise<MessageDoc[]>;
+    /**
+     * 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.
+     */
+    getThreadMetadata(ctx: RunQueryCtx, args: {
+        threadId: string;
+    }): Promise<ThreadDoc>;
+    /**
+     * Update the metadata for a thread.
+     * @param ctx A ctx object from a mutation or action.
+     * @param args.threadId The thread to update the metadata for.
+     * @param args.patch The patch to apply to the thread.
+     * @returns The updated thread metadata.
+     */
+    updateThreadMetadata(ctx: RunMutationCtx, args: {
+        threadId: string;
+        patch: Partial<WithoutSystemFields<ThreadDoc>>;
+    }): Promise<ThreadDoc>;
+    /**
+     * Get the embeddings for a set of messages.
+     * @param messages The messages to get the embeddings for.
+     * @returns The embeddings for the messages.
+     */
+    generateEmbeddings(ctx: RunActionCtx, { userId, threadId, }: {
+        userId: string | undefined;
+        threadId: string | undefined;
+    }, messages: CoreMessage[]): Promise<{
+        vectors: (number[] | null)[];
+        dimension: VectorDimension;
+        model: string;
+    } | undefined>;
+    /**
+     * Generate embeddings for a set of messages, and save them to the database.
+     * It will not generate or save embeddings for messages that already have an
+     * embedding.
+     * @param ctx The ctx parameter to an action.
+     * @param args The messageIds to generate embeddings for.
+     */
+    generateAndSaveEmbeddings(ctx: RunActionCtx, args: {
         messageIds: string[];
-    }>>;
+    }): Promise<void>;
     /**
      * Explicitly save a "step" created by the AI SDK.
      * @param ctx The ctx argument to a mutation or action.
      * @param args The Step generated by the AI SDK.
      */
-    saveStep<TOOLS extends ToolSet>(ctx: RunMutationCtx, args: {
+    saveStep<TOOLS extends ToolSet>(ctx: ActionCtx, args: {
         userId?: string;
         threadId: string;
         /**
@@ -574,7 +687,24 @@ export declare class Agent<AgentTools extends ToolSet> {
          * Defaults to the chat provider for the Agent.
          */
         provider?: string;
-    }): Promise<MessageDoc[]>;
+    }): Promise<{
+        messages: MessageDoc[];
+        pending?: MessageDoc;
+    }>;
+    /**
+     * Manually save the result of a generateObject call to the thread.
+     * This happens automatically when using {@link generateObject} or {@link streamObject}
+     * from the `thread` object created by {@link continueThread} or {@link createThread}.
+     * @param ctx The context passed from the mutation or action function calling this.
+     * @param args The arguments to the saveObject function.
+     */
+    saveObject(ctx: RunActionCtx, args: {
+        userId: string | undefined;
+        threadId: string;
+        promptMessageId: string;
+        result: GenerateObjectResult<unknown>;
+        metadata?: Omit<MessageWithMetadata, "message">;
+    }): Promise<void>;
     /**
      * Commit or rollback a message that was pending.
      * This is done automatically when saving messages by default.
@@ -593,68 +723,6 @@ export declare class Agent<AgentTools extends ToolSet> {
             kind: "success";
         };
     }): Promise<void>;
-    /**
-     * This behaves like {@link generateText} from the "ai" package except that
-     * it add context based on the userId and threadId and saves the input and
-     * resulting messages to the thread, if specified.
-     * 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}.
-     * @returns The result of the generateText function.
-     */
-    generateText<TOOLS extends ToolSet | undefined = undefined, OUTPUT = never, OUTPUT_PARTIAL = never>(ctx: RunActionCtx, { userId: argsUserId, threadId, usageHandler, tools: threadTools, }: {
-        userId?: string;
-        threadId?: string;
-        /**
-         * The usage handler to use for this thread. Overrides any handler
-         * set in the agent constructor.
-         */
-        usageHandler?: UsageHandler;
-        /** @deprecated Pass `tools` in the next parameter instead. This is only intended to pass through thread-default tools.  */
-        tools?: ToolSet;
-    }, args: 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
-     * resulting messages to the thread, if specified.
-     * 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: RunActionCtx, { userId: argsUserId, threadId, usageHandler, 
-    /**
-     * @deprecated Pass `tools` in the next parameter instead.
-     * This is only intended to pass through thread-default tools.
-     */
-    tools: threadTools, }: {
-        userId?: string;
-        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>, 
-    /**
-     * The {@link ContextOptions} and {@link StorageOptions}
-     * options to use for fetching contextual messages and saving input/output messages.
-     */
-    options?: Options & {
-        /**
-         * Whether to save incremental data (deltas) from streaming responses.
-         * Defaults to false.
-         * If false, it will not save any deltas to the database.
-         * If true, it will save deltas with {@link DEFAULT_STREAMING_OPTIONS}.
-         *
-         * Regardless of this option, when streaming you are able to use this
-         * `streamText` function as you would with the "ai" package's version:
-         * iterating over the text, streaming it over HTTP, etc.
-         */
-        saveStreamDeltas?: boolean | StreamingOptions;
-    }): Promise<StreamTextResult<TOOLS extends undefined ? AgentTools : TOOLS, PARTIAL_OUTPUT> & GenerationOutputMetadata>;
     _saveMessagesAndFetchContext<T extends {
         id?: string;
         prompt?: string;
@@ -675,64 +743,24 @@ export declare class Agent<AgentTools extends ToolSet> {
         order: number | undefined;
         stepOrder: number | undefined;
     }>;
-    /**
-     * This behaves like {@link generateObject} from the "ai" package except that
-     * it add context based on the userId and threadId and saves the input and
-     * resulting messages to the thread, if specified.
-     * Use {@link continueThread} to get a version of this function already scoped
-     * to a thread (and optionally userId).
-     */
-    generateObject<T>(ctx: RunActionCtx, { userId: argsUserId, threadId, usageHandler, }: {
-        userId?: string;
-        threadId?: string;
-        usageHandler?: UsageHandler;
-    }, 
-    /**
-     * The arguments to the generateObject function, similar to the ai.generateObject function.
-     */
-    args: OurObjectArgs<T>, 
-    /**
-     * The {@link ContextOptions} and {@link StorageOptions}
-     * options to use for fetching contextual messages and saving input/output messages.
-     */
-    options?: Options): Promise<GenerateObjectResult<T> & 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
-     * resulting messages to the thread, if specified.
-     * Use {@link continueThread} to get a version of this function already scoped
-     * to a thread (and optionally userId).
-     */
-    streamObject<T>(ctx: RunActionCtx, { userId: argsUserId, threadId, usageHandler, }: {
+    _shouldSaveOutputMessages(storageOpts?: StorageOptions): boolean;
+    _mergedContextOptions(opts: ContextOptions | undefined): ContextOptions;
+    _searchOptionsWithEmbeddingAndDefaults(ctx: RunActionCtx, { userId, threadId }: {
         userId?: string;
         threadId?: string;
-        usageHandler?: UsageHandler;
-    }, 
-    /**
-     * The arguments to the streamObject function, similar to the ai `streamObject` function.
-     */
-    args: OurStreamObjectArgs<T>, 
-    /**
-     * 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>;
+    }, contextOptions: ContextOptions, messages: CoreMessage[]): Promise<SearchOptions>;
+    doEmbed(ctx: RunActionCtx, options: {
+        userId: string | undefined;
+        threadId: string | undefined;
+        values: string[];
+        abortSignal?: AbortSignal;
+        headers?: Record<string, string | undefined>;
+    }): Promise<{
+        embeddings: number[][];
+    }>;
     /**
-     * Manually save the result of a generateObject call to the thread.
-     * This happens automatically when using {@link generateObject} or {@link streamObject}
-     * from the `thread` object created by {@link continueThread} or {@link createThread}.
-     * @param ctx The context passed from the mutation or action function calling this.
-     * @param args The arguments to the saveObject function.
+     * WORKFLOW UTILITIES
      */
-    saveObject(ctx: RunMutationCtx, args: {
-        userId: string | undefined;
-        threadId: string;
-        promptMessageId: string;
-        result: GenerateObjectResult<unknown>;
-        metadata?: Omit<MessageWithMetadata, "message">;
-    }): Promise<void>;
-    _mergedContextOptions(opts: ContextOptions | undefined): ContextOptions;
-    _searchOptionsWithDefaults(contextOptions: ContextOptions, messages: CoreMessage[]): Promise<SearchOptions>;
     /**
      * Create a mutation that creates a thread so you can call it from a Workflow.
      * e.g.
@@ -877,7 +905,7 @@ export declare class Agent<AgentTools extends ToolSet> {
         seed?: number | undefined;
         maxRetries?: number | undefined;
         stream?: boolean | undefined;
-        toolChoice?: "required" | "auto" | "none" | {
+        toolChoice?: "required" | "none" | "auto" | {
             type: "tool";
             toolName: string;
         } | undefined;
@@ -900,9 +928,10 @@ export declare class Agent<AgentTools extends ToolSet> {
             searchOtherThreads?: boolean | undefined;
         } | undefined;
         storageOptions?: {
-            saveAllInputMessages?: boolean | undefined;
-            saveAnyInputMessages?: boolean | undefined;
-            saveOutputMessages?: boolean | undefined;
+            saveMessages?: "all" | "none" | "promptAndOutput";
+            saveAllInputMessages?: boolean;
+            saveAnyInputMessages?: boolean;
+            saveOutputMessages?: boolean;
         } | undefined;
     }, Promise<{
         text: string;
@@ -1025,18 +1054,167 @@ export declare class Agent<AgentTools extends ToolSet> {
             searchOtherThreads?: boolean | undefined;
         } | undefined;
         storageOptions?: {
-            saveAllInputMessages?: boolean | undefined;
-            saveAnyInputMessages?: boolean | undefined;
-            saveOutputMessages?: boolean | undefined;
+            saveMessages?: "all" | "none" | "promptAndOutput";
+            saveAllInputMessages?: boolean;
+            saveAnyInputMessages?: boolean;
+            saveOutputMessages?: boolean;
         } | undefined;
     }, Promise<{
         object: T;
     }>>;
+    /**
+     * 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.
+     */
+    asSaveMessagesMutation(): import("convex/server").RegisteredMutation<"internal", {
+        userId?: string | undefined;
+        pending?: boolean | undefined;
+        promptMessageId?: string | undefined;
+        failPendingSteps?: boolean | undefined;
+        threadId: string;
+        messages: {
+            id?: string | undefined;
+            fileIds?: string[] | undefined;
+            error?: string | undefined;
+            model?: string | undefined;
+            provider?: string | undefined;
+            text?: string | undefined;
+            reasoning?: string | undefined;
+            usage?: {
+                promptTokens: number;
+                completionTokens: number;
+                totalTokens: number;
+            } | undefined;
+            providerMetadata?: Record<string, Record<string, any>> | undefined;
+            sources?: {
+                title?: string | undefined;
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                id: string;
+                sourceType: "url";
+                url: string;
+            }[] | undefined;
+            reasoningDetails?: ({
+                signature?: string | undefined;
+                type: "text";
+                text: string;
+            } | {
+                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";
+                content: string | ({
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    mimeType?: string | undefined;
+                    type: "image";
+                    image: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    filename?: string | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                })[];
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                role: "assistant";
+                content: string | ({
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    type: "text";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    filename?: string | undefined;
+                    type: "file";
+                    mimeType: string;
+                    data: string | ArrayBuffer;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    signature?: string | undefined;
+                    type: "reasoning";
+                    text: string;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    type: "redacted-reasoning";
+                    data: string;
+                } | {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    type: "tool-call";
+                    toolCallId: string;
+                    toolName: string;
+                    args: any;
+                })[];
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                role: "tool";
+                content: {
+                    providerOptions?: Record<string, Record<string, any>> | undefined;
+                    args?: any;
+                    experimental_content?: ({
+                        type: "text";
+                        text: string;
+                    } | {
+                        mimeType?: string | undefined;
+                        type: "image";
+                        data: string;
+                    })[] | undefined;
+                    isError?: boolean | undefined;
+                    type: "tool-result";
+                    toolCallId: string;
+                    toolName: string;
+                    result: any;
+                }[];
+            } | {
+                providerOptions?: Record<string, Record<string, any>> | undefined;
+                role: "system";
+                content: string;
+            };
+        }[];
+    }, Promise<{
+        lastMessageId: string;
+        messageIds: string[];
+    }>>;
 }
 export declare function filterOutOrphanedToolMessages(docs: MessageDoc[]): {
     id?: string | undefined;
     userId?: string | undefined;
     embeddingId?: string | undefined;
+    fileIds?: string[] | undefined;
+    files?: any[] | undefined;
     error?: string | undefined;
     agentName?: string | undefined;
     model?: string | undefined;
@@ -1117,12 +1295,6 @@ export declare function filterOutOrphanedToolMessages(docs: MessageDoc[]): {
     } | undefined;
     text?: string | undefined;
     reasoning?: string | undefined;
-    files?: {
-        data?: string | ArrayBuffer | undefined;
-        url?: string | undefined;
-        fileId?: string | undefined;
-        mimeType: string;
-    }[] | undefined;
     usage?: {
         promptTokens: number;
         completionTokens: number;
@@ -1133,8 +1305,8 @@ export declare function filterOutOrphanedToolMessages(docs: MessageDoc[]): {
         title?: string | undefined;
         providerOptions?: Record<string, Record<string, any>> | undefined;
         id: string;
-        url: string;
         sourceType: "url";
+        url: string;
     }[] | undefined;
     reasoningDetails?: ({
         signature?: string | undefined;
@@ -1165,7 +1337,6 @@ export declare function filterOutOrphanedToolMessages(docs: MessageDoc[]): {
     stepOrder: number;
     tool: boolean;
 }[];
-type MessageWithMetadata = OpaqueIds<InnerMessageWithMetadata>;
 type CoreMessageMaybeWithId = CoreMessage & {
     id?: string | undefined;
 };