Tutorial Claude Agent SDK: crea agent con Claude Sonnet 4.5

Il Claude Agent SDK definisce un ciclo agent strutturato in quattro passaggi chiave: raccogliere contesto, agire, verificare il lavoro e ripetere.

In pratica, inizia con una ricerca agentica per il contesto e aggiungi la ricerca semantica quando ti serve velocità. Le azioni dovrebbero concentrarsi su strumenti ad alto segnale, script bash e integrazioni con servizi esterni tramite il Model Context Protocol. 

La verifica combina controlli basati su regole, feedback visivo ed eventuale supporto LLM. È consigliata un’iterazione continua per affinare le prestazioni, ampliare gli strumenti e migliorare le capacità di ricerca man mano che le funzionalità si evolvono.

Funzionalità principali:

1. SDK: TypeScript e Python per backend web/Node.js e data science, con concetti condivisi così i team possono riutilizzare pattern tra gli stack.
2. Modalità: Streaming per UX interattive a bassa latenza e single-shot per esecuzioni batch o deterministiche—scegli per attività per bilanciare velocità e controllo.
3. Gestione del contesto: Compattazione automatica e controllo del contesto per sessioni lunghe, per evitare overflow e mantenere gli agent sulla rotta durante sessioni estese.
4. Tooling: Operazioni su file, esecuzione del codice e ricerca web integrate, oltre a estensibilità per strumenti e dati esterni via MCP.
5. Permessi: Controlli di capacità granulari (ad esempio allow/deny per singolo tool e policy mode) per vincolare cosa può fare un agent in produzione.
6. Pronto per la produzione: Gestione errori, sessioni e monitoraggio integrati, così puoi distribuire agent affidabili con osservabilità fin dal primo giorno.
7. Integrazione con Claude: Caching dei prompt automatico e ottimizzazioni delle prestazioni per ridurre latenza e costi migliorando il throughput.
8. Autenticazione: Usa una chiave API di Claude o instrada tramite provider come Amazon Bedrock e Google Vertex AI per adattarti al tuo ambiente di deployment.
9. Prompt di sistema: Definisci ruolo, competenze e guardrail per modellare il comportamento dell’agent in modo coerente tra attività e sessioni.
10. Integrazioni (MCP): Collega strumenti personalizzati, database e API tramite l’open Model Context Protocol, uno standard supportato da Anthropic con SDK ufficiali TypeScript e un ecosistema in crescita.

Primi passi con il Claude Agent SDK in Python

Prima di iniziare a costruire qualsiasi progetto, devi configurare alcuni prerequisiti, installare la CLI di Claude Code e il Claude Agent SDK.

Prerequisiti

• Assicurati di avere Python versione 3.10 o superiore. 
• Per usare efficacemente la CLI di Claude Code, devi anche installare Node.js versione 18 o superiore e il pacchetto NPM.

Installa la CLI di Claude Code

Per Windows: 

Apri PowerShell ed esegui il seguente comando per scaricare e installare Claude Code:

irm https://claude.ai/install.ps1 | iex

Dopo l’installazione, aggiungi C:\Users\<user>\.local\bin al PATH di sistema. Riavvia PowerShell e dovresti vedere che Claude è in esecuzione.

Per altre piattaforme:

Se hai installato Node.js e NPM, prova a eseguire il seguente comando nel terminale per installare Claude Code:

npm i -g @anthropic-ai/claude-code

Segui le istruzioni per impostare le variabili d’ambiente, in modo da poter accedere a Claude Code semplicemente digitando “claude” nel terminale.

Configurare Claude Code

Dopo aver installato Claude Code, aprilo digitando “claude” nel terminale ed eseguendo l’accesso. Se hai un piano Claude Pro o Max, scegli “Accedi con il tuo account in abbonamento” così l’uso verrà scalato dal tuo piano.

Se preferisci il pay‑as‑you‑go, autenticati invece con una chiave API; la fatturazione passerà dalla Anthropic Console. 

Infine, imposta tema e preferenze di interfaccia/CLI in modo che tutto si adatti al tuo flusso di lavoro fin dal primo giorno.

