Delphi의 Anthropic Claude — 완전한 튜토리얼 (2026)

왜 Claude용 네이티브 Delphi 컴포넌트일까요?

Anthropic Claude는 시장에서 가장 유능한 AI 패밀리 중 하나이지만 모든 공개 예제는 Python 또는 Node를 사용해요. Delphi 및 C++Builder 개발자에게 REST 엔드포인트를 손으로 호출하는 것은 JSON을 손수 만들고, Server-Sent Events를 다루고, TLS를 관리하고, 속도 제한을 처리하고, Anthropic이 새 기능을 출시할 때마다 보일러플레이트를 다시 작성하는 것을 의미해요 — 그들은 대략 분기마다 그렇게 해요. sgcWebSockets와 함께 제공되는 TsgcHTTP_API_Anthropic 컴포넌트가 그 마찰을 제거해요. 메시지, 스트리밍, 비전, 도구 사용, 확장 사고, 프롬프트 캐싱, 파일, 일괄 처리 및 Model Context Protocol 커넥터 — 전체 Anthropic 표면에 대한 강력하게 타입이 지정된 래퍼로, 폼에 드롭하여 모든 VCL, FMX 또는 콘솔 애플리케이션에서 사용할 수 있어요.

이 튜토리얼은 작동하는 Delphi 코드로 모든 주요 기능을 살펴봐요. 끝까지 따르면 채팅 클라이언트, 비전이 활성화된 문서 분석기, 에이전트 도구 러너 및 비용 최적화된 프로덕션 파이프라인을 구축할 수 있을 거예요. 모든 스니펫은 최신 claude-sonnet-4-20250514 및 claude-opus-4-20250514 모델을 대상으로 하며, 모두 Delphi 7부터 Delphi 13까지 변경 없이 실행돼요.

본격적으로 시작하기 전에 철학에 대한 간단한 메모. 컴포넌트는 의도적으로 두 가지 표면을 노출해요. "빠른" 표면(_CreateMessage, _CreateMessageStream, _CreateMessageWithImage와 같은 메서드)은 몇 개의 문자열을 받아 문자열을 반환해요 — 프로토타입, 데모 및 온도, top-p, 메타데이터 또는 정지 시퀀스를 신경 쓰지 않는 호출의 80%에 완벽해요. "타입이 지정된" 표면(TsgcAnthropicClass_Request_Messages 및 TsgcAnthropicClass_Response_Messages와 같은 클래스)은 강력한 타이핑과 IDE 자동 완성으로 Anthropic API가 지원하는 모든 매개변수에 대한 완전한 제어를 제공해요. 빠른 API로 배우고; 프로덕션을 위해 타입이 지정된 API로 승격하세요. 동일한 컴포넌트, 두 계층, 중복 없음.

1. 설정 및 첫 메시지

uses 절에 sgcHTTP_API_Anthropic을 추가하고, 컴포넌트를 생성하고, API 키를 설정하고(console.anthropic.com에서 얻기), _CreateMessage를 호출하세요. 이것이 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;

컴포넌트가 무거운 일을 해요: JSON 요청 본문을 빌드하고, x-api-key 및 anthropic-version 헤더를 설정하고, /v1/messages에 게시하고, 응답을 일반 Delphi 문자열로 파싱해요. 요청 매개변수에 대한 완전한 제어가 필요하면 타입이 지정된 TsgcAnthropicClass_Request_Messages 클래스를 사용하세요.

운영 팁 하나: API 키를 바이너리에 절대 굽지 마세요. 환경 변수, 레지스트리 키 또는 시크릿 매니저에서 읽으세요. Anthropic은 이제 유출된 키에 대해 GitHub를 스캔하고 자동으로 폐기해요 — 누군가 .pas 파일을 스크린샷했기 때문에 금요일 오후 6시에 업데이트를 출시하고 싶지 않을 거예요.

2. SSE로 응답 스트리밍

동기 호출은 짧은 프롬프트에 괜찮지만 채팅 UI의 경우 Claude가 생성할 때 토큰이 나타나기를 원해요. Anthropic은 응답을 Server-Sent Events로 스트리밍하며, 컴포넌트는 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;

주목할 만한 세부 사항 하나: 스트리밍은 백그라운드 스레드에서 실행되므로 프로덕션 코드에서는 TThread.Synchronize 또는 TThread.Queue를 통해 UI를 업데이트하세요. 위 스니펫은 간결성을 위해 ProcessMessages를 사용해요. 또 다른 점: SSE 스트림은 시퀀스로 여러 이벤트 타입(message_start, content_block_start, 반복된 content_block_delta, content_block_stop, message_delta, message_stop)을 보내며 필요하지 않은 것은 무시해야 해요. 헬퍼 SSEExtractText는 content_block_delta에서 텍스트 델타를 가져오는 일반적인 경우를 처리해요; 사용 통계 및 중지 이유의 경우 message_delta를 직접 파싱해요.

