모델 가용성
다음 도구는 Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5 및 이전 모델에서만 기본적으로 사용 가능합니다. 다른 모든 모델(Claude Code가 인식하지 못하는 모델 ID 포함)에서는 옵트인하지 않는 한 사용할 수 없습니다:
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
CLAUDE_CODE_ENABLE_TASKS=0을 설정할 때 TodoWrite를 대신 제공합니다.이 기본 집합은 Claude Code v2.1.268 이상에 적용되며, TypeScript Agent SDK는 v0.3.268부터 이를 번들로 제공합니다.tool_use 블록을 볼 수 없습니다. Agent SDK는 번들된 Claude Code 바이너리를 통해 이러한 기본값을 적용합니다. pathToClaudeCodeExecutable(TypeScript) 또는 cli_path(Python)를 자신의 Claude Code 설치로 지정하면 해당 설치가 제공하는 도구를 자체 기본값에 따라 얻습니다. 실행 중인 세션에서 정확한 집합을 보려면 사용 가능한 도구 확인을 참조하십시오. 세션을 옵트인하려면 다음 중 하나를 수행하십시오:
allowedTools(TypeScript) 또는allowed_tools(Python) 옵션에서 도구 중 하나의 이름을 지정합니다tools옵션에 도구를 나열합니다. 이는 세션의 기본 제공 도구를 이름이 지정된 도구로 제한합니다. 사용하는 다른 기본 제공 도구와 함께 원하는 도구를 포함합니다- 이 페이지의 예제처럼
env옵션에서CLAUDE_CODE_ENABLE_TODO_TOOLS=1을 설정합니다. TypeScript에서env는 서브프로세스 환경을 대체하므로...process.env를 전개하여 상속된 변수를 유지합니다. Python에서env는 상속된 환경 위에 병합됩니다
할일 생명주기
Claude는 각 할일을 예측 가능한 생명주기를 통해 이동합니다:- 생성됨: Claude가 작업을 식별할 때 할일을
pending으로 추가합니다 - 활성화됨: Claude가 작업을 시작할 때 할일을
in_progress로 설정합니다 - 완료됨: Claude가 작업이 성공적으로 완료되었을 때 표시합니다
- 제거됨: Claude가 더 이상 필요하지 않은 할일을
TaskUpdate호출에서status: "deleted"를 설정하여 삭제합니다
Claude가 할일을 생성하는 경우
작업 추적 도구가 있는 세션에서 Claude는 다음과 같은 대부분의 다단계 작업에 대해 할일을 생성합니다:- 복잡한 다단계 작업 - 3개 이상의 서로 다른 작업이 필요한 경우
- 사용자 제공 작업 목록 - 여러 항목이 언급될 때
- 더 긴 작업 - 진행 상황 추적이 도움이 되는 경우
- 명시적 요청 - 사용자가 할일 구성을 요청할 때
예제
이 예제들을 실행하기 전에 빠른 시작을 따라 Claude Agent SDK를 설치하십시오. 이 페이지의 모든 예제는 동일한 권한 설정 및 종료 동작을 공유합니다:- 권한 모드: 예제 프롬프트는 Claude에게 프로젝트에서 실제 작업을 수행하도록 요청하므로 각 예제는
permissionMode: "acceptEdits"(TypeScript) 또는permission_mode="acceptEdits"(Python)를 설정하여 작업이 생성하는 파일 편집을 자동 승인합니다. 권한 모드에서 대안을 참조하십시오. - 턴 제한: 각 예제는 에이전트가 완료되고 최종 결과 메시지를 생성할 때까지 실행됩니다. 세션이 먼저 턴 제한에 도달하면 해당 결과 메시지는
error_max_turns서브타입을 가집니다. 해당 종료를 감지하려면subtype을 확인하십시오. - 오류 처리: 이 예제들은 단일
query()호출을 사용합니다.error_max_turns결과를 생성한 후query()는Reached maximum number of turns를 포함하는 오류를 발생시킵니다. 각 예제는 이것이 발생할 때 깔끔하게 종료하기 위해 루프를 try 블록으로 래핑합니다. 결과 서브타입에 대해서는 결과 처리를 참조하십시오.
작업 시스템 메시지인
SDKTaskNotificationMessage(TypeScript) 또는 TaskNotificationMessage(Python)는 백그라운드 명령 및 서브에이전트와 같은 백그라운드 작업을 보고합니다. 메시지 스트림에서 할일 활동을 어시스턴트 메시지의 tool_use 블록으로 볼 수 있습니다.할일 변경 모니터링
다음 예제는 어시스턴트 스트림에서TaskCreate 및 TaskUpdate tool_use 블록을 감시하고 각 새 작업의 주제와 함께 + 줄을 인쇄하며 각 상태 변경의 작업 ID와 새 상태와 함께 업데이트 줄을 인쇄합니다. 렌더링된 표시 대신 작업 활동의 로그를 원할 때 이 형태를 사용하십시오. + 줄에는 할당된 ID가 포함되지 않으므로 이 로그는 업데이트를 생성과 다시 일치시킬 수 없습니다. 해당 상관관계를 유지하려면 실시간 진행 상황 표시처럼 ID를 캡처하십시오.
스트리밍된 tool_use 입력은 모델이 내보낸 원본 형태입니다. Claude Code는 실행 전에 일부 거의 올바른 키 이름을 수정하여 id 또는 task_id를 taskId로, active_form을 activeForm으로 매핑하지만, 이 수정은 스트림에 반영되지 않습니다. 이 페이지의 두 예제처럼 TaskUpdate 입력 필드를 방어적으로 읽으십시오. 정규 이름이 항상 존재한다고 가정하지 마십시오.
실시간 진행 상황 표시
다음 예제는 어시스턴트 스트림에서TaskCreate 및 TaskUpdate tool_use 블록을 감시하고 TaskTracker 클래스에서 작업 ID로 키가 지정된 작업 맵을 유지하며 모든 변경에서 진행 상황 요약을 다시 렌더링합니다. 요약은 완료되고 진행 중인 작업을 계산하고 각 활성 항목의 activeForm 레이블을 subject 대신 표시합니다. 애플리케이션이 각 이벤트를 기록하는 대신 진행 상황 표시를 유지할 때 이 형태를 사용하십시오.
할당된 작업 ID는 TaskCreate 입력에 없습니다. Claude Code는 각 도구의 구조화된 출력을 tool_result 블록을 포함하는 사용자 메시지에서 tool_use_result 필드로 전달합니다. TaskCreate의 경우 해당 객체는 TypeScript의 도구 출력 유형 아래 TaskCreateOutput으로 문서화되며, Python에서 필드는 동일한 형태의 일반 dict입니다. 추적기는 tool_use_id로 각 tool_result 블록을 해당 tool_use 호출과 쌍을 이루고 쌍을 이룬 메시지의 tool_use_result에서 task.id를 읽습니다. Claude는 TaskList로 목록을 다시 읽을 수 있고 TaskGet으로 한 작업의 전체 세부 정보를 읽을 수 있습니다.
관련 문서
- Agent SDK 참고 - TypeScript: TypeScript SDK의 옵션, 유형 및 도구 스키마(작업 도구 입력 및 출력 유형 포함)
- Agent SDK 참고 - Python: Python SDK의 옵션, 유형 및 도구 문서
- 스트리밍 입력: 두 입력 모드 및 이 예제들이 사용하는 단일 샷 호출 대신 스트리밍 입력을 사용할 때
- Claude에 사용자 정의 도구 제공: SDK의 인프로세스 MCP 서버로 자신의 도구를 정의합니다