TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 세션은
TodoWrite 대신 구조화된 Task 도구인 TaskCreate, TaskUpdate, TaskGet, TaskList를 사용합니다. Python SDK는 Python 패키지 버전이 아닌 실행하는 Claude Code CLI에서 이 변경 사항을 가져옵니다. pip 패키지 내에 번들된 CLI 또는 cli_path로 지정한 CLI가 v2.1.142 이상이면 전환이 적용됩니다. 모니터링 코드 변경 방법은 Task 도구로 마이그레이션을 참조하십시오. 이 페이지의 예제는 아직 마이그레이션하지 않은 세션에 대해 TodoWrite를 계속 표시하기 위해 CLAUDE_CODE_ENABLE_TASKS=0을 설정합니다.할일 생명주기
할일은 예측 가능한 생명주기를 따릅니다:- 생성됨 - 작업이 식별될 때
pending으로 생성됨 - 활성화됨 - 작업이 시작될 때
in_progress로 활성화됨 - 완료됨 - 작업이 성공적으로 완료될 때
- 제거됨 - 그룹의 모든 작업이 완료될 때
할일이 사용되는 경우
SDK는 대부분의 다단계 작업에 대해 할일을 생성합니다. 예를 들면:- 복잡한 다단계 작업 - 3개 이상의 서로 다른 작업이 필요한 경우
- 사용자 제공 작업 목록 - 여러 항목이 언급될 때
- 중요한 작업 - 진행 상황 추적이 도움이 되는 경우
- 명시적 요청 - 사용자가 할일 구성을 요청할 때
예제
이 예제들을 실행하기 전에 빠른 시작을 따라 Claude Agent SDK를 설치하십시오. 각 예제는 에이전트가 완료될 때까지 실행되고 최종 결과 메시지를 생성합니다. 세션이 먼저 턴 제한에 도달하면 해당 결과 메시지는error_max_turns 서브타입을 가집니다. 해당 종료를 감지하려면 subtype을 확인하십시오.
이 예제들은 단일 query() 호출을 사용합니다. error_max_turns 결과를 생성한 후 query()는 Reached maximum number of turns를 포함하는 오류를 발생시킵니다. 각 예제는 이것이 발생할 때 깔끔하게 종료하기 위해 루프를 try 블록으로 래핑합니다.
결과 서브타입에 대해서는 결과 처리를 참조하십시오.
할일 변경 모니터링
실시간 진행 상황 표시
Task 도구로 마이그레이션
Task 도구는 단일TodoWrite 호출을 각 새 항목에 대한 TaskCreate와 각 상태 변경에 대한 TaskUpdate로 분할하며, TaskList와 TaskGet은 모델이 현재 목록을 다시 읽을 수 있도록 사용 가능합니다. 모니터링 코드는 여전히 어시스턴트 스트림의 tool_use 블록을 검사하지만, 모든 호출에서 전체 목록을 바꾸는 대신 작업 ID로 키가 지정된 맵을 유지합니다. Task 도구는 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 기본값이므로 options.env 변경이 필요하지 않습니다.
할당된 작업 ID는
TaskCreate 입력에 없습니다. 일치하는 tool_result에서 { task: { id, subject } }로 반환되므로, 맵을 키로 지정하기 위해 결과 블록에서 캡처합니다. 다음 예제는 할일 변경 모니터링 루프에 대한 최소한의 변경을 보여줍니다. 이는 tool_use 입력만 읽고 tool_result 블록에서 ID 캡처를 건너뜁니다. 전체 목록을 렌더링하려면 스트림에서 TaskList 도구 결과를 감시하거나 TaskCreate 결과와 TaskUpdate 입력을 맵으로 누적합니다.
스트리밍된 tool_use 입력은 모델이 내보낸 원본 형태입니다. Claude Code는 실행 전에 일부 거의 올바른 키 이름을 수정하여 id 또는 task_id를 taskId로, active_form을 activeForm으로 매핑하지만, 이 수정은 스트림에 반영되지 않습니다. 아래 샘플처럼 TaskUpdate 입력 필드를 방어적으로 읽으십시오. 정규 이름이 항상 존재한다고 가정하지 마십시오.