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

package/src/client/createTool.ts

@@ -1,93 +1,279 @@
-import type { Schema, Tool, ToolCallOptions, ToolSet } from "ai";
+import type { ToolResultOutput } from "@ai-sdk/provider-utils";
+import type {
+  FlexibleSchema,
+  ModelMessage,
+  Tool,
+  ToolExecutionOptions,
+  ToolSet,
+} from "ai";
 import { tool } from "ai";
-import { z } from "zod";
-import type { Agent } from "./index.js";
 import type { GenericActionCtx, GenericDataModel } from "convex/server";
 import type { ProviderOptions } from "../validators.js";
+import type { Agent } from "./index.js";
+
+const MIGRATION_URL = "node_modules/@convex-dev/agent/MIGRATION.md";
+const warnedDeprecations = new Set<string>();
+function warnDeprecation(key: string, message: string) {
+  if (!warnedDeprecations.has(key)) {
+    warnedDeprecations.add(key);
+    console.warn(`[@convex-dev/agent] ${message}\n  See: ${MIGRATION_URL}`);
+  }
+}
 
 export type ToolCtx<DataModel extends GenericDataModel = GenericDataModel> =
   GenericActionCtx<DataModel> & {
-    agent: Agent;
+    agent?: Agent;
     userId?: string;
     threadId?: string;
     messageId?: string;
   };
 
 /**
- * This is a wrapper around the ai.tool function that adds extra context to the
- * tool call, including the action context, userId, threadId, and messageId.
- * @param tool The tool. See https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling
- * but swap parameters for args and handler for execute.
- * @returns A tool to be used with the AI SDK.
+ * Function that is called to determine if the tool needs approval before it can be executed.
  */
-export function createTool<INPUT, OUTPUT, Ctx extends ToolCtx = ToolCtx>(def: {
-  /**
-  An optional description of what the tool does.
-  Will be used by the language model to decide whether to use the tool.
-  Not used for provider-defined tools.
+export type ToolNeedsApprovalFunctionCtx<
+  INPUT,
+  Ctx extends ToolCtx = ToolCtx,
+> = (
+  ctx: Ctx,
+  input: INPUT,
+  options: {
+    /**
+     * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
-  description?: string;
-  /**
-  The schema of the input that the tool expects. The language model will use this to generate the input.
-  It is also used to validate the output of the language model.
-  Use descriptions to make the input understandable for the language model.
+    toolCallId: string;
+    /**
+     * Messages that were sent to the language model to initiate the response that contained the tool call.
+     * The messages **do not** include the system prompt nor the assistant response that contained the tool call.
      */
-  args: ToolParameters<INPUT>;
-  /**
-  An async function that is called with the arguments from the tool call and produces a result.
-  If not provided, the tool will not be executed automatically.
+    messages: ModelMessage[];
+    /**
+     * Additional context.
+     *
+     * Experimental (can break in patch releases).
+     */
+    experimental_context?: unknown;
+  },
+) => boolean | PromiseLike<boolean>;
 
