Главная / Статьи

Пять паттернов инженерии агентов, которые стоит заимствовать из Harness от DeepSeek

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

Издатель: REACTAPP.TOP9 мин чтения1995 слов

Источники: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness

Агенты постоянно становятся лучше в написании кода, использовании инструментов, поиске файлов и выполнении длительных задач. Однако за всем этим скрывается более серьезная проблема: что мешает агенту стать настолько запутанным, непредсказуемым и практически не поддающимся отладке? Анализ инженерных решений в open-source решении DeepSeek показывает пять идей, которые стоит заимствовать, даже если вы никогда не будете использовать это решение. Это скорее общие принципы для систем агентов, чем уникальные трюки DeepSeek.

1. Сделайте журнал событий источником истины

В большинстве систем агентов диалог хранится в списке, который затем передается модели:

messages = [...]

В другом месте лесник записывает то, что произошло:

logger.info({
    "messages": messages,
    "tool_calls": tool_calls,
    "tokens": tokens
})

Это кажется разумным, но это приводит к двум версиям одних и тех же событий, и именно в этом заключается риск. Предположим, приложение изменяет список сообщений перед его отправкой, например, добавляя дополнительную инструкцию:

messages.append({
    "role": "system",
    "content": "Remember to be concise."
})

Если журнал событий никогда не фиксировал такую правку, значит, модель столкнулась с чем-то, о чём ваши журналы ничего не знают. Шесть часов спустя агент совершает что-то странное, и вы открываете журналы, пытаясь понять причину. Причиной может быть системное сообщение, которого нет нигде в зафиксированной истории.

Лучший подход

Сделайте журнал событий единственным источником информации. В нём хранятся факты: запрос пользователя, каждый вызов инструмента, каждый результат и ответы ассистента:

events = [
    UserMessage("Fix the authentication bug"),
    ToolCall("grep", {"query": "auth"}),
    ToolResult("Found 12 matches"),
    AssistantMessage("I'll inspect the middleware")
]

Контекст модели затем формируется на основе этих событий и не сохраняется в виде отдельного списка:

def build_context(events):
    return [
        event.to_message()
        for event in events
        if event.visible_to_model
    ]

Суть в том, что не существует никакого приватного, скрытого массива сообщений. Его вычисляют каждый раз. Сравните обе структуры. Оптимальный вариант проходит от журнала через конструктор контекста к запросу:

Event Log
    ↓
Context Builder
    ↓
LLM Request

Следует избегать ситуаций, когда логи разделяются: одна ветвь отвечает за логи, а другая — за сообщения, поступающие в модель:

Event Log ─────────→ Logs
       \
        → Messages ─→ LLM

Это небольшое изменение структуры значительно упрощает отладку.

Продвиньтесь дальше и проверьте это

Во время разработки вы можете добавить проверку, которая воссоздаст ожидаемый контекст на основе логов и сравнит его с тем, что действительно собираются отправить:

expected = build_context(event_log)
actual = request.messages
if actual != expected:
    raise RuntimeError(
        "log-reconstruction desync"
    )

При таком подходе дрейф контекста становится несрабатывающим тестом, а не загадочной ошибкой в производственной среде. Есть ещё и преимущество: возможности наблюдаемости становятся гораздо более полезными. Если представление траектории показывает вызовы модели, вызовы инструментов, результаты их работы, использование токенов и временные показатели, никому не нужно собирать отдельную информацию о произошедшем, поскольку все данные уже имеются — агенту они необходимы для воссоздания собственного контекста. Один источник истины выполняет две функции.

2. Не блокируйте циклы агента сразу

Каждый разработчик агентов рано или поздно сталкивается с этой проблемой. Модель постоянно выполняет один и тот же поиск:

grep "authentication"
grep "authentication"
grep "authentication"
grep "authentication"
...

Проблема ясна, и очевидное решение тоже просто: отклонять повторные звонки.

if previous_call == current_call:
    raise LoopError()

