Claude Sonnet 4: una guida pratica per sviluppatori

Anthropic ha recentemente lanciato gli aggiornati Claude Sonnet 4.5, Claude Agents SDK e Imagine with Claude.

Con il rilascio di Claude Sonnet 4, gli sviluppatori hanno ora accesso a nuove potenti funzionalità, tra cui esecuzione di codice nativa, una Files API flessibile e uso dinamico degli strumenti. Queste feature aprono possibilità entusiasmanti per creare applicazioni AI che vadano oltre le semplici interazioni testuali.

In questo tutorial, ti guiderò attraverso queste nuove funzionalità costruendo un agente basato su Python che può risolvere problemi di matematica avanzata direttamente dal terminale. Imparerai a usare il nuovo tool di esecuzione di codice nativo e la Files API.

Alla fine, avrai un agente funzionante basato su Claude Sonnet 4 per analizzare problemi, scrivere ed eseguire codice Python e generare visualizzazioni come quelle qui sotto.

Dai un’occhiata al repository GitHub di questo progetto per vedere tutto il codice per costruire l’applicazione.

Se stai iniziando ora a lavorare con LLM come Claude, questa roadmap per sviluppatori AI illustra strumenti, competenze e percorsi di apprendimento essenziali per iniziare.

Novità dell’API di Anthropic

Prima di entrare nel tutorial, vediamo tutte le nuove funzionalità rilasciate di recente e disponibili tramite l’API di Anthropic. Se le conosci già, puoi saltare avanti.

Secondo me l’intero annuncio di Claude 4 si può riassumere in questa immagine:

I modelli Claude 4 (Opus e Sonnet 4) superano la concorrenza nei task verificati di ingegneria del software con un margine significativo. Anthropic ha raggiunto questo traguardo introducendo alcuni cambiamenti importanti nel comportamento dei modelli:

1. Runtime lunghi: Entrambi i modelli supportano diverse ore di esecuzione continua per risolvere problemi con migliaia di passaggi.
2. Ragionamento esteso con uso di strumenti: Entrambi i modelli ora possono usare strumenti come la ricerca sul web durante il ragionamento esteso, permettendo a Claude di alternare tra ragionamento e uso di tool per migliorare le risposte.
3. Esecuzione parallela degli strumenti: I modelli possono ora usare più tool contemporaneamente invece che in sequenza.
4. Maggiore aderenza alle istruzioni: Una migliore “steerability” offre agli utenti maggior controllo sulle implementazioni e su come Claude risponde alle istruzioni.
5. Capacità di memoria migliorate: Con accesso a file locali, i modelli possono estrarre e salvare fatti chiave per mantenere continuità e costruire conoscenza tacita nel tempo.
6. Comportamenti di scorciatoia ridotti: Rispetto alle versioni precedenti, entrambi i modelli hanno il 65% di probabilità in meno di usare scorciatoie o cavilli per completare i task (vedi il post di annuncio completo per i dettagli).

Inoltre, nell’ambito dell’annuncio della famiglia di modelli Claude 4, Anthropic ha aggiunto quattro nuove funzionalità per creare agenti AI: lo strumento di esecuzione del codice, la Files API, il connettore MCP e il prompt caching esteso. Questi strumenti cambiano il modo in cui gli sviluppatori possono costruire applicazioni AI.

Code execution tool: esegui codice Python in modo sicuro

Il code execution tool permette a Claude di eseguire codice Python in un ambiente sandbox sicuro. Invece di limitarsi a suggerire codice, ora Claude può eseguirlo, analizzare i risultati e iterare sulle soluzioni.

Per usare il code execution tool, aggiungilo all’array tools e includi l’header beta richiesto:

from anthropic import Anthropic

# Initialize client with the code execution beta header
client = Anthropic(
   default_headers={
       "anthropic-beta": "code-execution-2025-05-22"
   }
)

# Send a request that triggers code execution
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": "Solve the quadratic equation 2x² + 5x - 3 = 0 and plot the parabola"
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Quando Claude esegue codice, la risposta contiene sia il codice generato sia i risultati dell’esecuzione. Ecco come analizzare le varie componenti:

# Parse the response to extract code and results
for item in response.content:
   if item.type == "server_tool_use":
       # This contains the actual Python code Claude wrote
       print(f"Code executed:\n{item.input['code']}")
   elif item.type == "code_execution_tool_result":
       # This contains the output from running the code
       print(f"Output:\n{item.content['stdout']}")
       if item.content.get('stderr'):
           print(f"Errors:\n{item.content['stderr']}")

