Support AI SDK v5

[macalinao]

How much work is there involved in this? Is there a large migration needed?

[ianmacartney]

I don't expect much. There's a thread in discord about it we can port some info from into here. Have you tried installing them together and seeing if anything doesn't work? Is it just a matter of the peer dependency not claiming support? I could start a PR supporting it that just bumps the deps for folks to install and see what doesn't work?

…

On Sat, Jul 12, 2025 at 5:00 AM Ian Macalinao ***@***.***> wrote: *macalinao* created an issue (get-convex/agent#79) <#79> How much work is there involved in this? Is there a large migration needed? — Reply to this email directly, view it on GitHub <#79>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW75QCAGCNIQIZG6JT33ID2F7AVCNFSM6AAAAACBLVINTCVHI2DSMVQWIX3LMV43ASLTON2WKOZTGIZDKMRVHEZTSMI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[ethan-huo]

V5 message format has significant changes, the latest design is excellent, and if Convex can immediately support V5 messages, I would really like to migrate from Mastra to Convex Agent

[ianmacartney]

You can try it out with npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@93 - let me know what breaks in the PR (#93 ) and we can iterate

[srich36]

I can iterate on this and push this to prod ASAP to test with ai sdk v5.

I'll note any issues I encounter here:

Playground

node_modules/@convex-dev/agent-playground/src/definePlaygroundAPI.ts:109:33 - error TS2339: Property 'maxSteps' does not exist on type '{ name?: string | undefined; chat: LanguageModelV2; textEmbedding?: EmbeddingModelV2<string> | undefined; instructions?: string | undefined; ... 6 more ...; rawRequestResponseHandler?: RawRequestResponseHandler | undefined; }'.

node_modules/@convex-dev/agent-playground/src/definePlaygroundAPI.ts:277:9 - error TS2345: Argument of type '{ system?: string | undefined; prompt?: string | undefined; messages?: ({ 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<...' is not assignable to parameter of type 'TextArgs<ToolSet, undefined, never, never>'.
  Type '{ system?: string | undefined; prompt?: string | undefined; messages?: ({ 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<...' is not assignable to type 'Omit<CallSettings & Prompt & { model: LanguageModel; tools?: ToolSet | undefined; toolChoice?: ToolChoice<NoInfer<ToolSet>> | undefined; ... 10 more ...; _internal?: { ...; } | undefined; }, "model" | ... 1 more ... | "toolChoice">'.
    Types of property 'messages' are incompatible.
      Type '({ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; })[] | undefined' is not assignable to type 'ModelMessage[] | undefined'.
        Type '({ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; })[]' is not assignable to type 'ModelMessage[]'.
          Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; }' is not assignable to type 'ModelMessage'.
            Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; }' is not assignable to type 'ModelMessage'.
              Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; }' is not assignable to type 'UserModelMessage'.
                Types of property 'content' are incompatible.
                  Type '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; } | { ...; })[]' is not assignable to type 'UserContent'.
                    Type '({ 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; } | { ...; })[]' is not assignable to type 'UserContent'.
                      Type '({ 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; } | { ...; })[]' is not assignable to type '(TextPart | ImagePart | FilePart)[]'.
                        Type '{ 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; } | { ...; }' is not assignable to type 'TextPart | ImagePart | FilePart'.
                          Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; filename?: string | undefined; type: "file"; mimeType: string; data: string | ArrayBuffer; }' is not assignable to type 'TextPart | ImagePart | FilePart'.
                            Property 'mediaType' is missing in type '{ providerOptions?: Record<string, Record<string, any>> | undefined; filename?: string | undefined; type: "file"; mimeType: string; data: string | ArrayBuffer; }' but required in type 'FilePart'.

277         { ...rest, ...(system ? { system } : {}) },

[ianmacartney]

if you install the corresponding playground version from the PR does that fix it? I'm starting to think that the playground API should be exported from the regular package (too) - as the playground package is really only benefiting by isolating dependencies when running it directly from the CLI - and most people can use the hosted version...

…

