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

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

• JSON выходные данные (output_format): Получайте ответ Claude в определённом формате JSON
• Строгое использование инструментов (strict: true): Гарантируйте проверку схемы для имён инструментов и входных данных

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

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

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

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

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

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

JSON выходные данные

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

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

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

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" \
  -H "anthropic-beta: structured-outputs-2025-11-13" \
  -d '{
    "model": "claude-sonnet-4-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": {
      "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
      }
    }
  }'

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

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

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

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

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

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

Для разработчиков Python и TypeScript вы можете использовать знакомые инструменты определения схемы, такие как Pydantic и Zod, вместо написания необработанных JSON схем.

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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

Python: client.beta.messages.parse() (Рекомендуется)

Метод parse() автоматически преобразует вашу модель Pydantic, проверяет ответ и возвращает атрибут parsed_output.

Python: вспомогательная функция transform_schema()

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

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

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

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

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

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

Типичные варианты использования

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

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

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

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

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

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

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

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

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

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" \
  -H "anthropic-beta: structured-outputs-2025-11-13" \
  -d '{
    "model": "claude-sonnet-4-5",
    "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.content[x].input

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

Гарантии:

• Входные данные инструмента input строго следуют input_schema
• Имя инструмента name всегда корректно (из предоставленных инструментов или серверных инструментов)

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

Типичные варианты использования

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

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

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

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

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
    # JSON outputs: structured response format
    output_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
        }
    }]
)

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

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

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

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

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

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

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

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

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

Недействительные выходные данные

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

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

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

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

Достигнут лимит токенов (stop_reason: "max_tokens")

Если ответ обрезан из-за достижения лимита max_tokens:

• Ответ будет иметь stop_reason: "max_tokens"
• Выходные данные могут быть неполными и не соответствовать вашей схеме
• Повторите попытку с более высоким значением max_tokens, чтобы получить полные структурированные выходные данные

Ошибки проверки схемы

Если ваша схема использует неподдерживаемые функции или слишком сложна, вы получите ошибку 400:

"Too many recursive definitions in schema"

• Причина: Схема имеет чрезмерные или циклические рекурсивные определения
• Решение: Упростите структуру схемы, уменьшите глубину вложенности

"Schema is too complex"

• Причина: Схема превышает пределы сложности
• Решение: Разбейте на меньшие схемы, упростите структуру или уменьшите количество инструментов, отмеченных как strict: true

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

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

Работает с:

• Пакетная обработка: Обрабатывайте структурированные выходные данные в масштабе со скидкой 50%
• Подсчёт токенов: Подсчитывайте токены без компиляции
• Потоковая передача: Потоковая передача структурированных выходных данных как обычных ответов
• Комбинированное использование: Используйте JSON выходные данные (output_format) и строгое использование инструментов (strict: true) вместе в одном запросе

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

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