Limitazioni della sandbox: L’ambiente di esecuzione del codice ha diverse restrizioni integrate per la sicurezza. Claude gira in un container isolato senza accesso a Internet, con risorse computazionali limitate (1 GB di RAM, 5 GB di spazio su disco e 1 CPU) e non può accedere al tuo file system locale. L’ambiente include preinstallate librerie popolari come numpy, pandas, matplotlib e scipy, ma non puoi installare pacchetti aggiuntivi durante l’esecuzione.

Files API: contesto file persistente per task complessi

La Files API ti permette di caricare documenti una sola volta e referenziarli in più conversazioni. Non serve più includere documenti di grandi dimensioni in ogni richiesta API.

Per prima cosa, carica il file sui server di Anthropic:

# Upload a file once - this stores it on Anthropic's servers
uploaded_file = client.beta.files.upload(
   file=open("sales_data.csv", "rb"),
   purpose="user_upload"
)
# The uploaded_file.id can now be referenced in multiple conversations

Una volta caricato, referenzia il file nelle chiamate API usando il content type container_upload:

# Reference the uploaded file in a conversation
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": [
           {"type": "text", "text": "Create a quarterly sales report from this data"},
           {"type": "container_upload", "file_id": uploaded_file.id}
       ]
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Quando Claude crea file durante l’esecuzione del codice (come grafici o dati elaborati), puoi estrarli e scaricarli:

# Extract file IDs of any files Claude created during execution
def extract_created_files(response):
   file_ids = []
   for item in response.content:
       if item.type == 'code_execution_tool_result':
           content = item.content
           if content.get('type') == 'code_execution_result':
               # Look for file objects in the execution results
               for file_obj in content.get('content', []):
                   if 'file_id' in file_obj:
                       file_ids.append(file_obj['file_id'])
   return file_ids

# Download any files Claude created
created_files = extract_created_files(response)
for file_id in created_files:
   file_content = client.beta.files.download(file_id)
   file_content.write_to_file(f"output_{file_id}.png")

Connettore MCP: collega Claude a qualsiasi workflow

Il connettore MCP porta il supporto al Model Context Protocol direttamente nell’API. Gli MCP consentono a Claude di connettersi a servizi esterni come database, API e strumenti di produttività senza codice di integrazione personalizzato.

In precedenza, collegarsi a server MCP richiedeva la creazione di un’infrastruttura client. Ora, puoi semplicemente fornire un URL di un server MCP remoto nella richiesta API e Claude scopre automaticamente gli strumenti disponibili, gestisce le connessioni e si occupa dell’autenticazione.

Questo apre l’accesso a un ecosistema in crescita di server MCP di aziende come Zapier e Asana, permettendoti di creare agenti che possono leggere il tuo calendario, aggiornare gli strumenti di project management o integrarsi con centinaia di altri servizi.

Primi passi con Claude Sonnet 4: panoramica del progetto e setup

Ora che abbiamo capito le nuove feature dell’API, costruiamo il nostro risolutore interattivo di problemi di matematica. Combinerà le capacità di esecuzione del codice di Claude con la gestione dei file per creare un assistente matematico completo.

La nostra applicazione accetterà domande di matematica in linguaggio naturale, eseguirà codice Python per risolverle, genererà visualizzazioni e salverà report completi.

Per un approccio strutturato alla creazione di progetti come questo, dai un’occhiata al percorso Developing AI Applications.

> Nota: Poiché interromperemo blocchi di codice lunghi con spiegazioni, l’indentazione potrebbe non essere del tutto accurata negli snippet. Per questo motivo, ti consigliamo di aprire il repo GitHub del progetto in una scheda separata mentre segui la guida.

Step 0: imposta l’ambiente del progetto Claude Sonnet 4

Prima di scrivere codice, impostiamo l’ambiente di sviluppo e le dipendenze.

Crea una nuova directory per il progetto e i file richiesti:

mkdir math-solver
cd math-solver
touch math_solver.py demo_problems.py requirements.txt README.md

Crea un file requirements.txt con le dipendenze necessarie:

anthropic>=0.42.0

Installa le dipendenze:

pip install -r requirements.txt

Imposta la tua chiave API di Anthropic come variabile d’ambiente:

export ANTHROPIC_API_KEY="your-api-key-here"

Step 1: progetta la struttura dell’applicazione

