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

Структурированные выходные данные ограничивают ответы Claude определённой схемой, обеспечивая корректные и анализируемые результаты для последующей обработки. Используйте JSON выходные данные (output_format) для структурированных ответов с данными или строгое использование инструментов (strict: true) для гарантированной валидации схемы имён инструментов и входных данных.

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

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

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

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

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

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

Когда использовать JSON выходные данные или строгое использование инструментов

Выберите правильный режим для вашего случая использования:

Почему строгое использование инструментов важно для агентов

Создание надёжных систем на основе агентов требует гарантированного соответствия схеме. Недействительные параметры инструментов нарушают работу ваших функций и рабочих процессов. Claude может вернуть несовместимые типы ("2" вместо 2) или отсутствующие поля, вызывая ошибки во время выполнения.

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

• Функции получают правильно типизированные аргументы каждый раз
• Нет необходимости проверять и повторно пытаться вызывать инструменты
• Готовые к производству агенты, которые работают последовательно в масштабе

Например, предположим, что система бронирования требует passengers: int. Без строгого режима Claude может предоставить passengers: "two" или passengers: "2". С strict: true вы гарантированно получите passengers: 2.

Как работают структурированные выходные данные

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

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

Использование Pydantic и Zod

Для разработчиков Python и TypeScript вы можете использовать знакомые инструменты определения схемы, такие как Pydantic и Zod, вместо написания необработанных JSON схем.

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

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

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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

Python: client.beta.messages.parse() (Рекомендуется)

Метод parse() автоматически преобразует вашу модель Pydantic, валидирует ответ и возвращает атрибут parsed_output.

Python: вспомогательная функция transform_schema()

Для случаев, когда вам нужно вручную преобразовать схемы перед отправкой, или когда вы хотите изменить схему, созданную Pydantic. В отличие от client.beta.messages.parse(), который автоматически преобразует предоставленные схемы, это даёт вам преобразованную схему, чтобы вы могли дополнительно её настроить.

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

Python и TypeScript SDK автоматически преобразуют схемы с неподдерживаемыми функциями:

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

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

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

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

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

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

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

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

Модификация подсказки и затраты на токены

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

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

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

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

Недействительные выходные данные

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

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

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

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

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

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

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

Ошибки валидации схемы

Если ваша схема использует неподдерживаемые функции или слишком сложна, вы получите ошибку 400:

"Too many recursive definitions in schema"

• Причина: Схема имеет чрезмерные или циклические рекурсивные определения
• Решение: Упростите структуру схемы, уменьшите глубину вложенности

"Schema is too complex"

• Причина: Схема превышает ограничения сложности
• Решение: Разбейте на меньшие схемы, упростите структуру или уменьшите количество инструментов, отмеченных как strict: true

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

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

Работает с:

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

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

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