ai 6.0.30 → 6.0.32

package/docs/03-agents/01-overview.mdx

@@ -0,0 +1,96 @@
+---
+title: Overview
+description: Learn how to build agents with the AI SDK.
+---
+
+# Agents
+
+Agents are **large language models (LLMs)** that use **tools** in a **loop** to accomplish tasks.
+
+These components work together:
+
+- **LLMs** process input and decide the next action
+- **Tools** extend capabilities beyond text generation (reading files, calling APIs, writing to databases)
+- **Loop** orchestrates execution through:
+  - **Context management** - Maintaining conversation history and deciding what the model sees (input) at each step
+  - **Stopping conditions** - Determining when the loop (task) is complete
+
+## ToolLoopAgent Class
+
+The ToolLoopAgent class handles these three components. Here's an agent that uses multiple tools in a loop to accomplish a task:
+
+```ts
+import { ToolLoopAgent, stepCountIs, tool } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const weatherAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    weather: tool({
+      description: 'Get the weather in a location (in Fahrenheit)',
+      inputSchema: z.object({
+        location: z.string().describe('The location to get the weather for'),
+      }),
+      execute: async ({ location }) => ({
+        location,
+        temperature: 72 + Math.floor(Math.random() * 21) - 10,
+      }),
+    }),
+    convertFahrenheitToCelsius: tool({
+      description: 'Convert temperature from Fahrenheit to Celsius',
+      inputSchema: z.object({
+        temperature: z.number().describe('Temperature in Fahrenheit'),
+      }),
+      execute: async ({ temperature }) => {
+        const celsius = Math.round((temperature - 32) * (5 / 9));
+        return { celsius };
+      },
+    }),
+  },
+  // Agent's default behavior is to stop after a maximum of 20 steps
+  // stopWhen: stepCountIs(20),
+});
+
+const result = await weatherAgent.generate({
+  prompt: 'What is the weather in San Francisco in celsius?',
+});
+
+console.log(result.text); // agent's final answer
+console.log(result.steps); // steps taken by the agent
+```
+
+The agent automatically:
+
+1. Calls the `weather` tool to get the temperature in Fahrenheit
+2. Calls `convertFahrenheitToCelsius` to convert it
+3. Generates a final text response with the result
+
+The Agent class handles the loop, context management, and stopping conditions.
+
+## Why Use the Agent Class?
+
+The Agent class is the recommended approach for building agents with the AI SDK because it:
+
+- **Reduces boilerplate** - Manages loops and message arrays
+- **Improves reusability** - Define once, use throughout your application
+- **Simplifies maintenance** - Single place to update agent configuration
+
+For most use cases, start with the Agent class. Use core functions (`generateText`, `streamText`) when you need explicit control over each step for complex structured workflows.
+
+## Structured Workflows
+
+Agents are flexible and powerful, but non-deterministic. When you need reliable, repeatable outcomes with explicit control flow, use core functions with structured workflow patterns combining:
+
+- Conditional statements for explicit branching
+- Standard functions for reusable logic
+- Error handling for robustness
+- Explicit control flow for predictability
+
+[Explore workflow patterns](/docs/agents/workflows) to learn more about building structured, reliable systems.
+
+## Next Steps
+
+- **[Building Agents](/docs/agents/building-agents)** - Guide to creating agents with the Agent class
+- **[Workflow Patterns](/docs/agents/workflows)** - Structured patterns using core functions for complex workflows
+- **[Loop Control](/docs/agents/loop-control)** - Execution control with stopWhen and prepareStep

package/docs/03-agents/02-building-agents.mdx

