Anthropic Claude en Delphi — Tutorial Completo (2026)

¿Por qué un componente Delphi nativo para Claude?

Anthropic Claude es una de las familias de IA más capaces del mercado, pero todos los ejemplos públicos usan Python o Node. Para los desarrolladores Delphi y C++Builder, llamar a los endpoints REST a mano significa escribir JSON a mano, lidiar con Server-Sent Events, gestionar TLS, manejar rate limits y reescribir boilerplate cada vez que Anthropic lanza una nueva función — lo que hacen aproximadamente cada trimestre. El componente TsgcHTTP_API_Anthropic que se distribuye con sgcWebSockets elimina esa fricción. Es un envoltorio fuertemente tipado sobre toda la superficie Anthropic — mensajes, streaming, visión, tool use, extended thinking, prompt caching, files, batches y el conector Model Context Protocol — que puedes arrastrar a un form y usar desde cualquier aplicación VCL, FMX o consola.

Este tutorial recorre cada capacidad principal con código Delphi funcionando. Al terminar serás capaz de construir un cliente de chat, un analizador de documentos con visión, un ejecutor agéntico de herramientas y un pipeline de producción optimizado en costes. Todos los snippets apuntan a los modelos más recientes claude-sonnet-4-20250514 y claude-opus-4-20250514, y todos funcionan sin cambios desde Delphi 7 hasta Delphi 13.

Una nota rápida sobre filosofía antes de empezar. El componente expone intencionadamente dos superficies. La superficie "rápida" (métodos como _CreateMessage, _CreateMessageStream, _CreateMessageWithImage) acepta unos pocos strings y devuelve un string — perfecto para prototipos, demos y el 80% de las llamadas donde no te importan temperature, top-p, metadata o stop sequences. La superficie "tipada" (clases como TsgcAnthropicClass_Request_Messages y TsgcAnthropicClass_Response_Messages) te da control completo sobre cada parámetro que soporta la API de Anthropic, con tipado fuerte y autocompletado del IDE. Usa la API rápida para aprender; promociona a la API tipada para producción. Mismo componente, dos capas, sin duplicación.

1. Configuración y tu primer mensaje

Añade sgcHTTP_API_Anthropic a tu cláusula uses, crea el componente, establece tu API key (consigue una en console.anthropic.com) y llama a _CreateMessage. Este es el mínimo absoluto para hablar 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;

El componente hace el trabajo pesado: construye el cuerpo JSON de la petición, fija las cabeceras x-api-key y anthropic-version, hace POST a /v1/messages y parsea la respuesta a un string Delphi plano. Si necesitas control completo sobre los parámetros de petición, usa la clase tipada TsgcAnthropicClass_Request_Messages.

Un consejo operativo: nunca incrustes la API key en el binario. Léela de una variable de entorno, una clave del registro o un gestor de secretos. Anthropic ahora escanea GitHub buscando claves filtradas y las revoca automáticamente — no quieres lanzar una actualización a las 6 de la tarde del viernes porque alguien hizo screenshot de tu archivo .pas.

2. Respuestas en streaming con SSE

Las llamadas síncronas están bien para prompts cortos, pero para una UI de chat quieres que los tokens aparezcan según Claude los genera. Anthropic hace streaming de respuestas como Server-Sent Events y el componente las expone a través del 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 detalle que merece la pena notar: el streaming corre en un hilo de fondo, así que actualiza la UI mediante TThread.Synchronize o TThread.Queue en código de producción. El snippet de arriba usa ProcessMessages por brevedad. Otro: el stream SSE envía múltiples tipos de evento en secuencia (message_start, content_block_start, varios content_block_delta, content_block_stop, message_delta, message_stop) y deberías ignorar los que no necesites. El helper SSEExtractText maneja el caso común de extraer el delta de texto de content_block_delta; para estadísticas de uso y razones de parada parseas message_delta directamente.

El streaming es esencial para cualquier UI de chat orientada al usuario — los usuarios perciben como rápida una respuesta que empieza en 400 ms, incluso si la respuesta completa tarda diez segundos. Sin streaming, miran un spinner durante diez segundos y asumen que la app está rota. El coste es idéntico: las peticiones con y sin streaming se facturan igual.

