UI Dojo

When iterating over messages from useChat, you can inspect the parts array of each message to render specific UI elements based on the part.type. Supported types in this implementation include:

• text: Standard text response. Use the <Response> component for formatting.
• reasoning: Internal model thought process. Use <Reasoning> components to display this.
• source-url: URLs provided by the model as citations. Use <Sources> and <Source> to render these.

You can use getVisibleReasoningText(message.parts) to extract reasoning text for display.

{message.parts.map((part, i) => {
  switch (part.type) {
    case "text":
      return (
        <Message from={message.role}>
          <MessageContent>
            <Response>{part.text}</Response>
          </MessageContent>
        </Message>
      );
    case "reasoning":
      // Handle reasoning separately or via getVisibleReasoningText
      return null;
    case "source-url":
      // Render using <Sources> component
      return null;
    default:
      return null;
  }
})} 

You can implement a "Shared State" pattern where an agent manages a structured piece of data (the "working memory") that is synchronized with a UI. This is achieved by configuring workingMemory within the Memory instance.

Key configuration options:

• enabled: Boolean to activate working memory.
• scope: The scope of the memory (e.g., "thread").
• schema: A Zod object defining the structure of the state.

When the agent uses tools to update this memory, the changes can be streamed to the frontend as STATE_DELTA events, allowing the UI to reflect the agent's internal state changes in real-time.

export const ckSharedStateAgent = new Agent({
  id: "ck_shared_state",
  // ... instructions ...
  memory: new Memory({
    storage: getStorage(),
    options: {
      workingMemory: {
        enabled: true,
        scope: "thread",
        schema: z.object({
          recipe: z.object({
            skill_level: z.enum(["Beginner", "Intermediate", "Advanced"]),
            special_preferences: z.array(z.enum(["High Protein", "Low Carb", "Spicy", "Budget-Friendly", "One-Pot Meal", "Vegetarian", "Vegan"])),
            cooking_time: z.enum(["5 min", "15 min", "30 min", "45 min", "60+ min"]),
            ingredients: z.array(z.object({
              icon: z.string(),
              name: z.string(),
              amount: z.string(),
            })),
            instructions: z.array(z.string()),
          }),
        }),
      },
    },
  }),
});

To use @assistant-ui/react with Mastra's chat capabilities, you can implement a custom runtime using useExternalStoreRuntime. This allows you to bridge Mastra's useChat hook with the Assistant UI component tree.

Key steps in the integration pattern:

1. Use Mastra's useChat hook to manage messages, sending, and running state.
2. Map Mastra messages to Assistant UI compatible formats using toAssistantUIMessage from @mastra/react.
3. Implement onNew to call Mastra's sendMessage with mode: "stream".
4. Implement onCancel to trigger an AbortController and Mastra's cancelRun.
5. Wrap your chat components in AssistantRuntimeProvider using the runtime created by useExternalStoreRuntime.

import { 
  useChat, 
  toAssistantUIMessage 
} from "@mastra/react";
import { 
  AssistantRuntimeProvider, 
  useExternalStoreRuntime, 
  type AppendMessage 
} from "@assistant-ui/react";

// Inside your component:
const { messages, sendMessage, cancelRun, isRunning: isRunningStream, setMessages } = useChat({
  agentId,
  initialMessages: initialMessages || [],
});

const onNew = async (message: AppendMessage) => {
  const input = message.content[0].text;
  await sendMessage({
    message: input,
    mode: "stream",
    threadId,
  });
};

const runtime = useExternalStoreRuntime({
  isRunning: isRunningStream,
  messages: messages.map(toAssistantUIMessage),
  convertMessage: (x) => x,
  onNew,
  onCancel: async () => { /* implement abort logic */ cancelRun?.(); },
});

return (
  <AssistantRuntimeProvider runtime={runtime}>
    {children}
  </AssistantRuntimeProvider>
);

To build a chat interface using the Vercel AI SDK (@ai-sdk/react) and Mastra, use the useChat hook. You must provide a transport configured with a DefaultChatTransport pointing to your Mastra agent's chat route.

When calling sendMessage, you can pass an optional body object to include additional parameters (like model or webSearch) that your Mastra agent expects.

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";

const { messages, sendMessage, status, regenerate } = useChat({
  transport: new DefaultChatTransport({
    // The endpoint defined in your Mastra configuration
    api: `${MASTRA_BASE_URL}/chat/yourAgentName`,
  }),
});

// Sending a message with custom body parameters
const handleSubmit = (text: string) => {
  sendMessage(
    { text },
    {
      body: {
        model: "openai/gpt-4o",
        webSearch: true,
      },
    }
  );
};