Support AI SDK 5

.github/workflows/node.js.yml

@@ -1,11 +1,11 @@
 name: Run tests
 on:
   push:
-    branches: ["main"]
+    branches: ["main", "ai-sdk-v5"]
   pull_request:
-    branches: ["main"]
+    branches: ["main", "ai-sdk-v5"]
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
@@ -18,6 +18,7 @@ jobs:
           node-version: "20.x"
           cache: "npm"
       - run: node setup.cjs
+      - run: cd playground && npm run build && cd ..
       - run: npx pkg-pr-new publish ./ ./playground
       - run: npm test
       - run: npm run typecheck

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0 AI SDK v5 support (alpha)
+
+- Supports LanguageModel: a string for gateway or LanguageModelV2.
+- Add a `.text` field to the toUIMessages return value (this is the
+  UIMessage exported by the Agent library.
+  Note: this is somewhat different, so your UIs will have to adjust.
+- No longer returns lastMessageId when saving message, instead it
+  returns all the messages it saved with all metadata.
+- All messages are returned when generating / streaming text / objects.
+  Not just the prompt message ID / order.
+- More functions are supported without using an Agent class.
+- The UIMessage is now based on the v5 UIMessage, and the MessageDoc is
+  based on the ModelMessage. The data at rest has not changed - backwards
+  compatible.
+- The `id` is no longer used / configurable when saving messages.
+  Reach out if you were using it - the normal message ID should suffice.
+- `maxRetries` option has been moved into a general `callSettings` config on Agent
+- The `maxSteps` option has been changed to the v5 `stopWhen` alternative.
+- saving pending messages now requires passing status: "pending" instead of
+  a top-level pending: true. Most people don't use this feature currently.
+
 ## 0.1.18
 
 - definePlaygroundAPI uses the new interface functions

CONTRIBUTING.md

@@ -49,14 +49,6 @@ npm run alpha
 - Convenience function to create a thread by copying an existing thread (fork)
 - Add a "failed" message when an error is thrown in generate/stream call.
 - Add a "failed" message when a stream is aborted.
-- Enable saving a message as part of the same `order` as a given message.
-  - Validate that you can save a tool response, and use that as promptMessageId
-    and have the response assistant message be on the same order & after the
-    tool call message stepOrder.
-  - Return the order from `saveMessage` so it can be used for idempotency &
-    appending, if not already returned
-  - Return more message metadata from `generateText` & `streamText` - all
-    message info, not just prompt id
 - Support new AI SDK version (and LanguageModelProviderV2)
 - Add a `contextHandler` option to the Agent component, that can be used to see
   and modify the context passed to the LLM before it's called.
@@ -71,16 +63,11 @@ npm run alpha
 - Improve the demo to show more of the features & have nicer UI
   - Add an example of aborting a stream.
   - Add an example of using tracing / telemetry.
-- When adding messages, increment order for each user message
 - Refactor agent code to more helper functions, and break up `client/index.ts`
   into more files.
-- Add a `deleteMessageOrder` function that takes a message id, and deletes all
-  messages at that message's order.
 - Add an example of using MCP with the Agent.
 - Automatically turn big text content into a file when saving a message and keep
   as a fileId. Re-hydrate it when reading out for generation.
-- Finish deprecating save{All,Any}InputMessages in favor of saveInputMessages &
-  other changes
 - When a generateText finishes with a tool call, return a `continue` fn that can
   be used to save the tool call response(s) and continue the generation at the
   same order.

docs/files.mdx

@@ -64,8 +64,10 @@ const { file } = await storeFile(
   ctx,
   components.agent,
   new Blob([bytes], { type: mimeType }),
-  filename,
-  sha256,
+  {
+    filename,
+    sha256,
+  },
 );
 const { fileId, url, storageId } = file;
 ```

docs/getting-started.mdx

@@ -80,9 +80,9 @@ attribute each message to a specific agent. Other options are defaults that can
 be over-ridden at each LLM call-site.
 
 ```ts
-import { tool } from "ai";
+import { tool, stepCountIs } from "ai";
 import { openai } from "@ai-sdk/openai";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { Agent, createTool } from "@convex-dev/agent";
 import { components } from "./_generated/api";
 
@@ -114,7 +114,7 @@ const supportAgent = new Agent(components.agent, {
   // Used for limiting the number of steps when tool calls are involved.
   // NOTE: if you want tool calls to happen automatically with a single call,
   // you need to set this to something greater than 1 (the default).
-  maxSteps: 1,
+  stopWhen: stepCountIs(5),
   // Used for limiting the number of retries when a tool call fails. Default: 3.
   maxRetries: 3,
   // Used for tracking token usage. See https://docs.convex.dev/agents/usage-tracking

docs/human-agents.mdx

@@ -90,7 +90,7 @@ needs human intervention to do so, such as confirmation of a fact.
 
 ```ts
 import { tool } from "ai";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 const askHuman = tool({
   description: "Ask a human a question",

docs/messages.mdx

@@ -172,7 +172,7 @@ apply, except you don't have to provide a model. It will use the agent's default
 chat model.
 
 ```ts
-import { z } from "zod";
+import { z } from "zod/v3";
 
 const result = await thread.generateObject({
   prompt: "Generate a plan based on the conversation so far",
@@ -280,7 +280,7 @@ function MyComponent({ threadId }: { threadId: string }) {
   return (
     <div>
       {toUIMessages(messages.results ?? []).map((message) => (
-        <div key={message.key}>{message.content}</div>
+        <div key={message.key}>{message.text}</div>
       ))}
     </div>
   );
@@ -321,7 +321,7 @@ It can work with any text, but is especially handy for streaming text.
 import { useSmoothText } from "@convex-dev/agent/react";
 
 // in the component
-const [visibleText] = useSmoothText(message.content);
+const [visibleText] = useSmoothText(message.text);
 ```
 
 You can configure the initial characters per second. It will adapt over time to
@@ -335,7 +335,7 @@ streaming and non-streaming messages, do:
 import { useSmoothText, type UIMessage } from "@convex-dev/agent/react";
 
 function Message({ message }: { message: UIMessage }) {
-  const [visibleText] = useSmoothText(message.content, {
+  const [visibleText] = useSmoothText(message.text, {
     startStreaming: message.status === "streaming",
   });
   return <div>{visibleText}</div>;
@@ -385,6 +385,44 @@ provide them as a prompt, as well as all generated messages.
 You can save messages to the database manually using `saveMessage` or
 `saveMessages`.
 
+- You can pass a `prompt` or a full `message` (`CoreMessage` type)
+- The `metadata` argument is optional and allows you to provide more details,
+  such as `sources`, `reasoningDetails`, `usage`, `warnings`, `error`, etc.
+
+### Without the Agent class:
+
+Note: If you aren't using the Agent class with a text embedding model set, you
+need to pass an `embedding` if you want to save it at the same time.
+
+```ts
+import { saveMessage } from "@convex-dev/agent";
+
+const { messageId } = await saveMessage(ctx, components.agent, {
+  threadId,
+  userId,
+  message: { role: "assistant", content: result },
+  metadata: [{ reasoning, usage, ... }] // See MessageWithMetadata type
+  agentName: "my-agent",
+  embedding: { vector: [0.1, 0.2, ...], model: "text-embedding-3-small" },
+});
+```
+
+```ts
+import { saveMessages } from "@convex-dev/agent";
+
+const { messages } = await saveMessages(ctx, components.agent, {
+  threadId,
+  userId,
+  messages: [{ role, content }, ...],
+  metadata: [{ reasoning, usage, ... }, ...] // See MessageWithMetadata type
+  agentName: "my-agent",
+  embeddings: { model: "text-embedding-3-small", vectors: [[0.1...], ...] },
+});
+```
+
+
+### Using the Agent class:
+
 ```ts
 const { messageId } = await agent.saveMessage(ctx, {
   threadId,
@@ -394,10 +432,9 @@ const { messageId } = await agent.saveMessage(ctx, {
 });
 ```
 
-You can pass a `prompt` or a full `message` (`CoreMessage` type)
 
 ```ts
-const { lastMessageId, messageIds} = await agent.saveMessages(ctx, {
+const { messages } = await agent.saveMessages(ctx, {
   threadId, userId,
   messages: [{ role, content }],
   metadata: [{ reasoning, usage, ... }] // See MessageWithMetadata type
@@ -410,9 +447,6 @@ generated lazily if the message is used as a prompt. Or you can provide an
 embedding upfront if it's available, or later explicitly generate them using
 `agent.generateEmbeddings`.
 
-The `metadata` argument is optional and allows you to provide more details, such
-as `sources`, `reasoningDetails`, `usage`, `warnings`, `error`, etc.
-
 ## Configuring the storage of messages
 
 Generally the defaults are fine, but if you want to pass in multiple messages

docs/tools.mdx

@@ -30,8 +30,9 @@ tools in a context that is convenient.
 
 ## Using tools
 
-The Agent component will automatically handle tool calls if you pass `maxSteps`
-to the `generateText` or `streamText` functions.
+The Agent component will automatically handle passing tool call results back in
+and re-generating if you pass `stopWhen: stepCountIs(num)` where `num > 1` to
+`generateText` or `streamText`.
 
 The tool call and result will be stored as messages in the thread associated
 with the source message. See [Messages](./messages.mdx) for more details.
@@ -90,8 +91,8 @@ By default, the context passed to a tool is a `ToolCtx` with:
 - `userId` - the user ID associated with the call, if any
 - `threadId` - the thread ID, if any
 - `messageId` - the message ID of the prompt message passed to generate/stream.
-- Everything in `ActionCtx`, such as `auth`, `storage`, `runQuery`, etc.
-  Note: in scheduled functions, workflows, etc, the auth user will be `null`.
+- Everything in `ActionCtx`, such as `auth`, `storage`, `runQuery`, etc. Note:
+  in scheduled functions, workflows, etc, the auth user will be `null`.
 
 To add more fields to the context, you can pass a custom context to the call,
 such as `agent.generateText({ ...ctx, orgId: "123" })`.

docs/workflows.mdx

@@ -129,7 +129,7 @@ For an action that generates text in a thread, similar to `thread.generateText`:
 
 ```ts
 export const getSupport = supportAgent.asTextAction({
-  maxSteps: 10,
+  stopWhen: stepCountIs(10),
 });
 ```