중지 이유 처리

결과 메시지의 stop_reason 필드는 모델이 생성을 중지한 이유를 알려줍니다. 이는 거부, 최대 토큰 제한 및 기타 종료 조건을 감지하는 권장 방법입니다(스트림 파싱이 필요하지 않습니다).

stop_reason은 스트리밍 활성화 여부와 관계없이 모든 ResultMessage에서 사용할 수 있습니다. include_partial_messages(Python) 또는 includePartialMessages(TypeScript)를 설정할 필요가 없습니다.

stop_reason 읽기

stop_reason 필드는 성공 및 오류 결과 메시지 모두에 존재합니다. 메시지 스트림을 반복한 후 확인하세요:

from claude_agent_sdk import query, ResultMessage
import asyncio

async def check_stop_reason():
    async for message in query(prompt="Write a poem about the ocean"):
        if isinstance(message, ResultMessage):
            print(f"Stop reason: {message.stop_reason}")
            if message.stop_reason == "refusal":
                print("The model declined this request.")

asyncio.run(check_stop_reason())

사용 가능한 중지 이유

중지 이유	의미
`end_turn`	모델이 정상적으로 응답 생성을 완료했습니다.
`max_tokens`	응답이 최대 출력 토큰 제한에 도달했습니다.
`stop_sequence`	모델이 구성된 중지 시퀀스를 생성했습니다.
`refusal`	모델이 요청 수행을 거부했습니다.
`tool_use`	모델의 최종 출력이 도구 호출이었습니다. SDK 결과에서는 도구 호출이 결과 반환 전에 일반적으로 실행되므로 이는 드문 경우입니다.
`null`	API 응답을 받지 못했습니다. 예를 들어, 첫 번째 요청 전에 오류가 발생했거나 캐시된 세션에서 결과가 재생된 경우입니다.

오류 결과의 중지 이유

오류 결과(error_max_turns 또는 error_during_execution 등)에도 stop_reason이 포함됩니다. 이 값은 오류가 발생하기 전에 수신된 마지막 어시스턴트 메시지를 반영합니다:

결과 변형	`stop_reason` 값
`success`	최종 어시스턴트 메시지의 중지 이유.
`error_max_turns`	턴 제한에 도달하기 전 마지막 어시스턴트 메시지의 중지 이유.
`error_max_budget_usd`	예산이 초과되기 전 마지막 어시스턴트 메시지의 중지 이유.
`error_max_structured_output_retries`	재시도 제한에 도달하기 전 마지막 어시스턴트 메시지의 중지 이유.
`error_during_execution`	마지막으로 확인된 중지 이유, 또는 API 응답 전에 오류가 발생한 경우 `null`.

거부 감지

stop_reason === "refusal"은 모델이 요청을 거부할 때 이를 감지하는 가장 간단한 방법입니다. 이전에는 거부를 감지하려면 부분 메시지 스트리밍을 활성화하고 StreamEvent 메시지에서 message_delta 이벤트를 수동으로 스캔해야 했습니다. 결과 메시지의 stop_reason을 사용하면 직접 확인할 수 있습니다:

다음 단계

실시간 응답 스트리밍: message_delta를 포함한 원시 API 이벤트를 도착하는 대로 접근
구조화된 출력: 에이전트로부터 타입이 지정된 JSON 응답 받기
비용 및 사용량 추적: 결과 메시지에서 토큰 사용량 및 청구 정보 이해

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio

async def handle_max_turns():
    options = ClaudeAgentOptions(max_turns=3)

    async for message in query(prompt="Refactor this module", options=options):
        if isinstance(message, ResultMessage):
            if message.subtype == "error_max_turns":
                print(f"Hit turn limit. Last stop reason: {message.stop_reason}")
                # stop_reason might be "end_turn" or "tool_use"
                # depending on what the model was doing when the limit hit

asyncio.run(handle_max_turns())

from claude_agent_sdk import query, ResultMessage
import asyncio

async def safe_query(prompt: str):
    async for message in query(prompt=prompt):
        if isinstance(message, ResultMessage):
            if message.stop_reason == "refusal":
                print("Request was declined. Please revise your prompt.")
                return None
            return message.result
    return None

asyncio.run(safe_query("Summarize this article"))