@mastra/ai-sdk 0.0.0-studio-deploy-20260404182525 → 0.0.0-studio-cli-20260504022012

package/CHANGELOG.md

@@ -1,11 +1,174 @@
 # @mastra/ai-sdk
 
-## 0.0.0-studio-deploy-20260404182525
+## 0.0.0-studio-cli-20260504022012
 
 ### Patch Changes
 
-- Updated dependencies [[`c55b527`](https://github.com/mastra-ai/mastra/commit/c55b52758a31368b2077b0dbbc3badfe4063f560), [`7eb2596`](https://github.com/mastra-ai/mastra/commit/7eb25960d607e07468c9a10c5437abd2deaf1e9a)]:
-  - @mastra/core@0.0.0-studio-deploy-20260404182525
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d)]:
+  - @mastra/core@0.0.0-studio-cli-20260504022012
+
+## 1.4.1
+
+### Patch Changes
+
+- Fixed workflow streaming in @mastra/ai-sdk so intermediate `data-workflow` parts stop repeating every completed step output. Added `data-workflow-step` parts with the full payload for the step that just changed, which reduces stream size for long-running workflows while preserving final workflow outputs. ([#15218](https://github.com/mastra-ai/mastra/pull/15218))
+
+  If your UI reads live step outputs during workflow execution, it should now consume `data-workflow-step` parts in addition to `data-workflow`. Final workflow snapshots still include the full step outputs.
+
+- Fix AI SDK v6 approval replay so ordinary user follow-up turns do not resume stale approval responses. ([#15480](https://github.com/mastra-ai/mastra/pull/15480))
+
+- Fixed tool call approvals in AI SDK v6: `handleChatStream` now automatically routes to `resumeStream` when the AI SDK v6 native approval flow is used on the client (no extra server-side wiring required). The v6 stream now emits native `tool-approval-request` parts so `useChat` can surface approval UI and call `addToolApprovalResponse()`, while also emitting the existing `data-tool-call-approval` chunk for backwards compatibility. ([#15345](https://github.com/mastra-ai/mastra/pull/15345))
+
+- Fixed AI SDK v6 tool approval streams so requireApproval works with handleChatStream and AssistantChatTransport. ([#15345](https://github.com/mastra-ai/mastra/pull/15345))
+
+- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`3d83d06`](https://github.com/mastra-ai/mastra/commit/3d83d06f776f00fb5f4163dddd32a030c5c20844), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`fdd54cf`](https://github.com/mastra-ai/mastra/commit/fdd54cf612a9af876e9fdd85e534454f6e7dd518), [`6315317`](https://github.com/mastra-ai/mastra/commit/63153175fe9a7b224e5be7c209bbebc01dd9b0d5), [`a371ac5`](https://github.com/mastra-ai/mastra/commit/a371ac534aa1bb368a1acf9d8b313378dfdc787e), [`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`7e0e63e`](https://github.com/mastra-ai/mastra/commit/7e0e63e2e485e84442351f4c7a79a424c83539dc), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`30456b6`](https://github.com/mastra-ai/mastra/commit/30456b6b08c8fd17e109dd093b73d93b65e83bc5), [`9d11a8c`](https://github.com/mastra-ai/mastra/commit/9d11a8c1c8924eb975a245a5884d40ca1b7e0491), [`9d3b24b`](https://github.com/mastra-ai/mastra/commit/9d3b24b19407ae9c09586cf7766d38dc4dff4a69), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`d246696`](https://github.com/mastra-ai/mastra/commit/d246696139a3144a5b21b042d41c532688e957e1), [`354f9ce`](https://github.com/mastra-ai/mastra/commit/354f9ce1ca6af2074b6a196a23f8ec30012dccca), [`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0), [`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e), [`8786a61`](https://github.com/mastra-ai/mastra/commit/8786a61fa54ba265f85eeff9985ca39863d18bb6), [`9467ea8`](https://github.com/mastra-ai/mastra/commit/9467ea87695749a53dfc041576410ebf9ee7bb67), [`7338d94`](https://github.com/mastra-ai/mastra/commit/7338d949380cf68b095342e8e42610dc51d557c1), [`c80dc16`](https://github.com/mastra-ai/mastra/commit/c80dc16e113e6cc159f510ffde501ad4711b2189), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9), [`d63ffdb`](https://github.com/mastra-ai/mastra/commit/d63ffdbb2c11e76fe5ea45faab44bc15460f010c), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`1bd5104`](https://github.com/mastra-ai/mastra/commit/1bd51048b6da93507276d6623e3fd96a9e1a8944), [`e9837b5`](https://github.com/mastra-ai/mastra/commit/e9837b53699e18711b09e0ca010a4106376f2653), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3), [`8fb2405`](https://github.com/mastra-ai/mastra/commit/8fb2405138f2d208b7962ad03f121ca25bcc28c5), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
+  - @mastra/core@1.26.0
+
+## 1.4.1-alpha.2
+
+### Patch Changes
+
+- Fix AI SDK v6 approval replay so ordinary user follow-up turns do not resume stale approval responses. ([#15480](https://github.com/mastra-ai/mastra/pull/15480))
+
+- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
+  - @mastra/core@1.26.0-alpha.11
+
+## 1.4.1-alpha.1
+
+### Patch Changes
+
+- Fixed workflow streaming in @mastra/ai-sdk so intermediate `data-workflow` parts stop repeating every completed step output. Added `data-workflow-step` parts with the full payload for the step that just changed, which reduces stream size for long-running workflows while preserving final workflow outputs. ([#15218](https://github.com/mastra-ai/mastra/pull/15218))
+
+  If your UI reads live step outputs during workflow execution, it should now consume `data-workflow-step` parts in addition to `data-workflow`. Final workflow snapshots still include the full step outputs.
+
+- Updated dependencies [[`3d83d06`](https://github.com/mastra-ai/mastra/commit/3d83d06f776f00fb5f4163dddd32a030c5c20844), [`7e0e63e`](https://github.com/mastra-ai/mastra/commit/7e0e63e2e485e84442351f4c7a79a424c83539dc), [`9467ea8`](https://github.com/mastra-ai/mastra/commit/9467ea87695749a53dfc041576410ebf9ee7bb67), [`7338d94`](https://github.com/mastra-ai/mastra/commit/7338d949380cf68b095342e8e42610dc51d557c1)]:
+  - @mastra/core@1.26.0-alpha.2
+
+## 1.4.1-alpha.0
+
+### Patch Changes
+
+- Fixed tool call approvals in AI SDK v6: `handleChatStream` now automatically routes to `resumeStream` when the AI SDK v6 native approval flow is used on the client (no extra server-side wiring required). The v6 stream now emits native `tool-approval-request` parts so `useChat` can surface approval UI and call `addToolApprovalResponse()`, while also emitting the existing `data-tool-call-approval` chunk for backwards compatibility. ([#15345](https://github.com/mastra-ai/mastra/pull/15345))
+
+- Fixed AI SDK v6 tool approval streams so requireApproval works with handleChatStream and AssistantChatTransport. ([#15345](https://github.com/mastra-ai/mastra/pull/15345))
+
+- Updated dependencies [[`d63ffdb`](https://github.com/mastra-ai/mastra/commit/d63ffdbb2c11e76fe5ea45faab44bc15460f010c)]:
+  - @mastra/core@1.25.1-alpha.0
+
+## 1.4.0
+
+### Minor Changes
+
+- Added structured output streaming to the AI SDK UI stream. When an agent produces structured output, the final object is now emitted as a `data-structured-output` data part in the UI message stream, making it available to frontends via AI SDK UI's custom data handling. ([#15237](https://github.com/mastra-ai/mastra/pull/15237))
+
+- 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,
+  });
+  ```
+
+### Patch Changes
+
+- Fixed reasoning streams so reasoning UI parts are only emitted when reasoning content is included. ([#15207](https://github.com/mastra-ai/mastra/pull/15207))
+
+- Updated dependencies [[`87df955`](https://github.com/mastra-ai/mastra/commit/87df955c028660c075873fd5d74af28233ce32eb), [`8fad147`](https://github.com/mastra-ai/mastra/commit/8fad14759804179c8e080ce4d9dec6ef1a808b31), [`582644c`](https://github.com/mastra-ai/mastra/commit/582644c4a87f83b4f245a84d72b9e8590585012e), [`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`4ba3bb1`](https://github.com/mastra-ai/mastra/commit/4ba3bb1e465ad2ddaba3bbf2bc47e0faec32985e), [`5d84914`](https://github.com/mastra-ai/mastra/commit/5d84914e0e520c642a40329b210b413fcd139898), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fd2f314`](https://github.com/mastra-ai/mastra/commit/fd2f31473d3449b6b97e837ef8641264377f41a7), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`e80fead`](https://github.com/mastra-ai/mastra/commit/e80fead1412cc0d1b2f7d6a1ce5017d9e0098ff7), [`0287b64`](https://github.com/mastra-ai/mastra/commit/0287b644a5c3272755cf3112e71338106664103b), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`075e91a`](https://github.com/mastra-ai/mastra/commit/075e91a4549baf46ad7a42a6a8ac8dfa78cc09e6), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0
+
+## 1.4.0-alpha.2
+
+### Minor Changes
+
+- Added structured output streaming to the AI SDK UI stream. When an agent produces structured output, the final object is now emitted as a `data-structured-output` data part in the UI message stream, making it available to frontends via AI SDK UI's custom data handling. ([#15237](https://github.com/mastra-ai/mastra/pull/15237))
+
+### Patch Changes
+
+- Updated dependencies [[`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0-alpha.3
+
+## 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
+
+- Fixed reasoning streams so reasoning UI parts are only emitted when reasoning content is included. ([#15207](https://github.com/mastra-ai/mastra/pull/15207))
+
+- Updated dependencies [[`87df955`](https://github.com/mastra-ai/mastra/commit/87df955c028660c075873fd5d74af28233ce32eb), [`075e91a`](https://github.com/mastra-ai/mastra/commit/075e91a4549baf46ad7a42a6a8ac8dfa78cc09e6)]:
+  - @mastra/core@1.24.2-alpha.0
+
+## 1.3.3
+
+### Patch Changes
+
+- Added toAISdkMessages() for loading stored Mastra messages into AI SDK v5 or v6 chat UIs. ([#14592](https://github.com/mastra-ai/mastra/pull/14592))
+
+  Use the default v5 behavior or pass { version: 'v6' } when your app is typed against AI SDK v6 useChat() message types.
+
+- Updated dependencies [[`8db7663`](https://github.com/mastra-ai/mastra/commit/8db7663c9a9c735828094c359d2e327fd4f8fba3), [`153e864`](https://github.com/mastra-ai/mastra/commit/153e86476b425db7cd0dc8490050096e92964a38), [`715710d`](https://github.com/mastra-ai/mastra/commit/715710d12fa47cf88e09d41f13843eddc29327b0), [`378c6c4`](https://github.com/mastra-ai/mastra/commit/378c6c4755726e8d8cf83a14809b350b90d46c62), [`9f91fd5`](https://github.com/mastra-ai/mastra/commit/9f91fd538ab2a44f8cc740bcad8e51205f74fbea), [`ba6fa9c`](https://github.com/mastra-ai/mastra/commit/ba6fa9cc0f3e1912c49fd70d4c3bb8c44903ddaa)]:
+  - @mastra/core@1.24.0
+
+## 1.3.3-alpha.0
+
+### Patch Changes
+
+- Added toAISdkMessages() for loading stored Mastra messages into AI SDK v5 or v6 chat UIs. ([#14592](https://github.com/mastra-ai/mastra/pull/14592))
+
+  Use the default v5 behavior or pass { version: 'v6' } when your app is typed against AI SDK v6 useChat() message types.
+
+- Updated dependencies [[`153e864`](https://github.com/mastra-ai/mastra/commit/153e86476b425db7cd0dc8490050096e92964a38)]:
+  - @mastra/core@1.23.1-alpha.0
+
+## 1.3.2
+
+### Patch Changes
+
+- Fixed an issue where nested agent sub-tool streams dropped the 'uiMessages' and 'messages' properties during chunk propagation. The response payloads are now merged into the buffered pipeline execution correctly. ([#15053](https://github.com/mastra-ai/mastra/pull/15053))
+
+- Updated dependencies [[`f32b9e1`](https://github.com/mastra-ai/mastra/commit/f32b9e115a3c754d1c8cfa3f4256fba87b09cfb7), [`7d6f521`](https://github.com/mastra-ai/mastra/commit/7d6f52164d0cca099f0b07cb2bba334360f1c8ab), [`a50d220`](https://github.com/mastra-ai/mastra/commit/a50d220b01ecbc5644d489a3d446c3bd4ab30245), [`665477b`](https://github.com/mastra-ai/mastra/commit/665477bc104fd52cfef8e7610d7664781a70c220), [`4cc2755`](https://github.com/mastra-ai/mastra/commit/4cc2755a7194cb08720ff2ab4dffb4b4a5103dfd), [`ac7baf6`](https://github.com/mastra-ai/mastra/commit/ac7baf66ef1db15e03975ef4ebb02724f015a391), [`ed425d7`](https://github.com/mastra-ai/mastra/commit/ed425d78e7c66cbda8209fee910856f98c6c6b82), [`1371703`](https://github.com/mastra-ai/mastra/commit/1371703835080450ef3f9aea58059a95d0da2e5a), [`0df8321`](https://github.com/mastra-ai/mastra/commit/0df832196eeb2450ab77ce887e8553abdd44c5a6), [`98f8a8b`](https://github.com/mastra-ai/mastra/commit/98f8a8bdf5761b9982f3ad3acbe7f1cc3efa71f3), [`ba6f7e9`](https://github.com/mastra-ai/mastra/commit/ba6f7e9086d8281393f2acae60fda61de3bff1f9), [`7eb2596`](https://github.com/mastra-ai/mastra/commit/7eb25960d607e07468c9a10c5437abd2deaf1e9a), [`1805ddc`](https://github.com/mastra-ai/mastra/commit/1805ddc9c9b3b14b63749735a13c05a45af43a80), [`fff91cf`](https://github.com/mastra-ai/mastra/commit/fff91cf914de0e731578aacebffdeebef82f0440), [`61109b3`](https://github.com/mastra-ai/mastra/commit/61109b34feb0e38d54bee4b8ca83eb7345b1d557), [`33f1ead`](https://github.com/mastra-ai/mastra/commit/33f1eadfa19c86953f593478e5fa371093b33779)]:
+  - @mastra/core@1.23.0
+
+## 1.3.2-alpha.0
+
+### Patch Changes
+
+- Fixed an issue where nested agent sub-tool streams dropped the 'uiMessages' and 'messages' properties during chunk propagation. The response payloads are now merged into the buffered pipeline execution correctly. ([#15053](https://github.com/mastra-ai/mastra/pull/15053))
+
+- Updated dependencies:
+  - @mastra/core@1.23.0-alpha.2
 
 ## 1.3.1
 

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:
@@ -202,3 +229,17 @@ const uiMessageStream = createUIMessageStream({
   },
 });
 ```
+
+## Loading stored messages
+
+Use `toAISdkMessages` from `@mastra/ai-sdk/ui` to convert stored Mastra messages for `useChat()` and other AI SDK UI hooks.
+
+The helper keeps the existing v5/default behavior. If your app is typed against `ai@6`, pass `version: 'v6'`.
+That uses the MessageList AI SDK v6 UI output path. MessageList input detection and ingestion remain unchanged.
+
+```typescript
+import { toAISdkMessages } from '@mastra/ai-sdk/ui';
+
+const v5Messages = toAISdkMessages(storedMessages);
+const v6Messages = toAISdkMessages(storedMessages, { version: 'v6' });
+```