Wire the Mastra TypeScript agent framework into a React chat UI with assistant-ui, with full streaming, tool calling, multi-agent support, and thread management.
Mastra is an open-source TypeScript agent framework. It provides primitives for AI applications: agents with memory and tool calling, deterministic LLM workflows, RAG, model routing, workflow graphs, and automated evals.
Info
This is an integration guide, not a runtime adapter. assistant-ui does not ship a @assistant-ui/react-mastra package. You wire up Mastra through the standard AI SDK runtime by routing your API endpoint through Mastra's agent stream.
Pick a pattern
| Pattern | When to pick |
|---|---|
| Full-stack | One Next.js app: API routes call Mastra in-process. Simpler deployment, single repo. |
| Separate server | Mastra runs as its own service; the Next.js frontend hits its API. Independent scaling, clearer separation of concerns. |
Both use the same client-side useChatRuntime from @assistant-ui/ai-sdk. The only difference is where the Mastra agent lives.
Architecture
Mastra integrates at the LLM-client layer on the server. assistant-ui talks to your API route via the AI SDK runtime; the route calls agent.stream(messages) and returns the result wrapped in a UI message stream. The client side is built on ExternalStoreRuntime through the AI SDK adapter.
Shared adapters (attachments, speech, feedback, history) work the same way described in adapters. Multi-thread support uses AssistantCloud or a custom thread list.
With Assistant Cloud, add cloud to the useChatRuntime call of either pattern and the app gets the thread list, message persistence, automatic titles, run reports and engagement events; a messageMetadata callback on the route fills in the model and usage of each run the same way as on any AI SDK route. See AI SDK + assistant-ui.
Requirements
- A Next.js project, or another framework that can run AI SDK route handlers.
- Model API keys (OpenAI, Anthropic, etc.) configured in your environment.
- Node 18 or newer.