Io ho configurato Claude Code con la chiave API. Puoi vedere la configurazione qui:

Installa il Claude Agent SDK

Assicurati che Python sia installato, poi apri il terminale. Per installare il Claude Agent SDK, esegui:

pip install claude-agent-sdk

Nota: Se riscontri un CLINotFoundError, assicurati di aver installato la CLI sopra e che Claude sia incluso nel tuo PATH.

Costruire progetti con Claude Agent SDK e Claude Sonnet 4.5

Ora costruiremo tre semplici progetti usando il Claude Agent SDK come framework, Claude Code per gli strumenti e l’uso del computer, e Claude Sonnet 4.5 come modello di AI.

1. Outline di blog one-shot: una semplice query one-shot che dimostra l’uso di base del Claude Agent SDK senza strumenti.
2. InspireBot CLI: questo progetto combina capacità di ricerca web con uno strumento di fallback personalizzato per citazioni motivazionali.
3. App multi‑tool NoteSmith: un’app per note completa con più strumenti, hook di sicurezza e tracciamento d’uso.

Tutto il codice sorgente è disponibile nel repository GitHub: kingabzpro/claude-agent-projects

1. Outline di blog one-shot

In questo progetto usiamo la funzione query() dell’SDK con Claude Sonnet 4.5 per creare l’outline di un blog. È una semplice query one-shot che mostra l’uso di base del Claude Agent SDK senza strumenti.

Il codice è composto da: 

1. Streaming asincrono: usa asyncio con l’iteratore async di query() per output non bloccante, token‑per‑token.
2. Prompt e opzioni: definisce un PROMPT per l’outline e configura modello/persona tramite ClaudeAgentOptions.
3. Flusso di messaggi tipizzati: itera sui messaggi; estrae solo il contenuto AssistantMessage → TextBlock.
4. Output in tempo reale: stampa il testo man mano che arriva (end="") per una vista pulita in console durante lo streaming.
5. Gestione dei risultati: ignora ResultMessage, lasciando che lo stream finisca naturalmente.
6. Punto di ingresso: esegue tutto con asyncio.run(main()) quando lo script viene avviato.
7. Personalizzabile e minimale: facile cambiare modello/prompt; script leggero, ideale per demo o pipeline.

oneshot_outline.py:

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
    ResultMessage,
)

PROMPT = """Create a crisp markdown outline (H2/H3 bullets) for a 500-word blog post:
Title: Why Sovereign AI Compute Matters in 2026
Audience: CTOs and Heads of AI
Tone: pragmatic, non-hype
Include: 3 buyer pains, 3 evaluation criteria, 1 closing CTA
"""

async def main():
    options = ClaudeAgentOptions(
        model="sonnet", 
        system_prompt="You are a precise technical copy strategist."
    )

    async for msg in query(prompt=PROMPT, options=options):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="")  # only the outline
        elif isinstance(msg, ResultMessage):
            pass  # let the iterator end naturally

if __name__ == "__main__":
    asyncio.run(main())

Eseguiremo lo script e poi salveremo l’output come file markdown. 

python oneshot_outline.py > outline.md 

Puoi aprire il file markdown e vedere che ha generato un testo tecnico corretto. 

Puoi tornare alla tua dashboard su https://console.anthropic.com/usage per controllare il tuo utilizzo. Come vedi, il modello è Claude Sonnet 4.5.

2. InspireBot CLI

In questo progetto, costruiamo un generatore di motivazione da terminale che effettua lo streaming di citazioni usando Claude Sonnet 4.5. Prova prima una WebSearch, poi ricorre a uno strumento personalizzato inspire_me che restituisce citazioni casuali.

Il codice è composto da:

• Strumento di fallback personalizzato: definisce inspire_me con citazioni motivazionali preimpostate, registrato tramite create_sdk_mcp_server.
• Helper CLI: is_tty, typewrite, bold, faint aggiungono animazione da macchina da scrivere e output stilizzato in terminale.
• Prompt e opzioni: configurato con ClaudeAgentOptions, consentendo strumenti (WebSearch + inspire_me) e una persona di sistema “InspireBot”.
• Chiamate agli strumenti in streaming: itera sui messaggi, mostrando uso degli strumenti (ToolUseBlock), risultati (ToolResultBlock) e output finale (TextBlock).
• Logica di fallback: se non appare un output utilizzabile, si ripiega su una citazione locale casuale.
• UX interattiva: mostra input/risultati degli strumenti in streaming, poi anima la riga ispirazionale finale con effetto macchina da scrivere.

