JSON Schema: описываем структуры данных

JSON Schema — стандарт для описания структуры JSON. В Claude API используется для описания инструментов (tool use) — Claude знает какие параметры передавать.

Базовая структура

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "Название города"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Единицы измерения"
    }
  },
  "required": ["city"]
}

Типы данных

# string
{"type": "string", "description": "Текст"}

# number (int или float)
{"type": "number", "description": "Число"}

# integer (только целое)
{"type": "integer", "description": "Целое число"}

# boolean
{"type": "boolean", "description": "true или false"}

# array
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Список строк"
}

# object (вложенный)
{
    "type": "object",
    "properties": {
        "x": {"type": "number"},
        "y": {"type": "number"}
    },
    "required": ["x", "y"]
}

Инструмент Claude API

TOOLS = [
    {
        "name": "search_web",
        "description": "Ищет информацию в интернете. Используй для актуальных данных.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Поисковый запрос"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Максимум результатов (1-10)",
                    "default": 3
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "read_file",
        "description": "Читает содержимое локального файла",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Путь к файлу (абсолютный или ~)"
                }
            },
            "required": ["path"]
        }
    }
]

description важнее всего

Claude выбирает инструмент на основе description. Чем точнее описание — тем лучше агент выбирает нужный инструмент:

# Плохо
{"name": "weather", "description": "Погода"}

# Хорошо
{"name": "get_weather", "description": "Получает текущую погоду и прогноз для города. Используй когда пользователь спрашивает про погоду, температуру, осадки."}