Strukturierte Ausgaben von Agenten abrufen
Validiertes JSON aus Agent-Workflows mit JSON Schema, Zod oder Pydantic zurückgeben. Erhalten Sie typsichere, strukturierte Daten nach Multi-Turn-Tool-Nutzung.
Strukturierte Ausgaben ermöglichen es Ihnen, die genaue Form der Daten zu definieren, die Sie von einem Agenten zurückerhalten möchten. Der Agent kann alle erforderlichen Tools verwenden, 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 validiert die Ausgabe dagegen und fordert bei Nichtübereinstimmung erneut auf. Wenn die Validierung nicht innerhalb des Wiederholungslimits erfolgreich ist, ist das Ergebnis ein Fehler statt strukturierter Daten; siehe Fehlerbehandlung.
Für vollständige Typsicherheit verwenden Sie Zod (TypeScript) oder Pydantic (Python), um Ihr Schema zu definieren und stark typisierte Objekte zurückzuerhalten.
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, bei 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.
**Schokoladenchip-Kekse**
Vorbereitungszeit: 15 Minuten | Backzeit: 10 Minuten
Zutaten:
- 2 1/4 Tassen Allzweckmehl
- 1 Tasse Butter, erweicht
...
```
Um dies in Ihrer App zu verwenden, müssten Sie den Titel extrahieren, '15 Minuten" in eine Zahl umwandeln, Zutaten von Anweisungen trennen und mit inkonsistenter Formatierung über Antworten hinweg umgehen.
Mit strukturierten Ausgaben
{
"name": "Schokoladenchip-Kekse",
"prep_time_minutes": 15,
"cook_time_minutes": 10,
"ingredients": [
{ "item": "Allzweckmehl", "amount": 2.25, "unit": "Tassen" },
{ "item": "Butter, erweicht", "amount": 1, "unit": "Tasse" }
// ...
],
"steps": ["Ofen auf 375°F vorheizen", "Butter und Zucker cremig rühren" /* ... */]
}
Typisierte Daten, die Sie direkt in Ihrer UI 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.
import { query } from "@anthropic-ai/claude-agent-sdk";
// Definieren Sie die Form der Daten, die Sie zurückerhalten 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.subtype === "success" && message.structured_output) {
console.log(message.structured_output);
// { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
# Definieren Sie die Form der Daten, die Sie zurückerhalten möchten
schema = {
"type": "object",
"properties": {
"company_name": {"type": "string"},
"founded_year": {"type": "number"},
"headquarters": {"type": "string"},
},
"required": ["company_name"],
}
async def main():
async for message in query(
prompt="Research Anthropic and provide key company information",
options=ClaudeAgentOptions(
output_format={"type": "json_schema", "schema": schema}
),
):
# Die Ergebnismeldung enthält structured_output mit validierten Daten
if isinstance(message, ResultMessage) and message.structured_output:
print(message.structured_output)
# {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'}
asyncio.run(main())
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 Ihrer gesamten Codebasis 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.
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>;
// Konvertieren Sie zu JSON Schema
const schema = z.toJSONSchema(FeaturePlan);
// Verwenden Sie in der Abfrage
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.subtype === "success" && message.structured_output) {
// Validieren Sie und erhalten Sie ein vollständig typisiertes Ergebnis
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 asyncio
from pydantic import BaseModel
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
class Step(BaseModel):
step_number: int
description: str
estimated_complexity: str # 'low', 'medium', 'high'
class FeaturePlan(BaseModel):
feature_name: str
summary: str
steps: list[Step]
risks: list[str]
async def main():
async for message in query(
prompt="Plan how to add dark mode support to a React app. Break it into implementation steps.",
options=ClaudeAgentOptions(
output_format={
"type": "json_schema",
"schema": FeaturePlan.model_json_schema(),
}
),
):
if isinstance(message, ResultMessage) and message.structured_output:
# Validieren Sie und erhalten Sie ein vollständig typisiertes Ergebnis
plan = FeaturePlan.model_validate(message.structured_output)
print(f"Feature: {plan.feature_name}")
print(f"Summary: {plan.summary}")
for step in plan.steps:
print(
f"{step.step_number}. [{step.estimated_complexity}] {step.description}"
)
asyncio.run(main())
Vorteile:
- Vollständige Typinferenz (TypeScript) und Typhinweise (Python)
- Laufzeitvalidierung mit
safeParse()odermodel_validate() - Bessere Fehlermeldungen
- Zusammensetzbare, wiederverwendbare Schemas
Konfiguration des Ausgabeformats
Die Option outputFormat (TypeScript) oder output_format (Python) akzeptiert ein Objekt mit:
type: Setzen Sie auf"json_schema"für strukturierte Ausgabenschema: Ein JSON Schema-Objekt, das Ihre Ausgabestruktur definiert. Sie können dies aus einem Zod-Schema mitz.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. Die 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 Multi-Step-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 eine einzelne strukturierte 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.
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.subtype === "success" && message.structured_output) {
const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> };
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}`);
}
});
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
# Definieren Sie die Struktur für TODO-Extraktion
todo_schema = {
"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"],
}
async def main():
# Agent verwendet Grep zum Finden von TODOs, Bash zum Abrufen von Git-Blame-Informationen
async for message in query(
prompt="Find all TODO comments in this codebase and identify who added them",
options=ClaudeAgentOptions(
output_format={"type": "json_schema", "schema": todo_schema}
),
):
if isinstance(message, ResultMessage) and message.structured_output:
data = message.structured_output
print(f"Found {data['total_count']} TODOs")
for todo in data["todos"]:
print(f"{todo['file']}:{todo['line']} - {todo['text']}")
if "author" in todo:
print(f" Added by {todo['author']} on {todo['date']}")
asyncio.run(main())
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 für die Aufgabe zu komplex ist, die Aufgabe selbst mehrdeutig ist, oder der Agent sein Wiederholungslimit beim Versuch, Validierungsfehler zu beheben, erreicht. Es kann auch ohne Validierungsfehler geschehen: Ein Modell-Fallback kann eine bereits abgeschlossene Ausgabe mitten im Stream zurückziehen, und wenn kein erfolgreicher Wiederholungsversuch sie ersetzt, endet der Durchlauf mit demselben Fehler. Überprüfen Sie das Feld errors der Ergebnismeldung, um die beiden Ursachen auseinanderzuhalten, bevor Sie Ihr Schema debuggen.
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 |
Keine gültige Ausgabe überstand mehrere Versuche (Validierungsfehler oder ein Modell-Fallback-Rückzug ohne erfolgreichen Wiederholungsversuch) |
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:
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) {
// Use the validated output
console.log(msg.structured_output);
} else if (msg.subtype === "error_max_structured_output_retries") {
// Handle the failure - retry with simpler prompt, fall back to unstructured, etc.
console.error("Could not produce valid output");
}
}
}
async for message in query(
prompt="Extract contact info from the document",
options=ClaudeAgentOptions(
output_format={"type": "json_schema", "schema": contact_schema}
),
):
if isinstance(message, ResultMessage):
if message.subtype == "success" and message.structured_output:
# Use the validated output
print(message.structured_output)
elif message.subtype == "error_max_structured_output_retries":
# Handle the failure
print("Could not produce valid output")
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 für den Agenten schwieriger 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