@assistant-ui/mcp-docs-server 0.1.17 → 0.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (202) hide show
  1. package/.docs/organized/code-examples/with-ag-ui.md +518 -234
  2. package/.docs/organized/code-examples/{with-ai-sdk-v5.md → with-ai-sdk-v6.md} +476 -189
  3. package/.docs/organized/code-examples/with-assistant-transport.md +503 -301
  4. package/.docs/organized/code-examples/with-cloud.md +524 -226
  5. package/.docs/organized/code-examples/with-custom-thread-list.md +433 -146
  6. package/.docs/organized/code-examples/with-elevenlabs-scribe.md +2241 -0
  7. package/.docs/organized/code-examples/with-external-store.md +517 -231
  8. package/.docs/organized/code-examples/with-ffmpeg.md +500 -220
  9. package/.docs/organized/code-examples/with-langgraph.md +630 -319
  10. package/.docs/organized/code-examples/with-parent-id-grouping.md +517 -231
  11. package/.docs/organized/code-examples/with-react-hook-form.md +517 -233
  12. package/.docs/organized/code-examples/with-react-router.md +2167 -0
  13. package/.docs/organized/code-examples/{store-example.md → with-store.md} +18 -22
  14. package/.docs/organized/code-examples/with-tanstack.md +23 -41
  15. package/.docs/raw/blog/2025-01-31-changelog/index.mdx +0 -2
  16. package/.docs/raw/docs/{about-assistantui.mdx → (docs)/about-assistantui.mdx} +2 -1
  17. package/.docs/raw/docs/{architecture.mdx → (docs)/architecture.mdx} +3 -2
  18. package/.docs/raw/docs/{cli.mdx → (docs)/cli.mdx} +1 -19
  19. package/.docs/raw/docs/{copilots → (docs)/copilots}/make-assistant-readable.mdx +1 -0
  20. package/.docs/raw/docs/{copilots → (docs)/copilots}/make-assistant-tool-ui.mdx +2 -1
  21. package/.docs/raw/docs/{copilots → (docs)/copilots}/make-assistant-tool.mdx +2 -1
  22. package/.docs/raw/docs/{copilots → (docs)/copilots}/model-context.mdx +1 -0
  23. package/.docs/raw/docs/{copilots → (docs)/copilots}/motivation.mdx +1 -0
  24. package/.docs/raw/docs/{copilots → (docs)/copilots}/use-assistant-instructions.mdx +1 -0
  25. package/.docs/raw/docs/{devtools.mdx → (docs)/devtools.mdx} +4 -4
  26. package/.docs/raw/docs/{guides/Attachments.mdx → (docs)/guides/attachments.mdx} +4 -5
  27. package/.docs/raw/docs/{guides/Branching.mdx → (docs)/guides/branching.mdx} +2 -1
  28. package/.docs/raw/docs/{guides → (docs)/guides}/context-api.mdx +1 -0
  29. package/.docs/raw/docs/(docs)/guides/dictation.mdx +370 -0
  30. package/.docs/raw/docs/{guides/Editing.mdx → (docs)/guides/editing.mdx} +1 -0
  31. package/.docs/raw/docs/{guides/Latex.mdx → (docs)/guides/latex.mdx} +1 -2
  32. package/.docs/raw/docs/{guides/Speech.mdx → (docs)/guides/speech.mdx} +9 -10
  33. package/.docs/raw/docs/{guides/ToolUI.mdx → (docs)/guides/tool-ui.mdx} +15 -14
  34. package/.docs/raw/docs/{guides/Tools.mdx → (docs)/guides/tools.mdx} +10 -7
  35. package/.docs/raw/docs/{getting-started.mdx → (docs)/index.mdx} +17 -22
  36. package/.docs/raw/docs/{mcp-docs-server.mdx → (docs)/mcp-docs-server.mdx} +1 -2
  37. package/.docs/raw/docs/{api-reference/context-providers/AssistantRuntimeProvider.mdx → (reference)/api-reference/context-providers/assistant-runtime-provider.mdx} +2 -1
  38. package/.docs/raw/docs/{api-reference/context-providers/TextMessagePartProvider.mdx → (reference)/api-reference/context-providers/text-message-part-provider.mdx} +2 -1
  39. package/.docs/raw/docs/{api-reference → (reference)/api-reference}/integrations/react-data-stream.mdx +2 -1
  40. package/.docs/raw/docs/{api-reference → (reference)/api-reference}/integrations/react-hook-form.mdx +2 -1
  41. package/.docs/raw/docs/{api-reference → (reference)/api-reference}/integrations/vercel-ai-sdk.mdx +2 -2
  42. package/.docs/raw/docs/{api-reference → (reference)/api-reference}/overview.mdx +1 -1
  43. package/.docs/raw/docs/(reference)/api-reference/primitives/action-bar-more.mdx +327 -0
  44. package/.docs/raw/docs/{api-reference/primitives/ActionBar.mdx → (reference)/api-reference/primitives/action-bar.mdx} +3 -1
  45. package/.docs/raw/docs/{api-reference/primitives/AssistantIf.mdx → (reference)/api-reference/primitives/assistant-if.mdx} +2 -2
  46. package/.docs/raw/docs/{api-reference/primitives/AssistantModal.mdx → (reference)/api-reference/primitives/assistant-modal.mdx} +3 -1
  47. package/.docs/raw/docs/{api-reference/primitives/Attachment.mdx → (reference)/api-reference/primitives/attachment.mdx} +3 -2
  48. package/.docs/raw/docs/{api-reference/primitives/BranchPicker.mdx → (reference)/api-reference/primitives/branch-picker.mdx} +2 -1
  49. package/.docs/raw/docs/{api-reference/primitives/Composer.mdx → (reference)/api-reference/primitives/composer.mdx} +101 -2
  50. package/.docs/raw/docs/{api-reference → (reference)/api-reference}/primitives/composition.mdx +1 -0
  51. package/.docs/raw/docs/{api-reference/primitives/Error.mdx → (reference)/api-reference/primitives/error.mdx} +2 -1
  52. package/.docs/raw/docs/{api-reference/primitives/MessagePart.mdx → (reference)/api-reference/primitives/message-part.mdx} +2 -2
  53. package/.docs/raw/docs/{api-reference/primitives/Message.mdx → (reference)/api-reference/primitives/message.mdx} +2 -1
  54. package/.docs/raw/docs/(reference)/api-reference/primitives/thread-list-item-more.mdx +221 -0
  55. package/.docs/raw/docs/{api-reference/primitives/ThreadListItem.mdx → (reference)/api-reference/primitives/thread-list-item.mdx} +2 -1
  56. package/.docs/raw/docs/{api-reference/primitives/ThreadList.mdx → (reference)/api-reference/primitives/thread-list.mdx} +2 -1
  57. package/.docs/raw/docs/{api-reference/primitives/Thread.mdx → (reference)/api-reference/primitives/thread.mdx} +2 -1
  58. package/.docs/raw/docs/{api-reference/runtimes/AssistantRuntime.mdx → (reference)/api-reference/runtimes/assistant-runtime.mdx} +2 -1
  59. package/.docs/raw/docs/{api-reference/runtimes/AttachmentRuntime.mdx → (reference)/api-reference/runtimes/attachment-runtime.mdx} +3 -2
  60. package/.docs/raw/docs/{api-reference/runtimes/ComposerRuntime.mdx → (reference)/api-reference/runtimes/composer-runtime.mdx} +2 -1
  61. package/.docs/raw/docs/{api-reference/runtimes/MessagePartRuntime.mdx → (reference)/api-reference/runtimes/message-part-runtime.mdx} +3 -2
  62. package/.docs/raw/docs/{api-reference/runtimes/MessageRuntime.mdx → (reference)/api-reference/runtimes/message-runtime.mdx} +3 -2
  63. package/.docs/raw/docs/{api-reference/runtimes/ThreadListItemRuntime.mdx → (reference)/api-reference/runtimes/thread-list-item-runtime.mdx} +2 -1
  64. package/.docs/raw/docs/{api-reference/runtimes/ThreadListRuntime.mdx → (reference)/api-reference/runtimes/thread-list-runtime.mdx} +2 -1
  65. package/.docs/raw/docs/{api-reference/runtimes/ThreadRuntime.mdx → (reference)/api-reference/runtimes/thread-runtime.mdx} +3 -5
  66. package/.docs/raw/docs/{legacy/styled/AssistantModal.mdx → (reference)/legacy/styled/assistant-modal.mdx} +2 -3
  67. package/.docs/raw/docs/{legacy/styled/Decomposition.mdx → (reference)/legacy/styled/decomposition.mdx} +1 -0
  68. package/.docs/raw/docs/{legacy/styled/Markdown.mdx → (reference)/legacy/styled/markdown.mdx} +2 -4
  69. package/.docs/raw/docs/{legacy/styled/Scrollbar.mdx → (reference)/legacy/styled/scrollbar.mdx} +2 -1
  70. package/.docs/raw/docs/{legacy/styled/ThreadWidth.mdx → (reference)/legacy/styled/thread-width.mdx} +1 -0
  71. package/.docs/raw/docs/{legacy/styled/Thread.mdx → (reference)/legacy/styled/thread.mdx} +2 -3
  72. package/.docs/raw/docs/{migrations → (reference)/migrations}/deprecation-policy.mdx +1 -0
  73. package/.docs/raw/docs/{migrations → (reference)/migrations}/react-langgraph-v0-7.mdx +1 -2
  74. package/.docs/raw/docs/{migrations → (reference)/migrations}/v0-11.mdx +1 -0
  75. package/.docs/raw/docs/{migrations → (reference)/migrations}/v0-12.mdx +1 -0
  76. package/.docs/raw/docs/{react-compatibility.mdx → (reference)/react-compatibility.mdx} +2 -3
  77. package/.docs/raw/docs/cloud/authorization.mdx +1 -0
  78. package/.docs/raw/docs/cloud/overview.mdx +1 -0
  79. package/.docs/raw/docs/cloud/persistence/ai-sdk.mdx +2 -3
  80. package/.docs/raw/docs/cloud/persistence/langgraph.mdx +5 -7
  81. package/.docs/raw/docs/runtimes/ai-sdk/use-chat.mdx +9 -8
  82. package/.docs/raw/docs/runtimes/ai-sdk/v4-legacy.mdx +2 -3
  83. package/.docs/raw/docs/runtimes/assistant-transport.mdx +7 -6
  84. package/.docs/raw/docs/runtimes/custom/custom-thread-list.mdx +38 -3
  85. package/.docs/raw/docs/runtimes/custom/external-store.mdx +6 -8
  86. package/.docs/raw/docs/runtimes/custom/local.mdx +43 -16
  87. package/.docs/raw/docs/runtimes/data-stream.mdx +32 -4
  88. package/.docs/raw/docs/runtimes/helicone.mdx +1 -0
  89. package/.docs/raw/docs/runtimes/langgraph/index.mdx +3 -3
  90. package/.docs/raw/docs/runtimes/langgraph/tutorial/index.mdx +1 -0
  91. package/.docs/raw/docs/runtimes/langgraph/tutorial/introduction.mdx +1 -0
  92. package/.docs/raw/docs/runtimes/langgraph/tutorial/part-1.mdx +1 -0
  93. package/.docs/raw/docs/runtimes/langgraph/tutorial/part-2.mdx +1 -0
  94. package/.docs/raw/docs/runtimes/langgraph/tutorial/part-3.mdx +2 -1
  95. package/.docs/raw/docs/runtimes/langserve.mdx +2 -2
  96. package/.docs/raw/docs/runtimes/mastra/full-stack-integration.mdx +4 -5
  97. package/.docs/raw/docs/runtimes/mastra/overview.mdx +1 -0
  98. package/.docs/raw/docs/runtimes/mastra/separate-server-integration.mdx +3 -4
  99. package/.docs/raw/docs/runtimes/pick-a-runtime.mdx +2 -4
  100. package/.docs/raw/docs/ui/assistant-modal.mdx +163 -0
  101. package/.docs/raw/docs/ui/assistant-sidebar.mdx +90 -0
  102. package/.docs/raw/docs/ui/attachment.mdx +227 -0
  103. package/.docs/raw/docs/ui/{Markdown.mdx → markdown.mdx} +11 -6
  104. package/.docs/raw/docs/ui/{Mermaid.mdx → mermaid.mdx} +12 -5
  105. package/.docs/raw/docs/ui/{PartGrouping.mdx → part-grouping.mdx} +4 -6
  106. package/.docs/raw/docs/ui/reasoning.mdx +148 -0
  107. package/.docs/raw/docs/ui/{Scrollbar.mdx → scrollbar.mdx} +9 -7
  108. package/.docs/raw/docs/ui/sources.mdx +87 -0
  109. package/.docs/raw/docs/ui/{SyntaxHighlighting.mdx → syntax-highlighting.mdx} +9 -5
  110. package/.docs/raw/docs/ui/thread-list.mdx +275 -0
  111. package/.docs/raw/docs/ui/{Thread.mdx → thread.mdx} +5 -6
  112. package/.docs/raw/docs/ui/tool-fallback.mdx +112 -0
  113. package/.docs/raw/docs/ui/tool-group.mdx +214 -0
  114. package/dist/constants.d.ts +10 -0
  115. package/dist/constants.d.ts.map +1 -0
  116. package/dist/constants.js +14 -0
  117. package/dist/constants.js.map +1 -0
  118. package/dist/index.d.ts +4 -0
  119. package/dist/index.d.ts.map +1 -0
  120. package/dist/index.js +33 -1
  121. package/dist/index.js.map +1 -0
  122. package/dist/prepare-docs/code-examples.d.ts +2 -0
  123. package/dist/prepare-docs/code-examples.d.ts.map +1 -0
  124. package/dist/prepare-docs/code-examples.js +129 -0
  125. package/dist/prepare-docs/code-examples.js.map +1 -0
  126. package/dist/prepare-docs/copy-raw.d.ts +2 -0
  127. package/dist/prepare-docs/copy-raw.d.ts.map +1 -0
  128. package/dist/prepare-docs/copy-raw.js +50 -0
  129. package/dist/prepare-docs/copy-raw.js.map +1 -0
  130. package/dist/prepare-docs/prepare.d.ts +2 -0
  131. package/dist/prepare-docs/prepare.d.ts.map +1 -0
  132. package/dist/prepare-docs/prepare.js +18 -195
  133. package/dist/prepare-docs/prepare.js.map +1 -0
  134. package/dist/stdio.d.ts +3 -0
  135. package/dist/stdio.d.ts.map +1 -0
  136. package/dist/stdio.js +4 -5
  137. package/dist/stdio.js.map +1 -0
  138. package/dist/tools/docs.d.ts +23 -0
  139. package/dist/tools/docs.d.ts.map +1 -0
  140. package/dist/tools/docs.js +168 -0
  141. package/dist/tools/docs.js.map +1 -0
  142. package/dist/tools/examples.d.ts +23 -0
  143. package/dist/tools/examples.d.ts.map +1 -0
  144. package/dist/tools/examples.js +95 -0
  145. package/dist/tools/examples.js.map +1 -0
  146. package/dist/tools/tests/test-setup.d.ts +4 -0
  147. package/dist/tools/tests/test-setup.d.ts.map +1 -0
  148. package/dist/tools/tests/test-setup.js +36 -0
  149. package/dist/tools/tests/test-setup.js.map +1 -0
  150. package/dist/utils/logger.d.ts +7 -0
  151. package/dist/utils/logger.d.ts.map +1 -0
  152. package/dist/utils/logger.js +20 -0
  153. package/dist/utils/logger.js.map +1 -0
  154. package/dist/utils/mcp-format.d.ts +7 -0
  155. package/dist/utils/mcp-format.d.ts.map +1 -0
  156. package/dist/utils/mcp-format.js +11 -0
  157. package/dist/utils/mcp-format.js.map +1 -0
  158. package/dist/utils/mdx.d.ts +9 -0
  159. package/dist/utils/mdx.d.ts.map +1 -0
  160. package/dist/utils/mdx.js +27 -0
  161. package/dist/utils/mdx.js.map +1 -0
  162. package/dist/utils/paths.d.ts +8 -0
  163. package/dist/utils/paths.d.ts.map +1 -0
  164. package/dist/utils/paths.js +84 -0
  165. package/dist/utils/paths.js.map +1 -0
  166. package/dist/utils/security.d.ts +2 -0
  167. package/dist/utils/security.d.ts.map +1 -0
  168. package/dist/utils/security.js +43 -0
  169. package/dist/utils/security.js.map +1 -0
  170. package/package.json +37 -19
  171. package/src/constants.ts +22 -0
  172. package/src/index.ts +51 -0
  173. package/src/prepare-docs/code-examples.ts +158 -0
  174. package/src/prepare-docs/copy-raw.ts +55 -0
  175. package/src/prepare-docs/prepare.ts +24 -0
  176. package/src/stdio.ts +7 -0
  177. package/src/tools/docs.ts +207 -0
  178. package/src/tools/examples.ts +107 -0
  179. package/src/tools/tests/docs.test.ts +124 -0
  180. package/src/tools/tests/examples.test.ts +94 -0
  181. package/src/tools/tests/integration.test.ts +46 -0
  182. package/src/tools/tests/json-parsing.test.ts +23 -0
  183. package/src/tools/tests/mcp-protocol.test.ts +133 -0
  184. package/src/tools/tests/path-traversal.test.ts +81 -0
  185. package/src/tools/tests/test-setup.ts +40 -0
  186. package/src/utils/logger.ts +20 -0
  187. package/src/utils/mcp-format.ts +12 -0
  188. package/src/utils/mdx.ts +39 -0
  189. package/src/utils/paths.ts +114 -0
  190. package/src/utils/security.ts +52 -0
  191. package/src/utils/tests/security.test.ts +119 -0
  192. package/.docs/raw/docs/index.mdx +0 -7
  193. package/.docs/raw/docs/ui/AssistantModal.mdx +0 -45
  194. package/.docs/raw/docs/ui/AssistantSidebar.mdx +0 -41
  195. package/.docs/raw/docs/ui/Attachment.mdx +0 -84
  196. package/.docs/raw/docs/ui/Reasoning.mdx +0 -152
  197. package/.docs/raw/docs/ui/ThreadList.mdx +0 -90
  198. package/.docs/raw/docs/ui/ToolFallback.mdx +0 -63
  199. package/.docs/raw/docs/ui/ToolGroup.mdx +0 -96
  200. package/dist/chunk-M2RKUM66.js +0 -38
  201. package/dist/chunk-NVNFQ5ZO.js +0 -423
  202. /package/.docs/raw/docs/{copilots → (docs)/copilots}/assistant-frame.mdx +0 -0