On Tue, Jul 29, 2025 at 2:18 PM Sean Rich ***@***.***> wrote: *srich36* left a comment (get-convex/agent#79) <#79 (comment)> I can iterate on this and push this to prod ASAP to test with ai sdk v5. I'll note any issues I encounter here: *Playground* ***@***.***/agent-playground/src/definePlaygroundAPI.ts:109:33 - error TS2339: Property 'maxSteps' does not exist on type '{ name?: string | undefined; chat: LanguageModelV2; textEmbedding?: EmbeddingModelV2<string> | undefined; instructions?: string | undefined; ... 6 more ...; rawRequestResponseHandler?: RawRequestResponseHandler | undefined; }'. ***@***.***/agent-playground/src/definePlaygroundAPI.ts:277:9 - error TS2345: Argument of type '{ system?: string | undefined; prompt?: string | undefined; messages?: ({ 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<...' is not assignable to parameter of type 'TextArgs<ToolSet, undefined, never, never>'. Type '{ system?: string | undefined; prompt?: string | undefined; messages?: ({ 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<...' is not assignable to type 'Omit<CallSettings & Prompt & { model: LanguageModel; tools?: ToolSet | undefined; toolChoice?: ToolChoice<NoInfer<ToolSet>> | undefined; ... 10 more ...; _internal?: { ...; } | undefined; }, "model" | ... 1 more ... | "toolChoice">'. Types of property 'messages' are incompatible. Type '({ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; })[] | undefined' is not assignable to type 'ModelMessage[] | undefined'. Type '({ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; })[]' is not assignable to type 'ModelMessage[]'. Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; }' is not assignable to type 'ModelMessage'. Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; }' is not assignable to type 'ModelMessage'. Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; }' is not assignable to type 'UserModelMessage'. Types of property 'content' are incompatible. Type '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; } | { ...; })[]' is not assignable to type 'UserContent'. Type '({ 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; } | { ...; })[]' is not assignable to type 'UserContent'. Type '({ 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; } | { ...; })[]' is not assignable to type '(TextPart | ImagePart | FilePart)[]'. Type '{ 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; } | { ...; }' is not assignable to type 'TextPart | ImagePart | FilePart'. Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; filename?: string | undefined; type: "file"; mimeType: string; data: string | ArrayBuffer; }' is not assignable to type 'TextPart | ImagePart | FilePart'. Property 'mediaType' is missing in type '{ providerOptions?: Record<string, Record<string, any>> | undefined; filename?: string | undefined; type: "file"; mimeType: string; data: string | ArrayBuffer; }' but required in type 'FilePart'. 277 { ...rest, ...(system ? { system } : {}) }, — Reply to this email directly, view it on GitHub <#79 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQWYWYRAVDPN6U6ANL633K7QIZAVCNFSM6AAAAACBLVINTCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMZUGEYDKMRRG4> . You are receiving this because you commented.Message ID: ***@***.***>

[ianmacartney]

also I just pushed a change where you should start being able to import definePlaygroundAPI from the component itself, which should help avoid that.

…

On Tue, Jul 29, 2025 at 2:28 PM Ian Macartney ***@***.***> wrote: if you install the corresponding playground version from the PR does that fix it? I'm starting to think that the playground API should be exported from the regular package (too) - as the playground package is really only benefiting by isolating dependencies when running it directly from the CLI - and most people can use the hosted version... On Tue, Jul 29, 2025 at 2:18 PM Sean Rich ***@***.***> wrote: > *srich36* left a comment (get-convex/agent#79) > <#79 (comment)> > > I can iterate on this and push this to prod ASAP to test with ai sdk v5. > > I'll note any issues I encounter here: > > *Playground* > > ***@***.***/agent-playground/src/definePlaygroundAPI.ts:109:33 - error TS2339: Property 'maxSteps' does not exist on type '{ name?: string | undefined; chat: LanguageModelV2; textEmbedding?: EmbeddingModelV2<string> | undefined; instructions?: string | undefined; ... 6 more ...; rawRequestResponseHandler?: RawRequestResponseHandler | undefined; }'. > > ***@***.***/agent-playground/src/definePlaygroundAPI.ts:277:9 - error TS2345: Argument of type '{ system?: string | undefined; prompt?: string | undefined; messages?: ({ 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<...' is not assignable to parameter of type 'TextArgs<ToolSet, undefined, never, never>'. > Type '{ system?: string | undefined; prompt?: string | undefined; messages?: ({ 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<...' is not assignable to type 'Omit<CallSettings & Prompt & { model: LanguageModel; tools?: ToolSet | undefined; toolChoice?: ToolChoice<NoInfer<ToolSet>> | undefined; ... 10 more ...; _internal?: { ...; } | undefined; }, "model" | ... 1 more ... | "toolChoice">'. > Types of property 'messages' are incompatible. > Type '({ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; })[] | undefined' is not assignable to type 'ModelMessage[] | undefined'. > Type '({ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; })[]' is not assignable to type 'ModelMessage[]'. > Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; } | { ...; } | { ...; } | { ...; }' is not assignable to type 'ModelMessage'. > Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; }' is not assignable to type 'ModelMessage'. > Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; role: "user"; content: string | ({ providerOptions?: Record<string, Record<string, any>> | undefined; type: "text"; text: string; } | { ...; } | { ...; })[]; }' is not assignable to type 'UserModelMessage'. > Types of property 'content' are incompatible. > Type '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; } | { ...; })[]' is not assignable to type 'UserContent'. > Type '({ 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; } | { ...; })[]' is not assignable to type 'UserContent'. > Type '({ 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; } | { ...; })[]' is not assignable to type '(TextPart | ImagePart | FilePart)[]'. > Type '{ 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; } | { ...; }' is not assignable to type 'TextPart | ImagePart | FilePart'. > Type '{ providerOptions?: Record<string, Record<string, any>> | undefined; filename?: string | undefined; type: "file"; mimeType: string; data: string | ArrayBuffer; }' is not assignable to type 'TextPart | ImagePart | FilePart'. > Property 'mediaType' is missing in type '{ providerOptions?: Record<string, Record<string, any>> | undefined; filename?: string | undefined; type: "file"; mimeType: string; data: string | ArrayBuffer; }' but required in type 'FilePart'. > > 277 { ...rest, ...(system ? { system } : {}) }, > > — > Reply to this email directly, view it on GitHub > <#79 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AACZQWYWYRAVDPN6U6ANL633K7QIZAVCNFSM6AAAAACBLVINTCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMZUGEYDKMRRG4> > . > You are receiving this because you commented.Message ID: > ***@***.***> >

