가이드

스트리밍 입력

Claude Agent SDK의 두 가지 입력 모드와 각각을 언제 사용해야 하는지 이해하기

개요

Claude Agent SDK는 에이전트와 상호작용하기 위한 두 가지 별개의 입력 모드를 지원합니다:

스트리밍 입력 모드 (기본값 및 권장) - 지속적이고 상호작용적인 세션
단일 메시지 입력 - 세션 상태와 재개를 사용하는 일회성 쿼리

이 가이드는 각 모드의 차이점, 이점, 사용 사례를 설명하여 애플리케이션에 적합한 접근 방식을 선택하는 데 도움을 줍니다.

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

스트리밍 입력 모드는 Claude Agent SDK를 사용하는 선호되는 방법입니다. 에이전트의 모든 기능에 대한 완전한 액세스를 제공하고 풍부하고 상호작용적인 경험을 가능하게 합니다.

이를 통해 에이전트는 사용자 입력을 받고, 중단을 처리하고, 권한 요청을 표시하고, 세션 관리를 처리하는 장기 실행 프로세스로 작동할 수 있습니다.

작동 방식

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
    participant App as Your Application
    participant Agent as Claude Agent
    participant Tools as Tools/Hooks
    participant FS as Environment/<br/>File System
    
    App->>Agent: Initialize with AsyncGenerator
    activate Agent
    
    App->>Agent: Yield Message 1
    Agent->>Tools: Execute tools
    Tools->>FS: Read files
    FS-->>Tools: File contents
    Tools->>FS: Write/Edit files
    FS-->>Tools: Success/Error
    Agent-->>App: Stream partial response
    Agent-->>App: Stream more content...
    Agent->>App: Complete Message 1
    
    App->>Agent: Yield Message 2 + Image
    Agent->>Tools: Process image & execute
    Tools->>FS: Access filesystem
    FS-->>Tools: Operation results
    Agent-->>App: Stream response 2
    
    App->>Agent: Queue Message 3
    App->>Agent: Interrupt/Cancel
    Agent->>App: Handle interruption
    
    Note over App,Agent: Session stays alive
    Note over Tools,FS: Persistent file system<br/>state maintained
    
    deactivate Agent

이점

이미지 업로드

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

대기열 메시지

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

도구 통합

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

훅 지원

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

실시간 피드백

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

컨텍스트 지속성

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

구현 예제

import { query } from "@anthropic-ai/claude-agent-sdk";
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-agent-sdk";

// 간단한 일회성 쿼리
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);
  }
}

가이드

스트리밍 입력

Claude Agent SDK의 두 가지 입력 모드와 각각을 언제 사용해야 하는지 이해하기

개요

Claude Agent SDK는 에이전트와 상호작용하기 위한 두 가지 별개의 입력 모드를 지원합니다:

스트리밍 입력 모드 (기본값 및 권장) - 지속적이고 상호작용적인 세션
단일 메시지 입력 - 세션 상태와 재개를 사용하는 일회성 쿼리

이 가이드는 각 모드의 차이점, 이점, 사용 사례를 설명하여 애플리케이션에 적합한 접근 방식을 선택하는 데 도움을 줍니다.

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

작동 방식

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
    participant App as Your Application
    participant Agent as Claude Agent
    participant Tools as Tools/Hooks
    participant FS as Environment/<br/>File System
    
    App->>Agent: Initialize with AsyncGenerator
    activate Agent
    
    App->>Agent: Yield Message 1
    Agent->>Tools: Execute tools
    Tools->>FS: Read files
    FS-->>Tools: File contents
    Tools->>FS: Write/Edit files
    FS-->>Tools: Success/Error
    Agent-->>App: Stream partial response
    Agent-->>App: Stream more content...
    Agent->>App: Complete Message 1
    
    App->>Agent: Yield Message 2 + Image
    Agent->>Tools: Process image & execute
    Tools->>FS: Access filesystem
    FS-->>Tools: Operation results
    Agent-->>App: Stream response 2
    
    App->>Agent: Queue Message 3
    App->>Agent: Interrupt/Cancel
    Agent->>App: Handle interruption
    
    Note over App,Agent: Session stays alive
    Note over Tools,FS: Persistent file system<br/>state maintained
    
    deactivate Agent

이점

이미지 업로드

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

대기열 메시지

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

도구 통합

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

훅 지원

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

실시간 피드백

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

컨텍스트 지속성

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

구현 예제

import { query } from "@anthropic-ai/claude-agent-sdk";
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-agent-sdk";

// 간단한 일회성 쿼리
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);
  }
}