3. Visión — enviando imágenes

Claude puede analizar imágenes JPEG, PNG, GIF y WebP. Las pasas como URL pública o como bytes codificados en base64. El componente expone _CreateMessageWithImage para el caso de URL y la API tipada para todo lo demás.

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 visión es ideal para OCR sobre facturas escaneadas, triaje de capturas de pantalla en tickets de soporte, interpretación de gráficos y cualquier tarea donde un motor OCR determinista tendría problemas con el layout. Cuida el coste de tokens: una imagen 1024x1024 consume aproximadamente 1.600 tokens de entrada. Anthropic redimensiona cualquier cosa mayor de 1568px en el lado largo antes de procesar, así que no tiene sentido subir capturas 4K — redimensiona en tu lado y ahorra el ancho de banda.

Casos prácticos que hemos visto desplegar a tiendas Delphi el último año: extracción de líneas de pedido de PDFs de proveedor demasiado inconsistentes para pipelines tradicionales OCR, clasificación de imágenes médicas en categorías amplias antes de enrutar a software especializado, lectura de valores de contadores en fotos de campo, y triaje de capturas de pantalla de bugs UI en tickets de helpdesk ("¿muestra la captura un problema de layout o un problema de datos?"). En todos los casos la victoria no fue la precisión bruta — fue eliminar la necesidad de escribir y mantener un parser frágil y específico por documento.

4. Tool Use (function calling)

Tool use deja que Claude decida cuándo llamar a tus funciones Pascal. Declaras cada herramienta con un nombre, una descripción y un JSON Schema para sus parámetros. Cuando Claude responde con un bloque tool_use en lugar de texto plano, ejecutas la llamada y devuelves el resultado a la conversación.

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;

Construye flujos agénticos encadenando herramientas: un agente de investigación podría combinar herramientas web_search, read_pdf y send_email. Mantén siempre una guarda iMaxIterations para que un modelo descarriado no pueda bucle infinito. En producción topamos en cinco llamadas de herramienta por turno de usuario por razones de coste; si Claude necesita más, normalmente es señal de que el prompt o el diseño de la herramienta están mal.

El mayor determinante individual de la calidad del tool-calling es el texto de la descripción. Los modelos eligen la herramienta correcta con los argumentos correctos aproximadamente el 99% del tiempo cuando las descripciones son precisas ("Return the current bid/ask for a US ticker symbol. Use this only for equities, not for crypto or FX"); caen quizá al 70% con una descripción vaga ("Get a price"). Dedica el tiempo. Añade ejemplos en la descripción. Indica qué NO hace la herramienta. El tú-del-futuro, depurando una llamada de función alucinada de 0,40 $ a las 11 de la noche, te lo agradecerá.

5. Extended Thinking

Claude 4 introduce un modo de pensamiento donde el modelo razona sobre un problema paso a paso antes de responder. Asignas un presupuesto de pensamiento en tokens y Claude devuelve el rastro de razonamiento separado de la respuesta final. Esto es un cambio de juego para matemáticas, revisión de código y análisis multi-paso.

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 extended thinking con moderación — los tokens de razonamiento se facturan como salida, así que un presupuesto de 16k tokens en Opus 4 puede costar fácilmente más que una llamada normal. Resérvalo para problemas donde la corrección importa más que la latencia. Buenos encajes: análisis de documentos legales, conciliación financiera, generación SQL compleja, depuración de stack traces, planificación multi-restricción. Malos encajes: respuestas de chat, clasificación de contenido, búsquedas sencillas — el tiempo y coste de pensamiento no se justifican.

Un truco útil es exponer el rastro de razonamiento en tu UI como una sección colapsable "mostrar pensamiento", como hace la app pública de Claude. A los power users les encanta ver cómo el modelo llegó a la respuesta; los usuarios casuales lo ignoran. En cualquier caso tienes un audit trail gratis.

6. Prompt Caching

