Middleware в SDK

Claude SDK предоставляет хук «middleware» (промежуточное ПО), или «interceptor» (перехватчик), который позволяет выполнять код до отправки запроса и после получения ответа. Используйте middleware для сквозных задач, таких как логирование, пользовательские повторные попытки, аннотирование запросов и обработка резервного переключения при отказах.

Каждое middleware может проверять или заменять запрос перед вызовом next(), а также ответ после возврата из next().

Регистрация middleware

Каждое middleware — это функция, которая получает исходящий запрос и следующий обработчик. Вызовите call_next(request), чтобы передать запрос дальше по цепочке (или непосредственно ядру SDK, если это последнее middleware), и верните его ответ. Всё, что находится до этого вызова, выполняется на пути туда; всё, что после, — на обратном пути.

def logging_middleware(request: APIRequest, call_next: CallNext) -> APIResponse[Any]:
    # Перед запросом
    print(f"-> {request.method} {request.url}")

    # Передать запрос дальше по цепочке
    response = call_next(request)

    # После запроса
    print(f"<- {response.status_code}")

    return response


client = Anthropic(middleware=[logging_middleware])

Порядок выполнения middleware

Когда вы регистрируете несколько middleware, они применяются в указанном порядке: код «до» первого middleware выполняется первым, а его код «после» — последним. Middleware, зарегистрированное на клиенте, выполняется раньше middleware, переданного в качестве параметра отдельного запроса.

В Go SDK повторные вызовы option.WithMiddleware объединяются (сначала клиентские, затем уровня метода). В остальных SDK передавайте массив; более поздние элементы оборачивают внутренние.

Замена HTTP-клиента

SDK также принимает пользовательский HTTP-клиент (для настройки прокси, пользовательского TLS или пула соединений). Для каждого клиента SDK используется только один HTTP-клиент; его установка заменяет клиент по умолчанию. Пользовательский HTTP-клиент получает запросы после выполнения всех middleware.

Встроенное middleware

SDK поставляется с middleware резервного переключения при отказах, которое автоматически повторяет запрос, отклонённый Claude (stop_reason: "refusal"), на резервной модели. В разделе Отказы и резервная обработка перечислены модели, классификаторы безопасности которых могут отклонять запросы, а в разделе Обнаружение и повтор на резервной модели описаны настройка и примеры для каждого языка.