Perché un componente Delphi nativo per Claude?
Anthropic Claude è una delle famiglie AI più capaci sul mercato, ma ogni esempio pubblico usa Python o Node. Per gli sviluppatori Delphi e C++Builder, chiamare gli endpoint REST a mano significa scrivere a mano JSON, destreggiarsi con i Server-Sent Events, gestire TLS, gestire i rate limit e riscrivere boilerplate ogni volta che Anthropic distribuisce una nuova funzionalità — il che fa più o meno ogni trimestre. Il componente TsgcHTTP_API_Anthropic distribuito con sgcWebSockets elimina questa frizione. È un wrapper fortemente tipizzato attorno all'intera superficie Anthropic — messaggi, streaming, vision, tool use, extended thinking, prompt caching, file, batch e il connettore Model Context Protocol — che puoi mettere su una form e usare da qualsiasi applicazione VCL, FMX o console.
Questo tutorial passa in rassegna ogni capacità principale con codice Delphi funzionante. Alla fine sarai in grado di costruire un client di chat, un analizzatore di documenti con visione, un tool runner agentico e una pipeline di produzione ottimizzata sui costi. Tutti gli snippet puntano agli ultimi modelli claude-sonnet-4-20250514 e claude-opus-4-20250514, e tutti girano invariati da Delphi 7 a Delphi 13.
Una breve nota sulla filosofia prima di tuffarci. Il componente espone intenzionalmente due superfici. La superficie "quick" (metodi come _CreateMessage, _CreateMessageStream, _CreateMessageWithImage) accetta poche stringhe e restituisce una stringa — perfetta per prototipi, demo e per l'80% delle chiamate in cui non ti interessano temperature, top-p, metadati o stop sequence. La superficie "typed" (classi come TsgcAnthropicClass_Request_Messages e TsgcAnthropicClass_Response_Messages) ti dà controllo completo su ogni parametro che l'API Anthropic supporta, con strong typing e auto-completion dell'IDE. Usa l'API quick per imparare; promuovi all'API typed per la produzione. Stesso componente, due layer, nessuna duplicazione.
1. Setup e il tuo primo messaggio
Aggiungi sgcHTTP_API_Anthropic alla tua clausola uses, crea il componente, imposta la tua API key (prendine una da console.anthropic.com) e chiama _CreateMessage. Questo è il minimo assoluto per parlare con Claude.
uses
sgcHTTP_API_Anthropic;
var
oClaude: TsgcHTTP_API_Anthropic;
vReply : string;
begin
oClaude := TsgcHTTP_API_Anthropic.Create(nil);
try
oClaude.AnthropicOptions.ApiKey := 'sk-ant-api03-...';
vReply := oClaude._CreateMessage(
'claude-sonnet-4-20250514',
'Write a haiku about Pascal compilers.');
ShowMessage(vReply);
finally
oClaude.Free;
end;
end;
Il componente fa il lavoro pesante: costruisce il body JSON della richiesta, imposta gli header x-api-key e anthropic-version, fa il POST a /v1/messages e fa il parsing della risposta in una semplice stringa Delphi. Se hai bisogno di controllo completo sui parametri della richiesta, usa la classe tipizzata TsgcAnthropicClass_Request_Messages.
Un consiglio operativo: non infornare mai l'API key nel binario. Leggila da una variabile d'ambiente, una chiave di registry o un secrets manager. Anthropic ora scansiona GitHub per chiavi trapelate e le revoca automaticamente — non vuoi spedire un aggiornamento alle 18 di venerdì perché qualcuno ha fatto uno screenshot del tuo file .pas.
2. Risposte in streaming con SSE
Le chiamate sincrone vanno bene per prompt brevi, ma per una UI di chat vuoi che i token appaiano man mano che Claude li genera. Anthropic fa lo streaming delle risposte come Server-Sent Events e il componente le espone attraverso l'evento OnHTTPAPISSE.
procedure TForm1.FormCreate(Sender: TObject);
begin
oClaude := TsgcHTTP_API_Anthropic.Create(Self);
oClaude.AnthropicOptions.ApiKey := 'sk-ant-api03-...';
oClaude.OnHTTPAPISSE := ClaudeSSE;
end;
procedure TForm1.ClaudeSSE(Sender: TObject;
const aEvent, aData: string; var Cancel: Boolean);
var
vDelta: string;
begin
// aEvent values: message_start, content_block_delta,
// content_block_stop, message_stop
if aEvent = 'content_block_delta' then
begin
vDelta := oClaude.SSEExtractText(aData);
Memo1.Text := Memo1.Text + vDelta;
Application.ProcessMessages;
end;
end;
procedure TForm1.btnAskClick(Sender: TObject);
begin
Memo1.Clear;
oClaude._CreateMessageStream(
'claude-sonnet-4-20250514',
edtPrompt.Text);
end;
Un dettaglio degno di nota: lo streaming gira su un thread in background, quindi aggiorna la UI tramite TThread.Synchronize o TThread.Queue nel codice di produzione. Lo snippet sopra usa ProcessMessages per brevità. Un altro: lo stream SSE invia più tipi di evento in sequenza (message_start, content_block_start, content_block_delta ripetuti, content_block_stop, message_delta, message_stop) e dovresti ignorare quelli che non ti servono. L'helper SSEExtractText gestisce il caso comune di estrarre il delta di testo da content_block_delta; per le statistiche di utilizzo e le stop reason fai il parsing di message_delta direttamente.
Lo streaming è essenziale per qualunque UI di chat rivolta all'utente — gli utenti percepiscono come veloce una risposta che inizia in 400 ms, anche se la risposta completa richiede dieci secondi. Senza streaming, fissano uno spinner per dieci secondi e pensano che l'app sia rotta. Il costo è identico: le richieste con e senza streaming sono fatturate allo stesso modo.
3. Vision — inviare immagini
Claude può analizzare immagini JPEG, PNG, GIF e WebP. Le passi o come URL pubblico o come byte codificati in base64. Il componente espone _CreateMessageWithImage per il caso URL e l'API tipizzata per tutto il resto.
var
oRequest : TsgcAnthropicClass_Request_Messages;
oMessage : TsgcAnthropicClass_Request_Message;
oImage : TsgcAnthropicClass_Request_Content_Image;
oResponse: TsgcAnthropicClass_Response_Messages;
begin
oRequest := TsgcAnthropicClass_Request_Messages.Create;
try
oRequest.Model := 'claude-sonnet-4-20250514';
oRequest.MaxTokens := 1024;
oMessage := oRequest.NewMessage('user');
oMessage.AddText('Describe what you see and read any text.');
oImage := oMessage.AddImage;
oImage.Source.LoadFromFile('C:\invoices\inv-2026-05-12.png');
oImage.MediaType := 'image/png';
oResponse := oClaude.CreateMessage(oRequest);
try
Memo1.Lines.Add(oResponse.Content[0].Text);
finally
oResponse.Free;
end;
finally
oRequest.Free;
end;
end;
La vision è ideale per l'OCR su fatture scannerizzate, lo smistamento di screenshot in ticket di supporto, l'interpretazione di grafici e qualunque task in cui un motore OCR deterministico farebbe fatica con il layout. Tieni d'occhio il costo in token: un'immagine 1024x1024 consuma circa 1.600 token di input. Anthropic ridimensiona qualsiasi cosa più grande di 1568px sul lato lungo prima di processare, quindi non ha senso caricare screenshot 4K — ridimensiona dalla tua parte e risparmia banda.
Casi d'uso pratici che abbiamo visto spedire dai team Delphi nell'ultimo anno: estrarre voci di linea da PDF di fornitori che erano troppo incoerenti per pipeline OCR tradizionali, classificare imaging medico in categorie ampie prima di instradare a software specialistico, leggere valori di contatori da foto di assistenza tecnica, e smistare screenshot di bug UI nei ticket dell'helpdesk ("lo screenshot mostra un problema di layout o un problema di dati?"). In ogni caso la vittoria non era l'accuratezza pura — era eliminare la necessità di scrivere e mantenere un parser fragile per documento.
4. Tool use (function calling)
Il tool use lascia che Claude decida quando chiamare le tue funzioni Pascal. Dichiari ogni tool con un nome, una descrizione e uno JSON Schema per i suoi parametri. Quando Claude risponde con un blocco tool_use invece di testo semplice, esegui la chiamata e reinserisci il risultato nella conversazione.
var
oRequest: TsgcAnthropicClass_Request_Messages;
oTool : TsgcAnthropicClass_Request_Tool;
begin
oRequest := TsgcAnthropicClass_Request_Messages.Create;
oRequest.Model := 'claude-sonnet-4-20250514';
oRequest.MaxTokens := 1024;
oTool := oRequest.NewTool;
oTool.Name := 'get_stock_price';
oTool.Description := 'Return the current bid/ask for a US ticker symbol.';
oTool.InputSchema :=
'{"type":"object",' +
'"properties":{"symbol":{"type":"string","description":"Ticker, e.g. AAPL"}},' +
'"required":["symbol"]}';
oRequest.NewMessage('user').AddText('What is Apple trading at?');
oResponse := oClaude.CreateMessage(oRequest);
if oResponse.StopReason = 'tool_use' then
begin
vSymbol := oResponse.ToolUse[0].InputAsJSON.S['symbol'];
vPrice := MyQuoteFeed.Quote(vSymbol); // your code
oClaude.SendToolResult(oResponse.ToolUse[0].Id,
Format('{"bid":%.2f,"ask":%.2f}', [vPrice.Bid, vPrice.Ask]));
end;
end;
Costruisci workflow agentici concatenando tool: un agente di ricerca potrebbe combinare tool web_search, read_pdf e send_email. Mantieni sempre una guardia iMaxIterations in modo che un modello che si comporta male non possa loopare per sempre. In produzione limitiamo a cinque chiamate di tool per turno utente per ragioni di costo; se Claude ne ha bisogno di più, di solito è un segno che il prompt o il design del tool sono sbagliati.
Il singolo determinante più grande della qualità del tool-calling è il testo della descrizione. I modelli scelgono il tool giusto con gli argomenti giusti circa il 99% delle volte quando le descrizioni sono precise ("Return the current bid/ask for a US ticker symbol. Use this only for equities, not for crypto or FX"); scendono a forse il 70% con una descrizione vaga ("Get a price"). Spendi il tempo. Aggiungi esempi nella descrizione. Indica cosa il tool NON fa. Il te futuro, mentre debugga una chiamata di funzione allucinata da $0,40 alle 23, ringrazierà il te presente.
5. Extended thinking
Claude 4 introduce una modalità di thinking in cui il modello ragiona passo passo su un problema prima di rispondere. Allochi un budget di thinking in token e Claude restituisce la traccia di ragionamento separatamente dalla risposta finale. È un game changer per matematica, code review e analisi multi-step.
oRequest.Thinking.Enabled := True;
oRequest.Thinking.BudgetTokens := 8000; // soft cap on internal reasoning
oRequest.MaxTokens := 16000;
oRequest.NewMessage('user').AddText(
'A train leaves Madrid at 07:00 doing 220 km/h. Another leaves ' +
'Barcelona at 07:15 doing 250 km/h. The route is 621 km. ' +
'Where do they meet?');
oResponse := oClaude.CreateMessage(oRequest);
MemoThinking.Lines.Text := oResponse.Thinking; // reasoning trace
MemoAnswer.Lines.Text := oResponse.Content[0].Text;
Usa l'extended thinking con parsimonia — i token di reasoning sono fatturati come output, quindi un budget di thinking di 16k token su Opus 4 può facilmente costare più di una chiamata normale. Riservalo a problemi in cui la correttezza conta più della latenza. Buoni utilizzi: analisi di documenti legali, riconciliazione finanziaria, generazione SQL complessa, debug di stack trace, scheduling multi-vincolo. Cattivi utilizzi: risposte di chat, classificazione di contenuti, lookup semplici — tempo e costo del thinking non sono giustificati.
Un trucco utile è esporre la traccia di reasoning nella tua UI come una sezione collapsabile "show thinking", come fa l'app Claude pubblica. Gli utenti power adorano vedere come il modello è arrivato alla risposta; gli utenti casual la ignorano. In entrambi i casi hai un audit trail gratis.
6. Prompt caching
Se continui a mandare lo stesso lungo prompt di sistema, knowledge base o definizioni di tool, il prompt caching può tagliare i costi fino al 90% e ridurre il tempo al primo token dell'80%. Marchi un content block come cacheable; Anthropic lo memorizza dal suo lato per 5 minuti (o 1 ora con la cache estesa) e rifattura solo il prezzo più economico di cache-read sulle chiamate successive.
var
oSystem: TsgcAnthropicClass_Request_System;
begin
oSystem := oRequest.NewSystemBlock;
oSystem.Text := LoadFile('C:\kb\product-manual.txt'); // 50k tokens
oSystem.CacheControl := 'ephemeral'; // mark as cacheable
oRequest.NewMessage('user').AddText('How do I configure SSL on the server?');
oResponse := oClaude.CreateMessage(oRequest);
// Inspect cache stats
ShowMessage(Format('Cache: created=%d, read=%d, input=%d, output=%d',
[oResponse.Usage.CacheCreationInputTokens,
oResponse.Usage.CacheReadInputTokens,
oResponse.Usage.InputTokens,
oResponse.Usage.OutputTokens]));
end;
Regola pratica: qualunque cosa oltre 1.024 token che riusi entro cinque minuti vale la pena cachearla. Grandi corpora di documentazione, esempi few-shot e grandi schemi di tool sono i candidati ovvi. La contabilità: le scritture in cache costano il 25% in più di un normale token di input, le letture dalla cache costano il 10% di un normale token di input. Quindi vai in pari dopo il secondo hit e inizi a risparmiare soldi veri dal terzo. Per un bot di customer support che risponde a 50 domande al minuto contro una knowledge base da 40k token, il prompt caching tipicamente taglia la bolletta mensile di Anthropic dell'80–85%.
Puoi marcare fino a quattro content block come cacheable per richiesta. Un pattern comune è: tool (cacheable, cambiano raramente), prompt di sistema (cacheable, cambia raramente), documento grande (cacheable, cambia per sessione), messaggi recenti (NON cacheable, cambiano ad ogni turno). Il componente gestisce naturalmente questa stratificazione — imposta solo CacheControl sui blocchi che vuoi cacheare.
7. Connettore MCP
Il Model Context Protocol consente a Claude di parlare con server di tool remoti senza che tu debba incapsulare ogni tool a mano. Punta il componente a un URL di server MCP e Claude può scoprire i tool, chiamarli e concatenare i risultati.
oRequest.MCPServers.Add(
'weather-mcp',
'https://mcp.example.com/weather',
'Bearer ' + GetMcpToken);
oRequest.NewMessage('user').AddText(
'What is the weather like in Madrid and should I take an umbrella?');
oResponse := oClaude.CreateMessage(oRequest);
ShowMessage(oResponse.Content[0].Text);
Combina il connettore MCP con il tuo TsgcAI_MCP_Server (coperto in un tutorial separato) e hai un agente completamente nativo Delphi che espone le tue API di dominio a qualsiasi client AI MCP-aware — Claude Desktop, Cursor, Continue, le tue app, qualunque cosa parli il protocollo. L'autenticazione è tua responsabilità: passa un bearer token o header firmato e validalo lato server. Anthropic non vede le tue credenziali — l'handshake del connettore MCP instrada il token dalla richiesta al server target.
Per i deployment SaaS multi-tenant, il pattern tipico è un singolo server MCP per tenant, con l'ID del tenant integrato nell'URL o nel bearer token. Claude chiama i tool di ogni tenant senza mai contaminare i dati. Abbiamo visto deployment di produzione fare fan-out a 200+ server MCP da una singola conversazione.
Checklist di produzione
Prima di mettere in produzione un'app Delphi alimentata da Anthropic, passa attraverso questa breve lista:
| Preoccupazione | Come gestirla |
| Memorizzazione della API key | Variabile d'ambiente o secret store dell'OS, mai hard-coded |
| Retry su 429 / 529 | Backoff esponenziale con jitter, massimo 3 tentativi |
| Tetti di costo | Traccia Usage per richiesta, rifiuta nuove chiamate oltre il budget giornaliero |
| Redazione PII | Rimuovi email/SSN/numeri di carta di credito prima di inviare all'API |
| Pinning della versione del modello | Usa nomi di modello completi datati; non fare affidamento su alias "latest" |
| Versioning dei prompt | Memorizza i prompt di sistema in source control insieme al codice |
| Telemetria | Logga modello, token di input, token di output, latenza per chiamata |
Dove andare dopo
Questo tutorial ha coperto le otto funzionalità di cui hai bisogno il 95% delle volte. Il componente supporta anche message batches (processing asincrono economico di migliaia di prompt — 50% più economico delle chiamate sincrone, ideale per job di arricchimento notturno), l'API Files (carica una volta, referenzia per sempre — perfetto per grandi PDF che interroghi ripetutamente), il conteggio dei token (stima i costi prima di pagare) e gli output JSON strutturati (conformità di schema forzata, niente più errori di parsing). Sfoglia la pagina del componente Anthropic per la matrice completa delle funzionalità e vai all'hub Per Iniziare se non hai ancora installato sgcWebSockets.
E se costruisci qualcosa di interessante con Claude in Delphi — un agente, un copilot, un analizzatore di documenti — raccontacelo. Adoriamo vedere cosa fanno gli sviluppatori Pascal quando la frizione dell'AI scompare.