程序包 io.agentscope.core.tool.builtin

类 TodoTools

java.lang.Object
io.agentscope.core.tool.builtin.TodoTools
public class TodoTools extends Object
Built-in task-list tool that lets the agent maintain a structured todo list for the current session, mirroring opencode's todowrite.

The single todo_write tool uses full-list-replace semantics: the model passes the entire updated list every call and the tool rebuilds AgentState.getTasksContext() from it. This is intentionally simpler than a granular create/update/delete surface — the model never has to reason about ids or partial diffs, and the latest complete list is always the source of truth (and is re-surfaced every turn by TaskReminderMiddleware).

The list is persisted automatically: AgentState.tasksContext is part of the agent state that ReActAgent flushes to its AgentStateStore after every call.

This tool is independent from the harness TaskTool (task_output / task_cancel / task_list), which manages background subagent runs — a different layer that this tool neither reads nor writes.

  • 构造器详细资料

    • TodoTools

      public TodoTools()

  • 方法详细资料

    • todoWrite

      @Tool(name="todo_write", description="Create and maintain a structured task list for the current session. Tracks progress,\norganizes multi-step work, and surfaces status to the user. Pass the COMPLETE updated\nlist every call \u2014 this tool replaces the whole list (it does not merge).\n\n## When to use\nUse proactively when:\n- The task needs 3+ distinct steps or actions\n- The work is non-trivial and benefits from planning\n- The user gives multiple tasks (numbered or comma-separated) or asks for a todo list\n- New instructions arrive \u2014 capture them as todos\n- You start a task \u2014 mark it in_progress (only one at a time) before working\n- You finish a task \u2014 mark it completed and add any follow-ups you discovered\n\n## When NOT to use\nSkip when the work is a single straightforward step (<3 trivial steps), or the request\nis purely informational/conversational, or tracking adds no value.\n\n## States\n- pending \u2014 not started\n- in_progress \u2014 actively working (exactly ONE at a time)\n- completed \u2014 finished successfully\n\n## Rules\n- Update status in real time; do not batch completions.\n- Mark completed only after the work is actually done, including any required\n verification \u2014 never based on intent.\n- Keep exactly one task in_progress while work remains.\n- If blocked or partial, keep the task in_progress and add a follow-up todo describing\n the blocker.\n- Items must be specific and actionable; break large work into smaller steps.\n- To drop a task that is no longer needed, simply omit it from the list.\n", stateInjected=true, readOnly=false, concurrencySafe=false) public String todoWrite(@ToolParam(name="todos",description="The COMPLETE updated todo list. Replaces the existing list entirely.") List<TodoTools.TodoItem> todos, AgentState state)
      Replaces the session task list with todos.

      state is auto-injected by the framework (stateInjected = true) and is not part of the model-visible schema.