Si sigues enviando el mismo prompt de sistema largo, base de conocimiento o definiciones de herramientas, el prompt caching puede recortar costes hasta un 90% y reducir el tiempo al primer token en un 80%. Marcas un bloque de contenido como cacheable; Anthropic lo guarda en su lado durante 5 minutos (o 1 hora con el cache extendido) y sólo te re-factura el precio más barato de cache-read en las llamadas posteriores.

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;

Regla general: cualquier cosa de más de 1.024 tokens que reutilices en cinco minutos merece cachearse. Los grandes corpora de documentación, los ejemplos few-shot y los esquemas de herramientas grandes son los candidatos obvios. La contabilidad: las escrituras de caché cuestan un 25% más que un token de entrada normal, las lecturas de caché cuestan el 10% de un token de entrada normal. Así que llegas al punto de equilibrio tras el segundo hit y empiezas a ahorrar dinero real desde el tercero. Para un bot de soporte al cliente respondiendo 50 preguntas por minuto contra una base de conocimiento de 40k tokens, el prompt caching típicamente recorta la factura mensual de Anthropic entre un 80 y un 85%.

Puedes marcar hasta cuatro bloques de contenido como cacheables por petición. Un patrón común es: herramientas (cacheable, raramente cambia), prompt de sistema (cacheable, raramente cambia), documento grande (cacheable, cambia por sesión), mensajes recientes (NO cacheable, cambia cada turno). El componente maneja esta superposición naturalmente — sólo fija CacheControl en los bloques que quieras cachear.

7. Conector MCP

El Model Context Protocol permite a Claude hablar con servidores remotos de herramientas sin que tengas que envolver cada herramienta a mano. Apunta el componente a una URL de servidor MCP y Claude puede descubrir las herramientas, llamarlas y encadenar los 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);

Combina el conector MCP con tu propio TsgcAI_MCP_Server (cubierto en un tutorial separado) y tienes un agente totalmente nativo Delphi que expone tus APIs de dominio a cualquier cliente IA compatible con MCP — Claude Desktop, Cursor, Continue, tus propias apps, cualquier cosa que hable el protocolo. La autenticación es tu responsabilidad: pasa un bearer token o una cabecera firmada y valida en el lado servidor. Anthropic no ve tus credenciales — el handshake del conector MCP enruta el token de la petición al servidor destino.

Para despliegues multi-tenant SaaS, el patrón típico es un servidor MCP por tenant, con el ID del tenant embebido en la URL o en el bearer token. Claude llama a las herramientas de cada tenant sin contaminar nunca datos entre tenants. Hemos visto despliegues en producción que se abren en abanico a más de 200 servidores MCP desde una sola conversación.

Checklist de producción

Antes de pasar a producción una app Delphi potenciada con Anthropic, repasa esta lista corta:

Preocupación	Cómo manejarla
Almacenamiento de API key	Variable de entorno o almacén de secretos del SO, nunca hardcoded
Reintentos en 429 / 529	Backoff exponencial con jitter, máximo 3 intentos
Techos de coste	Trackea Usage por petición, rechaza llamadas nuevas pasado el presupuesto diario
Redacción de PII	Quita emails/SSN/tarjetas antes de enviar a la API
Fijación de versión de modelo	Usa nombres completos fechados de modelo; no te fíes de los alias "latest"
Versionado de prompt	Guarda los prompts de sistema en control de versiones junto al código
Telemetría	Loguea modelo, tokens entrada, tokens salida, latencia por llamada

Por dónde seguir

Este tutorial cubrió las ocho funciones que necesitas el 95% del tiempo. El componente también soporta message batches (procesamiento async barato de miles de prompts — un 50% más barato que llamadas síncronas, ideal para trabajos nocturnos de enriquecimiento), la Files API (sube una vez, referencia para siempre — perfecto para PDFs grandes que consultas repetidamente), conteo de tokens (estima costes antes de pagar) y salidas JSON estructuradas (conformidad de esquema forzada, no más errores de parse). Navega la página del componente Anthropic para la matriz completa de funciones y dirígete al hub de Primeros Pasos si todavía no has instalado sgcWebSockets.

Y si construyes algo interesante con Claude en Delphi — un agente, un copiloto, un analizador de documentos — cuéntanoslo. Nos encanta ver qué hacen los desarrolladores Pascal una vez que desaparece la fricción de la IA.