@@ -1,10 +1,8 @@
1
1
  ---
2
2
  title: Assistant Transport
3
+ description: Stream agent state to the frontend and handle user commands for custom agents.
3
4
  ---
4
5
 
5
- import { Callout } from "fumadocs-ui/components/callout";
6
- import { Tab, Tabs } from "fumadocs-ui/components/tabs";
7
-
8
6
  If you've built an agent as a Python or TypeScript script and want to add a UI to it, you need to solve two problems: streaming updates to the frontend and integrating with the UI framework. Assistant Transport handles both.
9
7
 
10
8
  Assistant Transport streams your agent's complete state to the frontend in real-time. Unlike traditional approaches that only stream predefined message types (like text or tool calls), it streams your entire agent state—whatever structure your agent uses internally.
@@ -71,7 +69,8 @@ The backend endpoint receives POST requests with the following payload:
71
69
  state: T, // The previous state that the frontend has access to
72
70
  commands: AssistantTransportCommand[],
73
71
  system?: string,
74
- tools?: ToolDefinition[]
72
+ tools?: ToolDefinition[],
73
+ threadId: string // The current thread/conversation identifier
75
74
  }
76
75
  ```
77
76
 
@@ -483,9 +482,11 @@ const runtime = useAssistantTransportRuntime({
483
482
  "Authorization": `Bearer ${await getAccessToken()}`,
484
483
  "X-Request-ID": crypto.randomUUID(),
485
484
  }),
486
- body: {
485
+ body: async () => ({
487
486
  customField: "value",
488
- },
487
+ requestId: crypto.randomUUID(),
488
+ timestamp: Date.now(),
489
+ }),
489
490
  });
490
491
  ```
