Agent SDK Todo/Task 추적
공식 기준: https://code.claude.com/docs/en/agent-sdk/todo-tracking
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Todo 추적은 복잡한 워크플로 진행을 사용자에게 보여 줍니다. TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 세션은 TodoWrite 대신 구조화 Task 도구 TaskCreate, TaskUpdate, TaskGet, TaskList를 사용합니다. Python SDK는 패키지 버전이 아니라 실행하는 CLI가 v2.1.142+일 때 전환됩니다.
레거시 TodoWrite 예제를 보려면 CLAUDE_CODE_ENABLE_TASKS=0을 설정합니다.
핵심 개념
Todo 수명주기
pending생성in_progress활성화completed완료- 그룹 완료 시 제거
생성 시점
- 3단계 이상 복합 작업
- 사용자가 여러 항목을 나열
- 진행 추적이 유용한 non-trivial 작업
- 사용자가 명시적으로 todo 조직 요청
아주 짧거나 단일 단계 요청은 건너뛸 수 있습니다.
상세
TodoWrite 모니터링 (레거시 호환)
import { query } from "@anthropic-ai/claude-agent-sdk";
try {
for await (const message of query({
prompt: "Optimize my React app performance and track progress with todos",
options: {
maxTurns: 15,
env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" }
}
})) {
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use" && block.name === "TodoWrite") {
for (const todo of block.input.todos) {
console.log(todo.status, todo.content);
}
}
}
}
}
} catch (error) {
console.log(`Session ended with an error: ${error}`);
}
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
import asyncio
async def main():
try:
async for message in query(
prompt="Optimize my React app performance and track progress with todos",
options=ClaudeAgentOptions(
max_turns=15,
env={"CLAUDE_CODE_ENABLE_TASKS": "0"},
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
for todo in block.input["todos"]:
print(todo["status"], todo["content"])
except Exception as e:
print(f"Session ended with an error: {e}")
asyncio.run(main())
Task 도구로 마이그레이션
모니터링 코드에서 TodoWrite 대신 TaskCreate/TaskUpdate/TaskList tool_use 블록을 파싱하세요. UI는 task id·status·content를 동일하게 표시할 수 있습니다. CLI v2.1.142+ 번들 여부를 확인하세요.
결과 처리
error_max_turns 등 오류 종료 시 single-shot query()가 throw할 수 있습니다. subtype을 검사하고 try/catch로 종료하세요.
체크리스트
- CLI/SDK 버전이 Task tools 전환점인지 확인
- UI 파서가 TodoWrite 또는 Task*를 모두 처리
- 레거시 데모만
CLAUDE_CODE_ENABLE_TASKS=0사용 - maxTurns 오류를 우아하게 처리