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).

Offline Stack Scanner

Run the local scanner before agent-loop audits or migrations:

python3 skills/ai-sdk-agents/scripts/ai_stack_scan.py --root <repo> --pretty

It emits ai_stack_scan.v1, uses no network by default, skips symlinks, and flags likely agent-loop risks such as missing explicit stopWhen on ToolLoopAgent. Verify signals against current AI SDK docs/source before changing behavior. Keep full scanner JSON local; share only specific redacted signals externally.

Reference Files