MODULE_08 · УРОК 8.1

Структурированные вопросы

Агент по своей воле почти никогда не спрашивает. Модели натаскивали быть полезными и решительными, поэтому уточняющий вопрос ощущается ими как признание слабости: проще угадать и бодро приступить. Иногда угадывает. А иногда выбирает не то направление, и час работы уходит в корзину вместе с вашими токенами.

Лечится это двумя деталями, и обе маленькие. Нужен инструмент ask_user, через который вопрос вообще технически возможен, и явная секция в системном промпте, объясняющая, когда им пользоваться. Одного инструмента без инструкции не хватит - модель сочтёт его декоративным.

ЧТО ПОЛУЧИТСЯ Инструмент ask_user, который задаёт вопрос и предлагает от двух до четырёх вариантов ответа, плюс секция # Handling Ambiguity в prompts.py. На размытый запрос агент начнёт спрашивать, а на точный, как и раньше, сразу возьмётся за дело.

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

  • Структурированный вопрос - не расплывчатое «что думаешь?», а конкретный вопрос вместе с коротким списком вариантов. На такой и ответить проще, и разобрать ответ потом легче.
  • Протокол ambiguity - заранее оговорённый порядок действий при неясности: сперва поискать ответ в коде, потом спросить, и только потом делать. Без такого порядка модель кидается в одну из крайностей - либо дёргает вас вопросом на пустом месте, либо молча пишет не то.

Быстрый путь

  1. Создать tools_ask.py - фабрика create_ask_user_tool.
  2. В prompts.py добавить секцию # Handling Ambiguity.
  3. В main.py зарегистрировать tool и добавить имя в tool_names.
  4. Прогнать два промпта: размытый и точный.

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

Файл Что делать
tools_ask.py Создать. create_ask_user_tool().
prompts.py Править. Добавить секцию Handling Ambiguity.
main.py Править. Подключить tool + имя в tool_names.

Шаг 1. Создайте tools_ask.py

Сразу договоримся, чего этот инструмент не делает: он не блокирует цикл и никого не ждёт. Он печатает вопрос в терминал и возвращает модели строку в духе «вопрос задан, ответа пока нет». Ответ вы дадите следующим сообщением. Настоящая пауза с ожиданием выбора - отдельная история, до неё мы ещё доберёмся.

tools_ask.py (целиком)

def create_ask_user_tool():
    """Вернуть async-функцию ask_user для регистрации у агента."""

    async def ask_user(question: str, options: list[str]) -> str:
        """Спросить пользователя с вариантами ответа.

        WHEN TO USE: задача размыта, есть несколько нормальных подходов,
          не хватает детали перед действием.
        WHEN NOT TO USE: уже достаточно контекста, чтобы продолжить.
        DO NOT USE FOR: риторика, отчёты о прогрессе, «ок?» после каждого шага.
        USAGE: question - текст; options - ровно 2-4 коротких варианта.
        """
        cleaned = [o.strip() for o in options if o and o.strip()]
        if len(cleaned) < 2 or len(cleaned) > 4:
            return (
                "ask_user: нужно от 2 до 4 непустых вариантов. "
                f"Получено: {len(cleaned)}."
            )

        formatted = "\n".join(f"{i}. {opt}" for i, opt in enumerate(cleaned, 1))
        print(f"\nQuestion: {question}\n{formatted}\n")
        return (
            f'Asked: "{question}"\n'
            f"Options:\n{formatted}\n\n"
            "(Awaiting user response.)"
        )

    return ask_user
ПОЧЕМУ ОТ ДВУХ ДО ЧЕТЫРЁХ ВАРИАНТОВ Один вариант - это не выбор, а уведомление. Пять и больше превращают простой вопрос в тест на внимательность, и человек начинает залипать вместо того, чтобы ответить за секунду. Четырёх хватает практически всегда: OAuth, JWT, cookies и «сначала расскажи, что уже есть в проекте».

Шаг 2. Секция в prompts.py

Хороший docstring у инструмента помогает, но сам по себе он проблему не решает. Без явной секции в системном промпте модель воспринимает ask_user как что-то необязательное и продолжает угадывать. Вставьте кусок после Guardrails, перед опциональным AGENTS.md:

