Scegliere un modello Claude
Il compromesso Opus/Sonnet/Haiku e come scegliere — senza tirare a indovinare.
Token, contesto e prezzi
Conta correttamente i token, max_tokens contro finestra di contesto e come stimare il costo.
La tua prima chiamata API
Installa l'SDK, autenticati ed esegui una chiamata reale a Claude in Python, TypeScript o cURL.
API Version 2026-10-21 — la prima versione con breaking change in tre anni
L'header anthropic-version di Claude è cambiato per la prima volta dal 2023. Cosa si rompe, perché è il tuo package manager a decidere quando la adotti e l'ordine esatto di aggiornamento.
Streaming e conversazioni multi-turno
Esegui lo streaming delle risposte e gestisci la cronologia su un'API stateless.
Uso degli strumenti / Function calling
Definisci gli strumenti, esegui il loop agentico e gestisci i risultati — comprese le tre regole sulla forma dei messaggi che causano i 400, e perché tool_choice "any" e "tool" ora danno errore sui modelli Claude più recenti.
Code Execution Tool — Bash, file e Python sandboxati
La sandbox server-side di Anthropic permette a Claude di eseguire Bash, editare file e eseguire Python — con 5 GiB di RAM, riuso del container per 30 giorni, e un free tier mensile di 1.550 ore. Le tre versioni del tool, cosa aggiunge ognuna, quando è gratis, e la gotcha di cattura file che nessuno documenta.
Vision, PDF e input di file
Invia immagini e documenti e riutilizza gli upload tramite file_id.
Output strutturato
Ottieni JSON conforme a uno schema su cui puoi fare affidamento — non il prompt-e-prega.
Extended Thinking ed Effort
Ragionamento adattivo e il controllo dell'effort — scegliere la profondità in base al carico di lavoro.
Regolare l'effort: 5 livelli, default per modello e la trappola della cache
Il parametro effort di luglio 2026 ha cinque livelli — low, medium, high, xhigh, max — e vive dentro output_config, non al livello principale. Influisce sulle chiamate agli strumenti (non solo sul ragionamento), invalida la prompt cache se cambiato a metà conversazione, e ogni modello ha un punto di partenza consigliato diverso. La guida pratica alla regolazione.
Il tool advisor: Sonnet lavora, Fable pensa
Il server-tool advisor (beta advisor-tool-2026-03-01) permette a un modello executor veloce di consultare un modello più forte a metà turno. Reference completa dei campi, la trappola del conteggio token che quasi tutti gli integratori si perdono, la matrice di abbinamento dei modelli e i prompt esatti che Anthropic usa in produzione.
Task Budget — cap token consultivi che fanno finire gli agenti con grazia
La beta Messages-API di marzo 2026 dà a Claude un budget di token per l'intero loop agentico — thinking, tool call, tool result, output — così che gli agenti long-running si auto-regolino e chiudano puliti invece di scappare via. Come funziona il countdown, perché è consultivo non applicato, e come dimensionarlo così che non causi comportamento refusal-like.
Prompt Caching e Ottimizzazione dei Costi
Riutilizza un prefisso di prompt stabile per ridurre costo e latenza — e l'insidia che lo rompe.
Diagnostica della cache — scopri esattamente perché la cache non ha funzionato
Smetti di tirare a indovinare sul perché cache_read_input_tokens è zero. L'API ti dice quale parte del prompt è divergente, e di quanti token.
Message Batches — job asincroni al 50% di sconto
Dimezza il costo e aumenta il throughput spostando il lavoro bulk sulla Batches API asincrona — con le insidie che fregano quasi tutti.
Messaggi di sistema a metà conversazione
Guida una sessione agentica lunga senza far esplodere la prompt cache — il nuovo ruolo system che puoi accodare dopo qualsiasi turno utente.
Modifiche ai Tool a Metà Conversazione
Aggiungi e ritira tool tra un turno e l'altro senza invalidare la prompt cache — la beta di Opus 5 che chiude la tassa nascosta più pesante delle sessioni agent lunghe.
Costruire agenti sull'API
Chiamata singola vs workflow vs agente personalizzato — il test decisionale e la progettazione del loop.
Agent gestiti
Loop di agent ospitato da Anthropic: agent vs sessioni, ambienti, memoria, vault e deployment pianificati (cron).
Memory Store per Managed Agents
La beta di luglio 2026 — memoria persistente server-side che si monta nella sandbox dei Managed Agents, con versioning, audit trail e redaction.
Budget di sessione per Managed Agents
La beta di agosto 2026 — tetti hard in dollari su una sessione di Managed Agents, applicati alle tariffe di listino pubblico, con lo stop reason budget_reached, l'overshoot da una richiesta e il modello pausa-e-riprendi.
Restrizioni di dominio per Managed Agents
La beta del 26 agosto 2026 — allowed_domains, blocked_domains, max_content_tokens e user_location su web_search e web_fetch dentro Managed Agents. Regole di formato, semantica multiagent, update mid-session, e l'errore url_not_allowed.
Cowork e team di agent
Lo spazio di lavoro desktop agentico e la collaborazione multi-agent come prodotti.
MCP e collegamento agli strumenti
Chiama server MCP remoti direttamente dalla Messages API — la forma della richiesta, allowlist e denylist, caricamento differito e i limiti che fanno male in produzione.
MCP 2026-07-28: la specifica stateless
La più grande revisione di MCP dal lancio: la sessione sparisce, ogni richiesta si autodescrive, e qualsiasi istanza del server può rispondere a qualsiasi chiamata. Cosa è cambiato davvero il 28 luglio 2026, e come migrare senza rompere i server di oggi.
MCP Apps: UI interattive dentro una tool call
MCP Apps (SEP-1865) permette a un server MCP di inviare una UI HTML che il client renderizza in un iframe sandboxed — con ogni azione che passa comunque per il normale audit path JSON-RPC. Cosa dice davvero la spec, cosa costruirci e cosa rifiutarsi di costruire.
MCP Tasks: lavoro long-running senza sessione
La spec stateless MCP del 2026-07-28 ha eliminato la sessione — e allora come modelli un job CI da 20 minuti, un import batch o un gate di approvazione umana? Con l'estensione ufficiale Tasks (SEP-2663). Lifecycle completo, protocollo wire, migrazione dalla vecchia Tasks API sperimentale e i pattern di polling/notifica che funzionano davvero in produzione.
Playwright MCP: la guida pratica approfondita (2026)
Playwright MCP di Microsoft è oggi il server MCP #1 al mondo — davanti a GitHub e Figma. Il dettaglio che quasi nessuno spiega: la modalità di default con accessibility snapshot non è solo più veloce della vision, è un paradigma di automazione completamente diverso. Profili, capability opt-in, la modalità estensione browser che si aggancia al tuo Chrome reale, la battaglia sul costo in token contro Playwright-as-a-Skill, e la linea di sicurezza da non superare.
Sicurezza, rifiuti e fallback
Gestisci i rifiuti con eleganza e distinguili dai blocchi dei classificatori.
Fallback lato server e Credito di fallback
La beta di Opus 5 che trasforma un rifiuto di Fable 5 / Opus 5 in una risposta normale dentro una singola chiamata API — più il token di credito che ti evita di pagare due volte la prompt cache al retry.
Errori, rate limit e affidabilità
La mappa degli errori, i retry con backoff, i tier di rate limit e la migrazione dei modelli.
Memoria e Context Editing
Dai agli agenti una memoria persistente e un contesto auto-potato — il memory tool lato client più il context editing che cancella i risultati degli strumenti ormai obsoleti per sopravvivere alle esecuzioni lunghe.
Compaction della conversazione — riassumi la cronologia lato server e vai avanti
La Messages API può riassumere una conversazione in un unico blocco firmato che rimandi indietro al posto dei messaggi che sostituisce. Le quattro varianti (on-demand, keep-tail, in background, a soglia), le regole dello scambio, i due errori che falliscono in silenzio con HTTP 200, e ciò che un riassunto non può mai portarsi dietro.
Tool Search e Deferred Loading
Scalare a migliaia di tool senza gonfiare il contesto: come funzionano davvero defer_loading e il tool di ricerca, i cinque errori 400 che producono e perché il corpo della richiesta non diventa più piccolo.
Message Threads — Invia solo il nuovo turno
La Messages API può tenere la conversazione sul server e farti inviare a ogni turno solo i nuovi messaggi. Cosa fa risparmiare davvero (byte e latenza, non token), il percorso di replay da costruire prima del rilascio, i tre gruppi di campi e il limite di 4 breakpoint di cache.
Programmatic Tool Calling
Lascia che Claude chiami i tuoi tool da Python dentro la sandbox di code execution — meno round-trip e risultati intermedi fuori dal contesto.
L'Admin API: automatizza la tua org Claude
La guida operativa alla Admin API di Anthropic — elenca i membri, invita utenti, gestisci gruppi RBAC, esegui offboarding puliti. Console + Claude Enterprise, con le insidie del seat-pool e dell'SSO che fanno inciampare i team veri.
Osservabilità degli agenti: tracciare un agente che non puoi riprodurre
Un'esecuzione di agente è una traccia distribuita non deterministica, quindi non puoi fare debug rieseguendola — devi averla registrata. Questa pagina spiega cosa registrare: le forme degli span OpenTelemetry GenAI (e perché ogni attributo gen_ai.* è ancora 'Development'), i nomi esatti di metriche ed eventi di Claude Code, il request-id che collega la tua traccia al supporto Anthropic e le tre trappole di privacy nella telemetria degli agenti.
Tracing OpenTelemetry di prima parte: due percorsi, una sola traccia
Da ottobre 2026 la Claude API e il Claude SDK emettono da soli span OpenTelemetry, senza strumentazione scritta a mano. Ma i due percorsi si sovrappongono, e sommarli entrambi raddoppia i tuoi numeri sui token. Questa pagina copre la configurazione di ciascuno, l'unica regola che mantiene onesti i conteggi dei token, il flag di traceparent che cancella in silenzio le tue tracce e le regole di consegna che disattivano una destinazione dopo 24 ore.
L'API Usage & Cost Analytics: attribuire ogni dollaro
La guida pratica all'API Usage and Cost Analytics di Claude — la beta che ha sostituito gli endpoint legacy usage_report e cost_report. Forma delle righe, il limite di cinque dimensioni, la semantica degli actor, la trappola dei centesimi (errore di 100 volte), le regole di freschezza dei dati che rompono le dashboard ingenue e la tabella di migrazione dal legacy.
Inference Hooks: DLP inline per Claude Enterprise
La guida operativa agli Inference Hooks di Claude Enterprise — il webhook HTTPS che consente al tuo server DLP di autorizzare o negare ogni prompt su chat, Claude Code e Cowork, prima che il modello lo veda. Spec completa, schema dei verdetti, firma, playbook di rollout.
Profili utente ed enforcement: non lasciare che un cliente faccia bannare l'intera organizzazione
La guida per l'operatore ai profili utente della Claude API — attribuisci ogni richiesta a un cliente finale così che una restrizione di sicurezza o un ban ricada su un solo profilo invece che sull'intera organizzazione. Riferimento completo dei campi, i quattro valori di enforcement_status, lo schema delle azioni enac_, i webhook dell'organizzazione e il ciclo di polling che serve perché la consegna degli eventi non è ancora attiva.