Галоўная / Артыкулы

Пяць патэрнаў агентнай інжынерыі, вартых запазычання з абвязкі DeepSeek

Журнал падзей як крыніца праўды, градуяваныя папярэджанні цыкла, яўнае абразанне, code mode з праверкай дазволаў і перадача свежаму агенту: пяць патэрнаў для сістэм, якія лёгка адладжваць.

Выдавец: REACTAPP.TOP9 хв чытання1995 слоў

Крыніцы: 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

Няма якой-небудзь велікай історыі, няма застарэлых аргументаў і няма збіранага “шуму” ад інструментаў. Усё, што ёсць, — гэта тэкучы стан.