Strukturierte Ausgaben von Agenten abrufen

Strukturierte Ausgaben ermöglichen es Ihnen, die genaue Form der Daten zu definieren, die Sie von einem Agenten zurückbekommen möchten. Der Agent kann alle Tools verwenden, die er benötigt, um die Aufgabe zu erfüllen, und Sie erhalten am Ende immer noch validiertes JSON, das Ihrem Schema entspricht. Definieren Sie ein JSON Schema für die benötigte Struktur, und das SDK garantiert, dass die Ausgabe damit übereinstimmt.

Für vollständige Typsicherheit verwenden Sie Zod (TypeScript) oder Pydantic (Python), um Ihr Schema zu definieren und stark typisierte Objekte zurückzubekommen.

Warum strukturierte Ausgaben?

Agenten geben standardmäßig freien Text zurück, was für Chat funktioniert, aber nicht, wenn Sie die Ausgabe programmgesteuert verwenden müssen. Strukturierte Ausgaben geben Ihnen typisierte Daten, die Sie direkt an Ihre Anwendungslogik, Datenbank oder UI-Komponenten übergeben können.

Stellen Sie sich eine Rezept-App vor, in der ein Agent das Web durchsucht und Rezepte zurückbringt. Ohne strukturierte Ausgaben erhalten Sie freien Text, den Sie selbst analysieren müssten. Mit strukturierten Ausgaben definieren Sie die gewünschte Form und erhalten typisierte Daten, die Sie direkt in Ihrer App verwenden können.

Schnellstart

Um strukturierte Ausgaben zu verwenden, definieren Sie ein JSON Schema, das die Form der gewünschten Daten beschreibt, und übergeben Sie es dann an query() über die Option outputFormat (TypeScript) oder output_format (Python). Wenn der Agent fertig ist, enthält die Ergebnismeldung ein Feld structured_output mit validierten Daten, die Ihrem Schema entsprechen.

Das folgende Beispiel fordert den Agenten auf, Anthropic zu recherchieren und den Firmennamen, das Gründungsjahr und den Hauptsitz als strukturierte Ausgabe zurückzugeben.

Typsichere Schemas mit Zod und Pydantic

Anstatt JSON Schema von Hand zu schreiben, können Sie Zod (TypeScript) oder Pydantic (Python) verwenden, um Ihr Schema zu definieren. Diese Bibliotheken generieren das JSON Schema für Sie und ermöglichen es Ihnen, die Antwort in ein vollständig typisiertes Objekt zu analysieren, das Sie in Ihrem gesamten Codebase mit Autovervollständigung und Typprüfung verwenden können.

Das folgende Beispiel definiert ein Schema für einen Implementierungsplan für Features mit einer Zusammenfassung, einer Liste von Schritten (jeweils mit Komplexitätsstufe) und potenziellen Risiken. Der Agent plant das Feature und gibt ein typisiertes FeaturePlan-Objekt zurück. Sie können dann auf Eigenschaften wie plan.summary zugreifen und über plan.steps mit vollständiger Typsicherheit iterieren.

Vorteile:

Vollständige Typinferenz (TypeScript) und Typhinweise (Python)
Laufzeitvalidierung mit safeParse() oder model_validate()
Bessere Fehlermeldungen
Zusammensetzbare, wiederverwendbare Schemas

Konfiguration des Ausgabeformats

Die Option outputFormat (TypeScript) oder output_format (Python) akzeptiert ein Objekt mit:

type: Auf "json_schema" für strukturierte Ausgaben setzen
schema: Ein JSON Schema-Objekt, das Ihre Ausgabestruktur definiert. Sie können dies aus einem Zod-Schema mit z.toJSONSchema() oder einem Pydantic-Modell mit .model_json_schema() generieren

Das SDK unterstützt Standard-JSON-Schema-Funktionen, einschließlich aller grundlegenden Typen (object, array, string, number, boolean, null), enum, const, required, verschachtelte Objekte und $ref-Definitionen. Eine vollständige Liste der unterstützten Funktionen und Einschränkungen finden Sie unter JSON Schema-Einschränkungen.

Beispiel: TODO-Tracking-Agent

Dieses Beispiel zeigt, wie strukturierte Ausgaben mit mehrstufiger Tool-Nutzung funktionieren. Der Agent muss TODO-Kommentare in der Codebasis finden und dann für jeden Git-Blame-Informationen nachschlagen. Er entscheidet autonom, welche Tools er verwenden soll (Grep zum Suchen, Bash zum Ausführen von Git-Befehlen) und kombiniert die Ergebnisse in einer einzigen strukturierten Antwort.

Das Schema enthält optionale Felder (author und date), da Git-Blame-Informationen möglicherweise nicht für alle Dateien verfügbar sind. Der Agent füllt aus, was er finden kann, und lässt den Rest weg.

Fehlerbehandlung