Проблема в том, что повторение иногда действительно необходимо. Запрос к сети может провалиться, файл мог измениться, и повторная попытка действительно может потребоваться. Вместо того чтобы блокировать модель, следует предупредить её.

Представьте систему давления, которая увеличивается с количеством повторений:

3 repeats → gentle reminder
5 repeats → stronger reminder
8 repeats → very strong reminder

На первом уровне может быть указано, что один и тот же вызов инструмента повторяется, и предложено перечитать последний результат:

if repeat_count >= 3:
    inject(
        "You are repeating the same tool call. "
        "Re-read the last result and consider another approach."
    )

Второй уровень более строгий, он требует от агента остановиться и переоценить ситуацию:

if repeat_count >= 5:
    inject(
        "You have repeated this exact operation several times. "
        "Stop and reassess the approach."
    )

В третьем пункте говорится, что ситуация напоминает цикл, и необходимо изменить подход, либо завершить работу:

if repeat_count >= 8:
    inject(
        "This appears to be a loop. "
        "Change your approach or wrap up."
    )

Обратите внимание, чего не делает этот харнес. Он никогда не возвращает однозначный отказ вроде этого:

return False

Контроль остается в руках модели. Ремень безопасности лишь предоставляет дополнительную информацию и позволяет модели принимать решение, что является важным отличием.

Подсчёт реальных повторений

Хороший детектор не должен попадаться на уловки из-за нерелевантных вызовов, вставленных между ними. Эта последовательность всё равно должна считаться повторением:

grep foo
todo update
grep foo

В противном случае модель может сбросить свой собственный счётчик, выполняя бесполезную работу между идентичными вызовами. Аргументы также следует нормализовать, чтобы эти два случая считались одинаковыми операциями:

{"query": "foo", "path": "src"}

и:

{"path": "src", "query": "foo"}

Порядок ключей в словаре не должен иметь значения. Также следует учитывать отклонённые вызовы. Если модель продолжает пытаться делать что-то подобное:

run dangerous command
→ denied
run dangerous command
→ denied
run dangerous command
→ denied

Именно тогда ему необходимо понять, что, возможно, разумно прекратить попытки.

Общая схема

Слабый подход представляет собой грубую реакцию на плохое поведение:

Bad behavior → hard block

Более сильная версия обнаруживает такое поведение, усиливает обратную связь и позволяет модели восстановиться:

Bad behavior
     ↓
Detect
     ↓
Increase feedback
     ↓
Let model recover

Это идея, кажущаяся на первый взгляд простой, и она подходит практически любой фреймворку агентов, предоставляющему возможность вызывать инструменты.

3. Расскажите модели о том, чего она не видела

Это кажется очевидным, однако многие инструменты делают ошибки в этом. Предположим, репозиторий содержит следующее:

4,000 files

и инструмент поиска возвращает только это:

100 files

Если ответ — это просто эти сто файлов, модель может прийти к выводу, что совпадений именно сто. На самом деле инструмент имел в виду: «Вот сто файлов, потому что я прекратил поиск», и эти два значения совершенно разные.

Четко указывайте на обрезку

Лучший ответ объясняет, что произошло, и где находится остальное:

Showing 100 of 4,000 results.
The result set was truncated.
Full results:
~/.agent/search-results/results.txt

Теперь модель знает три вещи: существует больше результатов, то, что у неё есть, — это лишь их подмножество, а полный список доступен при необходимости. Это гораздо более надёжная ситуация.

Отбор примеров может быть эффективнее, чем использование первых N элементов

Предположим, что существует 4 000 файлов, но места хватает только на 100. Примитивный способ — это простой отрезок данных:

results[:100]

Отсортированные результаты могут быть опасны, поскольку из одного каталога или согласно одной схеме именования могут поступить сотни файлов. Распределение примеров по всему списку даёт более полную информацию:

def sample_results(results, limit=100):
    step = len(results) / limit
return [
        results[int(i * step)]
        for i in range(limit)
    ]

Конкретный алгоритм имеет меньшее значение, чем принцип: никогда не позволяйте модели путать реально существующее с тем, что показал инструмент.