-  @args is the input of the tool call.
-  @options.abortSignal is a signal that can be used to abort the tool call.
+export type ToolExecuteFunctionCtx<
+  INPUT,
+  OUTPUT,
+  Ctx extends ToolCtx = ToolCtx,
+> = (
+  ctx: Ctx,
+  input: INPUT,
+  options: ToolExecutionOptions,
+) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT>;
+
+type NeverOptional<N, T> = 0 extends 1 & N
+  ? Partial<T>
+  : [N] extends [never]
+    ? Partial<Record<keyof T, undefined>>
+    : T;
+
+/**
+ * Error message type for deprecated 'handler' property.
+ * Using a string literal type causes TypeScript to show this message in errors.
+ */
+type HANDLER_REMOVED_ERROR =
+  "⚠️ 'handler' was removed in @convex-dev/agent v0.6.0. Rename to 'execute'. See: node_modules/@convex-dev/agent/MIGRATION.md";
+
+export type ToolOutputPropertiesCtx<
+  INPUT,
+  OUTPUT,
+  Ctx extends ToolCtx = ToolCtx,
+> = NeverOptional<
+  OUTPUT,
+  {
+    /**
+     * An async function that is called with the arguments from the tool call and produces a result.
+     * If `execute` is not provided, the tool will not be executed automatically.
+     *
+     * @param input - The input of the tool call.
+     * @param options.abortSignal - A signal that can be used to abort the tool call.
      */
-  handler: (
-    ctx: Ctx,
-    args: INPUT,
-    options: ToolCallOptions,
-  ) => PromiseLike<OUTPUT>;
-  /**
-   * Provide the context to use, e.g. when defining the tool at runtime.
-   */
-  ctx?: Ctx;
-  /**
-   * Optional function that is called when the argument streaming starts.
-   * Only called when the tool is used in a streaming context.
-   */
-  onInputStart?: (
-    ctx: Ctx,
-    options: ToolCallOptions,
-  ) => void | PromiseLike<void>;
+    execute?: ToolExecuteFunctionCtx<INPUT, OUTPUT, Ctx>;
+    outputSchema?: FlexibleSchema<OUTPUT>;
+    /**
+     * @deprecated Removed in v0.6.0. Use `execute` instead.
+     */
+    handler?: HANDLER_REMOVED_ERROR;
+  }
+>;
+
+/**
+ * Error message type for deprecated 'args' property.
+ * Using a string literal type causes TypeScript to show this message in errors.
+ */
+type ARGS_REMOVED_ERROR =
+  "⚠️ 'args' was removed in @convex-dev/agent v0.6.0. Rename to 'inputSchema'. See: node_modules/@convex-dev/agent/MIGRATION.md";
+
+export type ToolInputProperties<INPUT> = {
   /**
-   * Optional function that is called when an argument streaming delta is available.
-   * Only called when the tool is used in a streaming context.
+   * The schema of the input that the tool expects.
+   * The language model will use this to generate the input.
+   * It is also used to validate the output of the language model.
+   *
+   * You can use descriptions on the schema properties to make the input understandable for the language model.
    */
-  onInputDelta?: (
-    ctx: Ctx,
-    options: {
-      inputTextDelta: string;
-    } & ToolCallOptions,
-  ) => void | PromiseLike<void>;
+  inputSchema: FlexibleSchema<INPUT>;
   /**
-   * Optional function that is called when a tool call can be started,
-   * even if the execute function is not provided.
+   * @deprecated Removed in v0.6.0. Use `inputSchema` instead.
    */
-  onInputAvailable?: (
-    ctx: Ctx,
-    options: {
-      input: [INPUT] extends [never] ? undefined : INPUT;
-    } & ToolCallOptions,
-  ) => void | PromiseLike<void>;
-
-  // Extra AI SDK pass-through options.
-  providerOptions?: ProviderOptions;
-}): Tool<INPUT, OUTPUT> {
-  const t = tool({
+  args?: ARGS_REMOVED_ERROR;
+};
+
+/**
+ * This is a wrapper around the ai.tool function that adds extra context to the
+ * tool call, including the action context, userId, threadId, and messageId.
+ * @param tool The tool. See https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling
+ * Currently contains deprecated parameters `args` and `handler` to maintain backwards compatibility
+ * but these will be removed in the future. Use `inputSchema` and `execute` instead, respectively.
+ * 
+ * @returns A tool to be used with the AI SDK.
+ */
+export function createTool<INPUT, OUTPUT, Ctx extends ToolCtx = ToolCtx>(
+  def: {
+    /**
+     * An optional description of what the tool does.
+     * Will be used by the language model to decide whether to use the tool.
+     * Not used for provider-defined tools.
+     */
+    description?: string;
+    /**
+     * An optional title of the tool.
+     */
+    title?: string;
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
+    providerOptions?: ProviderOptions;
+  } & ToolInputProperties<INPUT> & {
+      /**
+       * An optional list of input examples that show the language
+       * model what the input should look like.
+       */
+      inputExamples?: Array<{
+        input: NoInfer<INPUT>;
+      }>;
+      /**
+       * Whether the tool needs approval before it can be executed.
+       */
+      needsApproval?:
+        | boolean
+        | ToolNeedsApprovalFunctionCtx<
+            [INPUT] extends [never] ? unknown : INPUT,
+            Ctx
+          >;
+      /**
+       * Strict mode setting for the tool.
+       *
+       * Providers that support strict mode will use this setting to determine
+       * how the input should be generated. Strict mode will always produce
+       * valid inputs, but it might limit what input schemas are supported.
+       */
+      strict?: boolean;
+      /**
+       * Provide the context to use, e.g. when defining the tool at runtime.
+       */
+      ctx?: Ctx;
+      /**
+       * Optional function that is called when the argument streaming starts.
+       * Only called when the tool is used in a streaming context.
+       */
+      onInputStart?: (
+        ctx: Ctx,
+        options: ToolExecutionOptions,
+      ) => void | PromiseLike<void>;
+      /**
+       * Optional function that is called when an argument streaming delta is available.
+       * Only called when the tool is used in a streaming context.
+       */
+      onInputDelta?: (
+        ctx: Ctx,
+        options: { inputTextDelta: string } & ToolExecutionOptions,
+      ) => void | PromiseLike<void>;
+      /**
+       * Optional function that is called when a tool call can be started,
+       * even if the execute function is not provided.
+       */
+      onInputAvailable?: (
+        ctx: Ctx,
+        options: {
+          input: [INPUT] extends [never] ? unknown : INPUT;
+        } & ToolExecutionOptions,
+      ) => void | PromiseLike<void>;
+    } & ToolOutputPropertiesCtx<INPUT, OUTPUT, Ctx> & {
+      /**
+       * Optional conversion function that maps the tool result to an output that can be used by the language model.
+       *
+       * If not provided, the tool result will be sent as a JSON object.
+       */
+      toModelOutput?: (
+        ctx: Ctx,
+        options: {
+          /**
+           * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
+           */
+          toolCallId: string;
+          /**
+           * The input of the tool call.
+           */
+          input: [INPUT] extends [never] ? unknown : INPUT;
+          /**
+           * The output of the tool call.
+           */
+          output: 0 extends 1 & OUTPUT
+            ? any
+            : [OUTPUT] extends [never]
+              ? any
+              : NoInfer<OUTPUT>;
+        },
+      ) => ToolResultOutput | PromiseLike<ToolResultOutput>;
+    },
+): Tool<INPUT, OUTPUT> {
+  // Runtime backwards compat - types will show errors but runtime still works
+  const inputSchema = def.inputSchema ?? (def as any).args;
+  if (!inputSchema)
+    throw new Error("To use a Convex tool, you must provide an `inputSchema`");
+
+  if ((def as any).args && !def.inputSchema) {
+    warnDeprecation(
+      "createTool.args",
+      "createTool: 'args' is deprecated. Use 'inputSchema' instead.",
+    );
+  }
+  if ((def as any).handler && !def.execute) {
+    warnDeprecation(
+      "createTool.handler",
+      "createTool: 'handler' is deprecated. Use 'execute' instead.",
+    );
+  }
+
+  const executeHandler = def.execute ?? (def as any).handler;
+  if (!executeHandler && !def.outputSchema)
+    throw new Error(
+      "To use a Convex tool, you must either provide an execute" +
+        " handler function, define an outputSchema, or both",
+    );
+
+  const t = tool<INPUT, OUTPUT>({
     type: "function",
     __acceptsCtx: true,
     ctx: def.ctx,
     description: def.description,
-    inputSchema: def.args,
-    async execute(args: INPUT, options: ToolCallOptions) {
+    title: def.title,
+    providerOptions: def.providerOptions,
+    inputSchema,
+    inputExamples: def.inputExamples,
+    needsApproval(this: Tool<INPUT, OUTPUT>, input, options) {
+      const needsApproval = def.needsApproval;
+      if (!needsApproval || typeof needsApproval === "boolean")
+        return Boolean(needsApproval);
+
       if (!getCtx(this)) {
         throw new Error(
           "To use a Convex tool, you must either provide the ctx" +
@@ -95,23 +281,56 @@ export function createTool<INPUT, OUTPUT, Ctx extends ToolCtx = ToolCtx>(def: {
             " call it (which injects the ctx, userId and threadId)",
         );
       }
-      return def.handler(getCtx(this), args, options);
+      return needsApproval(getCtx(this), input, options);
     },
-    providerOptions: def.providerOptions,
+    strict: def.strict,
+    ...(executeHandler
+      ? {
+          execute(
+            this: Tool<INPUT, OUTPUT>,
+            input: INPUT,
+            options: ToolExecutionOptions,
+          ) {
+            if (!getCtx(this)) {
+              throw new Error(
+                "To use a Convex tool, you must either provide the ctx" +
+                  " at definition time (dynamically in an action), or use the Agent to" +
+                  " call it (which injects the ctx, userId and threadId)",
+              );
+            }
+            return executeHandler(getCtx(this), input, options);
+          },
+        }
+      : {}),
+    outputSchema: def.outputSchema,
   });
   if (def.onInputStart) {
-    t.onInputStart = def.onInputStart.bind(t, getCtx(t));
+    const origOnInputStart = def.onInputStart;
+    t.onInputStart = function (this: Tool<INPUT, OUTPUT>, options) {
+      return origOnInputStart.call(this, getCtx(this), options);
+    };
   }
   if (def.onInputDelta) {
-    t.onInputDelta = def.onInputDelta.bind(t, getCtx(t));
+    const origOnInputDelta = def.onInputDelta;
+    t.onInputDelta = function (this: Tool<INPUT, OUTPUT>, options) {
+      return origOnInputDelta.call(this, getCtx(this), options);
+    };
   }
   if (def.onInputAvailable) {
-    t.onInputAvailable = def.onInputAvailable.bind(t, getCtx(t));
+    const origOnInputAvailable = def.onInputAvailable;
+    t.onInputAvailable = function (this: Tool<INPUT, OUTPUT>, options) {
+      return origOnInputAvailable.call(this, getCtx(this), options);
+    };
+  }
+  if (def.toModelOutput) {
+    const origToModelOutput = def.toModelOutput;
+    t.toModelOutput = function (this: Tool<INPUT, OUTPUT>, options) {
+      return origToModelOutput.call(this, getCtx(this), options);
+    };
   }
   return t;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getCtx<Ctx extends ToolCtx>(tool: any): Ctx {
   return (tool as { ctx: Ctx }).ctx;
 }
@@ -126,8 +345,7 @@ export function wrapTools(
       continue;
     }
     for (const [name, tool] of Object.entries(toolSet)) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      if (!(tool as any).__acceptsCtx) {
+      if (tool && !(tool as any).__acceptsCtx) {
         output[name] = tool;
       } else {
         const out = { ...tool, ctx };
@@ -137,6 +355,3 @@ export function wrapTools(
   }
   return output;
 }
-
-// Vendoring in from "ai" package since it wasn't exported
-type ToolParameters<T> = z.Schema<T> | Schema<T>;

package/src/client/defaultComponent.ts

@@ -0,0 +1,17 @@
+import { componentsGeneric } from "convex/server";
+import type { AgentComponent } from "./types.js";
+
+export type CustomComponent = {
+  /**
+   * If you have a custom name for the agent component, you can pass it here
+   * as components.myAgentName.
+   */
+  component?: AgentComponent;
+};
+
+export function componentAPI(args?: CustomComponent): AgentComponent {
+  return args?.component ?? defaultComponent;
+}
+
+export const defaultComponent = componentsGeneric()
+  .agent as unknown as AgentComponent;

package/src/client/definePlaygroundAPI.ts

@@ -12,7 +12,7 @@ import { v } from "convex/values";
 import {
   createThread as createThread_,
   listMessages as listMessages_,
-  deserializeMessage,
+  toModelMessage,
   vContextOptions,
   vMessage,
   vMessageDoc,
@@ -21,7 +21,15 @@ import {
   vThreadDoc,
   type Agent,
   type AgentComponent,
+  vStreamArgs,
+  syncStreams,
+  vStreamMessagesReturnValue,
+  isTool,
+  extractText,
+  type MessageDoc,
 } from "./index.js";
+import { serializeNewMessagesInStep } from "../mapping.js";
+import { getModelName, getProviderName } from "../shared.js";
 
 export type PlaygroundAPI = ApiFromModules<{
   playground: ReturnType<typeof definePlaygroundAPI>;
@@ -61,9 +69,7 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
   }
 
   const isApiKeyValid = queryGeneric({
-    args: {
-      apiKey: v.string(),
-    },
+    args: { apiKey: v.string() },
     handler: async (ctx, args) => {
       try {
         await validateApiKey(ctx, args.apiKey);
@@ -107,17 +113,14 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
         instructions: agent.options.instructions,
         contextOptions: agent.options.contextOptions,
         storageOptions: agent.options.storageOptions,
-        maxRetries: agent.options.maxRetries,
+        maxRetries: agent.options.callSettings?.maxRetries,
         tools: agent.options.tools ? Object.keys(agent.options.tools) : [],
       }));
     },
   });
 
   const listUsers = queryGeneric({
-    args: {
-      apiKey: v.string(),
-      paginationOpts: paginationOptsValidator,
-    },
+    args: { apiKey: v.string(), paginationOpts: paginationOptsValidator },
     handler: async (ctx, args) => {
       await validateApiKey(ctx, args.apiKey);
       const users = await ctx.runQuery(component.users.listUsersWithThreads, {
@@ -133,12 +136,7 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
         ),
       };
     },
-    returns: vPaginationResult(
-      v.object({
-        _id: v.string(),
-        name: v.string(),
-      }),
-    ),
+    returns: vPaginationResult(v.object({ _id: v.string(), name: v.string() })),
   });
 
   // List threads for a user (query)
@@ -167,10 +165,7 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
             } = await ctx.runQuery(component.messages.listMessagesByThreadId, {
               threadId: thread._id,
               order: "desc",
-              paginationOpts: {
-                numItems: 1,
-                cursor: null,
-              },
+              paginationOpts: { numItems: 1, cursor: null },
             });
             return {
               ...thread,
@@ -198,16 +193,20 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
       apiKey: v.string(),
       threadId: v.string(),
       paginationOpts: paginationOptsValidator,
+      streamArgs: vStreamArgs,
     },
     handler: async (ctx, args) => {
       await validateApiKey(ctx, args.apiKey);
-      return listMessages_(ctx, component, {
+      const paginated = await listMessages_(ctx, component, {
         threadId: args.threadId,
         paginationOpts: args.paginationOpts,
         statuses: ["success", "failed", "pending"],
       });
+      const streams = await syncStreams(ctx, component, args);
+
+      return { ...paginated, streams };
     },
-    returns: vPaginationResult(vMessageDoc),
+    returns: vStreamMessagesReturnValue,
   });
 
   // Create a thread (mutation)
@@ -267,18 +266,46 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
       const namedAgent = agents.find(({ name }) => name === agentName);
       if (!namedAgent) throw new Error(`Unknown agent: ${agentName}`);
       const { agent } = namedAgent;
-      const { messageId, text } = await agent.generateText(
+      const { text, steps } = await agent.streamText(
         ctx,
         { threadId, userId },
         {
           ...rest,
           ...(system ? { system } : {}),
-          ...(messages ? { messages: messages.map(deserializeMessage) } : {}),
+          ...(messages ? { messages: messages.map(toModelMessage) } : {}),
         },
-        { contextOptions, storageOptions },
+        { contextOptions, storageOptions, saveStreamDeltas: true },
       );
-      return { messageId, text };
+      const outputMessages = await Promise.all(
+        (await steps).map(async (step) => {
+          const { messages } = await serializeNewMessagesInStep(
+            ctx,
+            component,
+            step,
+            {
+              model: getModelName(agent.options.languageModel),
+              provider: getProviderName(agent.options.languageModel),
+            },
+          );
+          return messages.map((messageWithMetadata, i) => {
+            return {
+              ...messageWithMetadata,
+              tool: isTool(messageWithMetadata.message),
+              text: extractText(messageWithMetadata.message),
+              status: "success",
+              providerMetadata: {},
+              threadId,
+              _id: crypto.randomUUID(),
+              _creationTime: Date.now(),
+              order: 0,
+              stepOrder: i + 1,
+            } satisfies MessageDoc;
+          });
+        }),
+      );
+      return { text: await text, messages: outputMessages.flat() };
     },
+    returns: v.object({ text: v.string(), messages: v.array(vMessageDoc) }),
   });
 
   // Fetch prompt context (action)
@@ -288,8 +315,11 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
       agentName: v.string(),
       userId: v.optional(v.string()),
       threadId: v.optional(v.string()),
-      messages: v.array(vMessage),
+      searchText: v.optional(v.string()),
+      targetMessageId: v.optional(v.string()),
       contextOptions: vContextOptions,
+      // @deprecated use searchText and targetMessageId instead
+      messages: v.optional(v.array(vMessage)),
       beforeMessageId: v.optional(v.string()),
     },
     handler: async (ctx, args) => {
@@ -302,20 +332,26 @@ export function definePlaygroundAPI<DataModel extends GenericDataModel>(
       if (!namedAgent) throw new Error(`Unknown agent: ${args.agentName}`);
       const { agent } = namedAgent;
       const contextOptions = args.contextOptions;
-      if (args.beforeMessageId) {
+      const targetMessageId = args.targetMessageId ?? args.beforeMessageId;
+      if (targetMessageId) {
         contextOptions.recentMessages =
           (contextOptions.recentMessages ?? 10) + 1;
       }
       const messages = await agent.fetchContextMessages(ctx, {
         userId: args.userId,
         threadId: args.threadId,
-        messages: args.messages.map(deserializeMessage),
+        targetMessageId,
+        searchText: args.searchText,
         contextOptions: args.contextOptions,
-        upToAndIncludingMessageId: args.beforeMessageId,
+        messages: args.messages?.map(toModelMessage),
       });
-      return messages.filter(
-        (m) => !args.beforeMessageId || m._id !== args.beforeMessageId,
+      const targetMessageIndex = messages.findIndex(
+        (m) => m._id === targetMessageId,
       );
+      if (targetMessageIndex !== -1) {
+        return messages.slice(0, targetMessageIndex);
+      }
+      return messages;
     },
   });