prompts.py - добавить в build_system_prompt

    parts.append("""
# Handling Ambiguity
Когда задача размыта или есть несколько нормальных подходов:
1. Сначала поищи в коде/доках (read, grep) - собери контекст.
2. Потом спроси через ask_user. НЕ угадывай.
3. Примеры: «добавь auth» → спроси OAuth или JWT;
   «подними БД» → спроси Postgres или SQLite.

Точные задачи (путь к файлу, номер строки, конкретная правка)
ask_user не требуют - действуй сразу.
""")

Нумерация здесь не для красоты. Порядок «сначала поиск, потом вопрос, потом действие» удерживает модель ровно посередине между двумя крайностями: не выпаливать вопрос, не открыв ни одного файла, и не уходить молча строить архитектуру, о которой вас никто не спрашивал.

МОДЕЛЬ ЛЮБИТ СНАЧАЛА ПОРЫТЬСЯ Даже с протоколом она обычно сначала прочитает три-четыре файла и только потом позовёт ask_user. Так и задумано, первый пункт как раз про поиск. Но есть побочный эффект: если проверка перед опасными командами режет bash и модель не может собрать контекст, до вопроса она может просто не дойти. Approval и ask_user иногда тянут в разные стороны, и это трение самой архитектуры, а не баг конкретного урока.

Шаг 3. Подключите в main.py

Осталось соединить всё вместе. Найдите место, где вы собираете список инструментов и tool_names, - после урока 6.2 там уже живёт task. Добавьте туда ask_user, не забыв именно про оба места: модель узнаёт об инструменте из списка имён в промпте, а вызвать может только то, что зарегистрировано у агента.

main.py - фрагмент

from tools_ask import create_ask_user_tool

ask_user_fn = create_ask_user_tool()

# ... needs_approval, bash_fn, task_fn как были ...

tool_names = ["read", "grep", "bash", "task", "ask_user"]

instructions = build_system_prompt({
    "working_directory": str(cwd),
    "sandbox_type": "local",  # или как у вас сейчас
    "tool_names": tool_names,
    # git_branch / project_context - если уже есть
})

agent = Agent(
    "deepseek:deepseek-chat",
    deps_type=Sandbox,
    tools=[
        Tool(bash_fn, takes_ctx=False),
        Tool(task_fn, takes_ctx=True),
        Tool(ask_user_fn, takes_ctx=False),
        # read/grep - как вы регистрировали раньше
    ],
    instructions=instructions,
)

Если read и grep у вас зарегистрированы через @agent.tool или отдельными Tool(...), ничего переделывать не надо: оставьте как есть и просто добавьте рядом Tool(ask_user_fn, takes_ctx=False).

Проверьте

Начнём с размытого запроса - тут вопрос должен появиться:

uv run python main.py . "Добавь аутентификацию в этот проект"

Ожидаем такую последовательность: несколько read и grep, возможно делегированный task, а затем в терминале блок Question: … с вариантами. Чего быть не должно - так это агента, который с ходу возводит целый стек аутентификации на собственный вкус.

Теперь точный запрос, где вопрос был бы уже занудством:

uv run python main.py . "В main.py в начале файла добавь комментарий TODO harness-8.1 и больше ничего не меняй"

Здесь ожидается либо правка, либо честный отказ от проверки перед опасным действием. А вот вопрос «какой стиль комментариев вы предпочитаете?» означал бы, что протокол вы прописали слишком рьяно и агент теперь спрашивает обо всём подряд.

НА ПОТОМ: НАСТОЯЩАЯ ПАУЗА Сейчас инструмент возвращает строку, и цикл спокойно едет дальше. В боевом harness всё серьёзнее: вы ловите вызов, показываете человеку интерфейс с вариантами, дожидаетесь выбора и возвращаете его либо как результат инструмента, либо следующим сообщением пользователя. События вокруг вызова инструментов появятся в модуле про расширяемость, туда эту паузу и вешают. Пока хватит печати в терминал и строки для модели.

Готово, если:

  • Есть tools_ask.py с ask_user на 2-4 варианта
  • В prompts.py есть секция Handling Ambiguity
  • В main.py tool зарегистрирован, имя в tool_names
  • Размытый промпт вызывает вопрос
  • Точный промпт - без лишнего ask_user
ДАЛЬШЕ Режимы проверки у вас уже есть, они отвечают на вопрос, кто принимает решение. В следующем уроке добавим второй слой поверх режима: политики на конкретные файлы и команды.