@@ -0,0 +1,367 @@
+---
+title: Building Agents
+description: Complete guide to creating agents with the Agent class.
+---
+
+# Building Agents
+
+The Agent class provides a structured way to encapsulate LLM configuration, tools, and behavior into reusable components. It handles the agent loop for you, allowing the LLM to call tools multiple times in sequence to accomplish complex tasks. Define agents once and use them across your application.
+
+## Why Use the ToolLoopAgent Class?
+
+When building AI applications, you often need to:
+
+- **Reuse configurations** - Same model settings, tools, and prompts across different parts of your application
+- **Maintain consistency** - Ensure the same behavior and capabilities throughout your codebase
+- **Simplify API routes** - Reduce boilerplate in your endpoints
+- **Type safety** - Get full TypeScript support for your agent's tools and outputs
+
+The ToolLoopAgent class provides a single place to define your agent's behavior.
+
+## Creating an Agent
+
+Define an agent by instantiating the ToolLoopAgent class with your desired configuration:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const myAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: 'You are a helpful assistant.',
+  tools: {
+    // Your tools here
+  },
+});
+```
+
+## Configuration Options
+
+The Agent class accepts all the same settings as `generateText` and `streamText`. Configure:
+
+### Model and System Instructions
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: 'You are an expert software engineer.',
+});
+```
+
+### Tools
+
+Provide tools that the agent can use to accomplish tasks:
+
+```ts
+import { ToolLoopAgent, tool } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const codeAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    runCode: tool({
+      description: 'Execute Python code',
+      inputSchema: z.object({
+        code: z.string(),
+      }),
+      execute: async ({ code }) => {
+        // Execute code and return result
+        return { output: 'Code executed successfully' };
+      },
+    }),
+  },
+});
+```
+
+### Loop Control
+
+By default, agents run for 20 steps (`stopWhen: stepCountIs(20)`). In each step, the model either generates text or calls a tool. If it generates text, the agent completes. If it calls a tool, the AI SDK executes that tool.
+
+To let agents call multiple tools in sequence, configure `stopWhen` to allow more steps. After each tool execution, the agent triggers a new generation where the model can call another tool or generate text:
+
+```ts
+import { ToolLoopAgent, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  stopWhen: stepCountIs(20), // Allow up to 20 steps
+});
+```
+
+Each step represents one generation (which results in either text or a tool call). The loop continues until:
+
+- A finish reasoning other than tool-calls is returned, or
+- A tool that is invoked does not have an execute function, or
+- A tool call needs approval, or
+- A stop condition is met
+
+You can combine multiple conditions:
+
+```ts
+import { ToolLoopAgent, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  stopWhen: [
+    stepCountIs(20), // Maximum 20 steps
+    yourCustomCondition(), // Custom logic for when to stop
+  ],
+});
+```
+
+Learn more about [loop control and stop conditions](/docs/agents/loop-control).
+
+### Tool Choice
+
+Control how the agent uses tools:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    // your tools here
+  },
+  toolChoice: 'required', // Force tool use
+  // or toolChoice: 'none' to disable tools
+  // or toolChoice: 'auto' (default) to let the model decide
+});
+```
+
+You can also force the use of a specific tool:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: {
+    weather: weatherTool,
+    cityAttractions: attractionsTool,
+  },
+  toolChoice: {
+    type: 'tool',
+    toolName: 'weather', // Force the weather tool to be used
+  },
+});
+```
+
+### Structured Output
+
+Define structured output schemas:
+
+```ts
+import { ToolLoopAgent, Output, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const analysisAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  output: Output.object({
+    schema: z.object({
+      sentiment: z.enum(['positive', 'neutral', 'negative']),
+      summary: z.string(),
+      keyPoints: z.array(z.string()),
+    }),
+  }),
+  stopWhen: stepCountIs(10),
+});
+
+const { output } = await analysisAgent.generate({
+  prompt: 'Analyze customer feedback from the last quarter',
+});
+```
+
+## Define Agent Behavior with System Instructions
+
+System instructions define your agent's behavior, personality, and constraints. They set the context for all interactions and guide how the agent responds to user queries and uses tools.
+
+### Basic System Instructions
+
+Set the agent's role and expertise:
+
+```ts
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions:
+    'You are an expert data analyst. You provide clear insights from complex data.',
+});
+```
+
+### Detailed Behavioral Instructions
+
+Provide specific guidelines for agent behavior:
+
+```ts
+const codeReviewAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: `You are a senior software engineer conducting code reviews.
+
+  Your approach:
+  - Focus on security vulnerabilities first
+  - Identify performance bottlenecks
+  - Suggest improvements for readability and maintainability
+  - Be constructive and educational in your feedback
+  - Always explain why something is an issue and how to fix it`,
+});
+```
+
+### Constrain Agent Behavior
+
+Set boundaries and ensure consistent behavior:
+
+```ts
+const customerSupportAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: `You are a customer support specialist for an e-commerce platform.
+
+  Rules:
+  - Never make promises about refunds without checking the policy
+  - Always be empathetic and professional
+  - If you don't know something, say so and offer to escalate
+  - Keep responses concise and actionable
+  - Never share internal company information`,
+  tools: {
+    checkOrderStatus,
+    lookupPolicy,
+    createTicket,
+  },
+});
+```
+
+### Tool Usage Instructions
+
+Guide how the agent should use available tools:
+
+```ts
+const researchAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: `You are a research assistant with access to search and document tools.
+
+  When researching:
+  1. Always start with a broad search to understand the topic
+  2. Use document analysis for detailed information
+  3. Cross-reference multiple sources before drawing conclusions
+  4. Cite your sources when presenting information
+  5. If information conflicts, present both viewpoints`,
+  tools: {
+    webSearch,
+    analyzeDocument,
+    extractQuotes,
+  },
+});
+```
+
+### Format and Style Instructions
+
+Control the output format and communication style:
+
+```ts
+const technicalWriterAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: `You are a technical documentation writer.
+
+  Writing style:
+  - Use clear, simple language
+  - Avoid jargon unless necessary
+  - Structure information with headers and bullet points
+  - Include code examples where relevant
+  - Write in second person ("you" instead of "the user")
+
+  Always format responses in Markdown.`,
+});
+```
+
+## Using an Agent
+
+Once defined, you can use your agent in three ways:
+
+### Generate Text
+
+Use `generate()` for one-time text generation:
+
+```ts
+const result = await myAgent.generate({
+  prompt: 'What is the weather like?',
+});
+
+console.log(result.text);
+```
+
+### Stream Text
+
+Use `stream()` for streaming responses:
+
+```ts
+const stream = myAgent.stream({
+  prompt: 'Tell me a story',
+});
+
+for await (const chunk of stream.textStream) {
+  console.log(chunk);
+}
+```
+
+### Respond to UI Messages
+
+Use `createAgentUIStreamResponse()` to create API responses for client applications:
+
+```ts
+// In your API route (e.g., app/api/chat/route.ts)
+import { createAgentUIStreamResponse } from 'ai';
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  return createAgentUIStreamResponse({
+    agent: myAgent,
+    messages,
+  });
+}
+```
+
+## End-to-end Type Safety
+
+You can infer types for your agent's `UIMessage`s:
+
+```ts
+import { ToolLoopAgent, InferAgentUIMessage } from 'ai';
+
+const myAgent = new ToolLoopAgent({
+  // ... configuration
+});
+
+// Infer the UIMessage type for UI components or persistence
+export type MyAgentUIMessage = InferAgentUIMessage<typeof myAgent>;
+```
+
+Use this type in your client components with `useChat`:
+
+```tsx filename="components/chat.tsx"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import type { MyAgentUIMessage } from '@/agent/my-agent';
+
+export function Chat() {
+  const { messages } = useChat<MyAgentUIMessage>();
+  // Full type safety for your messages and tools
+}
+```
+
+## Next Steps
+
+Now that you understand building agents, you can:
+
+- Explore [workflow patterns](/docs/agents/workflows) for structured patterns using core functions
+- Learn about [loop control](/docs/agents/loop-control) for advanced execution control
+- See [manual loop examples](/cookbook/node/manual-agent-loop) for custom workflow implementations