MODULE_03 · УРОК 3.2

Динамический промпт

Секции Agency и Guardrails мы написали, но живут они внутри здоровенной f-строки в main.py. Пока это одна папка и три инструмента, терпимо. А потом появится другой набор tools, захочется подсказать модели текущую ветку git, добавить условную секцию - и каждый раз вы будете лезть в середину многострочника с ножницами, стараясь не сломать отступы. Поэтому сборку промпта мы вынесем в prompts.py, в обычную функцию build_system_prompt: на входе факты о запуске, на выходе готовый текст.

ЧТО ПОЛУЧИТСЯ Файл prompts.py с функцией build_system_prompt(ctx), а в main.py вместо текстовой простыни останется один вызов: instructions=build_system_prompt({...}) со словарём фактов о запуске.

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

  • Контекст промпта - самый обычный словарь, для наглядности оформленный как TypedDict. Внутри рабочая директория, тип песочницы, имена инструментов, а при желании ещё и ветка git с текстом из AGENTS.md.
  • Чистая функция - та, что на одних и тех же входных данных всегда возвращает один и тот же текст. Никакого чтения диска внутри: файл AGENTS.md мы прочитаем в main.py на уроке 3.4 и передадим сюда уже готовой строкой.

Быстрый путь

  1. Создать prompts.py.
  2. Перенести туда Agency / Guardrails из main.py.
  3. В main.py вызвать build_system_prompt(...) - вызов функции с контекстом.
  4. Один раз print готового текста и посмотреть глазами, как выглядит промпт.

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

Файл Что делать
prompts.py Создать. PromptContext + build_system_prompt.
main.py Править. Убрать длинный f-string; вызвать билдер.
остальное Не трогать.

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

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

from typing import TypedDict, NotRequired


class PromptContext(TypedDict):
    working_directory: str
    sandbox_type: str
    tool_names: list[str]
    git_branch: NotRequired[str]
    project_context: NotRequired[str]


def build_system_prompt(ctx: PromptContext) -> str:
    parts: list[str] = []

    parts.append(f"Ты coding-агент. Рабочая директория: {ctx['working_directory']}")
    parts.append(f"Песочница (sandbox): {ctx['sandbox_type']}")

    tools = ", ".join(ctx["tool_names"])
    parts.append(f"""
# Agency
- ПОЛЬЗУЙСЯ инструментами: читай, ищи, запускай - потом отвечай.
- НЕ объясняй, что собираешься сделать. Сделай, потом коротко отчитайся.
- Доступные инструменты: {tools}
- Для поиска - grep, для файла - read; bash - только если без него никак.
""")

    if branch := ctx.get("git_branch"):
        parts.append(f"- Текущая ветка git: {branch}")

    parts.append("""
# Guardrails
- Меняй по минимуму.
- Сначала поищи существующий паттерн в проекте.
- Новые зависимости - только по явной просьбе пользователя.
""")

    if project := ctx.get("project_context"):
        parts.append(f"""
# Инструкции проекта (из AGENTS.md)
{project}
""")

    return "\n".join(parts)

Ни Jinja, ни модного «фреймворка промптов» тут нет и не нужно: список строк, join в конце, условные секции через обычный if. Скучно? Вот и отлично, промпты как раз тот случай, где скучное решение переживёт три поколения красивых.

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

Теперь без сожалений удалите тот самый многострочник instructions = f"""...""" из прошлого урока: весь его текст уже переехал в prompts.py. На освободившемся месте будет заметно меньше кода:

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

from prompts import build_system_prompt

# имена так, как вы реально регистрируете tools
tool_names = ["read", "grep", "bash"]

instructions = build_system_prompt({
    "working_directory": str(cwd),
    "sandbox_type": "local",
    "tool_names": tool_names,
    # позже: "git_branch": "...", "project_context": "..."
})

# временно - убедиться, что секции на месте:
# print(instructions)

agent = Agent(
    "deepseek:deepseek-chat",
    deps_type=Path,
    tools=[Tool(bash_fn, takes_ctx=False)],
    instructions=instructions,
)
ЗАЧЕМ ФУНКЦИЯ, А НЕ СТРОКА Строку не проверишь тестом и не подрежешь для субагента, её можно только копировать целиком. А функцию легко позвать из теста: передали ветку - строка про ветку в тексте есть, не передали - её нет. Кажется, что ради этого не стоило заводить отдельный файл, но окупается он уже на третьей новой секции.

Проверьте

uv run python main.py . "Найди все TODO-комментарии в проекте"

Снаружи ничего не изменилось, смысл промпта тот же, что и в 3.1. Зато теперь его можно посмотреть глазами: раскомментируйте print(instructions), и в консоли должны найтись рабочая директория, sandbox local, обе секции и список инструментов. Один раз прочитать промпт целиком стоит обязательно, дальше вы будете собирать его вслепую.

Ради полноты картины передайте ещё "git_branch": "main" и распечатайте снова: строка про ветку появилась. Уберите ключ - исчезла. Именно так и работают опциональные секции, никакого шаблонизатора для этого не понадобилось.

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

  • Есть файл prompts.py с build_system_prompt
  • В main.py instructions собирается через эту функцию, а не гигантским f-string
  • git_branch и project_context опциональны и появляются только если переданы
  • В распечатке промпта видны Agency, Guardrails и имена tools