Структурированные выходные данные

«Structured outputs» (структурированные выходные данные) ограничивают ответы Claude так, чтобы они следовали определённой схеме, обеспечивая валидный, поддающийся разбору вывод для последующей обработки. Структурированные выходные данные предоставляют две взаимодополняющие функции:

• Выходные данные JSON (output_config.format): получайте ответ Claude в определённом формате JSON
• Строгое использование инструментов (strict: true): гарантируйте валидацию схемы для имён инструментов и их входных данных

Вы можете использовать эти функции независимо или вместе в одном запросе.

Зачем использовать структурированные выходные данные

Без структурированных выходных данных Claude может генерировать некорректные ответы JSON или невалидные входные данные инструментов, которые ломают ваши приложения. Даже при тщательном составлении подсказок вы можете столкнуться с:

• Ошибками разбора из-за невалидного синтаксиса JSON
• Отсутствующими обязательными полями
• Несогласованными типами данных
• Нарушениями схемы, требующими обработки ошибок и повторных попыток

Структурированные выходные данные гарантируют соответствующие схеме ответы благодаря ограниченному декодированию:

• Всегда валидны: больше никаких ошибок JSON.parse()
• Типобезопасны: гарантированные типы полей и обязательные поля
• Надёжны: не нужны повторные попытки из-за нарушений схемы

Выходные данные JSON

Выходные данные JSON управляют форматом ответа Claude, гарантируя, что Claude возвращает валидный JSON, соответствующий вашей схеме. Используйте выходные данные JSON, когда вам нужно:

• Управлять форматом ответа Claude
• Извлекать данные из изображений или текста
• Генерировать структурированные отчёты
• Форматировать ответы API

Быстрый старт

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
print(next(block.text for block in response.content if block.type == "text"))

Формат ответа: валидный JSON, соответствующий вашей схеме, в текстовом блоке содержимого ответа

{
  "name": "John Smith",
  "email": "john@example.com",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

Как это работает

1. 1

   Определите вашу схему JSON

   Создайте схему JSON, описывающую структуру, которой должен следовать Claude. Схема использует стандартный формат JSON Schema с некоторыми ограничениями (см. Ограничения JSON Schema).

2. 2

   Добавьте параметр output_config.format

   Включите параметр output_config.format в ваш запрос API с type: "json_schema" и определением вашей схемы.

3. 3

   Разберите ответ

   Ответ Claude — это валидный JSON, соответствующий вашей схеме, возвращаемый в текстовом блоке содержимого ответа.

Работа с выходными данными JSON в SDK

SDK предоставляют вспомогательные средства, упрощающие работу с выходными данными JSON, включая преобразование схем, автоматическую валидацию и интеграцию с популярными библиотеками схем.

Использование нативных определений схем

Вместо написания сырых схем JSON вы можете использовать привычные инструменты определения схем на вашем языке:

• Python: модели Pydantic с client.messages.parse()
• TypeScript: схемы Zod с zodOutputFormat() или типизированные литералы JSON Schema с jsonSchemaOutputFormat()
• Java: обычные классы Java с автоматическим выводом схемы через outputConfig(Class<T>)
• Ruby: классы Anthropic::BaseModel с output_config: {format: Model}
• PHP: классы, реализующие StructuredOutputModel, с outputConfig: ['format' => MyClass::class]
• C#: обычные классы C# с обобщённой перегрузкой Create<T>(), которая выводит схему автоматически
• Go: структуры Go, автоматически отражаемые в схемы JSON в бета-API, или сырые схемы JSON через output_config
• CLI: сырые схемы JSON, передаваемые через output_config

from pydantic import BaseModel
from anthropic import Anthropic


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

Методы, специфичные для SDK

Каждый SDK предоставляет вспомогательные средства, упрощающие работу со структурированными выходными данными. Полные сведения смотрите на страницах отдельных SDK.

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Прямой доступ к разобранному выводу
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# Сначала преобразуйте модель Pydantic в JSON-схему, затем трансформируйте её
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# При необходимости измените схему
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)

Как работает преобразование в SDK

SDK для Python, TypeScript, Ruby и PHP автоматически преобразуют схемы с неподдерживаемыми возможностями. SDK для C# и Go применяют те же преобразования, когда схема выводится из нативного типа (Create<T>() в C#; отражение структур или BetaJSONSchemaOutputFormat() в бета-API Go). Шаги преобразования:

