Elenchi Todo
Traccia e visualizza i todo utilizzando Claude Agent SDK per una gestione organizzata delle attività
Il tracciamento dei todo fornisce un modo strutturato per gestire le attività e visualizzare i progressi agli utenti. Claude Agent SDK include funzionalità todo integrate che aiutano a organizzare flussi di lavoro complessi e mantengono gli utenti informati sulla progressione delle attività.
Ciclo di vita dei Todo
I todo seguono un ciclo di vita prevedibile:
- Creati come
pendingquando le attività vengono identificate - Attivati a
in_progressquando il lavoro inizia - Completati quando l'attività termina con successo
- Rimossi quando tutte le attività in un gruppo sono completate
Quando vengono utilizzati i Todo
L'SDK crea automaticamente todo per:
- Attività complesse multi-step che richiedono 3 o più azioni distinte
- Elenchi di attività forniti dall'utente quando vengono menzionati più elementi
- Operazioni non banali che traggono beneficio dal tracciamento dei progressi
- Richieste esplicite quando gli utenti chiedono l'organizzazione dei todo
Esempi
Monitoraggio dei cambiamenti dei Todo
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Optimize my React app performance and track progress with todos",
// Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
// Task tools instead and these tool_use blocks never appear.
options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
})) {
// Todo updates are reflected in the message stream
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use" && block.name === "TodoWrite") {
const todos = block.input.todos;
console.log("Todo Status Update:");
todos.forEach((todo, index) => {
const status =
todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
console.log(`${index + 1}. ${status} ${todo.content}`);
});
}
}
}
}
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
async for message in query(
prompt="Optimize my React app performance and track progress with todos",
# Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
# Task tools instead and these tool_use blocks never appear.
options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),
):
# Todo updates are reflected in the message stream
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
todos = block.input["todos"]
print("Todo Status Update:")
for i, todo in enumerate(todos):
status = (
"✅"
if todo["status"] == "completed"
else "🔧"
if todo["status"] == "in_progress"
else "❌"
)
print(f"{i + 1}. {status} {todo['content']}")
Visualizzazione dei progressi in tempo reale
import { query } from "@anthropic-ai/claude-agent-sdk";
class TodoTracker {
private todos: any[] = [];
displayProgress() {
if (this.todos.length === 0) return;
const completed = this.todos.filter((t) => t.status === "completed").length;
const inProgress = this.todos.filter((t) => t.status === "in_progress").length;
const total = this.todos.length;
console.log(`\nProgress: ${completed}/${total} completed`);
console.log(`Currently working on: ${inProgress} task(s)\n`);
this.todos.forEach((todo, index) => {
const icon =
todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
console.log(`${index + 1}. ${icon} ${text}`);
});
}
async trackQuery(prompt: string) {
for await (const message of query({
prompt,
// Re-enable TodoWrite, which this tracker watches for.
options: { maxTurns: 20, 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") {
this.todos = block.input.todos;
this.displayProgress();
}
}
}
}
}
}
// Usage
const tracker = new TodoTracker();
await tracker.trackQuery("Build a complete authentication system with todos");
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
from typing import List, Dict
class TodoTracker:
def __init__(self):
self.todos: List[Dict] = []
def display_progress(self):
if not self.todos:
return
completed = len([t for t in self.todos if t["status"] == "completed"])
in_progress = len([t for t in self.todos if t["status"] == "in_progress"])
total = len(self.todos)
print(f"\nProgress: {completed}/{total} completed")
print(f"Currently working on: {in_progress} task(s)\n")
for i, todo in enumerate(self.todos):
icon = (
"✅"
if todo["status"] == "completed"
else "🔧"
if todo["status"] == "in_progress"
else "❌"
)
text = (
todo["activeForm"]
if todo["status"] == "in_progress"
else todo["content"]
)
print(f"{i + 1}. {icon} {text}")
async def track_query(self, prompt: str):
async for message in query(
prompt=prompt,
# Re-enable TodoWrite, which this tracker watches for.
options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
self.todos = block.input["todos"]
self.display_progress()
# Usage
tracker = TodoTracker()
await tracker.track_query("Build a complete authentication system with todos")
Migrazione ai tool Task
I tool Task dividono la singola chiamata TodoWrite in TaskCreate per ogni nuovo elemento e TaskUpdate per ogni cambio di stato, con TaskList e TaskGet disponibili affinché il modello possa leggere di nuovo l'elenco corrente. Il codice di monitoraggio continua a ispezionare i blocchi tool_use nel flusso dell'assistente, ma mantiene una mappa con chiave dell'ID attività invece di sostituire l'intero elenco ad ogni chiamata. {/* min-version: 2.1.142 */}I tool Task sono l'impostazione predefinita a partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, quindi non è necessario alcun cambio options.env.
Con TodoWrite |
Con tool Task |
|---|---|
Una chiamata di tool riscrive l'intero array todos |
TaskCreate aggiunge un elemento, TaskUpdate modifica un elemento per taskId |
Corrisponde a block.name === "TodoWrite" |
Corrisponde a block.name === "TaskCreate" o "TaskUpdate" |
Forma dell'elemento: { content, status, activeForm } |
Input TaskCreate: { subject, description, activeForm?, metadata? }. Input TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status è "pending", "in_progress" o "completed"; impostare status: "deleted" per eliminare |
Renderizza block.input.todos direttamente |
Accumula elementi tra le chiamate, o leggi uno snapshot da un risultato dello strumento TaskList |
L'ID attività assegnato non è nell'input TaskCreate. Ritorna nel tool_result corrispondente come { task: { id, subject } }, quindi acquisiscilo dal blocco del risultato per inserire la chiave nella mappa. L'esempio seguente mostra il cambio minimo al ciclo Monitoraggio dei cambiamenti dei Todo. Per renderizzare un elenco completo, guarda un risultato dello strumento TaskList nel flusso o accumula i risultati TaskCreate e gli input TaskUpdate in una mappa:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Optimize my React app performance",
})) {
if (message.type !== "assistant") continue;
for (const block of message.message.content) {
if (block.type !== "tool_use") continue;
if (block.name === "TaskCreate") {
const input = block.input as { subject: string };
console.log(`+ ${input.subject}`);
} else if (block.name === "TaskUpdate") {
const input = block.input as { taskId: string; status?: string };
if (input.status) console.log(` ${input.taskId} -> ${input.status}`);
}
}
}
from claude_agent_sdk import query, AssistantMessage, ToolUseBlock
async for message in query(
prompt="Optimize my React app performance",
):
if not isinstance(message, AssistantMessage):
continue
for block in message.content:
if not isinstance(block, ToolUseBlock):
continue
if block.name == "TaskCreate":
print(f"+ {block.input['subject']}")
elif block.name == "TaskUpdate" and block.input.get("status"):
print(f" {block.input['taskId']} -> {block.input['status']}")