workshop: add Chapter 3 preview stubs (multi-agent)

- Add lib/ai/agents/quiz-master.ts with TODO placeholder
- Add lib/ai/agents/planner.ts with TODO placeholder
- Add lib/ai/agents/analyst.ts with TODO placeholder
- Update index.ts with commented exports for Chapter 3

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: NiallJoeMaher

lib/ai/agents/analyst.ts

@@ -0,0 +1,62 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+import type { AgentResult, CreateAgentProps } from "./types";
+
+// TODO CHAPTER 3: Implement the Analyst Agent
+//
+// The Analyst analyzes content and extracts key insights.
+// It should:
+// 1. Accept content and analysis type (summary, key-points, deep-analysis, study-notes)
+// 2. Use generateText to analyze the content
+// 3. Return structured analysis or summary
+//
+// Triggers: "analyze", "summarize", "key points", "what's important"
+//
+// See CHAPTER-3.md for the complete implementation.
+
+/**
+ * Analyst Agent - Analyzes content and extracts insights
+ *
+ * @param _props - Agent props (session, dataStream)
+ * @returns AI SDK tool that analyzes and summarizes content
+ */
+export const createAnalystAgent = (_props: CreateAgentProps) =>
+  tool({
+    description:
+      "Analyze content, extract key insights, and create summaries. " +
+      "Use when the user wants to understand, summarize, or extract key points. " +
+      "Triggers: analyze, summarize, key points, main ideas, extract insights.",
+    inputSchema: z.object({
+      content: z.string().describe("The text or content to analyze"),
+      analysisType: z
+        .enum(["summary", "key-points", "deep-analysis", "study-notes"])
+        .default("summary")
+        .describe("Type of analysis to perform"),
+      focusOn: z
+        .string()
+        .optional()
+        .describe("Specific aspect to focus the analysis on"),
+      outputLength: z
+        .enum(["brief", "moderate", "detailed"])
+        .default("moderate")
+        .describe("Desired length of the analysis output"),
+    }),
+    execute: async ({ analysisType }): Promise<AgentResult> => {
+      // TODO: Implement in Chapter 3
+      // 1. Build prompt based on analysis type
+      // 2. Use generateText to analyze content
+      // 3. Return structured analysis result
+
+      console.log(`[Analyst] TODO: Perform ${analysisType} analysis`);
+
+      // Placeholder await to satisfy linter (remove when implementing)
+      await Promise.resolve();
+
+      return {
+        agentName: "analyst",
+        success: false,
+        summary: `TODO: Implement analyst in Chapter 3 to perform ${analysisType} analysis`,
+      };
+    },
+  });

lib/ai/agents/index.ts

@@ -2,4 +2,10 @@
 
 // Specialized agents
 export { createTutorAgent } from "./tutor";
+
+// TODO CHAPTER 3: Uncomment these exports when implementing multi-agent system
+// export { createQuizMasterAgent } from "./quiz-master";
+// export { createPlannerAgent } from "./planner";
+// export { createAnalystAgent } from "./analyst";
+
 export type { AgentContext, AgentResult, CreateAgentProps } from "./types";

lib/ai/agents/planner.ts

