Anthropic Claude em Delphi — Tutorial Completo (2026)

Por que um componente Delphi nativo para o Claude?

O Anthropic Claude é uma das famílias de IA mais capazes do mercado, mas todo exemplo público usa Python ou Node. Para desenvolvedores Delphi e C++Builder, chamar os endpoints REST na mão significa montar JSON manualmente, malabarismos com Server-Sent Events, gerenciamento de TLS, lidar com rate limits e reescrever boilerplate toda vez que a Anthropic lança um recurso novo — o que ela faz a cada trimestre, aproximadamente. O componente TsgcHTTP_API_Anthropic distribuído com o sgcWebSockets remove essa fricção. É um wrapper fortemente tipado sobre toda a superfície da Anthropic — mensagens, streaming, visão, tool use, extended thinking, prompt caching, arquivos, batches e o conector Model Context Protocol — que você pode arrastar para um form e usar de qualquer aplicação VCL, FMX ou de console.

Este tutorial percorre cada capacidade principal com código Delphi funcionando. Ao final, você será capaz de construir um cliente de chat, um analisador de documentos com visão, um runner de ferramentas agentic e um pipeline de produção com custos otimizados. Todos os snippets têm como alvo os modelos mais recentes claude-sonnet-4-20250514 e claude-opus-4-20250514, e todos rodam inalterados do Delphi 7 ao Delphi 13.

Uma nota rápida sobre a filosofia antes de mergulharmos. O componente intencionalmente expõe duas superfícies. A superfície “quick” (métodos como _CreateMessage, _CreateMessageStream, _CreateMessageWithImage) aceita algumas strings e retorna uma string — perfeito para protótipos, demos e os 80% das chamadas em que você não se importa com temperature, top-p, metadata ou stop sequences. A superfície “typed” (classes como TsgcAnthropicClass_Request_Messages e TsgcAnthropicClass_Response_Messages) dá controle total sobre cada parâmetro suportado pela API da Anthropic, com tipagem forte e auto-completion no IDE. Use a API quick para aprender; promova para a API typed em produção. Mesmo componente, duas camadas, sem duplicação.

1. Setup e sua primeira mensagem

Adicione sgcHTTP_API_Anthropic ao seu uses, crie o componente, defina sua chave de API (consiga uma em console.anthropic.com) e chame _CreateMessage. Esse é o mínimo absoluto para conversar com o 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;

O componente faz o trabalho pesado: monta o corpo JSON da requisição, define os cabeçalhos x-api-key e anthropic-version, faz o POST em /v1/messages e faz parse da resposta como uma string Delphi simples. Se precisar de controle total sobre os parâmetros, use a classe tipada TsgcAnthropicClass_Request_Messages.

Uma dica operacional: nunca embuta a chave de API no binário. Leia de uma variável de ambiente, de uma chave do registro ou de um gerenciador de segredos. A Anthropic agora varre o GitHub atrás de chaves vazadas e as revoga automaticamente — você não quer subir um update às 18h de sexta porque alguém deu um screenshot do seu .pas.

2. Respostas em streaming com SSE

Chamadas síncronas são ok para prompts curtos, mas para uma UI de chat você quer que os tokens apareçam conforme o Claude os gera. A Anthropic faz streaming das respostas como Server-Sent Events, e o componente os expõe pelo 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;

Um detalhe que vale destacar: o streaming roda em uma thread de fundo, então atualize a UI via TThread.Synchronize ou TThread.Queue em código de produção. O snippet acima usa ProcessMessages por brevidade. Outro: a stream SSE envia múltiplos tipos de evento em sequência (message_start, content_block_start, vários content_block_delta, content_block_stop, message_delta, message_stop) e você deve ignorar os que não precisar. O helper SSEExtractText resolve o caso comum de extrair o delta de texto de content_block_delta; para estatísticas de uso e stop reasons, faça parse de message_delta diretamente.

Streaming é essencial em qualquer UI de chat voltada ao usuário — usuários percebem uma resposta que começa em 400 ms como rápida, mesmo que a resposta completa demore dez segundos. Sem streaming, eles encaram um spinner por dez segundos e assumem que o app travou. O custo é idêntico: requisições com e sem streaming são cobradas igual.

