@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.5

package/.docs/raw/getting-started/start.mdx

@@ -0,0 +1,72 @@
+---
+title: "Start with Mastra | Getting Started"
+description: Choose how to get started with Mastra - quickstart, framework integration, or agentic UI.
+---
+
+import { CardGrid, CardGridItem } from "@site/src/components/cards/card-grid";
+ 
+# Start
+Start a new Mastra project, or integrate Mastra with your preferred framework.
+
+## New project
+
+The `create mastra` command is the fastest way to build your first agent. It walks you through setup and generates an example agent you can run and adapt in [Studio](/docs/v1/getting-started/studio) right away. You can always integrate Mastra with your framework or UI when you’re ready.
+
+<CardGrid columns={1}>
+  <CardGridItem
+    title="Quickstart"
+    href="/guides/v1/getting-started/quickstart"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 34 21" fill="none" width="32" height="32"><path d="M4.49805 11.6934C6.98237 11.6934 8.99609 13.7081 8.99609 16.1924C8.9959 18.6765 6.98225 20.6904 4.49805 20.6904C2.01394 20.6903 0.000196352 18.6765 0 16.1924C0 13.7081 2.01382 11.6935 4.49805 11.6934ZM10.3867 0C12.8709 0 14.8846 2.01388 14.8848 4.49805C14.8848 4.8377 14.847 5.16846 14.7755 5.48643C14.4618 6.88139 14.1953 8.4633 14.9928 9.65L16.2575 11.5319C16.3363 11.6491 16.4727 11.7115 16.6137 11.703C16.7369 11.6957 16.8525 11.6343 16.9214 11.5318L18.1876 9.64717C18.9772 8.47198 18.7236 6.90783 18.4205 5.52484C18.3523 5.21392 18.3164 4.89094 18.3164 4.55957C18.3167 2.07546 20.3313 0.0615234 22.8154 0.0615234C25.2994 0.0617476 27.3132 2.0756 27.3135 4.55957C27.3135 4.93883 27.2665 5.30712 27.178 5.65896C26.8547 6.94441 26.5817 8.37932 27.2446 9.52714L28.459 11.6301C28.4819 11.6697 28.5245 11.6934 28.5703 11.6934C31.0545 11.6935 33.0684 13.7081 33.0684 16.1924C33.0682 18.6765 31.0544 20.6903 28.5703 20.6904C26.0861 20.6904 24.0725 18.6765 24.0723 16.1924C24.0723 15.8049 24.1212 15.4288 24.2133 15.0701C24.5458 13.7746 24.8298 12.3251 24.1609 11.1668L23.0044 9.16384C22.9656 9.09659 22.8931 9.05859 22.8154 9.05859C22.7983 9.05859 22.7824 9.06614 22.7728 9.08033L21.4896 10.9895C20.686 12.1851 20.9622 13.781 21.284 15.1851C21.3582 15.5089 21.3975 15.8461 21.3975 16.1924C21.3973 18.6764 19.3834 20.6902 16.8994 20.6904C14.4152 20.6904 12.4006 18.6765 12.4004 16.1924C12.4004 15.932 12.4226 15.6768 12.4651 15.4286C12.6859 14.14 12.8459 12.7122 12.1167 11.6271L11.2419 10.3253C10.6829 9.49347 9.71913 9.05932 8.78286 8.70188C7.0906 8.05584 5.88867 6.41734 5.88867 4.49805C5.88886 2.0139 7.90254 3.29835e-05 10.3867 0Z" fill="currentColor"/></svg>}
+  >
+    Spin up a Mastra server and interact with agents in Studio or via the API
+  </CardGridItem>
+</CardGrid>
+
+## Integrate with your framework
+
+Add Mastra to an existing project, or scaffold a new Mastra-powered app if you’re starting from scratch.
+
+<CardGrid columns={3}>
+  <CardGridItem
+    title="Next.js"
+    href="/guides/v1/getting-started/next-js"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180" width="32"><mask height="180" id=":r8:mask0_408_134" maskUnits="userSpaceOnUse" width="180" x="0" y="0" style={{maskType: "alpha"}}><circle cx="90" cy="90" fill="black" r="90"></circle></mask><g mask="url(#:r8:mask0_408_134)"><circle cx="90" cy="90" data-circle="true" fill="black" r="90"></circle><path d="M149.508 157.52L69.142 54H54V125.97H66.1136V69.3836L139.999 164.845C143.333 162.614 146.509 160.165 149.508 157.52Z" fill="url(#:r8:paint0_linear_408_134)"></path><rect fill="url(#:r8:paint1_linear_408_134)" height="72" width="12" x="115" y="54"></rect></g><defs><linearGradient gradientUnits="userSpaceOnUse" id=":r8:paint0_linear_408_134" x1="109" x2="144.5" y1="116.5" y2="160.5"><stop stopColor="white"></stop><stop offset="1" stopColor="white" stopOpacity="0"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id=":r8:paint1_linear_408_134" x1="121" x2="120.799" y1="54" y2="106.875"><stop stopColor="white"></stop><stop offset="1" stopColor="white" stopOpacity="0"></stop></linearGradient></defs></svg>}
+  >
+    Build an AI-powered Next.js app
+  </CardGridItem>
+  <CardGridItem
+    title="React"
+    href="/guides/v1/getting-started/vite-react"
+    logo={<svg width="32" height="32" viewBox="0 0 569 512" xmlns="http://www.w3.org/2000/svg"><g fill="#087EA4" fillRule="nonzero"><path d="M285.5,201 C255.400481,201 231,225.400481 231,255.5 C231,285.599519 255.400481,310 285.5,310 C315.599519,310 340,285.599519 340,255.5 C340,225.400481 315.599519,201 285.5,201"></path><path d="M568.959856,255.99437 C568.959856,213.207656 529.337802,175.68144 466.251623,150.985214 C467.094645,145.423543 467.85738,139.922107 468.399323,134.521063 C474.621631,73.0415145 459.808523,28.6686204 426.709856,9.5541429 C389.677085,-11.8291748 337.36955,3.69129898 284.479928,46.0162134 C231.590306,3.69129898 179.282771,-11.8291748 142.25,9.5541429 C109.151333,28.6686204 94.3382249,73.0415145 100.560533,134.521063 C101.102476,139.922107 101.845139,145.443621 102.708233,151.02537 C97.4493791,153.033193 92.2908847,155.161486 87.3331099,157.39017 C31.0111824,182.708821 0,217.765415 0,255.99437 C0,298.781084 39.6220545,336.307301 102.708233,361.003527 C101.845139,366.565197 101.102476,372.066633 100.560533,377.467678 C94.3382249,438.947226 109.151333,483.32012 142.25,502.434597 C153.629683,508.887578 166.52439,512.186771 179.603923,511.991836 C210.956328,511.991836 247.567589,495.487529 284.479928,465.972527 C321.372196,495.487529 358.003528,511.991836 389.396077,511.991836 C402.475265,512.183856 415.36922,508.884856 426.75,502.434597 C459.848667,483.32012 474.661775,438.947226 468.439467,377.467678 C467.897524,372.066633 467.134789,366.565197 466.291767,361.003527 C529.377946,336.347457 569,298.761006 569,255.99437 M389.155214,27.1025182 C397.565154,26.899606 405.877839,28.9368502 413.241569,33.0055186 C436.223966,46.2772304 446.540955,82.2775015 441.522965,131.770345 C441.181741,135.143488 440.780302,138.556788 440.298575,141.990165 C414.066922,134.08804 387.205771,128.452154 360.010724,125.144528 C343.525021,103.224055 325.192524,82.7564475 305.214266,63.9661533 C336.586743,39.7116483 366.032313,27.1025182 389.135142,27.1025182 M378.356498,310.205598 C368.204912,327.830733 357.150626,344.919965 345.237759,361.405091 C325.045049,363.479997 304.758818,364.51205 284.459856,364.497299 C264.167589,364.51136 243.888075,363.479308 223.702025,361.405091 C211.820914,344.919381 200.80007,327.83006 190.683646,310.205598 C180.532593,292.629285 171.306974,274.534187 163.044553,255.99437 C171.306974,237.454554 180.532593,219.359455 190.683646,201.783142 C200.784121,184.229367 211.770999,167.201087 223.601665,150.764353 C243.824636,148.63809 264.145559,147.579168 284.479928,147.591877 C304.772146,147.579725 325.051559,148.611772 345.237759,150.68404 C357.109048,167.14607 368.136094,184.201112 378.27621,201.783142 C388.419418,219.363718 397.644825,237.458403 405.915303,255.99437 C397.644825,274.530337 388.419418,292.625022 378.27621,310.205598 M419.724813,290.127366 C426.09516,307.503536 431.324985,325.277083 435.380944,343.334682 C417.779633,348.823635 399.836793,353.149774 381.668372,356.285142 C388.573127,345.871232 395.263781,335.035679 401.740334,323.778483 C408.143291,312.655143 414.144807,301.431411 419.805101,290.207679 M246.363271,390.377981 C258.848032,391.140954 271.593728,391.582675 284.5,391.582675 C297.406272,391.582675 310.232256,391.140954 322.737089,390.377981 C310.880643,404.583418 298.10766,417.997563 284.5,430.534446 C270.921643,417.999548 258.18192,404.585125 246.363271,390.377981 Z M187.311556,356.244986 C169.137286,353.123646 151.187726,348.810918 133.578912,343.334682 C137.618549,325.305649 142.828222,307.559058 149.174827,290.207679 C154.754833,301.431411 160.736278,312.655143 167.239594,323.778483 C173.74291,334.901824 180.467017,345.864539 187.311556,356.285142 M149.174827,221.760984 C142.850954,204.473938 137.654787,186.794745 133.619056,168.834762 C151.18418,163.352378 169.085653,159.013101 187.211197,155.844146 C180.346585,166.224592 173.622478,176.986525 167.139234,188.210257 C160.65599,199.433989 154.734761,210.517173 149.074467,221.760984 M322.616657,121.590681 C310.131896,120.827708 297.3862,120.385987 284.379568,120.385987 C271.479987,120.385987 258.767744,120.787552 246.242839,121.590681 C258.061488,107.383537 270.801211,93.9691137 284.379568,81.4342157 C297.99241,93.9658277 310.765727,107.380324 322.616657,121.590681 Z M401.70019,188.210257 C395.196875,176.939676 388.472767,166.09743 381.527868,155.68352 C399.744224,158.819049 417.734224,163.151949 435.380944,168.654058 C431.331963,186.680673 426.122466,204.426664 419.785029,221.781062 C414.205023,210.55733 408.203506,199.333598 401.720262,188.230335 M127.517179,131.790423 C122.438973,82.3176579 132.816178,46.2973086 155.778503,33.0255968 C163.144699,28.9632474 171.455651,26.9264282 179.864858,27.1225964 C202.967687,27.1225964 232.413257,39.7317265 263.785734,63.9862316 C243.794133,82.7898734 225.448298,103.270812 208.949132,125.204763 C181.761691,128.528025 154.90355,134.14313 128.661281,141.990165 C128.199626,138.556788 127.778115,135.163566 127.456963,131.790423 M98.4529773,182.106474 C101.54406,180.767925 104.695358,179.429376 107.906872,178.090828 C114.220532,204.735668 122.781793,230.7969 133.498624,255.99437 C122.761529,281.241316 114.193296,307.357063 107.8868,334.058539 C56.7434387,313.076786 27.0971497,284.003505 27.0971497,255.99437 C27.0971497,229.450947 53.1907013,202.526037 98.4529773,182.106474 Z M155.778503,478.963143 C132.816178,465.691432 122.438973,429.671082 127.517179,380.198317 C127.838331,376.825174 128.259842,373.431953 128.721497,369.978497 C154.953686,377.878517 181.814655,383.514365 209.009348,386.824134 C225.500295,408.752719 243.832321,429.233234 263.805806,448.042665 C220.069,481.834331 180.105722,492.97775 155.838719,478.963143 M441.502893,380.198317 C446.520883,429.691161 436.203894,465.691432 413.221497,478.963143 C388.974566,493.017906 348.991216,481.834331 305.274481,448.042665 C325.241364,429.232737 343.566681,408.752215 360.050868,386.824134 C387.245915,383.516508 414.107066,377.880622 440.338719,369.978497 C440.820446,373.431953 441.221885,376.825174 441.563109,380.198317 M461.193488,334.018382 C454.869166,307.332523 446.294494,281.231049 435.561592,255.99437 C446.289797,230.744081 454.857778,204.629101 461.173416,177.930202 C512.216417,198.911955 541.942994,227.985236 541.942994,255.99437 C541.942994,284.003505 512.296705,313.076786 461.153344,334.058539"></path></g></svg>}
+    preserveLogoColor
+  >
+    Add agents to your React + Vite app
+  </CardGridItem>
+  <CardGridItem
+    title="SvelteKit"
+    href="/guides/v1/getting-started/sveltekit"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 107 128"><path d="M94.1566,22.8189c-10.4-14.8851-30.94-19.2971-45.7914-9.8348L22.2825,29.6078A29.9234,29.9234,0,0,0,8.7639,49.6506a31.5136,31.5136,0,0,0,3.1076,20.2318A30.0061,30.0061,0,0,0,7.3953,81.0653a31.8886,31.8886,0,0,0,5.4473,24.1157c10.4022,14.8865,30.9423,19.2966,45.7914,9.8348L84.7167,98.3921A29.9177,29.9177,0,0,0,98.2353,78.3493,31.5263,31.5263,0,0,0,95.13,58.117a30,30,0,0,0,4.4743-11.1824,31.88,31.88,0,0,0-5.4473-24.1157" fill="#ff3e00"/><path d="M45.8171,106.5815A20.7182,20.7182,0,0,1,23.58,98.3389a19.1739,19.1739,0,0,1-3.2766-14.5025,18.1886,18.1886,0,0,1,.6233-2.4357l.4912-1.4978,1.3363.9815a33.6443,33.6443,0,0,0,10.203,5.0978l.9694.2941-.0893.9675a5.8474,5.8474,0,0,0,1.052,3.8781,6.2389,6.2389,0,0,0,6.6952,2.485,5.7449,5.7449,0,0,0,1.6021-.7041L69.27,76.281a5.4306,5.4306,0,0,0,2.4506-3.631,5.7948,5.7948,0,0,0-.9875-4.3712,6.2436,6.2436,0,0,0-6.6978-2.4864,5.7427,5.7427,0,0,0-1.6.7036l-9.9532,6.3449a19.0329,19.0329,0,0,1-5.2965,2.3259,20.7181,20.7181,0,0,1-22.2368-8.2427,19.1725,19.1725,0,0,1-3.2766-14.5024,17.9885,17.9885,0,0,1,8.13-12.0513L55.8833,23.7472a19.0038,19.0038,0,0,1,5.3-2.3287A20.7182,20.7182,0,0,1,83.42,29.6611a19.1739,19.1739,0,0,1,3.2766,14.5025,18.4,18.4,0,0,1-.6233,2.4357l-.4912,1.4978-1.3356-.98a33.6175,33.6175,0,0,0-10.2037-5.1l-.9694-.2942.0893-.9675a5.8588,5.8588,0,0,0-1.052-3.878,6.2389,6.2389,0,0,0-6.6952-2.485,5.7449,5.7449,0,0,0-1.6021.7041L37.73,51.719a5.4218,5.4218,0,0,0-2.4487,3.63,5.7862,5.7862,0,0,0,.9856,4.3717,6.2437,6.2437,0,0,0,6.6978,2.4864,5.7652,5.7652,0,0,0,1.602-.7041l9.9519-6.3425a18.978,18.978,0,0,1,5.2959-2.3278,20.7181,20.7181,0,0,1,22.2368,8.2427,19.1725,19.1725,0,0,1,3.2766,14.5024,17.9977,17.9977,0,0,1-8.13,12.0532L51.1167,104.2528a19.0038,19.0038,0,0,1-5.3,2.3287" fill="#fff"/></svg>}
+    preserveLogoColor
+  >
+Integrate Mastra with SvelteKit
+  </CardGridItem>
+  <CardGridItem
+    title="Astro"
+    href="/guides/v1/getting-started/astro"
+    logo={<svg width="32" height="32" viewBox="0 0 85 107" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M27.5893 91.1365C22.7555 86.7178 21.3443 77.4335 23.3583 70.7072C26.8503 74.948 31.6888 76.2914 36.7005 77.0497C44.4374 78.2199 52.0358 77.7822 59.2231 74.2459C60.0453 73.841 60.8052 73.3027 61.7036 72.7574C62.378 74.714 62.5535 76.6892 62.3179 78.6996C61.7452 83.5957 59.3086 87.3778 55.4332 90.2448C53.8835 91.3916 52.2437 92.4167 50.6432 93.4979C45.7262 96.8213 44.3959 100.718 46.2435 106.386C46.2874 106.525 46.3267 106.663 46.426 107C43.9155 105.876 42.0817 104.24 40.6844 102.089C39.2086 99.8193 38.5065 97.3081 38.4696 94.5909C38.4511 93.2686 38.4511 91.9345 38.2733 90.6309C37.8391 87.4527 36.3471 86.0297 33.5364 85.9478C30.6518 85.8636 28.37 87.6469 27.7649 90.4554C27.7187 90.6707 27.6517 90.8837 27.5847 91.1341L27.5893 91.1365Z" fill="currentColor"/><path d="M0 69.5866C0 69.5866 14.3139 62.6137 28.6678 62.6137L39.4901 29.1204C39.8953 27.5007 41.0783 26.3999 42.4139 26.3999C43.7495 26.3999 44.9325 27.5007 45.3377 29.1204L56.1601 62.6137C73.1601 62.6137 84.8278 69.5866 84.8278 69.5866C84.8278 69.5866 60.5145 3.35233 60.467 3.21944C59.7692 1.2612 58.5911 0 57.0029 0H27.8274C26.2392 0 25.1087 1.2612 24.3634 3.21944C24.3108 3.34983 0 69.5866 0 69.5866Z" fill="currentColor"/></svg>}
+  >
+    Add AI agents to your Astro site
+  </CardGridItem>
+  <CardGridItem
+    title="Express"
+    href="/guides/v1/getting-started/express"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 861.6297 500" width="32" height="32"><path d="M822.05434 464.78529c-23.57102 8.91305-50.08664-1.16881-61.78139-23.49073l-112.4692-155.53981-16.30803-21.72701-130.51543 177.49688c-11.00437 21.35391-36.14786 31.22309-58.7396 23.05618l168.14149-225.57746L453.94772 35.178469c23.20955-8.38407 49.07747.715704 61.98587 21.727011l116.55901 157.4569L749.74175 57.518928c11.0937-21.002063 36.16603-30.356097 58.30506-21.752557l-60.70782 80.543289-82.23033 107.02469c-9.6735 8.63851-9.6735 23.77308 0 32.41158l156.61338 209.03936ZM39.626477 236.19163l13.700796-67.66046C90.953337 34.743916 244.32044-20.928337 349.83703 61.941017 411.61839 110.45615 427.0318 179.1902 424.01558 256.64057H75.94892C70.325459 394.9777 170.14188 478.51165 297.82 435.87559c42.0737-15.33669 73.74401-50.3044 84.17297-93.75842 6.74816-21.72701 17.89283-25.45896 38.29067-19.1709-6.89256 53.65922-37.9963 101.20027-84.40304 129.00732-77.62638 42.45286-173.75024 30.1679-238.204672-30.44338-31.082401-34.94215-49.844311-79.11186-53.49956-125.76104 0-7.66837-2.556118-14.82549-4.345401-21.727-.170408-12.89987-.255612-25.51006-.255612-37.83054zm36.756986-9.35539H391.14389c-1.96821-100.27654-65.2577-171.413323-149.66074-172.077907C147.52023 53.480264 80.294322 123.05782 76.153409 226.40169Z" fill="currentColor"/></svg>}
+  >
+    Create endpoints that call agents and stream responses
+  </CardGridItem>
+</CardGrid>
+
+Mastra works great with agentic UI frameworks like [AI SDK UI](/guides/v1/build-your-ui/ai-sdk-ui), [CopilotKit](/guides/v1/build-your-ui/copilotkit), and [Assistant UI](/guides/v1/build-your-ui/assistant-ui). Use them with any of the frontend frameworks above to stream agent responses, render tools, and build chat interfaces.
+
+## Start from a template
+Have a use case in mind? Start with a pre-built [template](https://mastra.ai/templates) from Mastra or our community.

package/.docs/raw/getting-started/studio.mdx

@@ -147,4 +147,4 @@ export const mastra = new Mastra({
 ## Next steps
 
 - Learn more about Mastra's suggested [project structure](/docs/v1/getting-started/project-structure).
-- Integrate Mastra with your frontend framework of choice - [Next.js](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/astro).
+- Integrate Mastra with your frontend framework of choice - [Next.js](/guides/v1/getting-started/next-js), [React](/guides/v1/getting-started/vite-react), or [Astro](/guides/v1/getting-started/astro).

package/.docs/raw/{frameworks/agentic-uis/ai-sdk.mdx → guides/build-your-ui/ai-sdk-ui.mdx}

@@ -1,14 +1,14 @@
 ---
-title: "Using AI SDK | Frameworks"
-description: "Learn how Mastra leverages the AI SDK library and how you can leverage it further with Mastra"
+title: "Using AI SDK UI | Frameworks"
+description: "Learn how Mastra leverages the AI SDK UI library and how you can leverage it further with Mastra"
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Using AI SDK
+# Using AI SDK UI
 
-[AI SDK](https://sdk.vercel.ai) is a free open-source library that gives you the tools you need to build AI-powered products. Mastra has great integration with AI SDK, including model routing, streaming support, custom React hooks, custom tool/UI, and more.
+[AI SDK UI](https://sdk.vercel.ai) is a free open-source library that gives you the tools you need to build AI-powered products. Mastra has great integration with AI SDK UI, including model routing, streaming support, custom React hooks, custom tool/UI, and more.
 
 :::note
 Migrating from AI SDK v4 to v5? See the [migration guide](/guides/v1/migrations/ai-sdk-v4-to-v5).
@@ -278,12 +278,12 @@ For more information about tool streaming see [Tool streaming documentation](/do
 
 ### Stream Transformations
 
-To manually transform Mastra's streams to AI SDK-compatible format, use the `toAISdkFormat()` utility.
+To manually transform Mastra's streams to AI SDK-compatible format, use the `toAISdkStream()` utility.
 
 ```typescript title="app/api/chat/route.ts" copy {3,13}
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
-import { toAISdkFormat } from "@mastra/ai-sdk";
+import { toAISdkStream } from "@mastra/ai-sdk";
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
@@ -293,7 +293,7 @@ export async function POST(req: Request) {
   // Transform stream into AI SDK format and create UI messages stream
   const uiMessageStream = createUIMessageStream({
     execute: async ({ writer }) => {
-      for await (const part of toAISdkFormat(stream, { from: "agent" })!) {
+      for await (const part of toAISdkStream(stream, { from: "agent" })!) {
         writer.write(part);
       }
     },
@@ -306,13 +306,107 @@ export async function POST(req: Request) {
 }
 ```
 
+#### Stream Transformation Options
+
+The `toAISdkStream()` function accepts the following options:
+
+<PropertiesTable
+  content={[
+    {
+      name: "from",
+      type: "'agent' | 'network' | 'workflow'",
+      isRequired: true,
+      description: "The type of Mastra stream being converted.",
+    },
+    {
+      name: "lastMessageId",
+      type: "string",
+      isOptional: true,
+      description: "(Agent only) The ID of the last message in the conversation.",
+    },
+    {
+      name: "sendStart",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "(Agent only) Whether to send start events.",
+    },
+    {
+      name: "sendFinish",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "(Agent only) Whether to send finish events.",
+    },
+    {
+      name: "sendReasoning",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "(Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream the actual reasoning content from models that support extended thinking.",
+    },
+    {
+      name: "sendSources",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "(Agent only) Whether to include source citations in the output.",
+    },
+    {
+      name: "messageMetadata",
+      type: "Function",
+      isOptional: true,
+      description: "(Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.",
+    },
+    {
+      name: "onError",
+      type: "Function",
+      isOptional: true,
+      description: "(Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.",
+    },
+  ]}
+/>
+
+**Example with reasoning enabled:**
+
+```typescript title="app/api/chat/route.ts" copy {11-14}
+import { mastra } from "../../mastra";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("reasoningAgent");
+  const stream = await myAgent.stream(messages, {
+    providerOptions: {
+      openai: { reasoningEffort: "high" },
+    },
+  });
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: "agent",
+        sendReasoning: true, // Enable reasoning content streaming
+      })!) {
+        writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  });
+}
+```
+
 ### Client Side Stream Transformations
 
-If you have a client-side `response` from `agent.stream(...)` and want AI SDK-formatted parts without custom SSE parsing, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and pipe it through `toAISdkFormat`:
+If you have a client-side `response` from `agent.stream(...)` and want AI SDK-formatted parts without custom SSE parsing, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and pipe it through `toAISdkStream`:
 
 ```typescript title="client-stream-to-ai-sdk.ts" copy
 import { createUIMessageStream } from "ai";
-import { toAISdkFormat } from "@mastra/ai-sdk";
+import { toAISdkStream } from "@mastra/ai-sdk";
 import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
 
 // Client SDK agent stream
@@ -334,7 +428,7 @@ const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
 
 const uiMessageStream = createUIMessageStream({
   execute: async ({ writer }) => {
-    for await (const part of toAISdkFormat(
+    for await (const part of toAISdkStream(
       chunkStream as unknown as MastraModelOutput,
       { from: "agent" },
     )) {
@@ -572,4 +666,4 @@ export const mastra = new Mastra({
 ```
 
 > You can then access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](/docs/v1/server-db/request-context) for more details.
- 
+

package/.docs/raw/{frameworks/web-frameworks → guides/getting-started}/astro.mdx

@@ -31,34 +31,34 @@ This guide assumes you're using Astro's Actions with React and the Vercel adapte
 
 <StepItem>
 
-Install the required Mastra packages:
+Install the required packages:
 
 <Tabs>
 <TabItem value="npm" label="npm">
 
 ```bash copy
-npm install mastra@beta @mastra/core@beta @mastra/libsql@beta
+npm install mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
 <TabItem value="yarn" label="yarn">
 
 ```bash copy
-yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta
+yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
 <TabItem value="pnpm" label="pnpm">
 
 ```bash copy
-pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta
+pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
 <TabItem value="bun" label="bun">
 
 ```bash copy
-bun add mastra@beta @mastra/core@beta @mastra/libsql@beta
+bun add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
@@ -140,14 +140,13 @@ Add `.mastra` and `.vercel` to your `.gitignore` file:
 
 Astro uses Vite, which accesses environment variables via `import.meta.env` rather than `process.env`. As a result, the model constructor must explicitly receive the `apiKey` from the Vite environment like this:
 
-```diff title="src/mastra/agents/weather-agent.ts"
-- import { openai } from "@ai-sdk/openai";
-+ import { createOpenAI } from "@ai-sdk/openai";
+```typescript title="src/mastra/agents/weather-agent.ts"
+ import { createOpenAI } from "@ai-sdk/openai";
 
-+ const openai = createOpenAI({
-+   apiKey: import.meta.env?.OPENAI_API_KEY,
-+   compatibility: "strict"
-+ });
+ const openai = createOpenAI({
+   apiKey: import.meta.env?.OPENAI_API_KEY,
+   compatibility: "strict"
+ });
 ```
 
 > More configuration details are available in the AI SDK docs. See [Provider Instance](https://ai-sdk.dev/providers/ai-sdk-providers/openai#provider-instance) for more information.
@@ -324,34 +323,34 @@ Before proceeding, ensure your Astro project is configured as follows:
 
 <StepItem>
 
-Install the required Mastra packages:
+Install the required packages:
 
 <Tabs>
 <TabItem value="npm" label="npm">
 
 ```bash copy
-npm install mastra@beta @mastra/core@beta @mastra/libsql@beta
+npm install mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
 <TabItem value="yarn" label="yarn">
 
 ```bash copy
-yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta
+yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
 <TabItem value="pnpm" label="pnpm">
 
 ```bash copy
-pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta
+pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
 <TabItem value="bun" label="bun">
 
 ```bash copy
-bun add mastra@beta @mastra/core@beta @mastra/libsql@beta
+bun add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
 ```
 
 </TabItem>
@@ -433,14 +432,13 @@ Add `.mastra` to your `.gitignore` file:
 
 Astro uses Vite, which accesses environment variables via `import.meta.env` rather than `process.env`. As a result, the model constructor must explicitly receive the `apiKey` from the Vite environment like this:
 
-```diff title="src/mastra/agents/weather-agent.ts"
-- import { openai } from "@ai-sdk/openai";
-+ import { createOpenAI } from "@ai-sdk/openai";
+```typescript title="src/mastra/agents/weather-agent.ts"
+ import { createOpenAI } from "@ai-sdk/openai";
 
-+ const openai = createOpenAI({
-+   apiKey: import.meta.env?.OPENAI_API_KEY,
-+   compatibility: "strict"
-+ });
+ const openai = createOpenAI({
+   apiKey: import.meta.env?.OPENAI_API_KEY,
+   compatibility: "strict"
+ });
 ```
 
 > More configuration details are available in the AI SDK docs. See [Provider Instance](https://ai-sdk.dev/providers/ai-sdk-providers/openai#provider-instance) for more information.
@@ -599,4 +597,4 @@ Let me know if you need more information!
 ## Next Steps
 
 - [Deployment | With Astro on Vercel](/docs/v1/deployment/web-framework#with-astro-on-vercel)
-- [Monorepo Deployment](../../deployment/monorepo)
+- [Monorepo Deployment](/docs/v1/deployment/monorepo)

package/.docs/raw/{frameworks/servers → guides/getting-started}/express.mdx

@@ -26,7 +26,7 @@ In this guide you'll learn how to install the necessary Mastra dependencies, cre
 First, install the necessary Mastra dependencies to run an Agent. This guide uses OpenAI as its model but you can use any supported [model provider](/models/v1).
 
 ```bash copy
-npm install mastra@beta @mastra/core@beta @mastra/libsql@beta zod@^3.0.0 @ai-sdk/openai@^1.0.0
+npm install mastra@beta @mastra/core@beta @mastra/libsql@beta zod@^3.0.0
 ```
 
 If not existent yet, create an `.env` file and add your OpenAI API key:
@@ -37,7 +37,7 @@ OPENAI_API_KEY=<your-api-key>
 
 :::note
 
-Each LLM provider uses a different env var. See [Model Capabilities](https://sdk.vercel.ai/providers) for more information.
+Each LLM provider uses a different env var. See [Model Providers](/models/v1/providers/) for more information.
 
 :::
 
@@ -75,7 +75,6 @@ export const weatherTool = createTool({
 Add a `weatherAgent` at `src/mastra/agents/weather-agent.ts`:
 
 ```ts title="src/mastra/agents/weather-agent.ts" copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
@@ -94,7 +93,7 @@ export const weatherAgent = new Agent({
 
       Use the weatherTool to fetch current weather data.
 `,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: { weatherTool },
 });
 ```

package/.docs/raw/guides/{guide → getting-started}/manual-install.mdx

@@ -11,7 +11,7 @@ import StepItem from "@site/src/components/StepItem";
 # Manual Install
 
 :::info
-Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [Standalone Server Quickstart](/guides/v1/quickstarts/standalone-server), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
+Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [Standalone Server Quickstart](/guides/v1/getting-started/quickstart), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
 :::
 
 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.

package/.docs/raw/guides/{quickstarts/nextjs.mdx → getting-started/next-js.mdx}

@@ -1,16 +1,14 @@
 ---
-title: "Next.js Quickstart"
-description: "Get started with Mastra, Next.js, and AS SDK UI. Quickly."
+title: "Next.js | Frameworks"
+description: "Get started with Mastra and Next.js"
 ---
 
-# Next.js Quickstart
+# Integrate Mastra in your Next.js project
 
-In this quickstart, you'll build a tool-calling AI agent using Mastra, then connect it to Next.js by importing and calling the agent directly from your routes.
+In this guide, you'll build a tool-calling AI agent using Mastra, then connect it to Next.js by importing and calling the agent directly from your routes.
 
 You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience.
 
-In about 5 minutes, you'll have a functional AI-powered app ready to extend with your own tools and logic.
-
 <figure>
 ![Screenshot of a chat-style web app displaying a completed "weatherTool" tool call, answering "What is the weather in London?" with a JSON result. A message suggests offering activity ideas, and a text input field is at the bottom.](/img/nextjs-quickstart.png)
 <figcaption class="text-sm text-center">What you'll build: an agent that can call a weather tool, display the JSON result, stream a weather summary in the chat UI, and persist conversation history across reloads.</figcaption>
@@ -20,7 +18,9 @@ In about 5 minutes, you'll have a functional AI-powered app ready to extend with
 
 * You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
 
-## Create a new Next.js app
+## Create a new Next.js app (optional)
+
+If you already have a Next.js app, skip to the next step.
 
 Run the following command to [create a new Next.js app](https://nextjs.org/docs/app/getting-started/installation):
 
@@ -41,7 +41,7 @@ npx create-next-app \
 This creates a project called `my-nextjs-agent`, but you can replace it with any name you want.
 
 ## Initialize Mastra
-`cd` and run [`mastra init`](/reference/v1/cli/create-mastra).
+`cd` into your Next.js project and run [`mastra init`](/reference/v1/cli/create-mastra).
 
 When prompted, choose a provider (e.g. OpenAI) and enter your key:
 
@@ -85,7 +85,7 @@ Create `src/app/api/chat/route.ts`:
 ```ts title="src/app/api/chat/route.ts"
 import { mastra } from "@/mastra";
 import { NextResponse } from "next/server";
-import { toAISdkFormat } from "@mastra/ai-sdk";
+import { toAISdkStream } from "@mastra/ai-sdk";
 import { convertMessages } from "@mastra/core/agent";
 import { createUIMessageStreamResponse } from "ai";
 
@@ -102,7 +102,7 @@ export async function POST(req: Request) {
   });
 
   return createUIMessageStreamResponse({
-    stream: toAISdkFormat(stream, { from: "agent" }),
+    stream: toAISdkStream(stream, { from: "agent" }),
   })
 }
 
@@ -271,6 +271,6 @@ From here, you can extend the project with your own tools and logic:
 
 When you're ready, read more about how Mastra integrates with AI SDK and Next.js, and how to deploy your agent anywhere, including Vercel:
 
-- Integrate Mastra with [AI SDK](/docs/v1/frameworks/agentic-uis/ai-sdk)
+- Integrate Mastra with [AI SDK](/guides/v1/build-your-ui/ai-sdk-ui)
 - Deploy your agent to [Vercel](/docs/v1/deployment/cloud-providers/vercel-deployer)
 - Deploy your agent [anywhere](/docs/v1/deployment/overview)

package/.docs/raw/guides/{quickstarts/standalone-server.mdx → getting-started/quickstart.mdx}

@@ -1,6 +1,6 @@
 ---
-title: "Standalone Server Quickstart"
-description: Get started with Mastra using the create mastra CLI to build a standalone server with agents, workflows, and tools.
+title: "Quickstart"
+description: Get started with Mastra using the create mastra CLI to build a server with agents, workflows, and tools.
 ---
 
 import Tabs from "@theme/Tabs";
@@ -9,11 +9,11 @@ import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 import { VideoPlayer } from "@site/src/components/video-player";
 
-# Standalone Server Quickstart
+# Mastra Quickstart
 
-The `create mastra` CLI command is the quickest way to spin up a standalone Mastra server. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt
+The `create mastra` CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt
 
-If you need more control over the setup, see the [manual installation guide](/guides/v1/guide/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.
+If you need more control over the setup, see the [manual installation guide](/guides/v1/getting-started/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.
 
 ## Before you begin
 
@@ -64,7 +64,7 @@ This creates a new directory for your project with a `src/mastra` folder contain
 
 :::tip
 
-You can use [flags](/reference/v1/cli/create-mastra#cli-flags)  with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/docs/v1/getting-started/templates)
+You can use [flags](/reference/v1/cli/create-mastra#cli-flags)  with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates)
 
 :::
 
@@ -80,7 +80,7 @@ Try asking about the weather. If your API key is set up correctly, you'll get a
 
 ## Next steps
 
-- Integrate Mastra with your frontend framework: [Next.js](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/astro)
+- Integrate Mastra with your frontend framework: [Next.js](/guides/v1/getting-started/next-js), [React](/guides/v1/getting-started/vite-react), or [Astro](/guides/v1/getting-started/astro)
 - Read more about [Mastra's features](/docs/v1#why-mastra)
 - Build an agent from scratch following one of our [guides](/guides/v1)
 - Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)