491
492
 
@@ -1,10 +1,9 @@
1
1
  ---
2
2
  title: Custom Thread List
3
+ description: Plug a custom thread database for multi-thread persistence.
3
4
  ---
4
5
 
5
- import { Callout } from "fumadocs-ui/components/callout";
6
- import { Steps, Step } from "fumadocs-ui/components/steps";
7
- import { ParametersTable } from "@/components/docs";
6
+ import { ParametersTable } from "@/components/docs/tables/ParametersTable";
8
7
 
9
8
  ## Overview
10
9
 
@@ -217,6 +216,42 @@ When the hook mounts it calls `list()` on your adapter, hydrates existing thread
217
216
  - `generateTitle()` powers the automatic title button and expects an `AssistantStream`.
218
217
  - Provide a `runtimeHook` that always returns a fresh runtime instance per active thread.
219
218
 
219
+ ## Avoiding Race Conditions in History Adapters
220
+
221
+ <Callout type="warn">
222
+ When implementing a custom history adapter, you must await thread initialization before saving messages. Failing to do so can cause the first message to be lost due to a race condition.
223
+ </Callout>
224
+
225
+ If you're building a history adapter that persists messages to your own database, use `api.threadListItem().initialize()` to ensure the thread is fully initialized before saving:
226
+
227
+ ```tsx
228
+ import { useAssistantApi } from "@assistant-ui/react";
229
+
230
+ // Inside your unstable_Provider component
231
+ const api = useAssistantApi();
232
+
233
+ const history = useMemo<ThreadHistoryAdapter>(
234
+ () => ({
235
+ async append(message) {
236
+ // Wait for initialization to complete and get the remoteId
237
+ const { remoteId } = await api.threadListItem().initialize();
238
+
239
+ // Now safe to save the message using the remoteId
240
+ await saveMessageToDatabase(remoteId, message);
241
+ },
242
+ // ...
243
+ }),
244
+ [api],
245
+ );
246
+ ```
247
+
248
+ The `initialize()` method:
249
+ - Can be called multiple times safely
250
+ - Always waits for the initial `initialize()` call to complete
251
+ - Returns the same `remoteId` on subsequent calls
252
+
253
+ See `AssistantCloudThreadHistoryAdapter` in the source code for a production-ready reference implementation.
254
+
220
255
  ## Optional Adapters