inspire_web.py:

import sys
import json
import asyncio
import random
import time
from typing import Any

from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    tool,
    create_sdk_mcp_server,
    AssistantMessage,
    TextBlock,
    ToolUseBlock,
    ToolResultBlock,
    ResultMessage,
)

# -------------------------
# Custom fallback tool
# -------------------------
QUOTES = [
    "Dream big, start small -- but start.",
    "Stay curious, stay humble, keep building.",
    "Every expert was once a beginner.",
    "Small wins stack into big victories.",
    "Consistency beats intensity when intensity is inconsistent.",
]

@tool("inspire_me", "Return a random motivational quote", {})
async def inspire_me(_: dict) -> dict:
    return {"content": [{"type": "text", "text": random.choice(QUOTES)}]}

UTILS = create_sdk_mcp_server("inspire_util", "1.0.0", [inspire_me])

# -------------------------
# Tiny terminal helpers
# -------------------------
def is_tty() -> bool:
    try:
        return sys.stdout.isatty()
    except Exception:
        return False

def typewrite(text: str, delay: float = 0.02) -> None:
    """Print with a typewriter effect if TTY; otherwise plain print."""
    if not is_tty():
        print(text)
        return
    for ch in text:
        print(ch, end="", flush=True)
        time.sleep(delay)
    print()

def faint(s: str) -> str:
    """Dim text if terminal supports ANSI."""
    return s if not is_tty() else f"\033[2m{s}\033[0m"

def bold(s: str) -> str:
    return s if not is_tty() else f"\033[1m{s}\033[0m"

# -------------------------
# Main
# -------------------------
async def main():
    topic = "engineering focus" if len(sys.argv) < 2 else " ".join(sys.argv[1:])

    options = ClaudeAgentOptions(
        model="sonnet",  # switch to "sonnet-4.5" if your CLI lists it
        system_prompt=(
            "You are InspireBot.\n"
            "- First, try WebSearch to find a short, uplifting quote relevant to the user's topic.\n"
            "- If WebSearch is unhelpful or no clear quote is found, call the custom 'inspire_me' tool.\n"
            "- Output ONE short line only. No preface, no commentary, <= 120 characters."
        ),
        allowed_tools=[
            "WebSearch",
            "mcp__inspire_util__inspire_me",
        ],
        mcp_servers={"inspire_util": UTILS},
    )

    prompt = (
        "Find a short, uplifting quote for today's inspiration. "
        f"Topic: {topic}. Prefer something crisp and modern.\n"
        "If search yields multiple options, pick the best single line."
    )

    final_line_parts: list[str] = []

    if is_tty():
        print(bold("🌐 InspireBot (WebSearch + fallback tool)"))
        print(faint("Tip: pass a custom topic:  python inspire_web_animated.py \"women in leadership\""))
        print()

    async for message in query(prompt=prompt, options=options):
        # Stream assistant messages for tool usage + final text
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, ToolUseBlock):
                    tool_name = block.name
                    tool_input = block.input or {}
                    print(f"{bold('🛠️  Tool used:')} {tool_name}")
                    print(f"{faint('   input:')} {json.dumps(tool_input, ensure_ascii=False)}")
                elif isinstance(block, ToolResultBlock):
                    # Show summarized tool result text if present
                    shown = False
                    if isinstance(block.content, list):
                        for part in block.content:
                            if isinstance(part, dict) and part.get("type") == "text":
                                text = (part.get("text") or "").strip()
                                if text:
                                    preview = text if len(text) <= 200 else (text[:197] + "...")
                                    print(f"{faint('   result:')} {preview}")
                                    shown = True
                                    break
                    if not shown:
                        print(f"{faint('   result:')} (no textual content)")
                elif isinstance(block, TextBlock):
                    # This should be the final "inspiration" line content
                    final_line_parts.append(block.text)

        elif isinstance(message, ResultMessage):
            # allow the iterator to finish naturally (no break)
            pass

    final_line = " ".join(part.strip() for part in final_line_parts).strip()
    if not final_line:
        final_line = random.choice(QUOTES)  # ultimate fallback, just in case

    # Animate the final line (typewriter), or plain if not a TTY
    typewrite(final_line, delay=0.02)

