3.7.4 · Features: caching, citations, thinking

Prompt caching

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    system=[
        {
            "type": "text",
            "text": CATALOGO_RICEFW_MERIDIANO,      # ~40 mil tokens, estável
            "cache_control": {"type": "ephemeral"},  # marca o fim do prefixo estável
        }
    ],
    messages=[{"role": "user", "content": pergunta}],  # varia a cada chamada
)

print(response.usage.cache_creation_input_tokens)  # gravou
print(response.usage.cache_read_input_tokens)      # leu (é o que você quer ver > 0)
print(response.usage.input_tokens)                 # pagou integral

Prefixo abaixo do mínimo não cacheia e não avisa — cache_creation_input_tokens volta zero e pronto.

O que destrói o cache sem avisar

A regra de arquitetura que resolve quase tudo: congele o system prompt e a lista de tools; ponha o que varia depois da última marcação. Data, modo, nome do usuário e contexto dinâmico vão para a mensagem do usuário, não para o system.

E o diagnóstico é sempre o mesmo: se cache_read_input_tokens fica zero entre chamadas que deveriam compartilhar prefixo, compare os bytes das duas requisições. O invalidador está lá.

Citations

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {"type": "text", "media_type": "text/plain", "data": TEXTO_FS_17},
                "title": "FS RICEFW 17 — Relatório de Pendências de Faturamento",
                "citations": {"enabled": True},
            },
            {"type": "text", "text": "Quais regras de alçada esta FS define para liberação?"},
        ],
    }],
)

for bloco in response.content:
    if bloco.type == "text":
        print(bloco.text)
        for c in (bloco.citations or []):
            print(f"    ↳ {c.document_title}: “{c.cited_text}”")

Como funciona:

• citations: {"enabled": True} vai em cada bloco document — todos ou nenhum.
• A resposta vem quebrada em vários blocos de texto; os que se apoiam numa fonte trazem um array citations.
• Cada citação tem cited_text, document_index, document_title e a localização: char_location para texto (índices de caractere) ou page_location para PDF (página, começando em 1).
• Incompatível com output_config.format — a combinação retorna 400.

Por que isso importa em consultoria: um entregável com citação é verificável pelo cliente sem confiar em você. A afirmação "a FS 17 exige dupla aprovação acima de 50 mil" vira "a FS 17 exige dupla aprovação acima de 50 mil — página 12, trecho citado". A segunda sobrevive a uma auditoria; a primeira sobrevive até alguém conferir.

E note a ligação com a aula 3.4.2: lá o problema era resumo fluente que omite. Citations é o mecanismo que ataca isso na origem — cada afirmação carrega o ponteiro para a fonte, e o revisor confere a fonte em vez de julgar a redação.

Thinking

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},        # low | medium | high | xhigh | max
    messages=[{"role": "user", "content": pergunta_dificil}],
)

Como escolher o effort:

Dois pontos de atenção:

• max_tokens limita raciocínio + resposta juntos. Com thinking ligado e teto apertado, você pode receber uma resposta quase toda de raciocínio e o texto final cortado. Em xhigh ou max, deixe folga real.
• O padrão de display mudou em relação a modelos anteriores. Interface que mostrava o raciocínio e agora mostra uma pausa longa e nada: falta display: "summarized".

Regra Wayon Entregável analítico produzido por API sobre documento de cliente — análise de escopo, leitura de contrato, comparação de especificações — vai com citations habilitado, e as citações vão junto na entrega. Sem citação, a análise é opinião com aparência de estudo. Aplicação que usa prompt caching sobre documento de cliente monitora cache_read_input_tokens: cache que nunca acontece é custo silencioso que aparece na fatura antes de aparecer no relatório.

📖 Prompt caching · Citations · Adaptive thinking