221
256
 
222
257
  If you need history or attachment support, expose them via `unstable_Provider`. The cloud implementation wraps each thread runtime with `RuntimeAdapterProvider` to inject:
@@ -1,12 +1,10 @@
1
1
  ---
2
2
  title: ExternalStoreRuntime
3
+ description: Bring your own Redux, Zustand, or state manager.
3
4
  ---
4
5
 
5
- import { Callout } from "fumadocs-ui/components/callout";
6
- import { Steps, Step } from "fumadocs-ui/components/steps";
7
- import { Card, Cards } from "fumadocs-ui/components/card";
8
- import { ParametersTable } from "@/components/docs";
9
- import { InstallCommand } from "@/components/docs/install-command";
6
+ import { ParametersTable } from "@/components/docs/tables/ParametersTable";
7
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
10
8
 
11
9
  ## Overview
12
10
 
@@ -1618,9 +1616,9 @@ Enable multi-thread support with custom thread management.
1618
1616
 
1619
1617
  ### Related Runtime APIs
1620
1618
 
1621
- - [AssistantRuntime API](/docs/api-reference/runtimes/AssistantRuntime) - Core runtime interface and methods
1622
- - [ThreadRuntime API](/docs/api-reference/runtimes/ThreadRuntime) - Thread-specific operations and state management
1623
- - [Runtime Providers](/docs/api-reference/context-providers/AssistantRuntimeProvider) - Context providers for runtime integration
1619
+ - [AssistantRuntime API](/docs/api-reference/runtimes/assistant-runtime) - Core runtime interface and methods
1620
+ - [ThreadRuntime API](/docs/api-reference/runtimes/thread-runtime) - Thread-specific operations and state management
1621
+ - [Runtime Providers](/docs/api-reference/context-providers/assistant-runtime-provider) - Context providers for runtime integration
1624
1622
 
