Структурированные вопросы
Агент по своей воле почти никогда не спрашивает. Модели натаскивали быть полезными и решительными, поэтому уточняющий вопрос ощущается ими как признание слабости: проще угадать и бодро приступить. Иногда угадывает. А иногда выбирает не то направление, и час работы уходит в корзину вместе с вашими токенами.
Лечится это двумя деталями, и обе маленькие. Нужен инструмент
ask_user, через который вопрос вообще технически
возможен, и явная секция в системном промпте, объясняющая, когда
им пользоваться. Одного инструмента без инструкции не хватит -
модель сочтёт его декоративным.
ask_user, который задаёт вопрос и
предлагает от двух до четырёх вариантов ответа, плюс секция
# Handling Ambiguity в prompts.py.
На размытый запрос агент начнёт спрашивать, а на точный,
как и раньше, сразу возьмётся за дело.
Слова, которые встретятся
- Структурированный вопрос - не расплывчатое «что думаешь?», а конкретный вопрос вместе с коротким списком вариантов. На такой и ответить проще, и разобрать ответ потом легче.
- Протокол ambiguity - заранее оговорённый порядок действий при неясности: сперва поискать ответ в коде, потом спросить, и только потом делать. Без такого порядка модель кидается в одну из крайностей - либо дёргает вас вопросом на пустом месте, либо молча пишет не то.
Быстрый путь
- Создать
tools_ask.py- фабрикаcreate_ask_user_tool. - В
prompts.pyдобавить секцию# Handling Ambiguity. - В
main.pyзарегистрировать tool и добавить имя вtool_names. - Прогнать два промпта: размытый и точный.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
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
Шаг 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 и больше ничего не меняй"
Здесь ожидается либо правка, либо честный отказ от проверки перед опасным действием. А вот вопрос «какой стиль комментариев вы предпочитаете?» означал бы, что протокол вы прописали слишком рьяно и агент теперь спрашивает обо всём подряд.
Готово, если:
- Есть
tools_ask.pyсask_userна 2-4 варианта - В
prompts.pyесть секция Handling Ambiguity - В
main.pytool зарегистрирован, имя вtool_names - Размытый промпт вызывает вопрос
- Точный промпт - без лишнего ask_user