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

Структурированные выходные данные ограничивают ответы 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-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) 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(response.content[0].text)

Формат ответа: валидный JSON, соответствующий вашей схеме, в response.content[0].text

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}



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



Работа с выводом в формате 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-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) 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.



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

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

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

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

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



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



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

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



Совместное использование обеих возможностей

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

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

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

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # Вывод в формате 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,
            },
        }
    },
    # Строгое использование инструментов: гарантированные параметры инструментов
    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 автоматически получает дополнительную системную подсказку, объясняющую ожидаемый формат вывода. Это означает:

• Количество ваших входных токенов немного выше
• Внедрённая подсказка стоит вам токенов, как и любая другая системная подсказка
• Изменение параметра 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": "[email protected]",
  "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, чтобы получить полный структурированный вывод



Ограничения сложности схемы

Структурированные выходные данные работают путём компиляции ваших 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



Дальнейшие шаги