스트리밍은 모든 사용자 대면 채팅 UI에 필수예요 — 사용자는 400ms 안에 시작되는 응답을 빠르다고 인식하며, 전체 답변이 10초 걸리더라도 그래요. 스트리밍이 없으면 10초 동안 스피너를 보고 앱이 깨졌다고 가정해요. 비용은 동일해요: 스트리밍과 비스트리밍 요청은 동일하게 청구돼요.

3. 비전 — 이미지 보내기

Claude는 JPEG, PNG, GIF 및 WebP 이미지를 분석할 수 있어요. 공개 URL 또는 base64 인코딩된 바이트로 전달해요. 컴포넌트는 URL 케이스에 _CreateMessageWithImage를 노출하고 다른 모든 것에 대해 타입이 지정된 API를 노출해요.

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;

비전은 스캔된 송장의 OCR, 지원 티켓의 스크린샷 분류, 차트 해석 및 결정적 OCR 엔진이 레이아웃으로 어려움을 겪을 모든 작업에 이상적이에요. 토큰 비용에 주의하세요: 1024x1024 이미지는 약 1,600 입력 토큰을 소비해요. Anthropic은 처리하기 전에 긴 가장자리에서 1568px보다 큰 것은 크기를 조정하므로 4K 스크린샷을 업로드할 필요가 없어요 — 자신의 측에서 다운스케일하고 대역폭을 절약하세요.

지난해에 Delphi 회사들이 출시하는 것을 본 실용적인 사용 사례: 전통적인 OCR 파이프라인에 너무 일관성이 없는 공급업체 PDF에서 라인 항목 추출, 전문 소프트웨어로 라우팅하기 전에 의료 이미지를 광범위한 범주로 분류, 현장 서비스 사진에서 미터 값 읽기, 헬프데스크 티켓에서 UI 버그 스크린샷 분류("스크린샷이 레이아웃 문제를 보여주나요 데이터 문제를 보여주나요?"). 모든 경우에 승리는 원시 정확도가 아니라 — 깨지기 쉬운 문서별 파서를 작성하고 유지 관리할 필요를 제거하는 것이었어요.

4. 도구 사용 (함수 호출)

도구 사용을 통해 Claude는 Pascal 함수를 호출할 시점을 결정할 수 있어요. 각 도구를 이름, 설명 및 매개변수에 대한 JSON 스키마로 선언해요. Claude가 일반 텍스트 대신 tool_use 블록으로 응답하면 호출을 실행하고 결과를 대화로 다시 공급해요.

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;

도구를 연결하여 에이전트 워크플로를 구축하세요: 연구 에이전트는 web_search, read_pdf 및 send_email 도구를 결합할 수 있어요. 항상 잘못 작동하는 모델이 영원히 반복할 수 없도록 iMaxIterations 가드를 유지하세요. 프로덕션에서는 비용 이유로 사용자 턴당 다섯 번의 도구 호출로 캡해요; Claude가 더 많이 필요하면 일반적으로 프롬프트 또는 도구 디자인이 잘못되었다는 신호예요.

도구 호출 품질의 가장 큰 결정 요인은 설명 텍스트예요. 설명이 정확할 때("미국 티커 심볼에 대한 현재 매수/매도가 반환. 주식에만 사용하고 암호화폐 또는 FX에는 사용하지 마세요") 모델은 약 99% 시간에 올바른 인수로 올바른 도구를 선택해요; 모호한 설명("가격 가져오기")에서는 약 70%로 떨어져요. 시간을 들이세요. 설명에 예제를 추가하세요. 도구가 무엇을 하지 않는지 명시하세요. 오후 11시에 $0.40 환각 함수 호출을 디버깅하는 미래의 자신이 현재의 자신에게 감사할 거예요.

5. 확장 사고

Claude 4는 모델이 답변하기 전에 문제를 단계별로 추론하는 사고 모드를 도입해요. 토큰에서 사고 예산을 할당하고 Claude는 최종 답변과 별도로 추론 추적을 반환해요. 이것은 수학, 코드 리뷰 및 다단계 분석의 게임 체인저예요.

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;

확장 사고를 아껴서 사용하세요 — 추론 토큰은 출력으로 청구되므로 Opus 4의 16k 토큰 사고 예산은 일반 호출보다 쉽게 더 많이 들 수 있어요. 정확성이 지연 시간보다 더 중요한 문제에 대해 예약하세요. 좋은 적합: 법률 문서 분석, 재무 조정, 복잡한 SQL 생성, 스택 트레이스 디버깅, 다중 제약 일정. 나쁜 적합: 채팅 응답, 콘텐츠 분류, 간단한 조회 — 사고 시간과 비용이 정당화되지 않아요.

유용한 트릭은 공개 Claude 앱처럼 UI에서 추론 추적을 접을 수 있는 "사고 표시" 섹션으로 노출하는 것이에요. 파워 유저는 모델이 답변에 도달한 방법을 보는 것을 좋아해요; 일반 사용자는 무시해요. 어느 쪽이든 무료로 감사 추적이 있어요.

6. 프롬프트 캐싱

