workshop: update Chapter 1 docs and add Chapter 2 stubs

- Update CHAPTER-1.md to show full geocoding implementation
- Fix weather tool code block to match actual implementation
- Update route.ts example with stepCountIs and experimental_activeTools
- Add lib/ai/agents/ directory with Chapter 2 preview stubs:
  - types.ts: Agent type definitions
  - tutor.ts: Tutor agent stub
  - index.ts: Barrel export with TODOs

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

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

Author: NiallJoeMaher

CHAPTER-1.md

@@ -48,69 +48,142 @@ const myTool = tool({
 
 ## The Weather Tool
 
-Here's the complete weather tool implementation:
+Here's the complete weather tool implementation with city name geocoding:
 
 ### File: `lib/ai/tools/get-weather.ts`
 
 ```typescript
 import { tool } from "ai";
 import { z } from "zod";
 
+// Helper function to convert city names to coordinates
+async function geocodeCity(
+  city: string
+): Promise<{ latitude: number; longitude: number } | null> {
+  try {
+    const response = await fetch(
+      `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1&language=en&format=json`
+    );
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+
+    if (!data.results || data.results.length === 0) {
+      return null;
+    }
+
+    const result = data.results[0];
+    return {
+      latitude: result.latitude,
+      longitude: result.longitude,
+    };
+  } catch {
+    return null;
+  }
+}
+
 export const getWeather = tool({
   description:
-    "Get the current weather at a location. Use this when users ask about weather.",
+    "Get the current weather at a location. You can provide either coordinates or a city name.",
   inputSchema: z.object({
-    latitude: z.number().describe("Latitude coordinate"),
-    longitude: z.number().describe("Longitude coordinate"),
+    latitude: z.number().optional(),
+    longitude: z.number().optional(),
+    city: z
+      .string()
+      .describe("City name (e.g., 'San Francisco', 'New York', 'London')")
+      .optional(),
   }),
-  execute: async ({ latitude, longitude }) => {
-    // In production, you'd call a real weather API
-    // For demo, we return mock data based on coordinates
+  execute: async (input) => {
+    let latitude: number;
+    let longitude: number;
+
+    // If city name provided, geocode it to coordinates
+    if (input.city) {
+      const coords = await geocodeCity(input.city);
+      if (!coords) {
+        return {
+          error: `Could not find coordinates for "${input.city}". Please check the city name.`,
+        };
+      }
+      latitude = coords.latitude;
+      longitude = coords.longitude;
+    } else if (input.latitude !== undefined && input.longitude !== undefined) {
+      latitude = input.latitude;
+      longitude = input.longitude;
+    } else {
+      return {
+        error:
+          "Please provide either a city name or both latitude and longitude coordinates.",
+      };
+    }
+
+    // Fetch weather data from Open-Meteo API
     const response = await fetch(
       `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&hourly=temperature_2m&daily=sunrise,sunset&timezone=auto`
     );
 
-    const data = await response.json();
+    const weatherData = await response.json();
 
-    return {
-      temperature: data.current.temperature_2m,
-      unit: data.current_units.temperature_2m,
-    };
+    // Include city name in response if provided
+    if ("city" in input) {
+      weatherData.cityName = input.city;
+    }
+
+    return weatherData;
   },
 });
 ```
 
+### Key Features
+
+1. **Geocoding**: The `geocodeCity` helper converts city names to coordinates using the free Open-Meteo Geocoding API
+2. **Flexible Input**: Accepts either a city name OR latitude/longitude coordinates
+3. **Error Handling**: Returns helpful error messages if geocoding fails
+4. **Real Data**: Uses the Open-Meteo Weather API for actual weather data
+
 ## Wiring Tools into the Chat Route
 
 Add the tool to your chat route:
 
 ### File: `app/(chat)/api/chat/route.ts`
 
 ```typescript
-import { streamText } from "ai";
+import { stepCountIs, streamText } from "ai";
 import { myProvider } from "@/lib/ai/providers";
 import { systemPrompt } from "@/lib/ai/prompts";
 import { getWeather } from "@/lib/ai/tools/get-weather";
 
 export async function POST(request: Request) {
-  const { messages } = await request.json();
+  const { messages, selectedChatModel } = await request.json();
 
   const result = streamText({
-    model: myProvider.languageModel("chat-model"),
-    system: systemPrompt(),
+    model: myProvider.languageModel(selectedChatModel),
+    system: systemPrompt({ selectedChatModel }),
     messages,
+    // Stop after 5 tool call steps
+    stopWhen: stepCountIs(5),
+    // Disable tools for reasoning models
+    experimental_activeTools:
+      selectedChatModel === "chat-model-reasoning" ? [] : ["getWeather"],
     // Add tools here!
     tools: {
       getWeather,
     },
-    // Let the AI call multiple tools if needed
-    maxSteps: 5,
   });
 
   return result.toDataStreamResponse();
 }
 ```
 
+### Key Configuration
+
+- **`stopWhen: stepCountIs(5)`**: Limits tool call chains to 5 steps
+- **`experimental_activeTools`**: Conditionally enables/disables tools (disabled for reasoning model)
+- **`tools`**: Object containing all available tools
+
 ## How Tool Calling Works
 
 ```
@@ -120,9 +193,12 @@ export async function POST(request: Request) {
 │ AI thinks: "I should use the getWeather tool"           │
 │                           ↓                             │
 │ AI generates tool call:                                 │
-│   { name: "getWeather", args: { lat: 48.8, lon: 2.3 }}  │
+│   { name: "getWeather", args: { city: "Paris" }}        │
 │                           ↓                             │
-│ Tool executes and returns: { temperature: 18, unit: "°C"}│
+│ Tool executes:                                          │
+│   1. geocodeCity("Paris") → { lat: 48.8, lon: 2.3 }     │
+│   2. fetch weather data from Open-Meteo API             │
+│   3. returns: { temperature: 18, cityName: "Paris" }    │
 │                           ↓                             │
 │ AI receives result and generates response:              │
 │   "The current temperature in Paris is 18°C"            │
@@ -139,19 +215,26 @@ Tool calls and results appear as special message parts. Here's how to render the
 "use client";
 
 type WeatherProps = {
-  temperature: number;
-  unit: string;
+  current: {
+    temperature_2m: number;
+  };
+  current_units: {
+    temperature_2m: string;
+  };
+  cityName?: string;
 };
 
-export function Weather({ temperature, unit }: WeatherProps) {
+export function Weather({ current, current_units, cityName }: WeatherProps) {
   return (
     <div className="flex items-center gap-2 rounded-lg border p-4">
       <span className="text-2xl">🌡️</span>
       <div>
-        <p className="font-semibold">Current Temperature</p>
+        <p className="font-semibold">
+          {cityName ? `Weather in ${cityName}` : "Current Weather"}
+        </p>
         <p className="text-3xl">
-          {temperature}
-          {unit}
+          {current.temperature_2m}
+          {current_units.temperature_2m}
         </p>
       </div>
     </div>
@@ -214,7 +297,8 @@ Should I bring an umbrella to Seattle?
 
 **Troubleshooting:**
 - If you see "I don't have access to real-time weather", check that the tool is properly added to the `tools` object in your chat route
-- If coordinates seem wrong, the AI is inferring lat/long from city names - this is expected behavior
+- If the city isn't found, try using a more common spelling or a larger nearby city
+- Check the browser console for any API errors
 
 ---
 

lib/ai/agents/index.ts

@@ -0,0 +1,14 @@
+// TODO CHAPTER 2: Export agents as they are implemented
+//
+// Uncomment these exports as you implement each agent:
+
+// Chapter 2: Tutor Agent
+// export { createTutorAgent } from "./tutor";
+
+// Chapter 3: Multi-Agent System
+// export { createQuizMasterAgent } from "./quiz-master";
+// export { createPlannerAgent } from "./planner";
+// export { createAnalystAgent } from "./analyst";
+
+// Re-export types for convenience
+export type { AgentResult, CreateAgentProps } from "./types";

lib/ai/agents/tutor.ts

@@ -0,0 +1,59 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+import type { AgentResult, CreateAgentProps } from "./types";
+
+// TODO CHAPTER 2: Implement the Tutor Agent
+//
+// The Tutor Agent explains concepts with different teaching approaches.
+// It should:
+// 1. Accept a topic and teaching approach (eli5, technical, analogy, step-by-step)
+// 2. Use generateText to call the AI and create an explanation
+// 3. Return a structured AgentResult with the explanation
+//
+// Triggers: "explain", "teach me", "how does X work", "what is"
+//
+// See CHAPTER-2.md for the complete implementation.
+
+/**
+ * Tutor Agent - Explains concepts with different teaching approaches
+ *
+ * @param _props - Agent props (session, dataStream)
+ * @returns AI SDK tool that can be used in streamText
+ */
+export const createTutorAgent = (_props: CreateAgentProps) =>
+  tool({
+    description:
+      "Explain a concept or topic in depth. Use when the user wants to learn or understand something. " +
+      "Triggers: explain, teach me, how does X work, what is, help me understand.",
+    inputSchema: z.object({
+      topic: z.string().describe("The topic or concept to explain"),
+      approach: z
+        .enum(["eli5", "technical", "analogy", "step-by-step"])
+        .default("step-by-step")
+        .describe(
+          "Teaching approach: eli5 (simple), technical (detailed), analogy (comparisons), step-by-step"
+        ),
+      priorKnowledge: z
+        .string()
+        .optional()
+        .describe("What the user already knows about the topic"),
+    }),
+    execute: async ({ topic }): Promise<AgentResult> => {
+      // TODO: Implement in Chapter 2
+      // 1. Build a prompt with the topic and approach
+      // 2. Call generateText with the prompt
+      // 3. Return the result as an AgentResult
+
+      console.log(`[Tutor] TODO: Explain "${topic}"`);
+
+      // Placeholder await to satisfy linter (remove when implementing)
+      await Promise.resolve();
+
+      return {
+        agentName: "tutor",
+        success: false,
+        summary: `TODO: Implement tutor agent in Chapter 2 to explain "${topic}"`,
+      };
+    },
+  });

lib/ai/agents/types.ts

@@ -0,0 +1,28 @@
+import type { DataStreamWriter } from "ai";
+import type { Session } from "next-auth";
+
+// TODO CHAPTER 2: Agent type definitions
+//
+// These types define the contract for all agents:
+// - CreateAgentProps: What gets passed to agent creators
+// - AgentResult: What agents return after execution
+//
+// See CHAPTER-2.md for complete implementation details.
+
+/**
+ * Props passed to every agent creator function
+ */
+export type CreateAgentProps = {
+  session: Session | null;
+  dataStream: DataStreamWriter;
+};
+
+/**
+ * Standard result format returned by all agents
+ */
+export type AgentResult = {
+  agentName: string;
+  success: boolean;
+  summary: string;
+  data?: Record<string, unknown>;
+};