Die Generierung strukturierter Ausgaben kann fehlschlagen, wenn der Agent kein gültiges JSON erzeugen kann, das Ihrem Schema entspricht. Dies geschieht normalerweise, wenn das Schema zu komplex für die Aufgabe ist, die Aufgabe selbst mehrdeutig ist, oder der Agent sein Wiederholungslimit beim Versuch, Validierungsfehler zu beheben, erreicht.

Wenn ein Fehler auftritt, hat die Ergebnismeldung einen subtype, der angibt, was schief gelaufen ist:

Subtype	Bedeutung
`success`	Ausgabe wurde erfolgreich generiert und validiert
`error_max_structured_output_retries`	Agent konnte nach mehreren Versuchen keine gültige Ausgabe erzeugen

Das folgende Beispiel prüft das Feld subtype, um zu bestimmen, ob die Ausgabe erfolgreich generiert wurde oder ob Sie einen Fehler behandeln müssen:

Tipps zur Vermeidung von Fehlern:

Halten Sie Schemas fokussiert. Tief verschachtelte Schemas mit vielen erforderlichen Feldern sind schwerer zu erfüllen. Beginnen Sie einfach und fügen Sie Komplexität nach Bedarf hinzu.
Passen Sie das Schema an die Aufgabe an. Wenn die Aufgabe möglicherweise nicht alle Informationen hat, die Ihr Schema erfordert, machen Sie diese Felder optional.
Verwenden Sie klare Prompts. Mehrdeutige Prompts machen es dem Agenten schwerer zu wissen, welche Ausgabe er erzeugen soll.

Verwandte Ressourcen

JSON Schema-Dokumentation: Erfahren Sie mehr über JSON Schema-Syntax zum Definieren komplexer Schemas mit verschachtelten Objekten, Arrays, Enums und Validierungsbeschränkungen
API Structured Outputs: Verwenden Sie strukturierte Ausgaben direkt mit der Claude API für Single-Turn-Anfragen ohne Tool-Nutzung
Custom tools: Geben Sie Ihrem Agenten benutzerdefinierte Tools, die während der Ausführung aufgerufen werden können, bevor strukturierte Ausgaben zurückgegeben werden

import { query } from '@anthropic-ai/claude-agent-sdk'

// Definieren Sie die Form der Daten, die Sie zurückbekommen möchten
const schema = {
  type: 'object',
  properties: {
    company_name: { type: 'string' },
    founded_year: { type: 'number' },
    headquarters: { type: 'string' }
  },
  required: ['company_name']
}

for await (const message of query({
  prompt: 'Research Anthropic and provide key company information',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  // Die Ergebnismeldung enthält structured_output mit validierten Daten
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

import { z } from 'zod'
import { query } from '@anthropic-ai/claude-agent-sdk'

// Definieren Sie das Schema mit Zod
const FeaturePlan = z.object({
  feature_name: z.string(),
  summary: z.string(),
  steps: z.array(z.object({
    step_number: z.number(),
    description: z.string(),
    estimated_complexity: z.enum(['low', 'medium', 'high'])
  })),
  risks: z.array(z.string())
})

type FeaturePlan = z.infer<typeof FeaturePlan>

// In JSON Schema konvertieren
const schema = z.toJSONSchema(FeaturePlan)

// In Abfrage verwenden
for await (const message of query({
  prompt: 'Plan how to add dark mode support to a React app. Break it into implementation steps.',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    // Validieren und vollständig typisiertes Ergebnis abrufen
    const parsed = FeaturePlan.safeParse(message.structured_output)
    if (parsed.success) {
      const plan: FeaturePlan = parsed.data
      console.log(`Feature: ${plan.feature_name}`)
      console.log(`Summary: ${plan.summary}`)
      plan.steps.forEach(step => {
        console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`)
      })
    }
  }
}

import { query } from '@anthropic-ai/claude-agent-sdk'

// Definieren Sie die Struktur für TODO-Extraktion
const todoSchema = {
  type: 'object',
  properties: {
    todos: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          text: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          author: { type: 'string' },
          date: { type: 'string' }
        },
        required: ['text', 'file', 'line']
      }
    },
    total_count: { type: 'number' }
  },
  required: ['todos', 'total_count']
}

// Agent verwendet Grep zum Finden von TODOs, Bash zum Abrufen von Git-Blame-Informationen
for await (const message of query({
  prompt: 'Find all TODO comments in this codebase and identify who added them',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: todoSchema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    const data = message.structured_output
    console.log(`Found ${data.total_count} TODOs`)
    data.todos.forEach(todo => {
      console.log(`${todo.file}:${todo.line} - ${todo.text}`)
      if (todo.author) {
        console.log(`  Added by ${todo.author} on ${todo.date}`)
      }
    })
  }
}

for await (const msg of query({
  prompt: 'Extract contact info from the document',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: contactSchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      // Verwenden Sie die validierte Ausgabe
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Behandeln Sie den Fehler - versuchen Sie es mit einfacherem Prompt, fallen Sie auf unstrukturiert zurück, usw.
      console.error('Could not produce valid output')
    }
  }
}