Claude Platform Docs
СообщенияВозможности модели

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

Получайте проверенные результаты в формате JSON из агентных рабочих процессов

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

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

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

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

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

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

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

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

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

  1. Определите схему

    Опишите нужную структуру в виде JSON-схемы или в виде типа в вашем языке. Схема следует спецификации JSON Schema с некоторыми ограничениями.

  2. Отправьте её в output_config.format

    Запрос передаёт схему в output_config.format с type: "json_schema". Вспомогательные функции SDK задают это за вас.

  3. Прочитайте ответ

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

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

from pydantic import BaseModel



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)

Передайте модель Pydantic в client.messages.parse() (рекомендуемый метод) как output_format. SDK преобразует схему модели, отправляет её как output_config.format, проверяет ответ и возвращает разобранную модель в parsed_output.

Предыдущий пример выводит:

Output
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

Если ключи поля известны, используйте вложенную модель Pydantic, а не dict. SDK отправляет поле dict как объект с пустым properties, поэтому Claude может вернуть для него только {}. Если ключи заранее неизвестны, см. Объекты с произвольными ключами.

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

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

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

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

Пример: поле с minimum: 100 становится обычным целым числом в отправляемой схеме, а SDK добавляет {minimum: 100} в описание поля. Вспомогательная функция, проверяющая ответы, всё равно проверяет ответ на соответствие minimum: 100.

Использование необработанной JSON-схемы

Чтобы использовать JSON-схему из файла, спецификации OpenAPI или кода, который строит её во время выполнения, передайте её в output_config.format.

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,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

Предыдущий пример выводит:

Output
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

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

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

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

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

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

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

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

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

client = anthropic.Anthropic()

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: структурированный формат ответа
    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)

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

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

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

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

Изменение подсказки и стоимость токенов

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

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

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

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

Объекты с произвольными ключами

Перечислите каждый ключ объекта — либо в properties, либо как поле класса или схемы, которые вы передаёте в SDK. Поскольку additionalProperties должно быть false, Claude может вернуть только перечисленные вами ключи.

API принимает объект с пустым или отсутствующим properties, но Claude может вернуть для него только {}. Тип map, словаря или record не перечисляет ключей, поэтому SDK для Python и TypeScript отправляют его как объект с пустым properties. SDK для Java и Ruby вместо этого выдают ошибку.

Если ключи заранее неизвестны, используйте вместо этого массив. Задайте каждому элементу key и value, как в этой схеме:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

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

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

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

{
  "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.
  • Вам будет выставлен счёт за сгенерированные токены.
  • Вывод может не соответствовать вашей схеме, поскольку сообщение об отказе имеет приоритет над ограничениями схемы.

Свойство, запрашивающее размышления (thinking) модели или пошаговые рассуждения, может привести к отказу reasoning_extraction. Вместо этого запрашивайте краткое объяснение. См. Храните рассуждения в блоках размышлений.

Достигнут лимит токенов (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:

ОграничениеЗначениеОписание
Строгих инструментов на запрос20Максимальное количество инструментов с strict: true. Нестрогие инструменты не учитываются в этом ограничении.
Необязательные параметры24Общее количество необязательных параметров во всех схемах строгих инструментов и схемах выходных данных JSON. Каждый параметр, не указанный в required, учитывается в этом ограничении.
Параметры с типами объединений16Общее количество параметров, использующих anyOf или массивы типов (например, "type": ["string", "null"]), во всех строгих схемах. Они особенно затратны, поскольку создают экспоненциальную стоимость компиляции.

Дополнительные внутренние ограничения

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

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

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

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

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

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

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

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

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

Миграция с бета-версии

Параметр output_format перенесён в output_config.format, и бета-заголовки больше не требуются. Параметр output_format устарел. Чтобы всё же использовать его, добавьте бета-заголовок structured-outputs-2025-11-13. Без него API возвращает ошибку 400.

В Python SDK (v1.0 и новее) словарь схемы, переданный как output_format={...}, вызывает TypeError. Вместо этого используйте output_config. Модель Pydantic, переданная как output_format=Model в parse() или stream(), работает без изменений и без бета-заголовка, поскольку SDK отправляет её как output_config. Обновлённую структуру API см. в разделе Использование необработанной JSON-схемы.

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

Работает с:

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

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

Доступность

Структурированные выходные данные
API
  • Messages API
  • Managed Agents Не поддерживается
Модели
  • Все модели

Обработка данных

Обзор обработки данных

Применимые конечные точки

  • /v1/messages
Нулевое хранение данныхДопускается (с оговорками)

Кроме Охватываемые модели

Ваши подсказки и выходные данные Claude не хранятся. Кэшируется только JSON-схема — до 24 часов с момента последнего использования. Это также относится к строгому использованию инструментов (strict: true для инструментов), которое использует тот же конвейер грамматик. Подробнее

HIPAAДопускается

PHI не должна включаться в определения JSON-схем; см. рекомендации по обработке PHI. Подробнее

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

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

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

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

Обеспечьте соответствие входных данных инструментов Claude JSON Schema с помощью выборки, ограниченной грамматикой.

Подключайте Claude к внешним инструментам и API. Узнайте, где выполняются инструменты и как работает агентный цикл.

Узнайте о структуре цен Anthropic на модели и функции.

Эта страница была полезной?