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

package/MIGRATION.md

@@ -0,0 +1,153 @@
+# Migration Guide: v0.3.x to v0.6.0 (AI SDK v6)
+
+This guide helps you upgrade from @convex-dev/agent v0.3.x to v0.6.0.
+
+## Step 1: Update dependencies
+
+Update all AI SDK packages **together** to avoid peer dependency conflicts:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/provider-utils@^4.0.6
+```
+
+### Official AI SDK providers
+
+Update your AI SDK provider packages to v3.x:
+```bash
+# For OpenAI
+npm install @ai-sdk/openai@^3.0.10
+
+# For Anthropic
+npm install @ai-sdk/anthropic@^3.0.13
+
+# For Groq
+npm install @ai-sdk/groq@^3.0.8
+
+# For Google (Gemini)
+npm install @ai-sdk/google@^3.0.8
+```
+
+### Third-party providers
+
+Third-party providers also need updates to be compatible with AI SDK v6:
+
+```bash
+# For OpenRouter
+npm install @openrouter/ai-sdk-provider@^2.0.0
+
+# For other providers, check their documentation for AI SDK v6 compatibility
+```
+
+### Handling dependency conflicts
+
+If you see peer dependency warnings or errors, try updating all packages at once:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/openai@^3.0.10 @openrouter/ai-sdk-provider@^2.0.0
+```
+
+If you still have conflicts, you can use `--force` as a last resort:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 --force
+```
+
+> **Note**: Using `--force` can lead to inconsistent dependency trees. After using it, verify your app works correctly and consider running `npm dedupe` to clean up.
+
+## Step 2: Update tool definitions
+
+Replace `parameters` with `inputSchema`:
+
+```typescript
+// Before (v5)
+const myTool = createTool({
+  description: "My tool",
+  parameters: z.object({ query: z.string() }),
+  execute: async (ctx, args) => { ... }
+})
+
+// After (v6)
+const myTool = createTool({
+  description: "My tool",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async (ctx, input, options) => { ... }
+})
+```
+
+## Step 3: Update Agent config (if using embeddings)
+
+```typescript
+// Before
+new Agent(components.agent, {
+  textEmbeddingModel: openai.embedding("text-embedding-3-small")
+})
+
+// After
+new Agent(components.agent, {
+  embeddingModel: openai.embedding("text-embedding-3-small")
+})
+```
+
+## Step 4: Update maxSteps (optional)
+
+```typescript
+// Before
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  maxSteps: 5
+})
+
+// After (maxSteps still works, but stopWhen is preferred)
+import { stepCountIs } from "ai"
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  stopWhen: stepCountIs(5)
+})
+```
+
+## Step 5: Verify
+
+```bash
+npm run typecheck
+npm test
+```
+
+## Common Issues
+
+### EmbeddingModelV2 vs EmbeddingModelV3 type errors
+Ensure all `@ai-sdk/*` packages are updated to v3.x. Older versions use AI SDK v5 types.
+
+### Tool `args` vs `input`
+AI SDK v6 renamed `args` to `input` in tool calls. The library maintains backwards compatibility, but you may see this in types.
+
+### `mimeType` vs `mediaType`
+AI SDK v6 renamed `mimeType` to `mediaType`. Backwards compatibility is maintained.
+
+### Peer dependency conflicts
+
+If you see errors like:
+```
+npm error ERESOLVE unable to resolve dependency tree
+npm error peer ai@"^5.0.0" from @openrouter/ai-sdk-provider@1.0.3
+```
+
+This means a third-party provider needs updating. Common solutions:
+
+1. **Update the provider** to a version compatible with AI SDK v6
+2. **Check npm** for the latest version: `npm view @openrouter/ai-sdk-provider versions`
+3. **Use `--force`** if a compatible version isn't available yet (temporary workaround)
+
+### Third-party provider compatibility
+
+| Provider | AI SDK v5 (ai@5.x) | AI SDK v6 (ai@6.x) |
+|----------|-------------------|-------------------|
+| @openrouter/ai-sdk-provider | v1.x | v2.x |
+| @ai-sdk/openai | v1.x-v2.x | v3.x |
+| @ai-sdk/anthropic | v1.x-v2.x | v3.x |
+| @ai-sdk/groq | v1.x-v2.x | v3.x |
+| @ai-sdk/google | v1.x-v2.x | v3.x |
+
+## More Information
+
+- [AI SDK v6 Migration Guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0)
+- [Convex Agent Documentation](https://docs.convex.dev/agents)

package/README.md

@@ -21,34 +21,39 @@ The Agent component is a core building block for building AI agents. It manages
 threads and messages, around which you Agents can cooperate in static or dynamic
 workflows.
 
-- [Agents](./docs/getting-started.mdx) provide an abstraction for using LLMs to
-  represent units of use-case-specific prompting with associated models,
-  prompts, [Tool Calls](./docs/tools.mdx), and behavior in relation to other
-  Agents, functions, APIs, and more.
-- [Threads](./docs/threads.mdx) persist [messages](./docs/messages.mdx) and can
-  be shared by multiple users and agents (including
-  [human agents](./docs/human-agents.mdx)).
+- [Agents](https://docs.convex.dev/agents/agent-usage) provide an abstraction
+  for using LLMs to represent units of use-case-specific prompting with
+  associated models, prompts,
+  [Tool Calls](https://docs.convex.dev/agents/tools), and behavior in relation
+  to other Agents, functions, APIs, and more.
+- [Threads](https://docs.convex.dev/agents/threads) persist
+  [messages](https://docs.convex.dev/agents/messages) and can be shared by
+  multiple users and agents (including
+  [human agents](https://docs.convex.dev/agents/human-agents)).
 - Streaming text and objects using deltas over websockets so all clients stay in
   sync efficiently, without http streaming. Enables streaming from async
   functions.
-- [Conversation context](./docs/context.mdx) is automatically included in each
-  LLM call, including built-in hybrid vector/text search for messages in the
-  thread and opt-in search for messages from other threads (for the same
-  specified user).
-- [RAG](./docs/rag.mdx) techniques are supported for prompt augmentation from
-  other sources, either up front in the prompt or as tool calls. Integrates with
-  the [RAG Component](https://www.convex.dev/components/rag), or DIY.
-- [Workflows](./docs/workflows.mdx) allow building multi-step operations that
-  can span agents, users, durably and reliably.
-- [Files](./docs/files.mdx) are supported in thread history with automatic
-  saving to [file storage](https://docs.convex.dev/file-storage) and
-  ref-counting.
-- [Debugging](./docs/debugging.mdx) is enabled by callbacks, the
-  [agent playground](./docs/playground.mdx) where you can inspect all metadata
-  and iterate on prompts and context settings, and inspection in the dashboard.
-- [Usage tracking](./docs/usage-tracking.mdx) is easy to set up, enabling usage
-  attribution per-provider, per-model, per-user, per-agent, for billing & more.
-- [Rate limiting](./docs/rate-limiting.mdx), powered by the
+- [Conversation context](https://docs.convex.dev/agents/context) is
+  automatically included in each LLM call, including built-in hybrid vector/text
+  search for messages in the thread and opt-in search for messages from other
+  threads (for the same specified user).
+- [RAG](https://docs.convex.dev/agents/rag) techniques are supported for prompt
+  augmentation from other sources, either up front in the prompt or as tool
+  calls. Integrates with the
+  [RAG Component](https://www.convex.dev/components/rag), or DIY.
+- [Workflows](https://docs.convex.dev/agents/workflows) allow building
+  multi-step operations that can span agents, users, durably and reliably.
+- [Files](https://docs.convex.dev/agents/files) are supported in thread history
+  with automatic saving to [file storage](https://docs.convex.dev/file-storage)
+  and ref-counting.
+- [Debugging](https://docs.convex.dev/agents/debugging) is enabled by callbacks,
+  the [agent playground](https://docs.convex.dev/agents/playground) where you
+  can inspect all metadata and iterate on prompts and context settings, and
+  inspection in the dashboard.
+- [Usage tracking](https://docs.convex.dev/agents/usage-tracking) is easy to set
+  up, enabling usage attribution per-provider, per-model, per-user, per-agent,
+  for billing & more.
+- [Rate limiting](https://docs.convex.dev/agents/rate-limiting), powered by the
   [Rate Limiter Component](https://www.convex.dev/components/rate-limiter),
   helps control the rate at which users can interact with agents and keep you
   from exceeding your LLM provider's limits.
@@ -58,13 +63,13 @@ workflows.
 [![Powerful AI Apps Made Easy with the Agent Component](https://thumbs.video-to-markdown.com/b323ac24.jpg)](https://youtu.be/tUKMPUlOCHY)
 **Read the [docs](https://docs.convex.dev/agents) for more details.**
 
-Play with the [example](./example/):
+Play with the example:
 
 ```sh
 git clone https://github.com/get-convex/agent.git
 cd agent
 npm run setup
-npm run example
+npm run dev
 ```
 
 Found a bug? Feature request?

package/dist/UIMessages.d.ts

@@ -0,0 +1,46 @@
+import { type UIMessage as AIUIMessage, type UIDataTypes, type UITools } from "ai";
+import type { MessageDoc, MessageStatus, ProviderOptions } from "./validators.js";
+export type UIStatus = "streaming" | MessageStatus;
+export type UIMessage<METADATA = unknown, DATA_PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = AIUIMessage<METADATA, DATA_PARTS, TOOLS> & {
+    key: string;
+    order: number;
+    stepOrder: number;
+    status: UIStatus;
+    agentName?: string;
+    userId?: string;
+    text: string;
+    _creationTime: number;
+};
+/**
+ * Converts a list of UIMessages to MessageDocs, along with extra metadata that
+ * may be available to associate with the MessageDocs.
+ * @param messages - The UIMessages to convert to MessageDocs.
+ * @param meta - The metadata to add to the MessageDocs.
+ * @returns
+ */
+export declare function fromUIMessages<METADATA = unknown>(messages: UIMessage<METADATA>[], meta: {
+    threadId: string;
+    userId?: string;
+    model?: string;
+    provider?: string;
+    providerOptions?: ProviderOptions;
+    metadata?: METADATA;
+}): Promise<(MessageDoc & {
+    streaming: boolean;
+    metadata?: METADATA;
+})[]>;
+type ExtraFields<METADATA = unknown> = {
+    streaming?: boolean;
+    metadata?: METADATA;
+};
+/**
+ * Converts a list of MessageDocs to UIMessages.
+ * This is somewhat lossy, as many fields are not supported by UIMessages, e.g.
+ * the model, provider, userId, etc.
+ * The UIMessage type is the augmented type that includes more fields such as
+ * key, order, stepOrder, status, agentName, text, etc.
+ */
+export declare function toUIMessages<METADATA = unknown, DATA_PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools>(messages: (MessageDoc & ExtraFields<METADATA>)[]): UIMessage<METADATA, DATA_PARTS, TOOLS>[];
+export declare function combineUIMessages(messages: UIMessage[]): UIMessage[];
+export {};
+//# sourceMappingURL=UIMessages.d.ts.map

package/dist/UIMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UIMessages.d.ts","sourceRoot":"","sources":["../src/UIMessages.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,IAAI,WAAW,EAU7B,KAAK,WAAW,EAChB,KAAK,OAAO,EACb,MAAM,IAAI,CAAC;AAUZ,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAEnD,MAAM,MAAM,SAAS,CACnB,QAAQ,GAAG,OAAO,EAClB,UAAU,SAAS,WAAW,GAAG,WAAW,EAC5C,KAAK,SAAS,OAAO,GAAG,OAAO,IAC7B,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,GAAG;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,QAAQ,GAAG,OAAO,EACrD,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GACA,OAAO,CAAC,CAAC,UAAU,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC,EAAE,CAAC,CAiEvE;AA8BD,KAAK,WAAW,CAAC,QAAQ,GAAG,OAAO,IAAI;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,GAAG,OAAO,EAClB,UAAU,SAAS,WAAW,GAAG,WAAW,EAC5C,KAAK,SAAS,OAAO,GAAG,OAAO,EAE/B,QAAQ,EAAE,CAAC,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,EAAE,GAC/C,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,CAiB1C;AA+dD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CA2CpE"}