Agent 如何使用 TODO 來規劃任務¶

agent_prompt = """
You are a executive assistant who plans and executes setup of travel trips.
If any details are missing, no need to ask user, just make realistic assumptions directly.
After entire plan is completed, succinctly explain rationale for sequence of actions of the plan.
"""

agent = create_agent(
    system_prompt=agent_prompt,
    model="openai:gpt-5.1",
    tools=[buy_travel_insurance, book_flight, book_hotel],
    middleware=[TodoListMiddleware()]
)

user_input = "Book business trip to Singapore between 20 and 24 Sep 2025 for an AI conference"
response = agent.invoke({"messages": [HumanMessage(user_input)]})

# Show the to-do list generated by the planning agent
print(response["todos"])

class Todo(TypedDict):
    """A single todo item with content and status."""

    content: str
    """The content/description of the todo item."""

    status: Literal["pending", "in_progress", "completed"]
    """The current status of the todo item."""

{
   "content": "Compare flight options from Singapore to Tokyo",
   "status": "completed"
},

class PlanningState(AgentState[Any]):
    """State schema for the todo middleware."""

    todos: Annotated[NotRequired[list[Todo]], OmitFromInput]
    """List of todo items for tracking task progress."""

todos: list[Todo] = [
    {
        "content": "Research visa requirements for Singapore passport holders visiting Japan",
        "status": "completed"
    },
    {
        "content": "Compare flight options from Singapore to Tokyo",
        "status": "in_progress"
    },
    {
        "content": "Book flights and hotels once itinerary is finalized",
        "status": "pending"
    }
]

@tool(description=WRITE_TODOS_TOOL_DESCRIPTION)
def write_todos(
    todos: list[Todo], tool_call_id: Annotated[str, InjectedToolCallId]
) -> Command[Any]:
    """Create and manage a structured task list for your current work session."""
    return Command(
        update={
            "todos": todos,
            "messages": [ToolMessage(f"Updated todo list to {todos}", tool_call_id=tool_call_id)],
        }
    )

WRITE_TODOS_TOOL_DESCRIPTION = """Use this tool to create and manage a structured task list for your current work session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.

Only use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.

## When to Use This Tool
Use this tool in these scenarios:

1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
3. User explicitly requests todo list - When the user directly asks you to use the todo list
4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
5. The plan may need future revisions or updates based on results from the first few steps

## How to Use This Tool
1. When you start working on a task - Mark it as in_progress BEFORE beginning work.
2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.
3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.
4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.

## When NOT to Use This Tool
It is important to skip using this tool when:
1. There is only a single, straightforward task
2. The task is trivial and tracking it provides no benefit
3. The task can be completed in less than 3 trivial steps
4. The task is purely conversational or informational

## Task States and Management

1. **Task States**: Use these states to track progress:
   - pending: Task not yet started
   - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)
   - completed: Task finished successfully

2. **Task Management**:
   - Update task status in real-time as you work
   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
   - Complete current tasks before starting new ones
   - Remove tasks that are no longer relevant from the list entirely
   - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.
   - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress to show the user that you are working on something.

3. **Task Completion Requirements**:
   - ONLY mark a task as completed when you have FULLY accomplished it
   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
   - When blocked, create a new task describing what needs to be resolved
   - Never mark a task as completed if:
     - There are unresolved issues or errors
     - Work is partial or incomplete
     - You encountered blockers that prevent completion
     - You couldn't find necessary resources or dependencies
     - Quality standards haven't been met

4. **Task Breakdown**:
   - Create specific, actionable items
   - Break complex tasks into smaller, manageable steps
   - Use clear, descriptive task names

Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully
Remember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all."""  # noqa: E501

