Chapter 5: Complete solution with all features

Brings the workshop to final state with all production features:

- Document tools (createDocument, updateDocument, requestSuggestions)
- Enhanced tool prompts for document creation
- UI polish (✓/✗ symbols in flashcard feedback)
- Fixed tool output display in messages
- Complete type definitions for all tools

This represents the final, production-ready chatbot with:
- Multi-modal input (text, images, files)
- Weather tool demonstration
- Study buddy agents (tutor, quiz-master, planner, analyst)
- Custom artifacts (flashcard, study-plan)
- Document creation and versioning

Author: NiallJoeMaher

app/(chat)/api/chat/route.ts

@@ -7,13 +7,6 @@ import {
   stepCountIs,
   streamText,
 } from "ai";
-import {
-  createAnalystAgent,
-  createPlannerAgent,
-  createQuizMasterAgent,
-  createTutorAgent,
-} from "@/lib/ai/agents";
-import { getWeather } from "@/lib/ai/tools/get-weather";
 import { unstable_cache as cache } from "next/cache";
 import type { ModelCatalog } from "tokenlens/core";
 
@@ -29,10 +22,20 @@ import { fetchModels } from "tokenlens/fetch";
 import { getUsage } from "tokenlens/helpers";
 import { auth, type UserType } from "@/app/(auth)/auth";
 import type { VisibilityType } from "@/components/visibility-selector";
+import {
+  createAnalystAgent,
+  createPlannerAgent,
+  createQuizMasterAgent,
+  createTutorAgent,
+} from "@/lib/ai/agents";
 import { entitlementsByUserType } from "@/lib/ai/entitlements";
 import type { ChatModel } from "@/lib/ai/models";
 import { type RequestHints, systemPrompt } from "@/lib/ai/prompts";
 import { myProvider } from "@/lib/ai/providers";
