Strukturierte Ausgaben im SDK

Erhalten Sie strukturierte, validierte JSON aus Agent-Workflows. Das Agent SDK unterstützt strukturierte Ausgaben durch JSON-Schemas und stellt sicher, dass Ihre Agenten Daten genau in dem Format zurückgeben, das Sie benötigen.

Warum strukturierte Ausgaben verwenden

Strukturierte Ausgaben bieten zuverlässige, typsichere Integration mit Ihren Anwendungen:

• Validierte Struktur: Erhalten Sie immer gültiges JSON, das Ihrem Schema entspricht
• Vereinfachte Integration: Kein Parsing- oder Validierungscode erforderlich
• Typsicherheit: Verwenden Sie mit TypeScript- oder Python-Typhinweisen für End-to-End-Sicherheit
• Saubere Trennung: Definieren Sie Ausgabeanforderungen separat von Aufgabenanweisungen
• Tool-Autonomie: Agent wählt aus, welche Tools verwendet werden, während das Ausgabeformat garantiert wird

Wie strukturierte Ausgaben funktionieren

Unterstützte JSON-Schema-Funktionen

Das Agent SDK unterstützt die gleichen JSON-Schema-Funktionen und Einschränkungen wie API Strukturierte Ausgaben.

Wichtige unterstützte Funktionen:

• Alle grundlegenden Typen: object, array, string, integer, number, boolean, null
• enum, const, required, additionalProperties (muss false sein)
• String-Formate: date-time, date, email, uri, uuid usw.
• $ref, $def und definitions

Für vollständige Details zu unterstützten Funktionen, Einschränkungen und Regex-Muster-Unterstützung siehe JSON-Schema-Einschränkungen in der API-Dokumentation.

Beispiel: TODO-Tracking-Agent

Hier ist ein vollständiges Beispiel, das einen Agent zeigt, der Code nach TODOs durchsucht und Git-Blame-Informationen extrahiert:

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

// Struktur für TODO-Extraktion definieren
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 src/ 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}`)
      }
    })
  }
}

Der Agent nutzt autonom die richtigen Tools (Grep, Bash), um Informationen zu sammeln und gibt validierte Daten zurück.

Fehlerbehandlung

Wenn der Agent keine gültigen Ausgaben entsprechend Ihrem Schema erzeugen kann, erhalten Sie ein Fehlerergebnis:

for await (const msg of query({
  prompt: 'Analyze the data',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: mySchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      console.error('Could not produce valid output')
    }
  }
}

Verwandte Ressourcen

• JSON-Schema-Dokumentation
• API Strukturierte Ausgaben - Für einzelne API-Aufrufe
• Benutzerdefinierte Tools - Definieren Sie Tools für Ihre Agenten
• TypeScript SDK-Referenz - Vollständige TypeScript-API
• Python SDK-Referenz - Vollständige Python-API