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

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

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

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

Структурированные выводы общедоступны в Claude API и Amazon Bedrock для Claude Opus 4.6, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.5 и Claude Haiku 4.5. Структурированные выводы остаются в публичной бета-версии на Microsoft Foundry.

This feature qualifies for Zero Data Retention (ZDR) with limited technical retention. See the Data retention section for details on what is retained and why.

Переходите с бета-версии? Параметр output_format перемещён в output_config.format, и заголовки бета-версии больше не требуются. Старый заголовок бета-версии (structured-outputs-2025-11-13) и параметр output_format продолжат работать в течение переходного периода. Примеры кода с обновлённой формой API см. ниже.

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

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

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

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

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

JSON-выводы

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

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

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

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

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

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

Определите вашу JSON-схему
Создайте JSON-схему, описывающую структуру, которой должен следовать Claude. Схема использует стандартный формат JSON Schema с некоторыми ограничениями (см. Ограничения JSON Schema).
Добавьте параметр output_config.format
Включите параметр output_config.format в ваш API-запрос с type: "json_schema" и определением вашей схемы.
Разберите ответ
Ответ Claude будет представлять собой валидный JSON, соответствующий вашей схеме, возвращённый в response.content[0].text.

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

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

Вспомогательные методы SDK (такие как .parse() и интеграция с Pydantic/Zod) по-прежнему принимают output_format в качестве удобного параметра. SDK обрабатывает преобразование в output_config.format внутренне. В примерах ниже показан синтаксис вспомогательных методов SDK.

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

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

Python: модели Pydantic с client.messages.parse()
TypeScript: схемы Zod с zodOutputFormat()
Java: обычные Java-классы с автоматическим выводом схемы через outputFormat(Class<T>)
Ruby: классы Anthropic::BaseModel с output_config: {format: Model}
C#, Go, PHP: сырые JSON-схемы, передаваемые через output_config

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

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

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

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

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

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

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

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

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

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

Валидировать параметры инструментов
Строить агентные рабочие процессы
Обеспечить типобезопасные вызовы функций
Обрабатывать сложные инструменты с вложенными свойствами

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

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

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

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

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

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

Формат ответа: Блоки использования инструментов с валидированными входными данными в response.content[x].input

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Гарантии:

input инструмента строго следует input_schema
name инструмента всегда валидно (из предоставленных инструментов или серверных инструментов)

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

Определите схему вашего инструмента
Создайте JSON-схему для input_schema вашего инструмента. Схема использует стандартный формат JSON Schema с некоторыми ограничениями (см. Ограничения JSON Schema).
Добавьте strict: true
Установите "strict": true как свойство верхнего уровня в определении вашего инструмента, рядом с name, description и input_schema.
Обработайте вызовы инструментов
Когда Claude использует инструмент, поле input в блоке tool_use будет строго следовать вашей input_schema, а name всегда будет валидным.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вывод упорядочит свойства следующим образом:

name (обязательное, в порядке схемы)
email (обязательное, в порядке схемы)
notes (необязательное, в порядке схемы)
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:

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

Эти ограничения применяются к совокупному итогу по всем строгим схемам в одном запросе. Например, если у вас 4 строгих инструмента с 6 необязательными параметрами каждый, вы достигнете лимита в 24 параметра, даже если ни один отдельный инструмент не кажется сложным.

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

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

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

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

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

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

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

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

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

Информацию о праве на ZDR для всех функций см. в разделе API и хранение данных.

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

Работает с:

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

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

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

Область действия грамматики: Грамматики применяются только к прямому выводу Claude, но не к вызовам инструментов, результатам инструментов или тегам размышлений (при использовании Расширенного мышления). Состояние грамматики сбрасывается между секциями, позволяя Claude свободно думать, при этом всё равно создавая структурированный вывод в финальном ответе.

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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
        }
      }
    }
  }'

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-6",
    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)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Help me plan a trip to Paris for next month"}
    ],
    # JSON outputs: structured response format
    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: guaranteed tool parameters
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

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

JSON-выводы

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

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

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

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

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

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

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

Извлечение данных

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

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

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

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

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

Валидированные входные данные инструментов

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

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

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

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

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

Поддерживаемые функции

Не поддерживается

Поддержка паттернов (regex)

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

Некорректные выводы

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

Явные ограничения

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

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

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

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

Классификация

Форматирование ответов API

Агентный рабочий процесс с несколькими валидированными инструментами