3. Visão — enviando imagens

O Claude consegue analisar imagens JPEG, PNG, GIF e WebP. Você as passa como URL pública ou como bytes em base64. O componente expõe _CreateMessageWithImage para o caso de URL e a API tipada para o restante.

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;

Visão é ideal para OCR em notas fiscais escaneadas, triagem de screenshots em tickets de suporte, interpretação de gráficos e qualquer tarefa onde um motor de OCR determinístico se atrapalharia com layout. Atenção ao custo de tokens: uma imagem 1024x1024 consome cerca de 1.600 tokens de entrada. A Anthropic redimensiona qualquer coisa maior que 1568px no lado maior antes de processar, então não adianta enviar screenshots em 4K — reduza do seu lado e poupe a largura de banda.

Casos de uso práticos que vimos lojas Delphi colocarem no ar no último ano: extração de itens de PDFs de fornecedores inconsistentes demais para pipelines de OCR tradicionais, classificação de imagens médicas em categorias amplas antes de rotear para softwares especializados, leitura de valores de medidores em fotos de campo e triagem de screenshots de bugs de UI em tickets de helpdesk (“o screenshot mostra um problema de layout ou de dados?”). Em todos os casos, o ganho não foi a precisão bruta — foi eliminar a necessidade de escrever e manter um parser frágil por documento.

4. Tool use (function calling)

Tool use deixa o Claude decidir quando chamar suas funções Pascal. Você declara cada tool com um nome, descrição e JSON Schema para seus parâmetros. Quando o Claude responde com um bloco tool_use em vez de texto puro, você executa a chamada e devolve o resultado para a conversa.

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;

Construa fluxos agentic encadeando tools: um agente de pesquisa pode combinar tools web_search, read_pdf e send_email. Mantenha sempre um guard iMaxIterations para que um modelo mal-comportado não fique em loop para sempre. Em produção, limitamos em cinco chamadas de tool por turno do usuário por questões de custo; se o Claude precisar de mais, geralmente é sinal de que o prompt ou o design da tool está errado.

O maior determinante isolado da qualidade de tool calling é o texto da descrição. Modelos escolhem a tool certa com os argumentos certos cerca de 99% das vezes quando as descrições são precisas (“Return the current bid/ask for a US ticker symbol. Use this only for equities, not for crypto or FX”); caem para uns 70% com uma descrição vaga (“Get a price”). Invista o tempo. Adicione exemplos na descrição. Diga o que a tool NÃO faz. Você-do-futuro, depurando uma chamada de função alucinada de US$ 0,40 às 23h, vai agradecer ao você-do-presente.

5. Extended thinking

O Claude 4 introduz um modo de pensamento em que o modelo raciocina passo a passo antes de responder. Você aloca um orçamento de thinking em tokens, e o Claude retorna o rastro de raciocínio separado da resposta final. Isso é uma virada de jogo para matemática, code review e análise em múltiplas etapas.

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;

Use extended thinking com parcimônia — tokens de raciocínio são cobrados como saída, então um orçamento de thinking de 16k tokens no Opus 4 facilmente custa mais do que uma chamada normal. Reserve para problemas em que correção importa mais que latência. Bons encaixes: análise de documentos jurídicos, conciliação financeira, geração de SQL complexa, depuração de stack traces, agendamento multirrestrição. Maus encaixes: respostas de chat, classificação de conteúdo, consultas simples — o tempo e o custo de thinking não se justificam.

Um truque útil é expor o rastro de raciocínio na sua UI como uma seção retrátil “mostrar thinking”, como o app público do Claude faz. Power users adoram ver como o modelo chegou à resposta; usuários casuais ignoram. De qualquer forma, você ganha um audit trail de graça.

6. Prompt caching

