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

Structured outputs (структурированные выводы) ограничивают ответы 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-4-8",
    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(response.content[0].text)

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

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

ant messages create \
  --transform 'content.0.text|@fromstr|{name,email}' \
  --format yaml <<'YAML'
model: claude-opus-4-8
max_tokens: 1024
messages:
  - role: user
    content: >-
      Extract contact info: John Smith, [email protected],
      interested in the Pro plan
output_config:
  format:
    type: json_schema
    schema:
      type: object
      properties:
        name: {type: string}
        email: {type: string}
        plan_interest: {type: string}
      required: [name, email, plan_interest]
      additionalProperties: false
YAML

name: John Smith
email: [email protected]



Как работает преобразование в 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-4-8",
    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-выводами



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