1625
1623
  ## Related Resources
1626
1624
 
@@ -1,12 +1,10 @@
1
1
  ---
2
2
  title: LocalRuntime
3
+ description: Quickest path to a working chat. Handles state while you handle the API.
3
4
  ---
4
5
 
5
- import { Callout } from "fumadocs-ui/components/callout";
6
- import { Steps, Step } from "fumadocs-ui/components/steps";
7
- import { Card, Cards } from "fumadocs-ui/components/card";
8
- import { ParametersTable } from "@/components/docs";
9
- import { InstallCommand } from "@/components/docs/install-command";
6
+ import { ParametersTable } from "@/components/docs/tables/ParametersTable";
7
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
10
8
 
11
9
  ## Overview
12
10
 
@@ -415,7 +413,7 @@ For custom thread storage, use `useRemoteThreadListRuntime` with your own adapte
415
413
  ```tsx
416
414
  import {
417
415
  unstable_useRemoteThreadListRuntime as useRemoteThreadListRuntime,
418
- useThreadListItem,
416
+ useAssistantApi,
419
417
  RuntimeAdapterProvider,
420
418
  AssistantRuntimeProvider,
421
419
  type unstable_RemoteThreadListAdapter as RemoteThreadListAdapter,
@@ -487,13 +485,13 @@ export function MyRuntimeProvider({ children }) {
487
485
  // The Provider component adds thread-specific adapters
488
486
  unstable_Provider: ({ children }) => {
489
487
  // This runs in the context of each thread
490
- const threadListItem = useThreadListItem();
491
- const remoteId = threadListItem.remoteId;
488
+ const api = useAssistantApi();
492
489
 
493
490
  // Create thread-specific history adapter
494
491
  const history = useMemo<ThreadHistoryAdapter>(
495
492
  () => ({
496
493
  async load() {
494
+ const { remoteId } = api.threadListItem().getState();
497
495
  if (!remoteId) return { messages: [] };
498
496
 
499
497
  const messages = await db.messages.findByThreadId(remoteId);
@@ -508,10 +506,8 @@ export function MyRuntimeProvider({ children }) {
508
506
  },
509
507
 
510
508
  async append(message) {
511
- if (!remoteId) {
512
- console.warn("Cannot save message - thread not initialized");
513
- return;
514
- }
509
+ // Wait for initialization to get remoteId (safe to call multiple times)
510
+ const { remoteId } = await api.threadListItem().initialize();
515
511
 
516
512
  await db.messages.create({
517
513
  threadId: remoteId,
@@ -522,7 +518,7 @@ export function MyRuntimeProvider({ children }) {
522
518
  });
523
519
  },
524
520
  }),
525
- [remoteId],
521
+ [api],
526
522
  );
527
523
 
528
524
  const adapters = useMemo(() => ({ history }), [history]);
@@ -570,6 +566,31 @@ The complete multi-thread implementation requires:
570
566
 
571
567
  Without the history adapter, threads would have no message persistence, making them effectively useless. The Provider pattern allows you to add thread-specific functionality while keeping the runtime creation simple.
572
568
 
569
+ <Callout type="warn" title="Avoiding Race Conditions">
570
+ When implementing a history adapter, `append()` may be called before the thread is fully initialized, causing the first message to be lost. Instead of checking `if (!remoteId)`, await initialization to ensure the `remoteId` is available:
571
+
572
+ ```tsx
573
+ import { useAssistantApi } from "@assistant-ui/react";
574
+
575
+ // Inside your unstable_Provider component
576
+ const api = useAssistantApi();
577
+
578
+ const history = useMemo<ThreadHistoryAdapter>(
579
+ () => ({
580
+ async append(message) {
581
+ // Wait for initialization - safe to call multiple times
582
+ const { remoteId } = await api.threadListItem().initialize();
583
+ await db.messages.create({ threadId: remoteId, ...message });
584
+ },
585
+ // ...
586
+ }),
587
+ [api],
588
+ );
589
+ ```
590
+
591
+ See `AssistantCloudThreadHistoryAdapter` in the source for a production reference.
592
+ </Callout>
593
+
573
594
  #### Database Schema Example
574
595
 
575
596
  ```typescript
