П’ять шаблонів інженерії агентів, які варто запозичити з DeepSeek's Harness
Журнал подій як джерело істини, попередження про цикли різного рівня, пряме обрізання даних, режим коду з перевіркою прав та передача обов’язків новому агенту: п’ять підходів для створення систем агентів, які можна налагоджувати.
Джерела: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness
Агенти постійно покращують свої навички написання коду, використання інструментів, пошуку файлів та виконання тривалих завдань. Однак під усім цим криється ще одна проблема: що заважає агенту стати настільки складним для дебагування, що його стає важко передбачити та навіть неможливо виправити? Аналіз інженерних рішень у відкритому для користування інструменті для агентів 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
Немає величезної історії, жодних застарілих міркувань та накопиченого „шуму“ від інструментів. Усе, що є, — це поточний стан.