if __name__ == "__main__":
    asyncio.run(main())

Eseguiremo lo script con l’argomento predefinito usando il seguente comando:  

python inspire_web.py

Come possiamo vedere, mostra gli strumenti usati, l’input a quegli strumenti e poi restituisce una citazione motivazionale.  

Forniamo ora allo script Python un argomento personalizzato:  

python inspire_web.py "Sadness and Love"

Questo restituisce una citazione motivazionale che include le parole chiave "love" e "sadness".

3. App multi‑tool NoteSmith

In questo progetto, costruiamo un assistente di ricerca multi‑tool che salva e cerca note in locale, riassume pagine web ed effettua lo streaming dei risultati con Claude Sonnet 4.5. Combina strumenti MCP personalizzati, strumenti integrati e un safety hook per un’esperienza CLI più ricca.

Il codice è composto da:

• Archiviazione locale: salva le note su disco con timestamp; supporta la ricerca case‑insensitive con una semplice logica di grep.
• Strumenti MCP personalizzati: save_note (salva testo) e find_note (cerca nelle note), registrati con create_sdk_mcp_server.
• Safety hook: block_dangerous_bash nega comandi shell dannosi (ad es. rm -rf /) prima dell’esecuzione dello strumento.
• Prompt di sistema e comandi: definisce /summarize, /note, /find, /help, /exit; il prompt guida l’uso degli strumenti (WebFetch, save_note, find_note).
• Interazione in streaming: usa ClaudeSDKClient per gestire AssistantMessage, ToolUseBlock, ToolResultBlock, stampando testo e risultati in tempo reale.
• Tracciamento dell’uso: stampa un footer con nome modello, token e costo su stderr mantenendo pulito l’output principale.
• Interfaccia chat: funziona come una REPL leggera in cui digiti comandi (/note, /find, /summarize) e ottieni risposte immediate, rendendo l’esperienza simile a una chat con un assistente.

note_smith.py:

import sys
import json
import asyncio
from datetime import datetime
from pathlib import Path
from typing import Any

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
    ToolUseBlock,
    ToolResultBlock,
    ResultMessage,
    tool,
    create_sdk_mcp_server,
    HookMatcher,
    HookContext,
)

# ----------------------------
# Storage (simple local notes)
# ----------------------------

NOTES_DIR = Path(__file__).parent / "notes"
NOTES_DIR.mkdir(exist_ok=True)

def _ts() -> str:
    return datetime.now().strftime("%Y-%m-%d_%H-%M-%S")

def save_note_to_disk(text: str) -> str:
    path = NOTES_DIR / f"note_{_ts()}.txt"
    path.write_text(text.strip() + "\n", encoding="utf-8")
    return str(path)

def grep_notes(pattern: str) -> list[str]:
    pat = pattern.lower()
    out: list[str] = []
    for p in NOTES_DIR.glob("*.txt"):
        for i, line in enumerate(p.read_text(encoding="utf-8").splitlines(), start=1):
            if pat in line.lower():
                out.append(f"{p.name}:{i}: {line}")
    return out

# ----------------------------
# Custom MCP tools
# ----------------------------

@tool("save_note", "Save a short note to local disk", {"text": str})
async def save_note(args: dict[str, Any]) -> dict[str, Any]:
    path = save_note_to_disk(args["text"])
    return {"content": [{"type": "text", "text": f"Saved note → {path}"}]}

@tool("find_note", "Find notes containing a pattern (case-insensitive)", {"pattern": str})
async def find_note(args: dict[str, Any]) -> dict[str, Any]:
    hits = grep_notes(args["pattern"])
    body = "\n".join(hits) if hits else "No matches."
    return {"content": [{"type": "text", "text": body}]}

