任務規劃與 write_todos：讓代理人先想清楚再做事

你有沒有用 AI 做一個稍微複雜的任務，然後到一半發現它在繞圈——把同一件事做了兩次，或者跳過了某個關鍵步驟，然後在結尾偷偷補了一句「你可能還需要自己確認一下 X」？

這不是幻覺，也不是模型不夠強——是代理人在執行任務時，腦子裡沒有一張計畫。它只知道「現在這一步要做什麼」，不知道整個任務有幾步、走到哪了、還有什麼沒完成。

write_todos 就是把這張計畫表外部化的那個工具。

`write_todos` 是什麼

write_todos 是 Deep Agents 的內建工具之一，讓代理人可以：

把任務拆成具體步驟：在開始執行之前，先列出「這個任務需要做哪些事」
追蹤每個步驟的狀態：進行中、已完成、待處理
動態調整計畫：執行過程中如果發現需要加步驟或改順序，可以更新

計畫存在外部——不是靠 context 裡的文字維持。這意味著即使 context 很長、已經離最初的規劃很遠，代理人還是可以回頭看計畫、知道自己走到哪了。

代理人什麼時候會自己呼叫它

你不需要手動呼叫 write_todos——代理人會根據任務的複雜度自己決定要不要先規劃。

一般來說，任務有這些特徵的時候，代理人傾向於先呼叫 write_todos：

有明確的「多個步驟」需要依序完成
後面的步驟依賴前面步驟的結果
任務的範圍比較廣，有多個子目標

反過來，簡單的問答或單步任務，代理人通常不會呼叫 write_todos，直接回應就好。

實際看一下它的執行過程

給一個需要多步驟的任務——

from deepagents import create_deep_agent
 
def read_codebase(path: str) -> str:
    """讀取指定路徑的程式碼檔案。"""
    return f"程式碼內容：{path} 的內容..."
 
def run_tests(test_file: str) -> str:
    """執行測試並回傳結果。"""
    return "測試結果：3 passed, 1 failed"
 
def write_report(content: str, filename: str) -> str:
    """把報告內容寫入檔案。"""
    return f"報告已儲存至 {filename}"
 
agent = create_deep_agent(
    tools=[read_codebase, run_tests, write_report],
    system_prompt="你是一個程式碼審查助理，負責分析程式碼、執行測試、產生報告。",
)
 
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "幫我分析 src/ 目錄下的程式碼品質，執行測試，然後產生一份審查報告存到 review.md"}
    ]
})

這個任務有三個階段——分析、測試、報告。代理人在接到這個請求後，通常會先呼叫 write_todos 把三個步驟記下來，然後逐步執行，每完成一個步驟就更新狀態。

用 streaming 跑可以觀察到這個過程：

for chunk in agent.stream({
    "messages": [
        {"role": "user", "content": "幫我分析程式碼品質..."}
    ]
}):
    # chunk 裡會包含 write_todos 的呼叫和結果
    if "tool_calls" in str(chunk):
        print(chunk)

「先規劃」帶來的實際差距

來比較兩種情境：

沒有規劃的代理人：

接到任務 → 直接開始做第一步 → 做完想下一步 → 做到一半可能想起來還有什麼 → 結尾可能遺漏某些東西 → 用戶自己對比才發現缺了 step 2 的一半

有 write_todos 的代理人：

接到任務 → 先寫出計畫（3 個步驟）→ 執行 step 1（標記完成）→ 執行 step 2（標記完成）→ 執行 step 3（標記完成）→ 確認所有步驟都完成 → 完成

差距不是在速度，是在可靠性——有計畫的代理人不容易跳步，也更容易在中途被打斷後繼續（因為計畫還在）。

在 `system_prompt` 裡引導規劃行為

雖然代理人會自己決定要不要規劃，但你可以透過 system_prompt 影響這個行為：

agent = create_deep_agent(
    tools=[...],
    system_prompt="""你是一個嚴謹的研究助理。
    
    處理任何多步驟任務之前，先用 write_todos 把步驟列清楚，再開始執行。
    每完成一個步驟，更新 todo 狀態，確保沒有遺漏。""",
)

不用把規劃邏輯完全硬塞進 prompt，點明「複雜任務先規劃」這個習慣就夠了。

任務規劃讓 agent 從「衝動型」變成「有條理型」

這個比喻可能有點誇張，但確實接近真實情況：

沒有 write_todos 的代理人更像是一個剛接到需求就立刻開始寫程式的工程師——行動力強，但容易忽略沒想清楚的地方。

有了 write_todos，代理人有機會先停下來說：「好，這個任務有五個步驟，分別是 A、B、C、D、E，我先從 A 開始。」然後有條理地推進。

下一篇要解決的是另一個問題：任務過程中產生的大量資訊要放在哪？

上一篇：Quickstart：5 分鐘建立你的第一個 Deep Agent 下一篇：Filesystem 工具：用檔案管理 Context，不讓 Token 爆炸

write_todos 是什麼