1. Удаление неподдерживаемых ограничений (например, minimum, maximum, minLength, maxLength)
2. Обновление описаний информацией об ограничениях (например, «Must be at least 100»), когда ограничение не поддерживается напрямую структурированными выходными данными
3. Добавление additionalProperties: false ко всем объектам
4. Фильтрация строковых форматов только до поддерживаемого списка
5. Валидация ответов по вашей исходной схеме (со всеми ограничениями)

Это означает, что Claude получает упрощённую схему, но ваш код по-прежнему обеспечивает соблюдение всех ограничений через валидацию.

Пример: поле Pydantic с minimum: 100 становится обычным целым числом в отправляемой схеме, но SDK обновляет описание на «Must be at least 100» и валидирует ответ по исходному ограничению.

Распространённые сценарии использования

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

Строгое использование инструментов

Чтобы обеспечить соответствие входных данных инструментов JSON Schema с помощью сэмплирования, ограниченного грамматикой, см. Строгое использование инструментов.

Совместное использование обеих функций

Выходные данные JSON и строгое использование инструментов решают разные задачи и работают вместе:

• Выходные данные JSON управляют форматом ответа Claude (что говорит Claude)
• Строгое использование инструментов валидирует параметры инструментов (как Claude вызывает ваши функции)

В сочетании Claude может вызывать инструменты с гарантированно валидными параметрами И возвращать структурированные ответы JSON. Это полезно для агентных рабочих процессов, где вам нужны и надёжные вызовы инструментов, и структурированные итоговые выходные данные.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON outputs (выходные данные JSON): структурированный формат ответа
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Strict tool use (строгое использование инструментов): гарантированные параметры инструментов
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

Важные соображения

Компиляция и кэширование грамматик

Структурированные выходные данные используют ограниченное сэмплирование со скомпилированными артефактами грамматик. Это вносит некоторые особенности производительности, о которых следует знать:

• Задержка первого запроса: при первом использовании конкретной схемы возникает дополнительная задержка, пока грамматика компилируется
• Автоматическое кэширование: скомпилированные грамматики кэшируются на 24 часа с момента последнего использования, что делает последующие запросы значительно быстрее
• Инвалидация кэша: кэш инвалидируется, если вы изменяете:
  • Структуру схемы JSON
  • Набор инструментов в вашем запросе (при совместном использовании структурированных выходных данных и использования инструментов)
  • Изменение только полей name или description не инвалидирует кэш

Модификация подсказки и стоимость токенов

При использовании структурированных выходных данных Claude автоматически получает дополнительную «system prompt» (системную подсказку), объясняющую ожидаемый формат вывода. Это означает:

• Количество ваших входных токенов немного выше
• Внедрённая подсказка стоит вам токенов, как и любая другая системная подсказка
• Изменение параметра output_config.format инвалидирует любой кэш подсказок для этой ветки разговора

Ограничения JSON Schema

Структурированные выходные данные поддерживают стандартную JSON Schema с некоторыми ограничениями. Эти ограничения общие как для выходных данных JSON, так и для строгого использования инструментов.

Порядок свойств

При использовании структурированных выходных данных свойства в объектах сохраняют порядок, определённый в вашей схеме, с одной важной оговоркой: обязательные свойства идут первыми, за ними следуют необязательные свойства.

Например, для такой схемы:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Вывод упорядочит свойства так:

1. name (обязательное, в порядке схемы)
2. email (обязательное, в порядке схемы)
3. notes (необязательное, в порядке схемы)
4. age (необязательное, в порядке схемы)

Это означает, что вывод может выглядеть так:

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Если порядок свойств в выводе важен для вашего приложения, пометьте все свойства как обязательные или учтите это переупорядочивание в вашей логике разбора.

Невалидные выходные данные

Хотя структурированные выходные данные гарантируют соответствие схеме в большинстве случаев, существуют сценарии, в которых вывод может не соответствовать вашей схеме:

Отказы (stop_reason: "refusal")

Claude сохраняет свои свойства безопасности и полезности даже при использовании структурированных выходных данных. Если Claude отказывается выполнить запрос по соображениям безопасности:

• Ответ имеет stop_reason: "refusal"
• Вы получите код состояния 200
• Вам будет выставлен счёт за сгенерированные токены
• Вывод может не соответствовать вашей схеме, поскольку сообщение об отказе имеет приоритет над ограничениями схемы

Достигнут лимит токенов (stop_reason: "max_tokens")

Если ответ обрезан из-за достижения лимита max_tokens:

• Ответ имеет stop_reason: "max_tokens"
• Вывод может быть неполным и не соответствовать вашей схеме
• Повторите запрос с более высоким значением max_tokens, чтобы получить полные структурированные выходные данные

Регистр значений перечислений