+import { createDocument } from "@/lib/ai/tools/create-document";
+import { getWeather } from "@/lib/ai/tools/get-weather";
+import { requestSuggestions } from "@/lib/ai/tools/request-suggestions";
+import { updateDocument } from "@/lib/ai/tools/update-document";
 import { isProductionEnvironment } from "@/lib/constants";
 import {
   createStreamId,
@@ -189,6 +192,9 @@ export async function POST(request: Request) {
               ? []
               : [
                   "getWeather",
+                  "createDocument",
+                  "updateDocument",
+                  "requestSuggestions",
                   // Study buddy agents
                   "tutor",
                   "quizMaster",
@@ -198,6 +204,12 @@ export async function POST(request: Request) {
           experimental_transform: smoothStream({ chunking: "word" }),
           tools: {
             getWeather,
+            createDocument: createDocument({ session, dataStream }),
+            updateDocument: updateDocument({ session, dataStream }),
+            requestSuggestions: requestSuggestions({
+              session,
+              dataStream,
+            }),
             // Study buddy agents
             tutor: createTutorAgent({ session, dataStream }),
             quizMaster: createQuizMasterAgent({ session, dataStream }),

artifacts/flashcard/client.tsx

@@ -151,8 +151,8 @@ function FlashcardViewer({
         <div className="mb-6 rounded-lg border border-blue-200 bg-blue-50 p-4 dark:border-blue-900 dark:bg-blue-950">
           <p className="font-medium text-blue-900 text-sm dark:text-blue-100">
             {selectedAnswer === currentQuestion.correctAnswer
-              ? "Correct!"
-              : `Incorrect. The correct answer is ${optionLabels[currentQuestion.correctAnswer]}.`}
+              ? "✓ Correct!"
+              : `✗ Incorrect. The correct answer is ${optionLabels[currentQuestion.correctAnswer]}.`}
           </p>
           <p className="mt-2 text-blue-800 text-sm dark:text-blue-200">
             {currentQuestion.explanation}

components/message.tsx

@@ -244,7 +244,7 @@ const PurePreviewMessage = ({
                     {state === "input-available" && (
                       <ToolInput input={part.input} />
                     )}
-                    {state === "output-available" && part.output && (
+                    {state === "output-available" && (
                       <ToolOutput
                         errorText={undefined}
                         output={

components/weather.tsx

@@ -80,7 +80,7 @@ const CloudIcon = ({ size = 24 }: { size?: number }) => (
   </svg>
 );
 
-export type WeatherAtLocation = {
+type WeatherAtLocation = {
   latitude: number;
   longitude: number;
   generationtime_ms: number;

lib/ai/prompts.ts

@@ -1,9 +1,73 @@
 import type { Geo } from "@vercel/functions";
 import type { ArtifactKind } from "@/components/artifact";
 
+export const artifactsPrompt = `
+Artifacts is a special user interface mode that helps users with writing, editing, and other content creation tasks. When artifact is open, it is on the right side of the screen, while the conversation is on the left side. When creating or updating documents, changes are reflected in real-time on the artifacts and visible to the user.
+
+When asked to write code, always use artifacts. When writing code, specify the language in the backticks, e.g. \`\`\`python\`code here\`\`\`. The default language is Python. Other languages are not yet supported, so let the user know if they request a different language.
+
+DO NOT UPDATE DOCUMENTS IMMEDIATELY AFTER CREATING THEM. WAIT FOR USER FEEDBACK OR REQUEST TO UPDATE IT.
+
+This is a guide for using artifacts tools: \`createDocument\` and \`updateDocument\`, which render content on a artifacts beside the conversation.
+
+**When to use \`createDocument\`:**
+- For substantial content (>10 lines) or code
+- For content users will likely save/reuse (emails, code, essays, etc.)
+- When explicitly requested to create a document
+- For when content contains a single code snippet
+
+**When NOT to use \`createDocument\`:**
+- For informational/explanatory content
+- For conversational responses
+- When asked to keep it in chat
+
+**Using \`updateDocument\`:**
+- Default to full document rewrites for major changes
+- Use targeted updates only for specific, isolated changes
+- Follow user instructions for which parts to modify
+
+**When NOT to use \`updateDocument\`:**
+- Immediately after creating a document
+
+Do not update document right after creating it. Wait for user feedback or request to update it.
+`;
+
 export const regularPrompt =
   "You are a friendly study buddy assistant! Keep your responses concise and helpful.";
 
+export const agentRoutingPrompt = `
+You are a Study Buddy with specialized agents available as tools. Choose the right agent based on what the user needs:
+
+**tutor** - Explain concepts with examples and analogies
+Use for: "explain", "teach me", "how does X work", "what is X", understanding concepts
+
+**quizMaster** - Create quizzes and practice questions (creates interactive flashcard artifact)
+Use for: "quiz me", "test my knowledge", "practice questions", "assessment"
+
+**planner** - Create study plans and learning roadmaps (creates interactive study-plan artifact)
+Use for: "study plan", "learning roadmap", "how should I learn", "schedule"
+
+**analyst** - Analyze content and extract key insights
+Use for: "summarize", "key points", "analyze this", "what's important"
+
+IMPORTANT ROUTING RULES:
+1. Match user intent to the most appropriate agent
+2. If the request doesn't clearly match an agent, respond conversationally
+3. After using an agent, suggest related follow-ups (e.g., after explaining, offer to quiz)
+4. You can chain agents - explain first, then offer to create a study plan
+
+CRITICAL: Agents (quizMaster, planner) create their own artifacts automatically. After using these agents:
+- Do NOT call createDocument - the artifact is already created
+- Do NOT try to display or reformat the agent's output
+- Simply acknowledge the artifact was created and offer follow-up suggestions
+
+Example flows:
+- "Explain machine learning" → use tutor
+- "Quiz me on what we just discussed" → use quizMaster (creates flashcard artifact automatically)
+- "Create a study plan for learning Python" → use planner (creates study-plan artifact automatically)
+- "Summarize this article" → use analyst
+`;
+
 export type RequestHints = {
   latitude: Geo["latitude"];
   longitude: Geo["longitude"];
@@ -28,7 +92,11 @@ export const systemPrompt = ({
 }) => {
   const requestPrompt = getRequestPromptFromHints(requestHints);
 
-  return `${regularPrompt}\n\n${requestPrompt}`;
+  if (selectedChatModel === "chat-model-reasoning") {
+    return `${regularPrompt}\n\n${requestPrompt}`;
+  }
+
+  return `${regularPrompt}\n\n${agentRoutingPrompt}\n\n${requestPrompt}\n\n${artifactsPrompt}`;
 };
 
 export const codePrompt = `

lib/artifacts/server.ts

@@ -1,7 +1,9 @@
 import type { UIMessageStreamWriter } from "ai";
 import type { Session } from "next-auth";
 import { codeDocumentHandler } from "@/artifacts/code/server";
+import { flashcardDocumentHandler } from "@/artifacts/flashcard/server";
 import { sheetDocumentHandler } from "@/artifacts/sheet/server";
+import { studyPlanDocumentHandler } from "@/artifacts/study-plan/server";
 import { textDocumentHandler } from "@/artifacts/text/server";
 import type { ArtifactKind } from "@/components/artifact";
 import { saveDocument } from "../db/queries";
@@ -93,6 +95,8 @@ export const documentHandlersByArtifactKind: DocumentHandler[] = [
   textDocumentHandler,
   codeDocumentHandler,
   sheetDocumentHandler,
+  flashcardDocumentHandler,
+  studyPlanDocumentHandler,
 ];
 
 export const artifactKinds = [

lib/types.ts

@@ -7,7 +7,10 @@ import type {
   createQuizMasterAgent,
   createTutorAgent,
 } from "./ai/agents";
+import type { createDocument } from "./ai/tools/create-document";
 import type { getWeather } from "./ai/tools/get-weather";
+import type { requestSuggestions } from "./ai/tools/request-suggestions";
+import type { updateDocument } from "./ai/tools/update-document";
 import type { Suggestion } from "./db/types";
 import type { AppUsage } from "./usage";
 
@@ -19,42 +22,30 @@ export const messageMetadataSchema = z.object({
 
 export type MessageMetadata = z.infer<typeof messageMetadataSchema>;
 
-// Tool types - inferred from actual tool definitions
+// Tool types
 type weatherTool = InferUITool<typeof getWeather>;
+type createDocumentTool = InferUITool<ReturnType<typeof createDocument>>;
+type updateDocumentTool = InferUITool<ReturnType<typeof updateDocument>>;
+type requestSuggestionsTool = InferUITool<
+  ReturnType<typeof requestSuggestions>
+>;
 
 // Agent tool types
 type tutorTool = InferUITool<ReturnType<typeof createTutorAgent>>;
 type quizMasterTool = InferUITool<ReturnType<typeof createQuizMasterAgent>>;
 type plannerTool = InferUITool<ReturnType<typeof createPlannerAgent>>;
 type analystTool = InferUITool<ReturnType<typeof createAnalystAgent>>;
 
-// Placeholder types for tools not yet implemented
-// UITools expects { input, output } shape for each tool
-type DocumentResult = {
-  id: string;
-  title: string;
-  kind: ArtifactKind;
-};
-
 export type ChatTools = {
   getWeather: weatherTool;
+  createDocument: createDocumentTool;
+  updateDocument: updateDocumentTool;
+  requestSuggestions: requestSuggestionsTool;
   // Study buddy agents
   tutor: tutorTool;
   quizMaster: quizMasterTool;
   planner: plannerTool;
   analyst: analystTool;
-  createDocument: {
-    input: { title: string; kind: ArtifactKind };
-    output: DocumentResult | { error: string };
-  };
-  updateDocument: {
-    input: { id: string; description: string };
-    output: DocumentResult | { error: string };
-  };
-  requestSuggestions: {
-    input: { documentId: string };
-    output: DocumentResult | { error: string };
-  };
 };
 
 export type CustomUIDataTypes = {
@@ -71,7 +62,7 @@ export type CustomUIDataTypes = {
   kind: ArtifactKind;
   clear: null;
   finish: null;
-  error: string;
+  error: string; // For error signaling from agents
   usage: AppUsage;
 };
 

tsconfig.json

@@ -31,5 +31,5 @@
     "next.config.js",
     ".next/dev/types/**/*.ts"
   ],
-  "exclude": ["node_modules", "tempfiles"]
+  "exclude": ["node_modules"]
 }