AI SDK Agents

Build autonomous agents with ToolLoopAgent: reusable model + tools + loop control.

Quick Start

Assume Zod v4.3.5 for schema typing.

import { ToolLoopAgent, tool } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';

const weatherAgent = new ToolLoopAgent({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    weather: tool({
      description: 'Get the weather in a location (F)',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => ({ location, temperature: 72 }),
    }),
  },
});

const result = await weatherAgent.generate({
  prompt: 'What is the weather in San Francisco?',
});

When to Use ToolLoopAgent vs Core Functions

• Use ToolLoopAgent for dynamic, multi-step tasks where the model decides which tools to call.
• Use generateText/streamText for deterministic flows or strict ordering.

Essential Patterns

Structured Output

import { ToolLoopAgent, Output } from 'ai';
import { z } from 'zod';

const analysisAgent = new ToolLoopAgent({
  model: 'openai/gpt-4o',
  output: Output.object({
    schema: z.object({
      sentiment: z.enum(['positive', 'neutral', 'negative']),
      summary: z.string(),
    }),
  }),
});

Streaming Agent

const stream = myAgent.stream({ prompt: 'Summarize this report' });
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

API Route

import { createAgentUIStreamResponse } from 'ai';

export async function POST(request: Request) {
  const { messages } = await request.json();
  return createAgentUIStreamResponse({ agent: myAgent, messages });
}

Type-Safe Client Integration

import { ToolLoopAgent, InferAgentUIMessage } from 'ai';

const myAgent = new ToolLoopAgent({ model, tools });
export type MyAgentUIMessage = InferAgentUIMessage<typeof myAgent>;

Loop Control Checklist

• Set

  stopWhen

  (default:

  stepCountIs(20)

  ) for safety.
• Use

  hasToolCall('finalAnswer')

  to stop on terminal actions.
• Use

  prepareStep

  to swap models, compress messages, or limit tools per step.

Runtime Configuration

• Use

  callOptionsSchema

  to define type-safe runtime options.
• Use

  prepareCall

  to select model/tools or inject RAG context once per call.
• Use

  prepareStep

  for per-step decisions (budget limits, dynamic tools).

Reference Files

references/fundamentals.md

references/loop-control.md

references/configuration.md

references/workflow-patterns.md

references/real-world.md

references/production.md

references/migration.md