MODULE_09 · УРОК 9.1

Todo tool

Дайте агенту задачу из пяти шагов, и он поведёт себя как человек в аврале: схватится за всё сразу, начнёт с третьего пункта, забудет про первый, а в конце бодро отчитается, что «в целом всё готово». Лекарство человечество придумало давно, и оно до обидного простое: список. Одно дело в работе. Доделать. Вычеркнуть. Взять следующее.

Tool todo - это тот самый список, только вживлённый в агента, с правилом, которое нельзя переубедить обаянием: одновременно в работе ровно один пункт. Не «постараюсь держать фокус», а честный отказ на уровне кода.

ЧТО ПОЛУЧИТСЯ Файл tools_todo.py с четырьмя действиями: add, start, complete, list. Многошаговые задачи раскладываются по списку, а простой вопрос этот tool вообще не трогает.

Слова, которые встретятся

  • in_progress - пункт, над которым агент работает прямо сейчас. Ровно один. Попытка открыть второй заканчивается отказом, а не вежливым «ну ладно, разрешаю».
  • Список в памяти - живёт ровно столько, сколько живёт процесс python main.py. Новый запуск получает чистый лист, и это осознанное решение: почему именно так, разберём в конце урока.

Быстрый путь

  1. Создать tools_todo.py.
  2. Запретить второй start, пока первый не complete.
  3. Подключить в main.py + имя в tool_names.
  4. Прогнать многошаговый и одношаговый промпт.

Какие файлы трогаем

Файл Что делать
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
ГЛАВНОЕ ПРАВИЛО Уберите «один in_progress», и модель радостно стартует все пункты сразу, чтобы «сэкономить время». Фокус испарится, список станет декорацией. И отказ должен быть конкретным: не сухое «нельзя», а какой именно id ещё висит незакрытым. Модели, как и самоуверенному стажёру, надо сказать, что именно доделать.

Когда планировать, когда нет

Сначала план Без 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 не вызывает
ДАЛЬШЕ План у агента появился. Осталось отучить его читать полрепозитория «на всякий случай»: сначала grep, потом точечный read.