AI SDK v6 Crash Course

When you need to return structured data (like an array of strings) instead of plain text, replace streamText with streamObject. This allows you to use a Zod schema to enforce the shape of the response. Instead of iterating over textStream, you should iterate over partialObjectStream to receive the object as it is being built by the LLM.

import { streamObject } from 'ai';
import { z } from 'zod';

const followupSuggestionsResult = streamObject({
  model: google('gemini-2.5-flash'),
  schema: z.object({
    suggestions: z.array(z.string()),
  }),
  messages: [
    // ... messages
  ],
});

// Iterate over the partial object stream
for await (const partialObject of followupSuggestionsResult.partialObjectStream) {
  // partialObject contains the structured data as it streams in
  writer.write({
    id: dataPartId,
    type: 'data-suggestions',
    data: partialObject.suggestions,
  });
}

When iterating over a UIMessageStream, you will encounter several event types that describe the lifecycle of tool calls and text generation:

Tool Call Events

• tool-input-start: Indicates a tool is being called. Contains toolCallId and toolName.
• tool-input-delta: Provides incremental updates to the tool's input (e.g., inputTextDelta).
• tool-input-available: Emitted when the complete tool input is ready. Contains the full input object.
• tool-output-available: Emitted when the tool execution completes. Contains the output object.

Text Generation Events

• text-start: Marks the beginning of a text response.
• text-delta: Provides incremental text chunks (delta).
• text-end: Marks the end of the text response.

Lifecycle Events

• start: The beginning of the stream.
• start-step: Indicates the beginning of a new step (often associated with a tool call).

By default, the AI SDK does not always wait for a stream to complete. If you do not consume the stream, the onFinish callback provided to functions like streamText may never be triggered. This is particularly critical when using onFinish for persistence logic (e.g., saving a chat message to a database).

To ensure a stream completes and triggers its lifecycle callbacks, you must use one of the following methods:

1. Manual Iteration: Use a for await...of loop to iterate over the stream chunks (e.g., streamTextResult.textStream).
2. The consumeStream() method: Call .consumeStream() on the result object returned by streamText.
3. The top-level consumeStream() function: Use the standalone consumeStream function from the ai package, passing in a stream (e.g., via .toUIMessageStream()).

import { google } from '@ai-sdk/google';
import { streamText } from 'ai';

const streamTextResult = streamText({
  model: google('gemini-2.5-flash'),
  prompt: 'Hello, world!',
  onFinish: () => {
    console.log('Stream finished!');
  },
});

// Option 1: Manual iteration
for await (const chunk of streamTextResult.textStream) {
  process.stdout.write(chunk);
}

// Option 2: Using the method on the result
await streamTextResult.consumeStream();

A model router is a pattern where an initial, fast LLM call is used to classify the complexity of a user's query. Based on this classification, the system routes the request to either a 'basic' (cheaper/faster) or 'advanced' (more capable) model. This optimizes for both cost and performance.

Implementation Steps

1. Routing Call: Use generateText to call a lightweight model. The prompt should instruct the model to return a specific token (e.g., 0 for basic, 1 for advanced) based on query complexity.
2. Selection Logic: Parse the result from modelRouterResult.text.trim() to determine the model type. Always implement a fallback to the 'basic' model if the output is ambiguous.
3. Execution: Use the selected model for the main task.
4. Metadata Injection: Pass the selected model name into the messageMetadata of the stream so the UI can display which model handled the request.

// 1. The Routing Call
const modelRouterResult = await generateText({
  model: basicModel,
  system: "Return 0 for simple queries, 1 for complex queries.",
  prompt: userPrompt,
});

// 2. The Selection Logic
const modelSelected: 'advanced' | 'basic' = 
  modelRouterResult.text.trim() === '1' ? 'advanced' : 'basic';

// 3. The Main Execution & Metadata Injection
const streamTextResult = await streamText({
  model: modelSelected === 'advanced' ? advancedModel : basicModel,
  messages,
});

writer.merge(
  streamTextResult.toUIMessageStream({
    messageMetadata: {
      model: modelSelected,
    },
  }),
);

Chain of Thought (CoT) prompting is a technique used to improve LLM performance on complex tasks by instructing the model to "think step by step" or plan its work before providing a final answer. This involves two phases in the model's output:

1. Thinking Phase: The model outputs tokens where it displays its reasoning, planning, or decomposition of the problem.
2. Answer Phase: The model provides the actual solution based on its reasoning.

To implement this effectively, you should:

• Instruct the model to plan the optimal path for user understanding.
• Explicitly tell the model to break down individual components or syntax elements.
• Use structured formats like XML tags to separate the reasoning from the final output.

const result = streamText({
  model: google('gemini-2.5-flash-lite'),
  prompt: `
    <task-context>
    You are a helpful TypeScript expert...
    </task-context>

    <the-ask>
    Explain the code, using the article as a reference.
    </the-ask>
  `,
});

A Generator-Evaluator workflow is a deterministic alternative to autonomous agents. Instead of giving an LLM full control over tool calling, you define a specific sequence of steps to improve output quality.

In this pattern, you:

1. Generate: Use an LLM to create an initial draft (e.g., a Slack message).
2. Evaluate: Use a second LLM call to critique the draft based on specific criteria (e.g., professionalism, clarity).
3. Refine: Use a final LLM call that takes the original context, the first draft, and the evaluation feedback to produce a high-quality final version.

This approach is more reliable than agents for tasks where a specific sequence of steps must always occur.

export const POST = async (req: Request): Promise<Response> => {
  const body: { messages: UIMessage[] } = await req.json();
  const { messages } = body;

  // 1. Generate initial draft
  const writeSlackResult = TODO; 

  // 2. Evaluate the draft
  const evaluateSlackResult = TODO; 

  // 3. Produce final draft and stream
  const finalSlackAttempt = TODO; 

  return finalSlackAttempt.toUIMessageStreamResponse();
};

When implementing message persistence, you must distinguish between the different onFinish callbacks provided by streamText and toUIMessageStreamResponse. Using the wrong callback or property will result in losing UI-specific data or failing to capture the full conversation history.

Callback Comparison

Implementation Example

To capture the full conversation history for persistence, use the onFinish callback within toUIMessageStreamResponse and ensure you pass the originalMessages to it.

export const POST = async (req: Request): Promise<Response> => {
  const body: { messages: UIMessage[] } = await req.json();
  const { messages } = body;

  const result = streamText({
    model: google('gemini-2.5-flash'),
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse({
    originalMessages: messages,
    onFinish: ({ messages, responseMessage }) => {
      // 'messages' contains the full history, ideal for database persistence
      // 'responseMessage' contains only the latest message
      console.log('Full history:', messages);
      console.log('Latest message:', responseMessage);
    },
  });
};

A robust prompt template should include the following components in this specific order to leverage LLM attention biases:

1. Task Context: High-level role-based prompting (e.g., "You are an AI career coach").
2. Tone Context: Defines the persona's voice (e.g., "friendly customer service tone").
3. Background Data: Reference information or documents (e.g., a knowledge base) wrapped in XML tags to prevent confusion.
4. Rules: Detailed instructions and edge-case handling (e.g., "If unsure, say X"). This is often where most engineering time is spent.
5. Examples: Few-shot prompting examples to demonstrate desired response patterns.
6. Conversation History: Previous interactions to maintain coherence.
7. The Ask: The actual user query and the primary instruction. This is the most critical part.
8. Thinking Instructions: Prompts the LLM to use Chain of Thought (e.g., "Think about your answer first").
9. Output Formatting: Explicit instructions on the return format (e.g., "Put your response in <response> tags").