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

Структурированные выходные данные ограничивают ответы 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-5",
    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(next(block.text for block in response.content if block.type == "text"))

Формат ответа: валидный JSON, соответствующий вашей схеме, в текстовом блоке содержимого ответа

{
  "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-5",
    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.

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, [email protected], interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Прямой доступ к разобранному выводу
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# Сначала преобразуйте модель Pydantic в JSON-схему, затем трансформируйте
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# При необходимости измените схему
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)



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

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

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-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)



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



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

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

• Задержка первого запроса: при первом использовании конкретной схемы возникает дополнительная задержка на время компиляции грамматики
• Автоматическое кэширование: скомпилированные грамматики кэшируются на 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, чтобы получить полный структурированный вывод

Регистр значений перечислений

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



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

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

При превышении этих ограничений вы получите ошибку 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



Следующие шаги