WRITE_TODOS_TOOL_DESCRIPTION = """使用此工具建立和管理目前工作會話的結構化任務清單。這有助於您追蹤進度、組織複雜任務，並向使用者展示您的工作細緻周全。

只有當您認為此工具有助於保持工作條理清晰時才使用它。如果使用者的請求非常簡單，只需不到 3 個步驟即可完成，則最好不要使用此工具，直接執行任務。

## 何時使用此工具

在以下情況下使用此工具：

1. 複雜的多步驟任務 - 當任務需要 3 個或更多不同的步驟或操作時
2. 重要的複雜任務 - 需要仔細規劃或多個操作的任務
3. 使用者明確要求使用待辦事項清單 - 當使用者直接要求您使用待辦事項清單時
4. 使用者提供多個任務 - 當使用者提供待辦事項清單（編號或逗號分隔）時
5. 根據前幾個步驟的結果，計劃可能需要在後續進行修訂或更新

## 如何使用此工具

1. 開始處理任務時 - 請在開始工作前將其標記為「in_progress」。
2. 完成任務後 - 將其標記為“completed”，並新增執行過程中發現的任何後續任務。
3. 您也可以更新未來的任務，例如刪除不再需要的任務，或新增必要的新任務。請勿更改已完成的任務。
4. 您可以一次對待待辦事項清單進行多項更新。例如，完成一項任務後，您可以將下一個需要開始的任務標記為「in_progress」。


## 何時不應使用此工具

以下情況請勿使用此工具：

1. 只有一個簡單直接的任務
2. 任務瑣碎，追蹤它沒有任何意義
3. 任務只需不到 3 個簡單的步驟即可完成
4. 任務純粹是對話或訊息傳遞

## 任務狀態與管理

1. **任務狀態**：使用以下狀態追蹤進度：

- pending：任務尚未開始
- in_progress：目前正在進行中（如果多個任務彼此無關且可以並行運行，則可以同時處於 in_progress 狀態）
- completed：任務已成功完成

2. **任務管理**：

- 工作時即時更新任務狀態
- 任務完成後立即標記為已完成（不要批量完成）
- 完成目前任務後再開始新任務
- 從清單中徹底刪除不再相關的任務
- 重要提示：建立此待辦事項清單時，應立即將第一個（或多個）任務標記為進行中！
- 重要提示：除非所有任務都已完成，否則應始終保留至少一個進行中的任務，以向使用者表明您正在處理某些工作。

3. **任務完成要求**：

- 只有當您完全完成任務時，才將其標記為已完成
- 如果您遇到錯誤、障礙或無法完成任務，請將任務狀態保持為“進行中”
- 如果任務受阻，請建立一個新任務，描述需要解決的問題
- 若出現以下情況，切勿將任務標記為已完成：
    - 存在未解決的問題或錯誤
    - 工作未完成或未完全完成
    - 您遇到了阻礙任務完成的障礙
    - 您找不到必要的資源或依賴項
    - 未達品質標準

4. **任務分解**：

- 建立具體、可執行的任務項
- 將複雜任務分解為更小、更易於管理的步驟
- 使用清晰、描述性的任務名稱

積極主動地進行任務管理，既能展現您的細緻周到，又能確保您順利完成所有要求。

記住：如果完成一項任務只需要呼叫幾個工具，而且您很清楚自己需要做什麼，那麼最好直接執行任務，完全不要呼叫該工具。"""

WRITE_TODOS_SYSTEM_PROMPT = """## `write_todos`

You have access to the `write_todos` tool to help you manage and plan complex objectives.
Use this tool for complex objectives to ensure that you are tracking each necessary step and giving the user visibility into your progress.
This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps.

It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed.
For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool.
Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests.

## Important To-Do List Usage Notes to Remember
- The `write_todos` tool should never be called multiple times in parallel.
- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant."""  # noqa: E501

WRITE_TODOS_SYSTEM_PROMPT = """## `write_todos`

您可以使用 `write_todos` 工具來管理和規劃複雜的目標。
使用此工具規劃複雜目標，確保您追蹤每個必要步驟，並讓使用者了解您的進度。
此工具對於規劃複雜目標以及將這些大型複雜目標分解為較小的步驟非常有用。

完成步驟後，務必立即將待辦事項標記為已完成。不要將多個步驟合併在一起再標記為已完成。
對於只需幾個步驟的簡單目標，最好直接完成目標，而不是使用此工具。
編寫待辦事項需要時間和代幣，僅在需要管理複雜的多步驟問題時才使用它！但對於簡單的幾步任務，不建議使用。

## 待辦事項清單使用注意事項

- 切勿同時多次呼叫 `write_todos` 工具。
- 不要害怕隨時修改待辦事項清單。新的資訊可能會揭示需要完成的新任務，或發現一些無關緊要的舊任務。"""  # noqa: E501

def wrap_model_call(
        self,
        request: ModelRequest,
        handler: Callable[[ModelRequest], ModelResponse],
    ) -> ModelCallResult:
        """Update the system message to include the todo system prompt."""
        if request.system_message is not None:
            new_system_content = [
                *request.system_message.content_blocks,
                {"type": "text", "text": f"\n\n{self.system_prompt}"},
            ]
        else:
            new_system_content = [{"type": "text", "text": self.system_prompt}]
        new_system_message = SystemMessage(
            content=cast("list[str | dict[str, str]]", new_system_content)
        )
        return handler(request.override(system_message=new_system_message))
view raw