Iniziamo creando la struttura base della nostra classe MathSolver. Questa classe gestirà tutte le funzionalità principali: comunicazione con l’API, gestione dei file e interazione con l’utente.

Per prima cosa, impostiamo gli import e la struttura di base:

#!/usr/bin/env python3
"""
Interactive Math Problem Solver using Claude 4 Code Execution Tool

This application allows users to ask math questions in natural language,
gets solutions using Claude's code execution capabilities, and saves
both visualizations and detailed markdown reports.
"""

import os
import json
import datetime
from pathlib import Path
from typing import List, Dict, Any
from anthropic import Anthropic

Ora definiamo la struttura della classe principale:

class MathSolver:
   def __init__(self, api_key: str = None):
       """Initialize the Math Solver with Anthropic client."""
       # API setup and directory creation will go here
       pass

   def solve_problem(self, question: str) -> Dict[str, Any]:
       """Send a math question to Claude and get solution with code execution."""
       pass
Here are the methods for file and report handling:
def extract_files_from_response(self, response) -> List[str]:
       """Extract file IDs from Claude's response."""
       pass

   def download_files(self, file_ids: List[str]) -> List[str]:
       """Download files created by code execution to local storage."""
       pass

   def extract_code_blocks(self, response) -> List[str]:
       """Extract all code blocks from the response."""
       Pass

Infine, aggiungiamo la gestione della sessione e l’entry point:

def generate_markdown_report(self, result: Dict[str, Any], downloaded_files: List[str]) -> str:
       """Generate a comprehensive markdown report of the solution."""
       pass

   def run_interactive_session(self):
       """Run the main interactive session loop."""
       pass


def main():
   """Main entry point for the application."""
   pass

Questa struttura ci dà una roadmap chiara: inizializzazione, risoluzione dei problemi, gestione dei file, generazione del report e interazione con l’utente. Ogni metodo ha una responsabilità specifica nella pipeline di risoluzione dei problemi matematici.

Costruire un risolutore matematico con l’esecuzione di codice di Claude Sonnet 4

Ora implementiamo le funzionalità core usando il tool di esecuzione del codice di Claude e le risposte in streaming.

Step 2: inizializza Claude con header API sicuri

Implementiamo il metodo __init__() per configurare il client API e la creazione delle directory.

Per prima cosa, gestiamo la chiave API:

def __init__(self, api_key: str = None):
   """Initialize the Math Solver with Anthropic client."""
   if not api_key:
       api_key = os.getenv("ANTHROPIC_API_KEY")
       if not api_key:
           raise ValueError(
               "Please set ANTHROPIC_API_KEY environment variable or provide api_key"
           )

Poi configuriamo il client Anthropic con gli header beta richiesti:

# Initialize client with both code execution and files API headers
   self.client = Anthropic(
       api_key=api_key,
       default_headers={
           "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"
       },
   )

Infine, creiamo la struttura delle directory di output:

# Create organized output directories
   self.output_dir = Path("math_solver_output")
   self.images_dir = self.output_dir / "images"
   self.reports_dir = self.output_dir / "reports"

   self.output_dir.mkdir(exist_ok=True)
   self.images_dir.mkdir(exist_ok=True)
   self.reports_dir.mkdir(exist_ok=True)

   print(f"📁 Output directories created:")
   print(f"   • Images: {self.images_dir}")
   print(f"   • Reports: {self.reports_dir}")

Questa inizializzazione fa tre cose importanti:

1. Gestione della chiave API: Controlla prima la chiave nelle variabili d’ambiente, poi usa il parametro in fallback.
2. Impostazione del client: Crea un client Anthropic con entrambi gli header beta per esecuzione del codice e Files API.
3. Struttura delle directory: Crea cartelle organizzate per archiviare immagini e report.

Step 3: scrivi la funzione core del solver

Il metodo solve_problem() è il cuore della nostra applicazione. Invia richieste a Claude con supporto allo streaming.

Iniziamo con la firma della funzione e il setup iniziale:

def solve_problem(self, question: str) -> Dict[str, Any]:
   """
   Send a math question to Claude and get solution with code execution.
   """
   print(f"\n🤔 Thinking about: {question}")

   try:
       # Use streaming to show real-time progress
       with self.client.messages.stream(
           model="claude-sonnet-4-20250514",
           max_tokens=4096,
Now we configure the message and tool specification:
messages=[
               {
                   "role": "user",
                   "content": f"""Solve this math problem using code execution:

Problem: {question}

Please:
1. Solve the problem with actual Python code
2. Create visualizations using matplotlib if helpful
3. Save any plots as PNG files using plt.savefig()
4. Show your calculations step by step
5. Use descriptive filenames for saved plots

Execute Python code to solve this problem.""",
               }
           ],
           tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
       ) as stream:
The streaming event processing handles real-time updates:
print("\n💭 Claude is working...")

           # Process streaming events and show progress
           for event in stream:
               if event.type == "content_block_start":
                   if hasattr(event.content_block, "type"):
                       if event.content_block.type == "text":
                           print("\n📝 Response:", end=" ", flush=True)
                       elif event.content_block.type == "server_tool_use":
                           print(f"\n🔧 Using tool: {event.content_block.name}")

Gestiamo diversi tipi di eventi in streaming:

	elif event.type == "content_block_delta":
                   if hasattr(event.delta, "text"):
                       print(event.delta.text, end="", flush=True)

               elif event.type == "content_block_stop":
                   print("", flush=True)  # New line

               elif event.type == "message_delta":
                   if hasattr(event.delta, "stop_reason"):
                       print(f"\n✅ Completed: {event.delta.stop_reason}")

Infine, restituiamo il risultato o gestiamo gli errori:

	# Get the final message
           final_message = stream.get_final_message()

           return {
               "response": final_message,
               "question": question,
               "timestamp": datetime.datetime.now().isoformat(),
           }

   except Exception as e:
       print(f"❌ Error solving problem: {e}")
       return None

Questa funzione dimostra diversi concetti importanti:

• Supporto allo streaming: Usiamo client.messages.stream() invece di client.messages.create() per avere feedback in tempo reale mentre Claude lavora al problema.
• Gestione degli eventi: L’API di streaming invia diversi tipi di eventi:
• content_block_start: quando Claude inizia a scrivere testo o a usare uno strumento
• content_block_delta: mentre il contenuto viene generato
• content_block_stop: quando un blocco di contenuto è terminato
• message_delta: quando l’intero messaggio è completo
• Specificazione degli strumenti: Includiamo lo strumento di esecuzione del codice nell’array tools con il tipo esatto "code_execution_20250522".
• Prompt strutturato: Il nostro prompt istruisce chiaramente Claude a usare l’esecuzione del codice e a salvare eventuali visualizzazioni.

Step 4: risolvi problemi di matematica con esecuzione di codice in streaming

Quando Claude crea file durante l’esecuzione del codice (come grafici di matplotlib), dobbiamo estrarne gli ID e scaricarli in locale.

Il metodo di estrazione dei file attraversa la struttura della risposta:

def extract_files_from_response(self, response) -> List[str]:
   """Extract file IDs from Claude's response."""
   file_ids = []

   for item in response.content:
       if item.type == "code_execution_tool_result":
           content_item = item.content
          
           if isinstance(content_item, dict):
               if content_item.get("type") == "code_execution_result":
                   content_list = content_item.get("content", [])

Poi cerchiamo gli ID dei file nel contenuto:

  for file_item in content_list:
                       if isinstance(file_item, dict) and "file_id" in file_item:
                           file_ids.append(file_item["file_id"])

   return file_ids

Il processo di download recupera i file e li salva in locale:

def download_files(self, file_ids: List[str]) -> List[str]:
   """Download files created by code execution to local storage."""
   downloaded_files = []

   for file_id in file_ids:
       try:
           # Get file metadata and download content
           file_metadata = self.client.beta.files.retrieve_metadata(file_id)
           filename = file_metadata.filename
          
           file_content = self.client.beta.files.download(file_id)
           local_path = self.images_dir / filename
           file_content.write_to_file(str(local_path))

Teniamo traccia dei file scaricati e gestiamo gli errori:

downloaded_files.append(str(local_path))
           print(f"✅ Downloaded: {filename}")

       except Exception as e:
           print(f"❌ Error downloading file {file_id}: {e}")

   return downloaded_files

• Logica di estrazione file: Il metodo extract_files_from_response() attraversa la struttura della risposta per trovare gli ID file. I risultati dell’esecuzione del codice sono annidati in un formato specifico in cui i file compaiono nell’array content.
• Processo di download dei file: Il metodo download_files():
• Ottiene i metadati per ogni file (incluso il nome originale)
• Scarica il contenuto del file usando la Files API
• Salva i file nella nostra struttura di directory organizzata
• Restituisce un elenco di percorsi locali per utilizzi successivi