@@ -0,0 +1,68 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+import type { AgentResult, CreateAgentProps } from "./types";
+
+// TODO CHAPTER 3: Implement the Planner Agent
+//
+// The Planner creates personalized study plans and learning roadmaps.
+// It should:
+// 1. Accept a topic, timeframe, hours/day, and current level
+// 2. Use generateObject to create structured study plan data
+// 3. Return weekly breakdown with goals, tasks, and resources
+//
+// In Chapter 4, this will create a study-plan artifact with checkboxes.
+//
+// Triggers: "study plan", "learning roadmap", "how should I learn"
+//
+// See CHAPTER-3.md for the complete implementation.
+
+/**
+ * Planner Agent - Creates study plans and learning roadmaps
+ *
+ * @param _props - Agent props (session, dataStream)
+ * @returns AI SDK tool that generates study plans
+ */
+export const createPlannerAgent = (_props: CreateAgentProps) =>
+  tool({
+    description:
+      "Create a personalized study plan or learning roadmap for a topic. " +
+      "Use when the user wants to plan their learning, create a study schedule, or get a structured approach. " +
+      "Triggers: study plan, learning roadmap, how to learn, schedule, curriculum.",
+    inputSchema: z.object({
+      topic: z
+        .string()
+        .describe("The topic or skill to create a study plan for"),
+      timeframe: z
+        .string()
+        .default("2 weeks")
+        .describe("How long the user has to learn (e.g., '1 week', '30 days')"),
+      hoursPerDay: z
+        .number()
+        .min(0.5)
+        .max(8)
+        .default(1)
+        .describe("Hours available for study per day"),
+      currentLevel: z
+        .enum(["complete beginner", "some basics", "intermediate", "advanced"])
+        .default("complete beginner")
+        .describe("User's current knowledge level"),
+    }),
+    execute: async ({ topic }): Promise<AgentResult> => {
+      // TODO: Implement in Chapter 3
+      // 1. Use generateObject with a study plan schema
+      // 2. Create weekly breakdown with goals and tasks
+      // 3. Format as markdown or create artifact in Chapter 4
+
+      console.log(`[Planner] TODO: Create study plan for "${topic}"`);
+
+      // Placeholder await to satisfy linter (remove when implementing)
+      await Promise.resolve();
+
+      return {
+        agentName: "planner",
+        success: false,
+        summary: `TODO: Implement planner in Chapter 3 to create study plan for "${topic}"`,
+      };
+    },
+  });

lib/ai/agents/quiz-master.ts

@@ -0,0 +1,62 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+import type { AgentResult, CreateAgentProps } from "./types";
+
+// TODO CHAPTER 3: Implement the Quiz Master Agent
+//
+// The Quiz Master creates interactive quizzes to test knowledge.
+// It should:
+// 1. Accept a topic, number of questions, and difficulty level
+// 2. Use generateObject to create structured quiz data
+// 3. Return quiz questions with multiple choice options
+//
+// In Chapter 4, this will create a flashcard artifact instead of text.
+//
+// Triggers: "quiz me", "test my knowledge", "practice questions"
+//
+// See CHAPTER-3.md for the complete implementation.
+
+/**
+ * Quiz Master Agent - Creates quizzes to test knowledge
+ *
+ * @param _props - Agent props (session, dataStream)
+ * @returns AI SDK tool that generates quiz questions
+ */
+export const createQuizMasterAgent = (_props: CreateAgentProps) =>
+  tool({
+    description:
+      "Create a quiz to test knowledge on a topic. " +
+      "Use when the user wants to be quizzed, test their knowledge, or practice. " +
+      "Triggers: quiz me, test me, practice questions, assessment, flashcards.",
+    inputSchema: z.object({
+      topic: z.string().describe("The topic to create quiz questions about"),
+      numberOfQuestions: z
+        .number()
+        .min(1)
+        .max(10)
+        .default(5)
+        .describe("Number of questions to generate"),
+      difficulty: z
+        .enum(["easy", "medium", "hard", "mixed"])
+        .default("medium")
+        .describe("Difficulty level of the questions"),
+    }),
+    execute: async ({ topic }): Promise<AgentResult> => {
+      // TODO: Implement in Chapter 3
+      // 1. Use generateObject with a quiz schema
+      // 2. Generate questions with options and explanations
+      // 3. Format as markdown or create artifact in Chapter 4
+
+      console.log(`[QuizMaster] TODO: Create quiz about "${topic}"`);
+
+      // Placeholder await to satisfy linter (remove when implementing)
+      await Promise.resolve();
+
+      return {
+        agentName: "quiz-master",
+        success: false,
+        summary: `TODO: Implement quiz master in Chapter 3 to create quiz about "${topic}"`,
+      };
+    },
+  });