UTILS_SERVER = create_sdk_mcp_server(
    name="notes_util",
    version="1.0.0",
    tools=[save_note, find_note],
)

# ----------------------------
# Optional safety hook (Bash)
# ----------------------------

async def block_dangerous_bash(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
):
    if input_data.get("tool_name") == "Bash":
        cmd = str(input_data.get("tool_input", {}).get("command", "")).strip().lower()
        if "rm -rf /" in cmd or "format c:" in cmd:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": "Dangerous command blocked"
                }
            }
    return {}

# ----------------------------
# Prompts & UI
# ----------------------------

SYSTEM_PROMPT = """You are NoteSmith, a concise research assistant.
- Prefer bullet answers with crisp takeaways.
- When the user asks to /summarize <url>, use WebFetch to retrieve and then summarize 5 key points + a 1-line TL;DR.
- When the user types /note <text>, call the custom save_note tool.
- When the user types /find <pattern>, call the custom find_note tool.
- Keep answers short unless asked to expand.
"""

HELP = """Commands:
  /summarize <url>      Summarize a webpage (WebFetch)
  /note <text>          Save a note locally
  /find <pattern>       Search saved notes
  /help                 Show this help
  /exit                 Quit
"""

# Use the broadest model label for compatibility; switch to "sonnet-4.5" if your CLI lists it.
MODEL = "sonnet"

# ----------------------------
# Main app
# ----------------------------

async def main():
    options = ClaudeAgentOptions(
        model=MODEL,
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=[
            # Built-ins (Claude may use these if relevant)
            "WebFetch", "Read", "Write", "Grep", "Glob",
            # Our MCP tools (SDK prefixes mcp__<alias>__<toolname>)
            "mcp__utils__save_note",
            "mcp__utils__find_note",
        ],
        mcp_servers={"utils": UTILS_SERVER},
        hooks={"PreToolUse": [HookMatcher(hooks=[block_dangerous_bash])]},
        setting_sources=None,  # no filesystem settings; everything is programmatic
    )

    print("💡 NoteSmith (Claude Sonnet)\n")
    print(HELP)

    async with ClaudeSDKClient(options=options) as client:
        while True:
            user = input("\nYou: ").strip()
            if not user:
                continue
            if user.lower() in {"/exit", "exit", "quit"}:
                print("Bye!")
                break
            if user.lower() in {"/help", "help"}:
                print(HELP)
                continue

            # Lightweight command parsing (the system prompt also guides tool usage)
            if user.startswith("/summarize "):
                url = user.split(" ", 1)[1].strip()
                prompt = f"Summarize this URL using WebFetch and return 5 bullets + TL;DR:\n{url}"
            elif user.startswith("/note "):
                text = user.split(" ", 1)[1]
                prompt = f'Please call tool save_note with text="{text}"'
            elif user.startswith("/find "):
                patt = user.split(" ", 1)[1]
                prompt = f'Please call tool find_note with pattern="{patt}"'
            else:
                prompt = user

            await client.query(prompt)

            # -------- Response streaming with footer to STDERR --------
            model_used = None
            usage = None
            cost = None

            async for message in client.receive_response():
                if isinstance(message, AssistantMessage):
                    if model_used is None:
                        model_used = message.model  # e.g., "sonnet" or "sonnet-4.5"
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="", flush=True)  # stdout
                        elif isinstance(block, ToolUseBlock):
                            print(f"\n🛠️  Using tool: {block.name} with input: {json.dumps(block.input)}")
                        elif isinstance(block, ToolResultBlock):
                            if isinstance(block.content, list):
                                for part in block.content:
                                    if isinstance(part, dict) and part.get("type") == "text":
                                        print(f"\n🔎 Tool says: {part.get('text')}")
                elif isinstance(message, ResultMessage):
                    usage = message.usage or {}
                    cost = message.total_cost_usd
                    # Do not break early; let stream end naturally

            # Footer (model + tokens + cost) → STDERR so normal output stays clean
            def _token_summary(u: dict) -> str:
                total = u.get("total_tokens")
                if total is None:
                    it, ot = u.get("input_tokens"), u.get("output_tokens")
                    if it is not None or ot is not None:
                        total = (it or 0) + (ot or 0)
                if total is None:
                    return "tokens=?"
                if "input_tokens" in u or "output_tokens" in u:
                    return f"tokens={total} (in={u.get('input_tokens','?')}, out={u.get('output_tokens','?')})"
                return f"tokens={total}"

            footer = (
                f"\n\n-- Turn done. model={(model_used or options.model)} "
                f"{_token_summary(usage or {})} cost={cost if cost is not None else '?'} --"
            )
            print(footer, file=sys.stderr)

