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

Структурированные выходные данные ограничивают ответы 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