Tool Calling & Structured Output

LLMs können mehr als Text generieren — mit Tool Calling führen sie Aktionen aus, und mit Structured Output liefern sie typsichere, maschinenlesbare Daten. Beides zusammen macht aus einem Chatbot eine vollwertige Anwendung.

Tool Definitions mit Zod

Was ist Tool Calling?

Das LLM entscheidet basierend auf der Nutzeranfrage, welches Tool (Funktion) aufgerufen werden soll, und generiert die passenden Parameter. Die eigentliche Ausführung passiert in Ihrem Code.

Tool Definition

import { tool } from 'ai'
import { z } from 'zod'

const weatherTool = tool({
  description: 'Ruft das aktuelle Wetter für eine Stadt ab',
  parameters: z.object({
    city: z.string().describe('Der Name der Stadt'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  execute: async ({ city, unit }) => {
    const data = await fetchWeatherAPI(city, unit)
    return { temperature: data.temp, condition: data.condition }
  },
})

Tools in Route Handlers

import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

export async function POST(req: Request) {
  const { messages } = await req.json()

  const result = streamText({
    model: openai('gpt-4.1'),
    messages,
    tools: {
      getWeather: weatherTool,
      searchProducts: productSearchTool,
      createOrder: orderTool,
    },
  })

  return result.toDataStreamResponse()
}

Das LLM entscheidet selbst, welches Tool für die Anfrage relevant ist:

• "Wie ist das Wetter?" → getWeather
• "Zeig mir Laptops unter 1000€" → searchProducts
• "Bestelle den Dell XPS" → createOrder

Multi-Step Tool Calls

Agentic Tool Calling

Für komplexe Aufgaben ruft das LLM mehrere Tools nacheinander auf:

const result = streamText({
  model: openai('gpt-4.1'),
  messages,
  tools: { getWeather, searchHotels, bookHotel },
  maxSteps: 5, // Erlaubt bis zu 5 Tool-Aufrufe
  onStepFinish: ({ stepType, toolResults }) => {
    console.log(`Step: ${stepType}`, toolResults)
  },
})

Beispiel-Ablauf:

1. User: "Buche mir ein Hotel in München für nächste Woche bei gutem Wetter"
2. LLM → getWeather({ city: 'München' }) → "15°C, sonnig"
3. LLM → searchHotels({ city: 'München', dates: '...' }) → 5 Hotels
4. LLM → "Hier sind 5 Hotels. Das Hotel Bayerischer Hof hat die besten Bewertungen. Soll ich buchen?"
5. User: "Ja, buche das Bayerischer Hof"
6. LLM → bookHotel({ hotelId: '...', dates: '...' }) → Buchungsbestätigung

Structured Output

generateObject — Typsichere Ausgaben

Statt unstrukturierten Text zu generieren, liefert generateObject Zod-validierte Objekte:

import { generateObject } from 'ai'
import { z } from 'zod'

const { object } = await generateObject({
  model: openai('gpt-4.1'),
  schema: z.object({
    title: z.string(),
    summary: z.string().max(200),
    tags: z.array(z.string()).max(5),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
    confidence: z.number().min(0).max(1),
  }),
  prompt: 'Analysiere diesen Kundenkommentar: "Das Produkt ist fantastisch!"',
})

// object ist typsicher: { title: string, summary: string, ... }

streamObject — Streaming Structured Output

Für große Objekte oder progressive UIs:

import { streamObject } from 'ai'

const result = streamObject({
  model: openai('gpt-4.1'),
  schema: productAnalysisSchema,
  prompt: 'Analysiere die Top-5 Produkte...',
})

for await (const partialObject of result.partialObjectStream) {
  // UI progressiv aktualisieren
  updateUI(partialObject)
}

Type-Safe Responses

End-to-End Type Safety

Das AI SDK + Zod ermöglicht vollständige Typsicherheit von der Schemadefinition bis zur UI:

1. Schema-Definition (Zod): Definiert die Struktur
2. AI SDK (generateObject): Generiert und validiert
3. TypeScript Inference: typeof schema._type → TypeScript-Type
4. React-Komponente: Typsichere Props aus dem generierten Objekt

Enum Mode vs. JSON Mode

Best Practice: Nutzen Sie generateObject statt generateText + manuelles JSON-Parsing. Das AI SDK garantiert schema-konforme Ausgaben und wirft typesafe Errors bei Validierungsfehlern.