Middleware do SDK

O Claude SDK fornece um hook de "middleware" (intermediário), ou interceptor, que permite executar código antes de uma requisição ser enviada e depois que a resposta é recebida. Use middleware para preocupações transversais, como logging, retentativas personalizadas, anotação de requisições e tratamento de fallback em caso de recusa.

Cada middleware pode inspecionar ou substituir a requisição antes de chamar next(), e a resposta depois que next() retorna.

Registrando middleware

Cada middleware é uma função que recebe a requisição de saída e o próximo handler. Chame call_next(request) para encaminhar a requisição para o restante da cadeia (ou diretamente para o núcleo do SDK, se este for o último middleware) e retorne sua resposta. Tudo o que vem antes dessa chamada é executado na ida; tudo o que vem depois é executado na volta.

def logging_middleware(request: APIRequest, call_next: CallNext) -> APIResponse[Any]:
    # Antes da requisição
    print(f"-> {request.method} {request.url}")

    # Encaminha a requisição para o restante da cadeia
    response = call_next(request)

    # Depois da requisição
    print(f"<- {response.status_code}")

    return response


client = Anthropic(middleware=[logging_middleware])

Ordem dos middlewares

Quando você registra vários middlewares, eles são aplicados na ordem fornecida: o código "antes" do primeiro middleware é executado primeiro, e seu código "depois" é executado por último. Middlewares registrados no cliente são executados antes dos middlewares passados como opção por requisição.

No SDK Go, chamadas repetidas a option.WithMiddleware são concatenadas (primeiro as do cliente, depois as do método). Nos outros SDKs, passe um array; as entradas posteriores envolvem as internas.

Substituindo o cliente HTTP

O SDK também aceita um cliente HTTP personalizado (para configuração de proxy, TLS personalizado ou pool de conexões). Apenas um cliente HTTP é usado por cliente do SDK; defini-lo substitui o padrão. O cliente HTTP personalizado recebe as requisições depois que todos os middlewares foram executados.

Middleware integrado

O SDK inclui um middleware de fallback em caso de recusa que repete automaticamente, em um modelo de fallback, uma requisição que Claude recusa (stop_reason: "refusal"). Recusas e fallback lista os modelos cujos classificadores de segurança podem recusar requisições, e Detectar e repetir em um modelo de fallback aborda a configuração e exemplos por linguagem.