@mastra/ai-sdk 1.3.4-alpha.0 → 1.4.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @mastra/ai-sdk
 
+## 1.4.0-alpha.1
+
+### Minor Changes
+
+- Added agent versioning support to chat and network route handlers. You can now pass `agentVersion` to `chatRoute()`, `handleChatStream()`, `networkRoute()`, and `handleNetworkStream()` to target a specific agent version by ID or status (draft/published). Route handlers also accept `?versionId=<id>` or `?status=draft|published` query parameters at request time, which take precedence over static configuration. Requires the Editor to be configured. ([#15296](https://github.com/mastra-ai/mastra/pull/15296))
+
+  ```typescript
+  // Static version on route config
+  chatRoute({
+    path: '/chat',
+    agent: 'weatherAgent',
+    agentVersion: { status: 'published' },
+  });
+
+  // Programmatic version on handler
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    agentVersion: { versionId: 'ver_abc123' },
+    params,
+  });
+  ```
+
 ## 1.3.4-alpha.0
 
 ### Patch Changes

package/README.md

@@ -158,6 +158,33 @@ export async function POST(req: Request) {
 }
 ```
 
+## Agent versioning
+
+All route handlers and standalone stream functions accept an optional `agentVersion` parameter to target a specific agent version. This requires the [Editor](https://mastra.ai/docs/editor/overview) to be configured.
+
+Pass a version ID or resolve by status:
+
+```typescript
+chatRoute({
+  path: '/chat',
+  agent: 'weatherAgent',
+  agentVersion: { status: 'published' },
+});
+```
+
+For route handlers (`chatRoute`, `networkRoute`), callers can also override the version at request time with query parameters: `?versionId=<id>` or `?status=draft|published`. Query parameters take precedence over the static `agentVersion` option.
+
+The standalone handlers (`handleChatStream`, `handleNetworkStream`) accept `agentVersion` directly:
+
+```typescript
+const stream = await handleChatStream({
+  mastra,
+  agentId: 'weatherAgent',
+  agentVersion: { versionId: 'ver_abc123' },
+  params,
+});
+```
+
 ## Manual transformation
 
 If you have a raw Mastra `stream`, you can manually transform it to AI SDK UI message parts:

package/dist/chat-route.d.ts

@@ -10,9 +10,15 @@ export type ChatStreamHandlerParams<UI_MESSAGE extends SupportedUIMessage = Supp
     /** The trigger for the request - sent by AI SDK's useChat hook */
     trigger?: 'submit-message' | 'regenerate-message';
 };
+/**
+ * Extracted from the second parameter of `Mastra.getAgentById` so the type
+ * stays in sync with core automatically.
+ */
+export type AgentVersionOptions = NonNullable<Parameters<Mastra['getAgentById']>[1]>;
 export type ChatStreamHandlerOptions<UI_MESSAGE extends SupportedUIMessage = SupportedUIMessage, OUTPUT = undefined> = {
     mastra: Mastra;
     agentId: string;
+    agentVersion?: AgentVersionOptions;
     params: ChatStreamHandlerParams<UI_MESSAGE, OUTPUT>;
     defaultOptions?: AgentExecutionOptions<OUTPUT>;
     version?: 'v5' | 'v6';
@@ -58,6 +64,7 @@ export declare function handleChatStream<UI_MESSAGE extends V6UIMessage = V6UIMe
 export type chatRouteOptions<OUTPUT = undefined> = {
     defaultOptions?: AgentExecutionOptions<OUTPUT>;
     version?: 'v5' | 'v6';
+    agentVersion?: AgentVersionOptions;
 } & ({
     path: `${string}:agentId${string}`;
     agent?: never;
@@ -113,6 +120,6 @@ export type chatRouteOptions<OUTPUT = undefined> = {
  * - If both `agent` and `:agentId` are present, a warning is logged and the fixed `agent` takes precedence
  * - Request context from the incoming request overrides `defaultOptions.requestContext` if both are present
  */
-export declare function chatRoute<OUTPUT = undefined>({ path, agent, defaultOptions, version, sendStart, sendFinish, sendReasoning, sendSources, }: chatRouteOptions<OUTPUT>): ReturnType<typeof registerApiRoute>;
+export declare function chatRoute<OUTPUT = undefined>({ path, agent, defaultOptions, version, agentVersion, sendStart, sendFinish, sendReasoning, sendSources, }: chatRouteOptions<OUTPUT>): ReturnType<typeof registerApiRoute>;
 export {};
 //# sourceMappingURL=chat-route.d.ts.map

package/dist/chat-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-route.d.ts","sourceRoot":"","sources":["../src/chat-route.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chat-route.d.ts","sourceRoot":"","sources":["../src/chat-route.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -13176,6 +13176,7 @@ function toAISdkStream(stream, options = {
 async function handleChatStream({
   mastra,
   agentId,
+  agentVersion,
   params,
   defaultOptions: defaultOptions3,
   version = "v5",
@@ -13190,7 +13191,7 @@ async function handleChatStream({
   if (resumeData && !runId) {
     throw new Error("runId is required when resumeData is provided");
   }
-  const agentObj = mastra.getAgentById(agentId);
+  const agentObj = agentVersion ? await mastra.getAgentById(agentId, agentVersion) : mastra.getAgentById(agentId);
   if (!agentObj) {
     throw new Error(`Agent ${agentId} not found`);
   }
@@ -13266,6 +13267,7 @@ function chatRoute({
   agent,
   defaultOptions: defaultOptions3,
   version = "v5",
+  agentVersion,
   sendStart = true,
   sendFinish = true,
   sendReasoning = false,
@@ -13289,6 +13291,25 @@ function chatRoute({
           schema: {
             type: "string"
           }
+        },
+        {
+          name: "versionId",
+          in: "query",
+          required: false,
+          description: "Specific agent version ID to use. Mutually exclusive with status.",
+          schema: {
+            type: "string"
+          }
+        },
+        {
+          name: "status",
+          in: "query",
+          required: false,
+          description: "Which stored config version to resolve: draft (latest) or published (active version). Mutually exclusive with versionId.",
+          schema: {
+            type: "string",
+            enum: ["draft", "published"]
+          }
         }
       ],
       requestBody: {
@@ -13396,9 +13417,20 @@ function chatRoute({
       if (!agentToUse) {
         throw new Error("Agent ID is required");
       }
+      const queryVersionId = c.req.query("versionId");
+      const rawStatus = c.req.query("status");
+      if (queryVersionId && rawStatus) {
+        throw new Error('Query parameters "versionId" and "status" are mutually exclusive');
+      }
+      if (rawStatus && rawStatus !== "draft" && rawStatus !== "published") {
+        throw new Error('Query parameter "status" must be "draft" or "published"');
+      }
+      const queryStatus = rawStatus;
+      const effectiveAgentVersion = queryVersionId ? { versionId: queryVersionId } : queryStatus ? { status: queryStatus } : agentVersion;
       const handlerOptions = {
         mastra,
         agentId: agentToUse,
+        agentVersion: effectiveAgentVersion,
         params: {
           ...params,
           requestContext: effectiveRequestContext,
@@ -13570,12 +13602,13 @@ function workflowRoute({
 async function handleNetworkStream({
   mastra,
   agentId,
+  agentVersion,
   params,
   defaultOptions: defaultOptions3,
   version = "v5"
 }) {
   const { messages, ...rest } = params;
-  const agentObj = mastra.getAgentById(agentId);
+  const agentObj = agentVersion ? await mastra.getAgentById(agentId, agentVersion) : mastra.getAgentById(agentId);
   if (!agentObj) {
     throw new Error(`Agent ${agentId} not found`);
   }
@@ -13612,7 +13645,8 @@ function networkRoute({
   path = "/network/:agentId",
   agent,
   defaultOptions: defaultOptions3,
-  version = "v5"
+  version = "v5",
+  agentVersion
 }) {
   if (!agent && !path.includes("/:agentId")) {
     throw new Error("Path must include :agentId to route to the correct agent or pass the agent explicitly");
@@ -13630,6 +13664,20 @@ function networkRoute({
           required: true,
           description: "The ID of the routing agent to execute as a network",
           schema: { type: "string" }
+        },
+        {
+          name: "versionId",
+          in: "query",
+          required: false,
+          description: "Specific agent version ID to use. Mutually exclusive with status.",
+          schema: { type: "string" }
+        },
+        {
+          name: "status",
+          in: "query",
+          required: false,
+          description: "Which stored config version to resolve: draft (latest) or published (active version). Mutually exclusive with versionId.",
+          schema: { type: "string", enum: ["draft", "published"] }
         }
       ],
       requestBody: {
@@ -13658,6 +13706,14 @@ function networkRoute({
           description: "Streaming AI SDK UIMessage event stream for the agent network",
           content: { "text/plain": { schema: { type: "string", description: "SSE stream" } } }
         },
+        "400": {
+          description: "Bad request - invalid input",
+          content: {
+            "application/json": {
+              schema: { type: "object", properties: { error: { type: "string" } } }
+            }
+          }
+        },
         "404": {
           description: "Agent not found",
           content: {
@@ -13689,9 +13745,20 @@ function networkRoute({
       if (!agentToUse) {
         throw new Error("Agent ID is required");
       }
+      const queryVersionId = c.req.query("versionId");
+      const rawStatus = c.req.query("status");
+      if (queryVersionId && rawStatus) {
+        throw new Error('Query parameters "versionId" and "status" are mutually exclusive');
+      }
+      if (rawStatus && rawStatus !== "draft" && rawStatus !== "published") {
+        throw new Error('Query parameter "status" must be "draft" or "published"');
+      }
+      const queryStatus = rawStatus;
+      const effectiveAgentVersion = queryVersionId ? { versionId: queryVersionId } : queryStatus ? { status: queryStatus } : agentVersion;
       const handlerOptions = {
         mastra,
         agentId: agentToUse,
+        agentVersion: effectiveAgentVersion,
         params: {
           ...params,
           requestContext: effectiveRequestContext