query()와 ClaudeSDKClient는 수명으로 골라

한 번 실행과 지속 연결을 나눠

query(prompt, options)는 서브프로세스를 띄워 프롬프트 하나를 끝까지 처리하고 닫는 비동기 생성기야. ClaudeSDKClient(options)는 한 번 연결한 서브프로세스를 살려 두고 여러 메시지를 보내는 장기 클라이언트야. 기능 우열이 아니라 작업 수명의 차이야.

끝이 분명한 작업에는 query()

스크립트와 CI, 배치 변환처럼 일을 하나 끝낸 뒤 프로세스가 내려가도 되는 곳에 잘 맞아. 각 호출이 독립적이므로 상태 정리도 단순해. cwk-site의 빌드 시점 콘텐츠 생성도 이런 일회성 흐름에서 query()를 써.

대화와 운영자에는 지속 클라이언트

여러 메시지가 상태를 공유하는 채팅이나 오래 도는 운영 에이전트에는 ClaudeSDKClient가 맞아. cwkPippa는 conversation_id마다 클라이언트 하나를 유지해 서브프로세스와 대화를 이어 가고, 호출자가 매번 전체 이력을 다시 보내지 않아도 SDK가 내부 상태를 재생해.

원칙: 한 번이면 query(), 오래 이어지면 Client야. 같은 제품 안에서 섞어도 되지만 수명과 반대로 고르지는 마.

Code

query()로 one-shot·python

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def explain_file(path: str):
    options = ClaudeAgentOptions(
        cwd="/Users/me/repo",
        allowed_tools=["Read"],  # 읽기만; 편집 X
    )
    async for event in query(
        prompt=f"Read {path} and write a one-paragraph explanation of what it does.",
        options=options,
    ):
        if hasattr(event, "text"):
            print(event.text, end="")

asyncio.run(explain_file("src/main.py"))

Long-lived ClaudeSDKClient·python

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def chat_session():
    client = ClaudeSDKClient(
        options=ClaudeAgentOptions(
            cwd="/Users/me/repo",
            system_prompt={"type": "preset", "preset": "claude_code"},
        )
    )
    await client.connect()
    try:
        # 멀티턴 대화; SDK가 모든 거 내부적으로 기억.
        async for event in client.send_message("What does this repo do?"):
            print_event(event)
        async for event in client.send_message("Add a CLI flag for verbose output."):
            print_event(event)
    finally:
        await client.disconnect()

asyncio.run(chat_session())

한 번 실행과 지속 연결을 나눠

끝이 분명한 작업에는 query()

대화와 운영자에는 지속 클라이언트

Code

External links

Exercise

Progress

댓글 0