@convex-dev/agent 0.0.11-alpha.0 → 0.0.11-alpha.2

package/src/client/index.ts

@@ -6,6 +6,7 @@ import type {
   GenerateTextResult,
   JSONValue,
   RepairTextFunction,
+  Schema,
   StepResult,
   StreamObjectResult,
   StreamTextResult,
@@ -21,55 +22,60 @@ import {
   jsonSchema,
   streamObject,
   streamText,
+  tool,
 } from "ai";
 import { assert } from "convex-helpers";
-import {
-  ConvexToZod,
-  convexToZod,
-  zodToConvex,
-} from "convex-helpers/server/zod";
 import { internalActionGeneric } from "convex/server";
-import { Infer, v, Validator } from "convex/values";
+import { Infer, v } from "convex/values";
 import { z } from "zod";
-import { Mounts } from "../component/_generated/api";
+import { Mounts } from "../component/_generated/api.js";
 import {
   validateVectorDimension,
-  VectorDimension,
-} from "../component/vector/tables";
+  type VectorDimension,
+} from "../component/vector/tables.js";
 import {
-  AIMessageWithoutId,
+  type AIMessageWithoutId,
   deserializeMessage,
   promptOrMessagesToCoreMessages,
   serializeMessageWithId,
   serializeNewMessagesInStep,
   serializeObjectResult,
   serializeStep,
-} from "../mapping";
+} from "../mapping.js";
 import {
   DEFAULT_MESSAGE_RANGE,
   DEFAULT_RECENT_MESSAGES,
   extractText,
-} from "../shared";
+} from "../shared.js";
 import {
-  CallSettings,
-  ProviderMetadata,
-  ProviderOptions,
-  SearchOptions,
+  type CallSettings,
+  type ProviderMetadata,
+  type ProviderOptions,
+  type SearchOptions,
   vContextOptions,
   vSafeObjectArgs,
   vStorageOptions,
   vTextArgs,
-} from "../validators";
-import {
-  MessageDoc,
+} from "../validators.js";
+import type {
+  OpaqueIds,
   RunActionCtx,
   RunMutationCtx,
   RunQueryCtx,
   UseApi,
 } from "./types.js";
+import schema from "../component/schema.js";
 