[srich36]

also I just pushed a change where you should start being able to import
definePlaygroundAPI from the component itself, which should help avoid that.
…

Awesome - importing definePlaygroundAPI from @convex-dev/agent + visiting the hosted version is working! Thank you.

[srich36]

running into a few other snags when adding tool calling to the mix

EDIT: Tool calling errors fixed after upgrading to new versions of the AI SDK. Things are working well!

Playground

Edit: TypeScript error only

Type 'Agent<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>' is not assignable to type 'Agent<ToolSet>'.
  The types of 'options.stopWhen' are incompatible between these types.
    Type 'StopCondition<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>> | StopCondition<...>[] | undefined' is not assignable to type 'StopCondition<NoInfer<ToolSet>> | StopCondition<NoInfer<ToolSet>>[] | undefined'.
      Type 'StopCondition<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>' is not assignable to type 'StopCondition<NoInfer<ToolSet>> | StopCondition<NoInfer<ToolSet>>[] | undefined'.
        Type 'StopCondition<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>' is not assignable to type 'StopCondition<NoInfer<ToolSet>>'.
          Types of parameters 'options' and 'options' are incompatible.
            Type '{ steps: StepResult<NoInfer<ToolSet>>[]; }' is not assignable to type '{ steps: StepResult<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>[]; }'.
              Types of property 'steps' are incompatible.
                Type 'StepResult<NoInfer<ToolSet>>[]' is not assignable to type 'StepResult<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>[]'.
                  Type 'StepResult<NoInfer<ToolSet>>' is not assignable to type 'StepResult<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>'.
                    Types of property 'content' are incompatible.
                      Type 'ContentPart<NoInfer<ToolSet>>[]' is not assignable to type 'ContentPart<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>[]'.
                        Type 'ContentPart<NoInfer<ToolSet>>' is not assignable to type 'ContentPart<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>'.
                          Type '{ type: "tool-call"; } & { type: "tool-call"; toolCallId: string; toolName: string; input: any; providerExecuted?: boolean | undefined; dynamic?: false | undefined; providerMetadata?: SharedV2ProviderMetadata | undefined; } & { ...; }' is not assignable to type 'ContentPart<NoInfer<{ webSearch: Tool<{ query: string; includeDomains?: string[] | undefined; }, { source: string; results: { title: string; text: string | undefined; url: string; score: number | undefined; }[]; }>; }>>'.
                            Type '{ type: "tool-call"; } & { type: "tool-call"; toolCallId: string; toolName: string; input: any; providerExecuted?: boolean | undefined; dynamic?: false | undefined; providerMetadata?: SharedV2ProviderMetadata | undefined; } & { ...; }' is not assignable to type '{ type: "tool-call"; } & { type: "tool-call"; toolCallId: string; toolName: string; input: unknown; providerExecuted?: boolean | undefined; dynamic: true; providerMetadata?: SharedV2ProviderMetadata | undefined; } & { ...; }'.
                              Type '{ type: "tool-call"; } & { type: "tool-call"; toolCallId: string; toolName: string; input: any; providerExecuted?: boolean | undefined; dynamic?: false | undefined; providerMetadata?: SharedV2ProviderMetadata | undefined; } & { ...; }' is not assignable to type '{ type: "tool-call"; toolCallId: string; toolName: string; input: unknown; providerExecuted?: boolean | undefined; dynamic: true; providerMetadata?: SharedV2ProviderMetadata | undefined; }'.
                                Types of property 'dynamic' are incompatible.
                                  Type 'false | undefined' is not assignable to type 'true'.
                                    Type 'undefined' is not assignable to type 'true'.ts(2322)

[heymaaz]

We currently use ai-sdk 5 and convex and just came across this amazing project. Would love to spend my weekend trying to refactor to this, but need the ai-sdk 5 support!

[ianmacartney]

Ok the latest version should be even closer! @srich36 your type errors should be resolved. Any comments on the PR (#93) are welcome

[srich36]

@ianmacartney will take a more in depth look tonight / tomorrow morning!

Btw I'm already running this branch with the ai sdk v5 in prod - been working well so far!

[ethan-huo]

@ianmacartney Can you export all types under /validators? UserMessage and ImagePart are types that I believe the application will use independently.

In addition, I think the parameters in initiateAsyncStreaming and agent.listMessages can directly accept
{ threadId, messages: Message[] }

[srich36]

I upgraded to the latest version of the pr and everything lgtm 👍

[nnennajohn]

@ianmacartney , any timeline on the v5 pr being merged? Thank you