동일한 긴 시스템 프롬프트, 지식 베이스 또는 도구 정의를 계속 보내는 경우 프롬프트 캐싱은 비용을 최대 90% 절감하고 첫 토큰까지의 시간을 80% 줄일 수 있어요. 콘텐츠 블록을 캐시 가능으로 표시해요; Anthropic은 자신의 측에 5분(또는 확장 캐시로 1시간) 동안 저장하고 후속 호출에서 더 저렴한 캐시 읽기 가격만 재청구해요.

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;

경험 법칙: 5분 내에 재사용하는 1,024 토큰을 초과하는 것은 캐싱할 가치가 있어요. 큰 문서 코퍼스, 몇 샷 예제 및 큰 도구 스키마가 명백한 후보예요. 회계: 캐시 쓰기는 일반 입력 토큰보다 25% 더 비싸고, 캐시 읽기는 일반 입력 토큰의 10%예요. 따라서 두 번째 히트 후 손익 분기점에 도달하고 세 번째부터 실제 돈을 절약하기 시작해요. 40k 토큰 지식 베이스에 대해 분당 50개 질문에 답하는 고객 지원 봇의 경우 프롬프트 캐싱은 일반적으로 월간 Anthropic 청구서를 80–85% 줄여요.

요청당 최대 네 개의 콘텐츠 블록을 캐시 가능으로 표시할 수 있어요. 일반적인 패턴: 도구(캐시 가능, 거의 변경되지 않음), 시스템 프롬프트(캐시 가능, 거의 변경되지 않음), 큰 문서(캐시 가능, 세션별로 변경), 최근 메시지(캐시 가능하지 않음, 매 턴 변경). 컴포넌트는 이 계층화를 자연스럽게 처리해요 — 캐시하려는 블록에 CacheControl을 설정하기만 하세요.

7. MCP 커넥터

Model Context Protocol을 사용하면 Claude가 각 도구를 손으로 래핑하지 않고도 원격 도구 서버와 통신할 수 있어요. 컴포넌트를 MCP 서버 URL로 가리키면 Claude는 도구를 발견하고, 호출하고, 결과를 연결할 수 있어요.

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

MCP 커넥터를 자신의 TsgcAI_MCP_Server(별도의 튜토리얼에서 다룸)와 결합하면 도메인 API를 모든 MCP 인식 AI 클라이언트 — Claude Desktop, Cursor, Continue, 자신의 앱, 프로토콜을 사용하는 모든 것 — 에 노출하는 완전히 Delphi 네이티브 에이전트를 갖게 돼요. 인증은 자신의 책임이에요: 베어러 토큰 또는 서명된 헤더를 전달하고 서버 측에서 검증하세요. Anthropic은 자격 증명을 보지 못해요 — MCP 커넥터 핸드셰이크는 요청에서 대상 서버로 토큰을 라우팅해요.

다중 테넌트 SaaS 배포의 경우 일반적인 패턴은 테넌트당 단일 MCP 서버이며, 테넌트 ID가 URL 또는 베어러 토큰에 임베드되어 있어요. Claude는 데이터를 교차 오염시키지 않고 각 테넌트의 도구를 호출해요. 단일 대화에서 200+ MCP 서버로 팬아웃하는 프로덕션 배포를 본 적이 있어요.

프로덕션 체크리스트

Anthropic 기반 Delphi 앱을 프로덕션으로 전환하기 전에 이 짧은 목록을 살펴보세요:

관심사	처리 방법
API 키 저장	환경 변수 또는 OS 시크릿 저장소, 절대 하드 코딩하지 않음
429 / 529에서 재시도	지터가 있는 지수 백오프, 최대 3회 시도
비용 상한선	요청당 Usage 추적, 일일 예산을 초과하면 새 호출 거부
PII 편집	API로 보내기 전에 이메일/SSN/CC 번호 제거
모델 버전 고정	전체 날짜가 있는 모델 이름 사용; "latest" 별칭에 의존하지 않음
프롬프트 버전 관리	시스템 프롬프트를 코드와 함께 소스 제어에 저장
텔레메트리	호출당 모델, 입력 토큰, 출력 토큰, 지연 시간 로깅

다음 단계

이 튜토리얼은 95% 시간에 필요한 여덟 가지 기능을 다뤘어요. 컴포넌트는 또한 메시지 일괄 처리(수천 개의 프롬프트의 저렴한 비동기 처리 — 동기 호출보다 50% 저렴하며, 야간 보강 작업에 이상적), 파일 API(한 번 업로드, 영원히 참조 — 반복적으로 쿼리하는 큰 PDF에 완벽), 토큰 카운팅(지불하기 전에 비용 추정) 및 구조화된 JSON 출력(강제 스키마 준수, 더 이상 파싱 오류 없음)을 지원해요. 전체 기능 매트릭스에 대해서는 Anthropic 컴포넌트 페이지를 탐색하고 아직 sgcWebSockets를 설치하지 않았다면 시작하기 허브로 이동하세요.

그리고 Delphi에서 Claude로 흥미로운 것을 빌드하면 — 에이전트, 코파일럿, 문서 분석기 — 알려주세요. AI 마찰이 사라지면 Pascal 개발자가 무엇을 하는지 보는 것을 좋아해요.