​
개요

Claude Code SDK는 에이전트와 상호작용하기 위한 두 가지 별개의 입력 모드를 지원합니다:
  • 스트리밍 입력 모드 (기본값 및 권장) - 지속적이고 상호작용적인 세션
  • 단일 메시지 입력 - 세션 상태와 재개를 사용하는 일회성 쿼리
이 가이드는 각 모드의 차이점, 장점, 사용 사례를 설명하여 애플리케이션에 적합한 접근 방식을 선택하는 데 도움을 줍니다.

​
스트리밍 입력 모드 (권장)

스트리밍 입력 모드는 Claude Code SDK를 사용하는 선호되는 방법입니다. 에이전트의 모든 기능에 대한 완전한 액세스를 제공하고 풍부하고 상호작용적인 경험을 가능하게 합니다. 이는 에이전트가 사용자 입력을 받고, 중단을 처리하고, 권한 요청을 표면화하고, 세션 관리를 처리하는 장기 실행 프로세스로 작동할 수 있게 합니다.

​
작동 방식

​
장점

이미지 업로드

시각적 분석과 이해를 위해 메시지에 직접 이미지를 첨부

대기열 메시지

순차적으로 처리되는 여러 메시지를 보내고, 중단할 수 있는 기능

도구 통합

세션 중 모든 도구와 사용자 정의 MCP 서버에 대한 완전한 액세스

훅 지원

다양한 지점에서 동작을 사용자 정의하기 위한 라이프사이클 훅 사용

실시간 피드백

최종 결과뿐만 아니라 생성되는 응답을 실시간으로 확인

컨텍스트 지속성

여러 턴에 걸쳐 대화 컨텍스트를 자연스럽게 유지

​
구현 예제

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* generateMessages() {
  // 첫 번째 메시지
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "이 코드베이스의 보안 문제를 분석해주세요"
    }
  };
  
  // 조건이나 사용자 입력을 기다림
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // 이미지와 함께 후속 조치
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "이 아키텍처 다이어그램을 검토해주세요"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// 스트리밍 응답 처리
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

​
단일 메시지 입력

단일 메시지 입력은 더 간단하지만 더 제한적입니다.

​
단일 메시지 입력을 사용해야 하는 경우

다음과 같은 경우에 단일 메시지 입력을 사용하세요:
  • 일회성 응답이 필요한 경우
  • 이미지 첨부, 훅 등이 필요하지 않은 경우
  • 람다 함수와 같은 상태 비저장 환경에서 작동해야 하는 경우

​
제한사항

단일 메시지 입력 모드는 다음을 지원하지 않습니다:
  • 메시지에 직접 이미지 첨부
  • 동적 메시지 대기열
  • 실시간 중단
  • 훅 통합
  • 자연스러운 다중 턴 대화

​
구현 예제

import { query } from "@anthropic-ai/claude-code";

// 간단한 일회성 쿼리
for await (const message of query({
  prompt: "인증 플로우를 설명해주세요",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// 세션 관리와 함께 대화 계속
for await (const message of query({
  prompt: "이제 권한 부여 프로세스를 설명해주세요",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}