Ошибки требуют такого же внимания

Ошибки инструментов также могут ввести агента в заблуждение. Предположим, команда заблокирована политикой безопасности. Такое простое сообщение является недостаточным:

Permission denied

Поскольку модель может решить, что её синтаксис неверен, и тогда пытаться снова и снова. Гораздо лучше использовать прямое сообщение:

Policy denial.
This command was intentionally blocked by the sandbox.
The command itself may be valid, but this operation is not permitted.
Do not retry using another method to bypass the policy.

Это не просто дружелюбное сообщение — это руководство для агента. Ваши инструменты выполняют не только операции, но и взаимодействуют с другой системой рассуждений. Результат работы инструмента должен отвечать на один вопрос: что нужно знать модели, чтобы правильно принять следующее решение?

4. Выполнение кода не должно обходить правила разрешений

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

files = search("authentication")
for file in files:
    content = read_file(file)
    print(analyze(content))

Это мощно. В то время как обычный цикл постоянно чередует вызовы модели и инструмента, раунд за раундом:

LLM
 ↓
search
 ↓
LLM
 ↓
read
 ↓
LLM
 ↓
read
 ↓
LLM
 ↓
read

Режим кода позволяет модели запустить программу, которая выполняет множество вызовов и возвращает краткое резюме:

LLM
 ↓
run_code(...)
 ↓
50 tool calls
 ↓
summary

Это может значительно сократить время на обработку запросов туда-обратно и использование ресурсов, но это поднимает серьезный вопрос безопасности.

Кто проверяет вызовы внутри программы?

В обычной архитектуре каждое действие модели проходит через слой разрешений перед тем, как попасть в инструмент:

Model
 ↓
Permission Layer
 ↓
Tool

Если бездумно добавлять выполнение кода, он может напрямую попасть в инструменты:

Model
 ↓
Code
 ↓
Tool

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

Model
 ↓
run_code
 ↓
Program
 ↓
Permission Layer
 ↓
Tool

Каждый вызов инструмента по-прежнему проходит через тот же пайплайн. Концептуально сама функция чтения файла проверяет разрешения перед выполнением каких-либо действий:

def read_file(path):
    permission = check_permission(
        operation="read",
        path=path
    )
if not permission.allowed:
        raise PermissionError(
            "File access denied"
        )
    return actual_read(path)

Интерпретатор кода не получает специальной версии функции. Он получает ту же самую, что используют все остальные.

Преобразование отказов в обычные ошибки программы

Следует более тонкий момент. Если программа пытается сделать что-то, что ей не разрешено:

try:
    delete_file("/important/file")
except PermissionError as e:
    print(e)

Он должен получить обычную ошибку, которую можно поймать. Его не следует оставлять в таком состоянии бесконечно:

hang forever

Он не должен тихо возвращать пустой результат:

return None

И оно не должно вести себя так, будто ничего не произошло:

pretend nothing happened

Программа должна понимать, что операция провалилась, что особенно важно, когда модель пишет программы в реальном времени. Режим кода настолько мощен именно потому, что он предоставляет модели больший контроль, а это означает, что границы разрешений должны становиться строже, а не слабее.

5. Иногда лучшей стратегией контекста является отсутствие контекста

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

Round 1
 ↓
Round 2
 ↓
Round 3
 ↓
Round 4
 ↓
Round 5
 ↓
Huge context

Теперь модель тратит своё внимание на повторное прочтение собственных прошлых действий вместо решения задачи. Краткое изложение — одно из решений, но существует и другой вариант: прекратить диалог, но сохранить рабочее пространство.

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

Agent A
→ inspect repository
→ make changes
→ save work
→ write handoff

Второй раунд начинается с совершенно нового агента, который анализирует рабочее пространство и переданные данные, а затем продолжает работу:

Agent B
→ read workspace
→ read handoff
→ continue

Здесь нет огромной истории, нет устаревших рассуждений и никакого избыточного «шума» от инструментов. Есть только текущее состояние.