Структурированные выходные данные не гарантируют регистр букв строковых значений enum и const: Claude может вернуть значение, отличающееся от вашей схемы только регистром, обычно в первой букве слова, следующего за пробелом. Например, для такой схемы:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

Вывод может содержать "Conversation Topic 3" (заглавная «T»), хотя именно такого значения нет в перечислении. Ответ завершается нормально, без ошибки и без специального stop_reason. Это относится как к выходным данным JSON, так и к строгому использованию инструментов. Сравнивайте значения перечислений без учёта регистра и избегайте значений перечислений, отличающихся только регистром.

Лимиты сложности схем

Структурированные выходные данные работают путём компиляции ваших схем JSON в грамматику, ограничивающую вывод Claude. Более сложные схемы дают более крупные грамматики, компиляция которых занимает больше времени. Для защиты от чрезмерного времени компиляции API применяет несколько лимитов сложности.

Явные лимиты

Следующие лимиты применяются ко всем запросам с output_config.format или strict: true:

Дополнительные внутренние лимиты

Помимо явных лимитов в предыдущей таблице, существуют дополнительные внутренние лимиты на размер скомпилированной грамматики. Эти лимиты существуют потому, что сложность схемы не сводится к одному измерению: такие возможности, как необязательные параметры, типы-объединения, вложенные объекты и количество инструментов, взаимодействуют друг с другом так, что скомпилированная грамматика может стать непропорционально большой.

При превышении этих лимитов вы получите ошибку 400 с сообщением «Schema is too complex for compilation.» Эти ошибки означают, что совокупная сложность ваших схем превышает то, что можно эффективно скомпилировать, даже если каждый отдельный лимит в предыдущей таблице соблюдён. В качестве последней меры API также применяет тайм-аут компиляции в 180 секунд. Схемы, проходящие все явные проверки, но дающие очень большие скомпилированные грамматики, могут упереться в этот тайм-аут.

Советы по снижению сложности схем

Если вы упираетесь в лимиты сложности, попробуйте эти стратегии по порядку:

1. Помечайте как строгие только критически важные инструменты. Если у вас много инструментов, оставьте строгий режим для инструментов, где нарушения схемы вызывают реальные проблемы, и полагайтесь на естественное следование Claude схеме для более простых инструментов.

2. Сократите количество необязательных параметров. Делайте параметры required, где это возможно. Каждый необязательный параметр примерно удваивает часть пространства состояний грамматики. Если у параметра всегда есть разумное значение по умолчанию, рассмотрите возможность сделать его обязательным и поручить Claude явно указывать это значение по умолчанию.

3. Упростите вложенные структуры. Глубоко вложенные объекты с необязательными полями усугубляют сложность. Делайте структуры плоскими, где это возможно.

4. Разделите на несколько запросов. Если у вас много строгих инструментов, рассмотрите возможность распределить их по отдельным запросам или субагентам.

При постоянных проблемах с валидными схемами обратитесь в поддержку, приложив определение вашей схемы.

Хранение данных

Подсказки и ответы обрабатываются с ZDR при использовании структурированных выходных данных. Однако сама схема JSON временно кэшируется на срок до 24 часов с момента последнего использования в целях оптимизации. Никакие данные подсказок или ответов не сохраняются после ответа API.

Структурированные выходные данные соответствуют требованиям HIPAA, но PHI не должна включаться в определения схем JSON. API компилирует схемы JSON в грамматики, которые кэшируются отдельно от содержимого сообщений, и эти кэшированные схемы не получают той же защиты PHI, что подсказки и ответы. Не включайте PHI в имена свойств схемы, значения enum, значения const или регулярные выражения pattern. PHI должна появляться только в содержимом сообщений (подсказках и ответах), где она защищена мерами безопасности HIPAA.

О соответствии требованиям ZDR и HIPAA для всех функций см. API и хранение данных.

Совместимость функций

Работает с:

• Пакетная обработка: обрабатывайте структурированные выходные данные в масштабе со скидкой 50%
• Подсчёт токенов: подсчитывайте токены без компиляции
• Потоковая передача: передавайте структурированные выходные данные потоком, как обычные ответы
• Совместное использование: используйте выходные данные JSON (output_config.format) и строгое использование инструментов (strict: true) вместе в одном запросе

Несовместимо с:

• Цитирование: цитирование требует чередования блоков цитат с текстом, что конфликтует со строгими ограничениями схемы JSON. Возвращает ошибку 400, если цитирование включено вместе с output_config.format.
• Предзаполнение сообщений: несовместимо с выходными данными JSON

Следующие шаги

Compatibility