@@ -877,7 +898,7 @@ const OpenAIAdapter: ChatModelAdapter = {
877
898
 
878
899
  ```tsx
879
900
  const CustomAPIAdapter: ChatModelAdapter = {
880
- async run({ messages, abortSignal }) {
901
+ async run({ messages, abortSignal, unstable_threadId }) {
881
902
  const response = await fetch("/api/chat", {
882
903
  method: "POST",
883
904
  headers: { "Content-Type": "application/json" },
@@ -886,6 +907,7 @@ const CustomAPIAdapter: ChatModelAdapter = {
886
907
  role: m.role,
887
908
  content: m.content,
888
909
  })),
910
+ threadId: unstable_threadId, // Pass thread ID to your backend
889
911
  }),
890
912
  signal: abortSignal,
891
913
  });
@@ -1101,6 +1123,11 @@ Parameters passed to the `run` function.
1101
1123
  description: "Additional context including configuration and tools",
1102
1124
  required: true,
1103
1125
  },
1126
+ {
1127
+ name: "unstable_threadId",
1128
+ type: "string | undefined",
1129
+ description: "The current thread/conversation identifier. Useful for passing to your backend API.",
1130
+ },
1104
1131
  ]}
1105
1132
  />
1106
1133
 
@@ -1230,8 +1257,8 @@ Interface for implementing custom thread list storage.
1230
1257
 
1231
1258
  ### Related Runtime APIs
1232
1259
 
1233
- - [AssistantRuntime API](/docs/api-reference/runtimes/AssistantRuntime) - Core runtime interface and methods
1234
- - [ThreadRuntime API](/docs/api-reference/runtimes/ThreadRuntime) - Thread-specific operations and state management
1260
+ - [AssistantRuntime API](/docs/api-reference/runtimes/assistant-runtime) - Core runtime interface and methods
1261
+ - [ThreadRuntime API](/docs/api-reference/runtimes/thread-runtime) - Thread-specific operations and state management
1235
1262
 
1236
1263
  ## Related Resources
1237
1264
 
@@ -1,10 +1,9 @@
1
1
  ---
2
2
  title: Data Stream Protocol
3
+ description: Integration with data stream protocol endpoints for streaming AI responses.
3
4
  ---
4
5
 
5
- import { Step, Steps } from "fumadocs-ui/components/steps";
6
- import { Callout } from "fumadocs-ui/components/callout";
7
- import { InstallCommand } from "@/components/docs/install-command";
6
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
8
7
 
9
8
  The `@assistant-ui/react-data-stream` package provides integration with data stream protocol endpoints, enabling streaming AI responses with tool support and state management.
10
9
 
@@ -63,7 +62,7 @@ Your backend endpoint should accept POST requests and return data stream respons
63
62
  import { createAssistantStreamResponse } from "assistant-stream";
64
63
 
65
64
  export async function POST(request: Request) {
66
- const { messages, tools, system } = await request.json();
65
+ const { messages, tools, system, threadId } = await request.json();
67
66
 
68
67
  return createAssistantStreamResponse(async (controller) => {
69
68
  // Process the request with your AI provider
@@ -81,6 +80,12 @@ export async function POST(request: Request) {
81
80
  }
82
81
  ```
83
82
 
83
+ The request body includes:
84
+ - `messages` - The conversation history
85
+ - `tools` - Available tool definitions
86
+ - `system` - System prompt (if configured)
87
+ - `threadId` - The current thread/conversation identifier
88
+
84
89
  </Step>
85
90
 
86
91
  </Steps>
@@ -114,6 +119,22 @@ const runtime = useDataStreamRuntime({
114
119
  });
115
120
  ```
116
121
 
122
+ ### Dynamic Body
123
+
124
+ ```tsx
125
+ const runtime = useDataStreamRuntime({
126
+ api: "/api/chat",
127
+ headers: async () => ({
128
+ "Authorization": `Bearer ${await getAuthToken()}`,
129
+ }),
130
+ body: async () => ({
131
+ requestId: crypto.randomUUID(),
132
+ timestamp: Date.now(),
133
+ signature: await computeSignature(),
134
+ }),
135
+ });
136
+ ```
137
+
117
138
  ### Event Callbacks
118
139
 
119
140
  ```tsx
@@ -136,6 +157,13 @@ const runtime = useDataStreamRuntime({
136
157
 
137
158
  ## Tool Integration
138
159
 
160
+ <Callout type="warn">
161
+ Human-in-the-loop tools (using `human()` for tool interrupts) are not supported
162
+ in the data stream runtime. If you need human approval workflows or interactive
163
+ tool UIs, consider using [LocalRuntime](/docs/runtimes/custom/local) or
164
+ [Assistant Cloud](/docs/cloud/overview) instead.
165
+ </Callout>
166
+
139
167
  ### Frontend Tools
140
168
 
141
169
  Use the `frontendTools` helper to serialize client-side tools:
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: Helicone
3
+ description: Configure Helicone proxy for OpenAI API logging and monitoring.
3
4
  ---
4
5
 
5
6
  Helicone acts as a proxy for your OpenAI API calls, enabling detailed logging and monitoring. To integrate, update your API base URL and add the Helicone-Auth header.
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: Getting Started
3
+ description: Connect to LangGraph Cloud API for agent workflows with streaming.
3
4
  ---
4
5
 
5
6
  ## Requirements
@@ -10,7 +11,6 @@ The state of the graph you are using must have a `messages` key with a list of L
10
11
 
11
12
  ## New project from template
12
13
 
13
- import { Steps, Step } from "fumadocs-ui/components/steps";
14
14
 
15
15
  <Steps>
16
16
  <Step>
@@ -36,7 +36,7 @@ NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
36
36
  </Step>
37
37
  </Steps>
38
38
 
39
- import { InstallCommand } from "@/components/docs/install-command";
39
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
40
40
 
41
41
  ## Installation in existing React project
42
42
 
@@ -266,7 +266,7 @@ NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
266
266
 
267
267
  ### Setup UI components
268
268
 
269
- Follow the [UI Components](/docs/ui/shadcn-ui/Thread) guide to setup the UI components.
269
+ Follow the [UI Components](/docs/ui/thread) guide to setup the UI components.
270
270
 
271
271
  </Step>
272
272
  </Steps>
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: "Introduction"
3
+ description: Build a stockbroker assistant with LangGraph and assistant-ui.
3
4
  ---
4
5
 
5
6
  import { redirect } from "next/navigation";
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: "Introduction"
3
+ description: Build a stockbroker assistant with LangGraph and assistant-ui.
3
4
  ---
4
5
 
5
6
  In this tutorial, we will build a stockbroker assistant using LangChain.js, LangGraph.js and assistant-ui.
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: "Part 1: Setup frontend"
3
+ description: Create a Next.js project with the LangGraph assistant-ui template.
3
4
  ---
4
5
 
5
6
  ## Create a new project
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: "Part 2: Generative UI"
3
+ description: Display stock ticker information with generative UI components.
3
4
  ---
4
5
 
5
6
  In the previous step, we set up the frontend to connect to a LangGraph Cloud endpoint.
@@ -1,11 +1,12 @@
1
1
  ---
2
2
  title: "Part 3: Approval UI"
3
+ description: Add human-in-the-loop approval for tool calls.
3
4
  ---
4
5
 
5
6
  ## Background: LangGraph implementation details
6
7
 
7
8
  import Image from "next/image";
8
- import { InstallCommand } from "@/components/docs/install-command";
9
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
9
10
  import approval from "./images/stockbroker-langgraph.png";
10
11
 
11
12
  <Image
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: LangChain LangServe
3
+ description: Connect to LangServe endpoints via Vercel AI SDK integration.
3
4
  ---
4
5
 
5
6
  <Callout type="warning">
@@ -12,8 +13,7 @@ Integration with a LangServe server via Vercel AI SDK.
12
13
 
13
14
  ## Getting Started
14
15
 
15
- import { Steps, Step } from "fumadocs-ui/components/steps";
16
- import { InstallCommand } from "@/components/docs/install-command";
16
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
17
17
 
18
18
  <Steps>
19
19
  <Step>
@@ -1,10 +1,9 @@
1
1
  ---
2
2
  title: Full-Stack Integration
3
+ description: Integrate Mastra directly into Next.js API routes.
3
4
  ---
4
5
 
5
- import { Step, Steps } from "fumadocs-ui/components/steps";
6
- import { Callout } from "fumadocs-ui/components/callout";
7
- import { InstallCommand } from "@/components/docs/install-command";
6
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
8
7
 
9
8
  Integrate Mastra directly into your Next.js application's API routes. This approach keeps your backend and frontend code within the same project.
10
9
 
@@ -28,7 +27,7 @@ This command installs necessary dependencies and creates basic configuration fil
28
27
  <Callout title="Need Help?">
29
28
  For detailed setup instructions, including adding API keys, basic
30
29
  configuration, and manual setup steps, please refer to the main [Getting
31
- Started guide](/docs/getting-started).
30
+ Started guide](/docs).
32
31
  </Callout>
33
32
 
34
33
  </Step>
@@ -138,7 +137,7 @@ This code creates a new Mastra `Agent` named `chef-agent`.
138
137
  - `instructions`: Defines the agent's persona and primary goal.
139
138
  - `model`: Specifies the language model the agent will use (in this case, OpenAI's GPT-4o Mini via Mastra's model router).
140
139
 
141
- Make sure you have set up your OpenAI API key as described in the [Getting Started guide](/docs/getting-started).
140
+ Make sure you have set up your OpenAI API key as described in the [Getting Started guide](/docs).
142
141
 
143
142
  </Step>
144
143
  <Step>
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: Overview
3
+ description: TypeScript agent framework for AI applications with tools and workflows.
3
4
  ---
4
5
 
5
6
  Mastra is an open-source TypeScript agent framework designed to provide the essential primitives for building AI applications. It enables developers to create AI agents with memory and tool-calling capabilities, implement deterministic LLM workflows, and leverage RAG for knowledge integration. With features like model routing, workflow graphs, and automated evals, Mastra provides a complete toolkit for developing, testing, and deploying AI applications.
@@ -1,10 +1,9 @@
1
1
  ---
2
2
  title: Separate Server Integration
3
+ description: Run Mastra as a standalone server connected to your frontend.
3
4
  ---
4
5
 
5
- import { Step, Steps } from "fumadocs-ui/components/steps";
6
- import { Callout } from "fumadocs-ui/components/callout";
7
- import { InstallCommand } from "@/components/docs/install-command";
6
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
8
7
 
9
8
  Run Mastra as a standalone server and connect your Next.js frontend (using assistant-ui) to its API endpoints. This approach separates your AI backend from your frontend application, allowing for independent development and scaling.
10
9
 
@@ -153,7 +152,7 @@ This command installs the necessary assistant-ui dependencies and sets up basic
153
152
  <Callout title="Need Help?">
154
153
  For detailed setup instructions for assistant-ui, including manual setup
155
154
  steps, please refer to the main [Getting Started
156
- guide](/docs/getting-started).
155
+ guide](/docs).
157
156
  </Callout>
158
157
 
159
158
  In the next step, we will configure this frontend to communicate with the separate Mastra server instead of using the default API route.
@@ -1,10 +1,8 @@
1
1
  ---
2
2
  title: Picking a Runtime
3
+ description: Which runtime fits your backend? Decision guide for common setups.
3
4
  ---
4
5
 
5
- import { Card, Cards } from "fumadocs-ui/components/card";
6
- import { Callout } from "fumadocs-ui/components/callout";
7
-
8
6
  Choosing the right runtime is crucial for your assistant-ui implementation. This guide helps you navigate the options based on your specific needs.
9
7
 
10
8
  ## Quick Decision Tree
@@ -187,7 +185,7 @@ const runtime = useExternalStoreRuntime({
187
185
 
188
186
  Explore our implementation examples:
189
187
 
190
- - **[AI SDK Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk)** - Vercel AI SDK with `useChatRuntime`
188
+ - **[AI SDK v6 Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6)** - Vercel AI SDK with `useChatRuntime`
191
189
  - **[External Store Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-external-store)** - `ExternalStoreRuntime` with custom state
192
190
  - **[Assistant Cloud Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud)** - Multi-thread with cloud persistence
193
191
  - **[LangGraph Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)** - Agent workflows
@@ -0,0 +1,163 @@
1
+ ---
2
+ title: AssistantModal
3
+ description: Floating chat bubble for support widgets and help desks.
4
+ ---
5
+
6
+ import { ParametersTable } from "@/components/docs/tables/ParametersTable";
7
+ import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
8
+ import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";
9
+
10
+ A floating chat modal built on Radix UI Popover. Ideal for support widgets, help desks, and embedded assistants.
11
+
12
+ <AssistantModalSample />
13
+
14
+ ## Getting Started
15
+
16
+ <Steps>
17
+ <Step>
18
+
19
+ ### Add `assistant-modal`
20
+
21
+ <InstallCommand shadcn={["assistant-modal"]} />
22
+
23
+ This adds `/components/assistant-ui/assistant-modal.tsx` to your project, which you can adjust as needed.
24
+
25
+ </Step>
26
+ <Step>
27
+
28
+ ### Use in your application
29
+
30
+ ```tsx title="/app/page.tsx" {1,6}
31
+ import { AssistantModal } from "@/components/assistant-ui/assistant-modal";
32
+
33
+ export default function Home() {
34
+ return (
35
+ <div className="h-full">
36
+ <AssistantModal />
37
+ </div>
38
+ );
39
+ }
40
+ ```
41
+
42
+ </Step>
43
+ </Steps>
44
+
45
+ ## Anatomy
46
+
47
+ The AssistantModal component is built with the following primitives:
48
+
49
+ ```tsx
50
+ import { AssistantModalPrimitive } from "@assistant-ui/react";
51
+
52
+ <AssistantModalPrimitive.Root>
53
+ <AssistantModalPrimitive.Anchor />
54
+ <AssistantModalPrimitive.Trigger />
55
+ <AssistantModalPrimitive.Content>
56
+ {/* Thread component goes here */}
57
+ </AssistantModalPrimitive.Content>
58
+ </AssistantModalPrimitive.Root>
59
+ ```
60
+
61
+ ## API Reference
62
+
63
+ ### Root
64
+
65
+ Contains all parts of the modal. Based on Radix UI Popover.
66
+
67
+ <ParametersTable
68
+ type="AssistantModalPrimitiveRootProps"
69
+ parameters={[
70
+ {
71
+ name: "defaultOpen",
72
+ type: "boolean",
73
+ description: "The initial open state when uncontrolled.",
74
+ },
75
+ {
76
+ name: "open",
77
+ type: "boolean",
78
+ description: "The controlled open state.",
79
+ },
80
+ {
81
+ name: "onOpenChange",
82
+ type: "(open: boolean) => void",
83
+ description: "Callback when the open state changes.",
84
+ },
85
+ {
86
+ name: "unstable_openOnRunStart",
87
+ type: "boolean",
88
+ description: "Automatically open the modal when the assistant starts running.",
89
+ },
90
+ ]}
91
+ />
92
+
93
+ ### Trigger
94
+
95
+ A button that toggles the modal open/closed state.
96
+
97
+ <ParametersTable
98
+ type="AssistantModalPrimitiveTriggerProps"
99
+ parameters={[
100
+ {
101
+ name: "asChild",
102
+ type: "boolean",
103
+ default: "false",
104
+ description: "Merge props with child element instead of rendering a wrapper button.",
105
+ },
106
+ ]}
107
+ />
108
+
109
+ This primitive renders a `<button>` element unless `asChild` is set.
110
+
111
+ ### Content
112
+
113
+ The popover content container that holds the chat interface.
114
+
115
+ <ParametersTable
116
+ type="AssistantModalPrimitiveContentProps"
117
+ parameters={[
118
+ {
119
+ name: "side",
120
+ type: "'top' | 'right' | 'bottom' | 'left'",
121
+ default: "'top'",
122
+ description: "The preferred side of the anchor to render against.",
123
+ },
124
+ {
125
+ name: "align",
126
+ type: "'start' | 'center' | 'end'",
127
+ default: "'end'",
128
+ description: "The preferred alignment against the anchor.",
129
+ },
130
+ {
131
+ name: "dissmissOnInteractOutside",
132
+ type: "boolean",
133
+ description: "Whether to close the modal when clicking outside.",
134
+ },
135
+ {
136
+ name: "asChild",
137
+ type: "boolean",
138
+ default: "false",
139
+ description: "Merge props with child element instead of rendering a wrapper div.",
140
+ },
141
+ ]}
142
+ />
143
+
144
+ ### Anchor
145
+
146
+ An optional anchor element to position the modal relative to.
147
+
148
+ <ParametersTable
149
+ type="AssistantModalPrimitiveAnchorProps"
150
+ parameters={[
151
+ {
152
+ name: "asChild",
153
+ type: "boolean",
154
+ default: "false",
155
+ description: "Merge props with child element instead of rendering a wrapper div.",
156
+ },
157
+ ]}
158
+ />
159
+
160
+ ## Related Components
161
+
162
+ - [Thread](/docs/ui/thread) - The main chat interface used inside the modal
163
+ - [AssistantSidebar](/docs/ui/assistant-sidebar) - Alternative layout for side panel chat