# Entry
if __name__ == "__main__":
    asyncio.run(main())

Per avviare l’app, digita il seguente comando nel terminale:

python note_smith.py

Questo avvierà l’interfaccia chat della CLI con comandi utili.

Per prima cosa riassumeremo la pagina web. Ho fornito l’URL del mio portfolio:

/summarize abid.work

Per prima cosa, l’agent determinerà quali strumenti usare, recupererà il contenuto della pagina, estrarrà cinque punti chiave e li mostrerà nell’interfaccia della chat. Alla fine, mostrerà un report d’uso che include nome del modello, uso dei token e costo.

I'll fetch and summarize the content from that URL for you.                                    
🛠️  Using tool: WebFetch with input: {"url": "https://abid.work", "prompt": "Extract the main content and key information from this page, including what the person does, their background, projects, and any notable achievements or areas of focus."}


**5 Key Points:**

• **Prolific Tech Educator** - Authored 500+ articles making data science & ML accessible through tutorials, cheat sheets, and practical guides

• **Certified Data Scientist** - Professional focus on building innovative machine learning solutions across NLP, computer vision, and MLOps

• **Multi-Domain Expertise** - Covers Python, SQL, AI, and end-to-end ML workflows with hands-on project demonstrations

• **Content-First Philosophy** - Maintains extensive portfolio including blogs, tutorials, book reviews, and career resources

• **Open Contributor** - Active on GitHub (kingabzpro) sharing code and projects with the community

**TL;DR:** Abid Ali Awan is a certified data scientist who's authored 500+ educational articles and tutorials, specializing in ML, NLP, and making complex tech concepts accessible to learners.

-- Turn done. model=claude-sonnet-4-5-20250929 tokens=326 (in=6, out=320) cost=0.062402849999999996 --

Ora salviamo una nota:

/note what is love

Abbiamo chiesto di salvare la nota con il testo “what is love”.

🛠️  Using tool: mcp__utils__save_note with input: {"text": "what is love"}


✓ Note saved: "what is love"

-- Turn done. model=claude-sonnet-4-5-20250929 tokens=81 (in=6, out=75) cost=0.07421549999999999 --

Infine, cercheremo la nota fornendo una parola chiave della nota:

/find love

Come puoi vedere, ha trovato il file e ne ha mostrato il testo.

🛠️  Using tool: mcp__utils__find_note with input: {"pattern": "love"}


**Found 1 note matching "love":**

• `note_2025-09-30_17-18-02.txt` - "what is love"

-- Turn done. model=claude-sonnet-4-5-20250929 tokens=105 (in=6, out=99) cost=0.08423339999999999 --

Conclusione 

Il Claude Agent SDK è semplice da configurare, soprattutto se hai già installato Claude Code in locale. Basta installare il pacchetto SDK. 

Il Python SDK offre due modi principali per interagire con Claude:

• query() – una semplice API di generazione del testo ideale per casi d’uso leggeri, anche se non supporta gli strumenti.
• ClaudeSDKClient – un’API agentica completa che consente di riprendere sessioni, usare strumenti, mantenere il controllo manuale e altro.

In questo tutorial, abbiamo esplorato il modello più recente di Anthropic, Claude Sonnet 4.5, e presentato il nuovo Claude Agent SDK. Abbiamo seguito il processo di installazione e costruito tre progetti d’esempio per dimostrarne le capacità.

Se ti interessa sperimentare workflow agentici, ti consiglio vivamente di provare questo SDK.