Se você fica enviando o mesmo system prompt longo, base de conhecimento ou definições de tools, o prompt caching pode cortar custos em até 90% e reduzir o time-to-first-token em 80%. Você marca um bloco de conteúdo como cacheável; a Anthropic o armazena do lado deles por 5 minutos (ou 1 hora com o cache estendido) e só cobra o preço de cache-read, mais barato, em chamadas subsequentes.

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;

Regra de bolso: qualquer coisa acima de 1.024 tokens que você reutiliza dentro de cinco minutos vale a pena cachear. Corpos grandes de documentação, exemplos de few-shot e schemas grandes de tools são candidatos óbvios. A contabilidade: cache writes custam 25% a mais que um token de entrada normal, cache reads custam 10% de um token de entrada normal. Ou seja, você empata após o segundo hit e começa a economizar de verdade a partir do terceiro. Para um bot de atendimento respondendo 50 perguntas por minuto contra uma base de conhecimento de 40k tokens, o prompt caching tipicamente corta a conta mensal da Anthropic em 80–85%.

Você pode marcar até quatro blocos de conteúdo como cacheáveis por requisição. Um padrão comum é: tools (cacheável, raramente muda), system prompt (cacheável, raramente muda), documento grande (cacheável, muda por sessão), mensagens recentes (NÃO cacheável, muda a cada turno). O componente lida com essa estratificação naturalmente — basta definir CacheControl nos blocos que você quer cachear.

7. Conector MCP

O Model Context Protocol deixa o Claude conversar com servidores remotos de tools sem você ter de embrulhar cada tool à mão. Aponte o componente para uma URL de servidor MCP e o Claude consegue descobrir as tools, chamá-las e encadear os resultados.

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);

Combine o conector MCP com seu próprio TsgcAI_MCP_Server (coberto em um tutorial à parte) e você tem um agente totalmente nativo em Delphi que expõe suas APIs de domínio para qualquer cliente de IA com suporte a MCP — Claude Desktop, Cursor, Continue, seus próprios apps, qualquer coisa que fale o protocolo. Autenticação é responsabilidade sua: passe um bearer token ou cabeçalho assinado e valide no lado servidor. A Anthropic não vê suas credenciais — o handshake do conector MCP roteia o token da requisição para o servidor alvo.

Para deployments SaaS multi-tenant, o padrão típico é um servidor MCP por tenant, com o tenant ID embutido na URL ou no bearer token. O Claude chama as tools de cada tenant sem nunca contaminar dados entre eles. Já vimos deployments em produção espalharem para 200+ servidores MCP a partir de uma única conversa.

Checklist de produção

Antes de jogar uma aplicação Delphi com Anthropic em produção, passe por esta lista curta:

Preocupação	Como tratar
Armazenamento da chave de API	Variável de ambiente ou secret store do SO, nunca hard-coded
Retries em 429 / 529	Backoff exponencial com jitter, máximo de 3 tentativas
Tetos de custo	Acompanhe Usage por requisição, recuse novas chamadas após o orçamento diário
Redação de PII	Remova e-mails/CPF/cartões antes de enviar para a API
Pin de versão de modelo	Use nomes de modelo com data completa; não dependa de aliases “latest”
Versionamento de prompts	Mantenha system prompts no controle de versão junto com o código
Telemetria	Logue modelo, tokens de entrada, tokens de saída e latência por chamada

Próximos passos

Este tutorial cobriu as oito features que você precisa em 95% das vezes. O componente também suporta message batches (processamento assíncrono barato de milhares de prompts — 50% mais barato que chamadas síncronas, ideal para jobs noturnos de enriquecimento), a Files API (upload uma vez, referencie para sempre — perfeita para PDFs grandes que você consulta repetidamente), contagem de tokens (estime custos antes de pagar) e saídas JSON estruturadas (conformidade forçada a um schema, fim dos erros de parse). Navegue pela página do componente Anthropic para a matriz completa de recursos e visite o hub Primeiros Passos se ainda não instalou o sgcWebSockets.

E se você construir algo interessante com o Claude em Delphi — um agente, um copiloto, um analisador de documentos — conte para a gente. Adoramos ver o que desenvolvedores Pascal fazem quando a fricção da IA desaparece.