Todo tool
Дайте агенту задачу из пяти шагов, и он поведёт себя как человек в аврале: схватится за всё сразу, начнёт с третьего пункта, забудет про первый, а в конце бодро отчитается, что «в целом всё готово». Лекарство человечество придумало давно, и оно до обидного простое: список. Одно дело в работе. Доделать. Вычеркнуть. Взять следующее.
Tool todo - это тот самый список, только вживлённый
в агента, с правилом, которое нельзя переубедить обаянием:
одновременно в работе ровно один пункт. Не «постараюсь держать
фокус», а честный отказ на уровне кода.
tools_todo.py с четырьмя действиями:
add, start, complete,
list. Многошаговые задачи раскладываются по списку,
а простой вопрос этот tool вообще не трогает.
Слова, которые встретятся
- in_progress - пункт, над которым агент работает прямо сейчас. Ровно один. Попытка открыть второй заканчивается отказом, а не вежливым «ну ладно, разрешаю».
-
Список в памяти - живёт ровно столько,
сколько живёт процесс
python main.py. Новый запуск получает чистый лист, и это осознанное решение: почему именно так, разберём в конце урока.
Быстрый путь
- Создать
tools_todo.py. - Запретить второй
start, пока первый неcomplete. - Подключить в
main.py+ имя вtool_names. - Прогнать многошаговый и одношаговый промпт.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
tools_todo.py |
Создать. create_todo_tool(). |
main.py |
Править. Зарегистрировать tool + tool_names. |
Шаг 1. Создайте tools_todo.py
tools_todo.py (целиком)
from __future__ import annotations
import uuid
from typing import Literal, TypedDict
class TodoItem(TypedDict):
id: str
description: str
state: Literal["pending", "in_progress", "completed"]
# Один список на процесс. Новый запуск main.py - пустой список.
_todos: list[TodoItem] = []
def create_todo_tool():
"""Вернуть async-функцию todo для регистрации у агента."""
async def todo(
action: Literal["add", "start", "complete", "list"],
description: str | None = None,
id: str | None = None,
) -> str:
"""Список задач для многошаговой работы.
WHEN TO USE: 3+ шага, несколько файлов, зависимости между правками.
Сначала план, потом движение по пунктам.
WHEN NOT TO USE: правка одного файла с известным местом, простой вопрос,
разведка без конкретного результата.
DO NOT USE FOR: статус пользователю - просто ответь текстом.
"""
if action == "add":
item: TodoItem = {
"id": uuid.uuid4().hex[:8],
"description": description or "(без названия)",
"state": "pending",
}
_todos.append(item)
return f"Added: [{item['id']}] {item['description']}"
if action == "start":
active = next((t for t in _todos if t["state"] == "in_progress"), None)
if active:
return (
f"Already working on: [{active['id']}] {active['description']}. "
"Complete it first."
)
nxt = next((t for t in _todos if t["id"] == id), None)
if nxt is None:
return f"No todo with id {id}."
nxt["state"] = "in_progress"
return f"Started: [{nxt['id']}] {nxt['description']}"
if action == "complete":
item = next((t for t in _todos if t["id"] == id), None)
if item is None:
return f"No todo with id {id}."
item["state"] = "completed"
return f"Completed: [{item['id']}] {item['description']}"
# list
if not _todos:
return "No todos."
return "\n".join(
f"[{t['state']}] {t['id']}: {t['description']}" for t in _todos
)
return todo
Когда планировать, когда нет
| Сначала план | Без todo |
|---|---|
| 3+ шага до результата | Одна правка, место известно |
| Несколько файлов | Простой вопрос без файлов |
| Есть зависимости между правками | Разведка «просто посмотреть» |
| Попросили фичу из нескольких частей | Баг с точным текстом ошибки |
Граница между колонками не абсолютная, и подкручивается она не кодом, а формулировками. Заметили, что агент заводит todo на опечатку в одной строке? Значит, WHEN NOT TO USE написан слишком мягко: добавьте туда именно тот случай, который вас раздражает.
Шаг 2. Подключите в main.py
from tools_todo import create_todo_tool
todo_fn = create_todo_tool()
tool_names = ["read", "grep", "bash", "task", "ask_user", "todo"]
# (оставьте те имена, что у вас реально есть)
agent = Agent(
"deepseek:deepseek-chat",
deps_type=Sandbox,
tools=[
# ... прежние Tool(...)
Tool(todo_fn, takes_ctx=False),
],
instructions=instructions,
)
Не забудьте пересобрать instructions
после обновления tool_names, иначе в
Agency не попадёт todo.
in_progress с прошлого вторника, и никто уже не
помнит, что там было. Захотите потом снимок для истории -
делайте его в конце сессии, но «висящие» пункты в новый запуск
не тащите.
Проверьте
Сначала что-то заведомо многошаговое: в логе должны появиться add, а потом пары start / complete.
uv run python main.py . "Добавь в pyproject.toml (или создай скрипт) цель verify: подряд ruff check (если есть) и pytest. Потом запусти проверку и кратко отчитайся. Работай по шагам через todo."
В логе tools вы увидите несколько вызовов todo с
add, а дальше движение по пунктам: start→complete,
start→complete. Двух in_progress одновременно быть
не должно, а если модель всё же попробует - получит своё
Already working on и вернётся к незакрытому пункту.
Теперь наоборот, вопрос на один шаг. Тут todo обязан промолчать.
uv run python main.py . "Что делает переменная cwd / working_directory в main.py? Коротко."
Ответ должен прийти через read или
grep, без единого todo add. Список для
одной строчки - это бюрократия, а мы её тут не разводим.
Готово, если:
- Есть
tools_todo.pyс add/start/complete/list - Второй start отклоняется, пока первый не complete
- Tool подключён, имя в
tool_names - Многошаговый промпт раскладывается по списку
- Простой вопрос todo не вызывает