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

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

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

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

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

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

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

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

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

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

1. 1

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

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

2. 2

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

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

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

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

Как работает преобразование в 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)

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

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

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

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

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

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

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

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

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

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 outputs (выходные данные 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,
            },
        }
    },
    # Strict tool use (строгое использование инструментов): гарантированные параметры инструментов
    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 автоматически получает дополнительную «system prompt» (системную подсказку), объясняющую ожидаемый формат вывода. Это означает:

• Количество ваших входных токенов немного выше
• Внедрённая подсказка стоит вам токенов, как и любая другая системная подсказка
• Изменение параметра 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": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

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

Невалидные выходные данные

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

Отказы (stop_reason: "refusal")

Claude сохраняет свои свойства безопасности и полезности даже при использовании структурированных выходных данных. Если Claude отказывается выполнить запрос по соображениям безопасности:

• Ответ имеет stop_reason: "refusal"
• Вы получите код состояния 200
• Вам будет выставлен счёт за сгенерированные токены
• Вывод может не соответствовать вашей схеме, поскольку сообщение об отказе имеет приоритет над ограничениями схемы

Свойство, запрашивающее размышления модели или пошаговые рассуждения, может привести к отказу 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:

Дополнительные внутренние лимиты

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

При превышении этих лимитов вы получите ошибку 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={...} в client.beta.messages.create() или count_tokens() и выдаёт TypeError. Вместо этого используйте output_config. Обновлённую форму API см. в разделе Использование необработанной JSON-схемы.

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

Подсказки и ответы обрабатываются с 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

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

Compatibility