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

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

• Выходные данные JSON (output_config.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" \
  -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
        }
      }
    }
  }'

Формат ответа: Корректный 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.messages.create(
    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": transform_schema(ContactInfo),
        }
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
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)

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

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

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

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

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

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

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

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" \
  -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.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.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
        }
    }]
)

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

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

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

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

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

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

• Ваше количество входных токенов будет немного выше
• Внедрённая подсказка стоит вам токенов, как и любая другая системная подсказка
• Изменение параметра output_config.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:

"Слишком много рекурсивных определений в схеме"

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

"Схема слишком сложна"

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

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

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

Работает с:

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

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

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