-export { convexToZod, zodToConvex };
-export type { ThreadDoc, MessageDoc } from "./types.js";
+export type ThreadDoc = OpaqueIds<
+  { _id: string; _creationTime: number } & Infer<
+    typeof schema.tables.threads.validator
+  >
+>;
+export type MessageDoc = OpaqueIds<
+  { _id: string; _creationTime: number } & Infer<
+    typeof schema.tables.messages.validator
+  >
+>;
 
 /**
  * Options to configure what messages are fetched as context,
@@ -179,8 +185,6 @@ export class Agent<AgentTools extends ToolSet> {
        * They can be AI SDK tools (import {tool} from "ai")
        * or tools that have Convex context
        * (import { createTool } from "@convex-dev/agent")
-       * Note: Convex tools can't currently annotate the parameters
-       * with descriptions, so the names should be self-evident from naming.
        */
       tools?: AgentTools;
       /**
@@ -1096,45 +1100,6 @@ export class Agent<AgentTools extends ToolSet> {
       },
     });
   }
-
-  /**
-   * Create a tool out of this agent so other agents can call this one.
-   * Create a tool out of this agent so other agents can call this one.
-   * @param spec The specification for the arguments to this agent.
-   *   They will be encoded as JSON and passed to the agent.
-   * @returns The agent as a tool that can be passed to other agents.
-   */
-  asTool(spec: {
-    description: string;
-    args: Validator<unknown, "required", string>;
-    contextOptions?: ContextOptions;
-    maxSteps?: number;
-    provideMessageHistory?: boolean;
-  }) {
-    return createTool({
-      ...spec,
-      handler: async (ctx, args, options) => {
-        const maxSteps = spec.maxSteps ?? this.options.maxSteps;
-        const contextOptions =
-          spec.contextOptions && this.mergedContextOptions(spec.contextOptions);
-        const { thread } = await this.createThread(ctx, {
-          parentThreadIds: ctx.threadId ? [ctx.threadId] : undefined,
-          userId: ctx.userId,
-        });
-        const messages = spec.provideMessageHistory ? options.messages : [];
-        messages.push({
-          role: "user",
-          content: JSON.stringify(args),
-        });
-        const value = await thread.generateText({
-          messages,
-          maxSteps,
-          ...contextOptions,
-        });
-        return value.text;
-      },
-    });
-  }
 }
 
 export type ToolCtx = RunActionCtx & {
@@ -1143,32 +1108,65 @@ export type ToolCtx = RunActionCtx & {
   messageId?: string;
 };
 
+// Vendoring in from "ai" package since it wasn't exported
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ToolParameters = z.ZodTypeAny | Schema<any>;
+type inferParameters<PARAMETERS extends ToolParameters> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  PARAMETERS extends Schema<any>
+    ? PARAMETERS["_type"]
+    : PARAMETERS extends z.ZodTypeAny
+      ? z.infer<PARAMETERS>
+      : never;
+
 /**
- * This is a wrapper around the ai.tool function that adds support for
- * userId and threadId to the tool, if they're called within a thread from an agent.
- * @param tool The AI tool. See https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling
- * @returns The same tool, but with userId and threadId args support added.
+ * 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.
  */
-export function createTool<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  V extends Validator<any, any, any>,
-  RESULT,
->(convexTool: {
-  args: V;
+export function createTool<PARAMETERS extends ToolParameters, RESULT>(t: {
+  /**
+  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;
+  /**
+  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.
+     */
+  args: PARAMETERS;
+  /**
+  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.
+
+  @args is the input of the tool call.
+  @options.abortSignal is a signal that can be used to abort the tool call.
+     */
   handler: (
     ctx: ToolCtx,
-    args: Infer<V>,
+    args: inferParameters<PARAMETERS>,
     options: ToolExecutionOptions
   ) => PromiseLike<RESULT>;
   ctx?: ToolCtx;
-}): Tool<ConvexToZod<V>, RESULT> {
-  const tool = {
+}): Tool<PARAMETERS, RESULT> & {
+  execute: (
+    args: inferParameters<PARAMETERS>,
+    options: ToolExecutionOptions
+  ) => PromiseLike<RESULT>;
+} {
+  const args = {
     __acceptsCtx: true,
-    ctx: convexTool.ctx,
-    description: convexTool.description,
-    parameters: convexToZod(convexTool.args),
-    async execute(args: Infer<V>, options: ToolExecutionOptions) {
+    ctx: t.ctx,
+    description: t.description,
+    parameters: t.args,
+    async execute(
+      args: inferParameters<PARAMETERS>,
+      options: ToolExecutionOptions
+    ) {
       if (!this.ctx) {
         throw new Error(
           "To use a Convex tool, you must either provide the ctx" +
@@ -1176,10 +1174,10 @@ export function createTool<
             " call it (which injects the ctx, userId and threadId)"
         );
       }
-      return convexTool.handler(this.ctx, args, options);
+      return t.handler(this.ctx, args, options);
     },
   };
-  return tool;
+  return tool(args);
 }
 
 function wrapTools(

package/src/client/types.ts

@@ -7,10 +7,7 @@ import {
   GenericActionCtx,
 } from "convex/server";
 import { GenericId } from "convex/values";
-import type { Doc } from "../component/_generated/dataModel";
 
-export type ThreadDoc = OpaqueIds<Doc<"threads">>;
-export type MessageDoc = OpaqueIds<Doc<"messages">>;
 
 /* Type utils follow */
 export type RunQueryCtx = {

package/src/component/schema.ts

@@ -1,8 +1,13 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
-import { vThreadStatus, vMessage, vMessageStatus, vStep } from "../validators";
+import {
+  vThreadStatus,
+  vMessage,
+  vMessageStatus,
+  vStep,
+} from "../validators.js";
 import { typedV } from "convex-helpers/validators";
-import vectorTables, { vVectorId } from "./vector/tables";
+import vectorTables, { vVectorId } from "./vector/tables.js";
 
 export const schema = defineSchema({
   threads: defineTable({