Chapter 2: Add tutor agent (first agent)

- Add lib/ai/agents/ directory with types and index
- Add tutor agent that explains concepts with examples
- Update route.ts to import and register tutor agent
- Update types.ts with tutor tool type inference

Author: NiallJoeMaher

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

@@ -7,6 +7,7 @@ import {
   stepCountIs,
   streamText,
 } from "ai";
+import { 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";
@@ -181,10 +182,11 @@ export async function POST(request: Request) {
           experimental_activeTools:
             selectedChatModel === "chat-model-reasoning"
               ? []
-              : ["getWeather"],
+              : ["getWeather", "tutor"],
           experimental_transform: smoothStream({ chunking: "word" }),
           tools: {
             getWeather,
+            tutor: createTutorAgent({ session, dataStream }),
           },
           experimental_telemetry: {
             isEnabled: isProductionEnvironment,

lib/ai/agents/index.ts

@@ -0,0 +1,5 @@
+// Agent type definitions
+
+// Specialized agents
+export { createTutorAgent } from "./tutor";
+export type { AgentContext, AgentResult, CreateAgentProps } from "./types";

lib/ai/agents/tutor.ts

@@ -0,0 +1,68 @@
+import { generateText, tool } from "ai";
+import { z } from "zod";
+import { myProvider } from "../providers";
+import type { AgentResult, CreateAgentProps } from "./types";
+
+const TUTOR_SYSTEM_PROMPT = `You are a patient, encouraging tutor who excels at explaining complex topics.
+
+Your teaching approach:
+- Start with what the student likely already knows
+- Use relatable analogies and real-world examples
+- Break complex ideas into digestible steps
+- Include brief knowledge checks when appropriate
+- Encourage curiosity and questions
+- Adapt explanation depth based on the topic complexity
+
+Structure your explanations with:
+1. A simple overview (1-2 sentences)
+2. The main explanation with examples
+3. Key takeaways or summary points
+
+Keep responses focused and educational. Avoid unnecessary fluff.`;
+
+/**
+ * Tutor Agent - Explains concepts with examples and analogies
+ *
+ * Triggers: "explain", "teach me", "how does X work", "what is"
+ * Output: Returns explanation text that the orchestrator will present
+ *
+ * Note: We use generateText instead of streaming because tool results
+ * are displayed in the chat UI, not the artifact panel. The orchestrator
+ * (main chat model) can then present the explanation conversationally.
+ */
+export const createTutorAgent = (_props: CreateAgentProps) =>
+  tool({
+    description:
+      "Explain a concept, topic, or idea in detail with examples and analogies. Use when the user asks to understand, learn about, or needs explanation of something. Triggers: explain, teach me, how does X work, what is X.",
+    inputSchema: z.object({
+      topic: z.string().describe("The topic or concept to explain"),
+      depth: z
+        .enum(["beginner", "intermediate", "advanced"])
+        .default("intermediate")
+        .describe("The depth of explanation needed based on user context"),
+      context: z
+        .string()
+        .optional()
+        .describe(
+          "Additional context about what the user already knows or specific aspects to focus on"
+        ),
+    }),
+    execute: async ({ topic, depth, context }): Promise<AgentResult> => {
+      const prompt = `Explain "${topic}" at a ${depth} level.${
+        context ? `\n\nAdditional context: ${context}` : ""
+      }`;
+
+      const { text } = await generateText({
+        model: myProvider.languageModel("chat-model"),
+        system: TUTOR_SYSTEM_PROMPT,
+        prompt,
+      });
+
+      return {
+        agentName: "tutor",
+        success: true,
+        summary: text,
+        data: { topic, depth, contentLength: text.length },
+      };
+    },
+  });

lib/ai/agents/types.ts

@@ -0,0 +1,33 @@
+import type { UIMessageStreamWriter } from "ai";
+import type { Session } from "next-auth";
+import type { ChatMessage } from "@/lib/types";
+
+/**
+ * Context passed to all specialized agents
+ * Contains session info, data stream for real-time updates, and chat ID
+ */
+export type AgentContext = {
+  session: Session;
+  dataStream: UIMessageStreamWriter<ChatMessage>;
+  chatId: string;
+};
+
+/**
+ * Standard result returned by all agents
+ * Provides consistent interface for orchestrator to handle agent responses
+ */
+export type AgentResult = {
+  agentName: string;
+  success: boolean;
+  summary: string;
+  data?: Record<string, unknown>;
+};
+
+/**
+ * Props for creating an agent tool
+ * Same pattern as existing tools (createDocument, requestSuggestions)
+ */
+export type CreateAgentProps = {
+  session: Session;
+  dataStream: UIMessageStreamWriter<ChatMessage>;
+};

lib/types.ts

@@ -1,6 +1,7 @@
 import type { InferUITool, UIMessage } from "ai";
 import { z } from "zod";
 import type { ArtifactKind } from "@/components/artifact";
+import type { createTutorAgent } from "./ai/agents";
 import type { getWeather } from "./ai/tools/get-weather";
 import type { Suggestion } from "./db/types";
 import type { AppUsage } from "./usage";
@@ -15,6 +16,7 @@ export type MessageMetadata = z.infer<typeof messageMetadataSchema>;
 
 // Tool types - inferred from actual tool definitions
 type weatherTool = InferUITool<typeof getWeather>;
+type tutorTool = InferUITool<ReturnType<typeof createTutorAgent>>;
 
 // Placeholder types for tools not yet implemented
 // UITools expects { input, output } shape for each tool
@@ -26,6 +28,7 @@ type DocumentResult = {
 
 export type ChatTools = {
   getWeather: weatherTool;
+  tutor: tutorTool;
   createDocument: {
     input: { title: string; kind: ArtifactKind };
     output: DocumentResult | { error: string };