메인 콘텐츠로 건너뛰기
할일 추적은 작업을 관리하고 사용자에게 진행 상황을 표시하는 구조화된 방법을 제공합니다. Claude Agent SDK에는 복잡한 워크플로우를 구성하고 사용자에게 작업 진행 상황을 알리는 데 도움이 되는 기본 제공 할일 기능이 포함되어 있습니다.
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을 설정합니다.

할일 생명주기

할일은 예측 가능한 생명주기를 따릅니다:
  1. 생성됨 - 작업이 식별될 때 pending으로 생성됨
  2. 활성화됨 - 작업이 시작될 때 in_progress로 활성화됨
  3. 완료됨 - 작업이 성공적으로 완료될 때
  4. 제거됨 - 그룹의 모든 작업이 완료될 때

할일이 사용되는 경우

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로 분할하며, TaskListTaskGet은 모델이 현재 목록을 다시 읽을 수 있도록 사용 가능합니다. 모니터링 코드는 여전히 어시스턴트 스트림의 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_idtaskId로, active_formactiveForm으로 매핑하지만, 이 수정은 스트림에 반영되지 않습니다. 아래 샘플처럼 TaskUpdate 입력 필드를 방어적으로 읽으십시오. 정규 이름이 항상 존재한다고 가정하지 마십시오.