--- title: Skill Claude API url: https://platform.claude.com/docs/it/agents-and-tools/agent-skills/claude-api-skill description: Una Agent Skill open-source che fornisce a Claude materiale di riferimento aggiornato sull'API, documentazione degli SDK e best practice per creare applicazioni con la Claude API e Claude Managed Agents. --- La skill `claude-api` è una [Agent Skill](https://platform.claude.com/docs/it/agents-and-tools/agent-skills/overview) open-source che fornisce a Claude materiale di riferimento dettagliato e aggiornato per creare applicazioni su due superfici Anthropic: * **Messages API:** La superficie principale per richieste singole, chat in streaming, "tool use" (uso degli strumenti), elaborazione batch, "prompt caching" (cache dei prompt), output strutturati e loop di agenti personalizzati. * **Claude Managed Agents (beta):** Una superficie ospitata da Anthropic per agenti stateful gestiti lato server, con esecuzione degli strumenti ospitata da Anthropic, configurazioni degli agenti persistenti e sandbox per sessione. Copre otto linguaggi di programmazione sia per la Messages API sia per Managed Agents: Python, TypeScript, C#, Go, Java, PHP, Ruby e cURL. La skill è inclusa in [Claude Code](https://code.claude.com/docs/en/overview) ed è disponibile anche nel [repository open-source delle skill di Anthropic](https://github.com/anthropics/skills), da cui puoi installarla in qualsiasi ambiente che supporti le Agent Skills. La skill usa la ["progressive disclosure" (divulgazione progressiva)](https://platform.claude.com/docs/it/agents-and-tools/agent-skills/overview#how-skills-work) per mantenere efficiente il contesto: Claude carica solo la documentazione pertinente al linguaggio del tuo progetto, alla superficie (Messages API o Managed Agents) e all'attività specifica in corso (uso degli strumenti, streaming, batch e così via), invece di caricare tutto in una volta. ## Cosa fornisce la skill Quando viene attivata, la skill fornisce a Claude: **Per la Messages API:** * **Documentazione degli SDK specifica per linguaggio:** installazione, avvio rapido, pattern comuni e gestione degli errori per il linguaggio del tuo progetto * **Indicazioni sull'uso degli strumenti:** esempi specifici per linguaggio e [fondamenti concettuali](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview) per il "function calling" (chiamata di funzioni), incluso il tool runner beta dove disponibile * **Pattern di streaming:** dettagli di implementazione per creare interfacce di chat e gestire la visualizzazione incrementale * **Elaborazione batch:** elaborazione batch offline al 50% del costo * **Cache dei prompt:** progettazione per la stabilità del prefisso, posizionamento dei breakpoint e verifica degli invalidatori silenziosi * **Migrazione dei modelli:** Indicazioni passo passo per migrare a modelli Claude più recenti (incluse le modifiche incompatibili e i cambiamenti di comportamento su [Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Sonnet 5.5](https://platform.claude.com/docs/it/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5), [Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/migration-guide), e [Claude Fable 5.1](https://platform.claude.com/docs/it/models/fable-5-1/migration-guide)) * **Migrazione al ragionamento preservato:** Individuazione, misurazione e correzione delle modifiche alla cronologia che invalidano i blocchi `thinking`, disponibile tramite il sottocomando `/claude-api preserved-thinking-migration` * **Informazioni sui modelli attuali:** ID dei modelli, dimensioni della "context window" (finestra di contesto) e prezzi * **Errori comuni:** indicazioni dettagliate per evitare gli errori frequenti durante l'integrazione con l'API **Per Managed Agents (beta):** * **Flusso di onboarding:** Una procedura guidata basata su un'intervista per configurare un nuovo Managed Agent da zero, disponibile tramite il sottocomando `/claude-api managed-agents-onboard` * **Documentazione Managed Agents specifica per linguaggio:** Creazione di agenti persistenti, avvio di sessioni, streaming di eventi e gestione delle conferme degli strumenti per Python, TypeScript, C#, Go, Java, PHP, Ruby e cURL * **Pattern client:** Riconnessione dello stream senza perdite, gate queued/processed basato su `processed_at`, gestione delle interruzioni, insidie del montaggio dei file e gestione delle credenziali * **Vincoli di deployment:** Managed Agents è disponibile solo sulla Claude API e su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws) (non su Amazon Bedrock, Google Cloud o Microsoft Foundry). La skill indirizza gli altri deployment verso la Messages API e l'uso degli strumenti. ## Quando si attiva la skill La skill si attiva in due modi: **L'attivazione automatica** avviene quando: * Il tuo codice importa un SDK Anthropic (`anthropic` per Python, `@anthropic-ai/sdk` per TypeScript/JavaScript) * Chiedi a Claude di aiutarti a creare, eseguire il debug o ottimizzare qualcosa con la Claude API, un SDK Anthropic o Managed Agents * Aggiungi, modifichi o regoli una funzionalità di Claude in un file (cache dei prompt, ragionamento adattivo, compattazione, uso degli strumenti, batch, file, citazioni, memoria) o un riferimento a un modello **L'invocazione manuale** avviene digitando `/claude-api` (con un sottocomando o testo libero opzionale) in qualsiasi ambiente in cui la skill è installata. La skill non si attiva per attività di programmazione generiche, lavoro di ML/data science o codice che importa altri SDK di IA (come OpenAI). ## Linguaggi supportati La skill rileva automaticamente il linguaggio del tuo progetto esaminando i file del progetto (ad esempio, `requirements.txt` per Python, `tsconfig.json` per TypeScript, `go.mod` per Go) e carica la documentazione appropriata. | Linguaggio | SDK Messages API | Tool runner | Managed Agents | | ---------- | ---------------- | ----------- | -------------- | | Python | Sì | Sì (beta) | Sì (beta) | | TypeScript | Sì | Sì (beta) | Sì (beta) | | C# | Sì | Sì (beta) | Sì (beta) | | Go | Sì | Sì (beta) | Sì (beta) | | Java | Sì | Sì (beta) | Sì (beta) | | PHP | Sì | Sì (beta) | Sì (beta) | | Ruby | Sì | Sì (beta) | Sì (beta) | | cURL | Sì | N/D | Sì (beta) | Se il tuo progetto usa più linguaggi, Claude chiede quale si applica. Per i linguaggi non supportati (Rust, Swift, C++), la skill fornisce esempi cURL/HTTP raw. ## Come usare la skill ### In Claude Code (inclusa) La skill è distribuita con [Claude Code](https://code.claude.com/docs/en/overview) e non richiede installazione. Quando chiedi a Claude di aiutarti a creare qualcosa con la Claude API, o quando il tuo progetto importa già un SDK Anthropic, la skill si attiva automaticamente. Puoi anche invocarla direttamente: Usa questa skill in Claude Code ```text /claude-api ``` Per saperne di più su come funzionano le skill incluse in Claude Code, consulta la [documentazione delle skill di Claude Code](https://code.claude.com/docs/en/skills#bundled-skills). ### Dal repository delle skill Il codice sorgente della skill è disponibile nel [repository delle skill di Anthropic](https://github.com/anthropics/skills). Puoi installarla usando il comando `npx`: ```bash npx skills add https://github.com/anthropics/skills --skill claude-api ``` Oppure chiedi a Claude Code di installarla come [plugin di Claude Code](https://code.claude.com/docs/en/plugins): Lascia che Claude Code la installi per te ```text Installa il plugin claude-api dal marketplace di plugin anthropics/skills ``` ```text wrap /plugin marketplace add anthropics/skills /plugin install claude-api@anthropic-agent-skills ``` ## Migrare a un modello Claude più recente La skill Claude API può eseguire migrazioni di modelli Claude su un'intera base di codice. Invocala direttamente con `/claude-api migrate`: Lascia che Claude Code migri il tuo codice per te ```text /claude-api migrate questo progetto all'ultimo modello Claude Opus ``` Puoi anche passare subito un ambito specifico per saltare la domanda di conferma dell'ambito: Lascia che Claude Code migri il tuo codice per te ```text /claude-api migrate tutto il contenuto di src/ all'ultimo modello Claude Opus ``` Lascia che Claude Code migri il tuo codice per te ```text /claude-api migrate apps/api.py e apps/worker.py all'ultimo modello Claude Opus ``` Quando l'ambito è ambiguo (ad esempio, un semplice `/claude-api migrate to claude-opus-5-5`), la skill ti chiede di scegliere tra l'intera directory di lavoro, una sottodirectory specifica o un elenco esplicito di file prima di modificare qualsiasi file. Questo vale sia per i chiamanti della Messages API sia per quelli di Managed Agents. La skill gestisce: * **Sostituzione degli ID dei modelli**, incluse le costanti tipizzate degli SDK (`Model.CLAUDE_OPUS_4_8` → `Model.CLAUDE_OPUS_5_5`) in tutti i linguaggi supportati, classificando ogni file come chiamante, definitore del modello o riferimento a stringa opaca prima di modificarlo * **Rilevamento della piattaforma cloud**, preservando i formati degli ID dei modelli specifici della piattaforma (ad esempio, il prefisso `anthropic.` su Amazon Bedrock) e saltando le modifiche per le funzionalità non disponibili sulle piattaforme gestite dai partner * **Modifiche incompatibili ai parametri**, come la rimozione di `temperature`, `top_p` e `top_k` per Claude Opus 4.8 e Claude Opus 4.7, e la conversione di `thinking: {type: "enabled", budget_tokens: N}` in `thinking: {type: "adaptive"}` * **Sostituzione del prefill**, convertendo i pattern di prefill dei messaggi dell'assistente in [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) dove applicabile * **Pulizia degli header beta**, rimuovendo gli header beta non richiesti dal modello di destinazione (ad esempio, `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14`) e tornando da `client.beta.messages.create()` (go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; csharp: `client.Beta.Messages.Create()`; php: `$client->beta->messages->create()`) a `client.messages.create()` (go: `client.Messages.New()`; java: `client.messages().create()`; csharp: `client.Messages.Create()`; php: `$client->messages->create()`) * **Calibrazione dell'effort**, raccomandando un valore iniziale di `output_config.effort` per il modello di destinazione (ad esempio, il valore predefinito `high` su Claude Opus 5, e `xhigh` per i casi d'uso di programmazione e agentici su Claude Opus 4.8 e Claude Opus 4.7) * **Regolazione del comportamento dei prompt**, segnalando i prompt relativi al controllo della lunghezza, all'attivazione degli strumenti, ai subagenti e al rispetto delle istruzioni che potrebbero comportarsi diversamente sul modello di destinazione * **Gestione dei valori predefiniti silenziosi**, riattivando il riepilogo del ragionamento (`thinking.display: "summarized"`) quando il ragionamento viene mostrato agli utenti su Claude Opus 4.8 e Claude Opus 4.7 * **Configurazione del fallback in caso di rifiuto**, aggiungendo la gestione di `stop_reason: "refusal"` prima di leggere il contenuto della risposta e configurando un [percorso di nuovo tentativo di fallback](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback) quando la destinazione è Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5 o Claude Sonnet 5.5 (il parametro lato server `fallbacks`, tipicamente nella sua modalità `"default"`, il middleware di fallback in caso di rifiuto dell'SDK o un nuovo tentativo con credito di fallback), e aggiornando il codice di fallback scritto per forme di anteprima precedenti Durante le modifiche, la skill spiega inline ogni cambiamento e la sua motivazione. Al termine, produce una checklist di elementi che richiedono verifica manuale (tipicamente test di integrazione, regolazione dei prompt di controllo della lunghezza e ridefinizione delle baseline di costo e "rate limit" (limite di velocità)). Per l'elenco completo delle modifiche specifiche per modello applicate dalla skill, consulta [Migrazione a Claude Opus 5.5 da Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Migrazione a Claude Opus 5.5 da Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), [Migrazione a Claude Sonnet 5.5 da Claude Sonnet 5](https://platform.claude.com/docs/it/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5), [guida alla migrazione a Claude Haiku 5.5](https://platform.claude.com/docs/it/models/haiku-5-5/migration-guide), e [guida alla migrazione a Claude Fable 5.1 e Claude Mythos 5.1](https://platform.claude.com/docs/it/models/fable-5-1/migration-guide). ## Verificare un'integrazione per il ragionamento preservato Il [ragionamento preservato](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking) mantiene valido un blocco `thinking` solo finché il prompt `system`, i `tools` e i messaggi che lo precedono rimangono invariati. Per trovare e correggere i punti in cui il tuo codice modifica quella cronologia, apri il repository che costruisce le tue richieste e invoca il sottocomando `preserved-thinking-migration`: Lascia che Claude Code verifichi il tuo codice per te ```text /claude-api preserved-thinking-migration ``` La skill procede in cinque passaggi: 1. **Ambito:** Verifica se la tua integrazione è interessata, quindi invia tre richieste di test per confermare che l'API segnali una modifica intenzionale. 2. **Individuazione:** Acquisisce alcune delle tue sessioni multi-turno, confronta le richieste consecutive ed elenca ogni punto in cui il tuo codice modifica il prefisso. 3. **Misurazione:** Riproduce le sessioni con `"drop_block"` e riporta quali conversazioni perdono blocchi `thinking`, a quale turno e perché. 4. **Correzione:** Sostituisce una modifica alla volta con il pattern corrispondente in [Apportare modifiche senza modificare il prefisso](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#replace-prefix-edits), e misura di nuovo dopo ogni cambiamento. 5. **Report:** Riepiloga ogni causa, la modifica apportata per essa e i conteggi prima e dopo. Se il tuo progetto dispone di una valutazione, la skill confronta anche i punteggi e l'utilizzo dei token con e senza i blocchi `thinking` scartati. Le richieste di test e le riproduzioni sono vere richieste alla Messages API, fatturate alle tariffe normali del modello. Ogni riproduzione richiede solo pochi token di output e imposta `tool_choice` su `none`, quindi nessuno strumento viene eseguito. La skill indica il costo e chiede la tua approvazione prima di inviarle. ## Configurare un Managed Agent Per creare lo scaffolding di un nuovo Managed Agent da zero, invoca il sottocomando `managed-agents-onboard`: Lascia che Claude Code configuri il tuo agente per te ```text /claude-api managed-agents-onboard ``` La skill conduce un'intervista che ti guida attraverso il modello mentale di Managed Agents (configurazioni degli Agent rispetto alle Session), crea un template di configurazione dell'agente, configura ambienti e strumenti, imposta il loop della sessione e genera codice eseguibile per il tuo linguaggio. La skill copre anche il flusso obbligatorio **Agent (una volta) → Session (ogni esecuzione)**: `model`, `system` e `tools` risiedono sull'agente, mai sulla sessione, e gli agenti dovrebbero essere creati una sola volta e referenziati tramite ID. Managed Agents richiede l'header beta `managed-agents-2026-04-01`, che l'SDK imposta automaticamente per tutte le chiamate `client.beta.agents.*`, `client.beta.environments.*`, `client.beta.sessions.*` e `client.beta.vaults.*`. ## Esempi di utilizzo Ecco alcuni esempi di attività che la skill aiuta Claude a gestire: **Creare un'applicazione di chat:** Lascia che Claude Code la crei per te ```text Crea un'interfaccia di chat in streaming con la Claude API in TypeScript ``` **Migrare un progetto esistente:** Lascia che Claude Code migri il tuo codice per te ```text /claude-api migrate questa base di codice all'ultimo modello Claude Opus e ricalibra l'effort ``` **Onboarding di un nuovo Managed Agent:** Lascia che Claude Code configuri il tuo agente per te ```text /claude-api managed-agents-onboard ``` In ogni caso, la skill carica la documentazione specifica per linguaggio pertinente e guida Claude nell'implementazione usando i pattern API attuali e le best practice. ## Prossimi passi Scopri come funzionano le Agent Skills e il modello di divulgazione progressiva Esplora gli SDK ufficiali di Anthropic per tutti i linguaggi supportati Esplora il repository pubblico delle skill di Anthropic su GitHub