Графавая інжынерыя для AI-агентаў кадавання: кантэкст, кантракты і выпраўленне
Чаму навучыў аднаго распрацоўшчыка граф агентаў на кантрактах: абмежаваны кантэкст, дэтэрмінаваная праверка, мэтавае выпраўленне і калі дадатковыя выдаткі на вылічэнні апраўданыя.
Крыніцы: Graph Engineering for AI Coding Agents: Beyond Prompt Loops
„Інжынерыя графаў“ апошнім часам прывлекае вялікую увагу, і большасць адпаведных адказаў сфокусаваныя на графах, вузлах і DAG-ах. Што тамце важна, але гэта не адпавядае на пытанне, якое насправды трэба задаць: чаму агентам для напісання коду на базе ШЫ раптам патрабуецца інжынерыя графаў?
Распрацоўшчык, які калькі месца працаваў з інструментамі на кшталт Claude Code, а пазней — Codex, зазначыў певную законамірнасць. Большасць завад у напісанні коду выступае не таму, што мадэль не можа напісаць код, а таму, што дугатраючыя працэсы паступова втрачаюць свою структуру. Кантэкст выходзіць з сінхронізаціі, прыемкі забываюцца, рэзультаты стаюць важкімі да пераканання, а калі ўсё пайшло не так, просты спосаб з’явіцца — часта гэта перазапуск усьго заваду.
Гэтыя спазыраванні прывелі да невялікага нарадчага канструкцыі пад назвай ContractGraph. У праце ніжэй опісаны яго ідэі, тое, што запрацавало, а чаго — ні. Ён не быў створаны для конкурэнціі з існуючымі канструкцыямі і не прыязначаны для конкрэтнага модэлю. Мета была болей вузкая: чы можна спраектаваць рабочы працэс так, каб кожны крок меў чыста вялікую мету, чыткая угоду і дэтэрміністычны спосаб дакладнага выявлення таго, чы справды крок завершаны?
Рэзультатам была схема, керованая контрактамі, якая рэалізавала працэс адкрыцтва праз адзінольныя заданні, чыстая перакананнае і цялевая парадктура, замест аднаго велічэзнага запіту. Першая рэалізацыя была спрамована на агентаў для адкрыцтва, але асновныя ідэі таксама падходзяць для агентаў для кодавання, пайплайнаў дакументаў, сістэмаў ацэнкі і будзь-яга працэсу, дзе калькі крокаў, керованых AI, должны даць рэзультаты, якія можна пераканаць. Памятайце, што гэта ўжо толькі эксперымент аднае з працавічакоў, таму выводы ўтвараюцца на адной основе дазвячэння, а не мераваных крэатываў.
Што значыць інжынерыя схем
Інжынерыя схем — гэта практыка разбівання складнага працэса адкрыцтва AI на маленькія елементы выканання і ўз’яўлення іх за дапамогою чыстых правілаў. Сістэма, створаная з выкарыстоўванням інжынерыі схем, зазвычай аб’еднвае калькі елементаў выканання, чыстую маршрутацыю, спакойны стан, перакананне і стойкую коордынацыю.
Адзіна адпаведнасць за кожны вузел. Кантэкты выбіраюць наступны крок. Стан, які дзеліцца між усіма элементамі робочага практыку, перадае інфармацыю, а стадыя пераканання вяршыць рашэнне пра тое, чы робіць працу далей, спробаваць знову, вылагодзіць або зупініць.
Два пытанні, якія стояць за дыяктурам
Разрахоўваючы, што большую частку часу пасвятыць вузелам, кантэктам і тэчыі выканання, распрацоўшчык з’ясав, што гэта не ўсё сама складная частка. Два пытанні продовжліваў вяртацца.
Першае: якую інфармацыю агенту AI трэба дазволіць вважаць правдзівай? Другое: калі ён завершыў заданне, як можна з’ясавіць, чы выходны рэзультат дэйсна падтрымлівае тое, пра што было запітана?
Чым большэй колькасці дзейнаў, якія трывалі дзяўно, было працавана, тым ясней ставала асаблівасць, што гэтыя пытанні маюцы большое значэнне, чым сам граф. Агент, які выкананае з некорэктных дадзеных або заканчывае працу без надзеяна способу пераканання ў правільнасці сваёй працы, проста пераносіць аблыкі з аднаго вузла на іншы. Гэтыя два пытанні сталі Кантэкстам і Контрактом. Кантэкст вялічы, у чым агент можа верыць, а контракт — што ён павінен стварыць. Усе іншае ў гэтый рамцы залежыць ад гэтых двух ідэй.
Кантэкст і контракты як будуючыя элементы
Граф не быў самым складным элементам. Асалодныя вызванні заключаліся у тым, каб кожны вузел пачынаў з правільных дадзеных і ствараў ўсё, што можна было бы пераканаць, перш чым дзейна працаваў далей.
Кантэкст. Агенты не павінны бачыць усё. Кожны вузел отрымае толькі тыя даны, якімі можа даваць перакананне, напрыклад, трэбаванні корыстувальніка, абмежэнні праекта, паўнастаўленыя дакументы або прынятыя рэзультаты з пакульшых вузелаў.
Контракт. Кожны вузел павінен маты чыстае апісанне таго, што ён павінен выдаты. Калі рэзультат не падпадае пад тыя вакументы, рабочы працэс не можа проста продаваць далей. Ён павінен пераканацца ў выходных даных, вылечыць несправны крок або зупініцца.
Проста кажучы, кантэкст вялічы, у чым агент можа даваць перакананне, а контракты — што ён павінен выдаты. Калі оба гэтыя межы ўскладненыя, граф стае набліжэй да разумення. Кожны вузел мае адну мэту, вузкы істочнік правды, выходны даны, якія можна вымерыць, і дэтэрміністычны блок перад пачатком наступнага крока.
Ад ідэі да выконвальнага графа
Калі кантэкст і контракты знаходзяцца разам, наступны вопыт — як з іх стварыць рабочы працэс, які можна запусціць. Метай не было прыкладзіць окольны граф для даследжэння, программавання чыра стварэння дакументаў. У замен працэс трэба скомпіляваць дынамічна на аднойчынку з самай задачы, а не з заранее візначаных шляхоў. Спачатку выконваюцца два крокі.
Першы крок — стварэнне кантэкста. Не кожны файл чы дакумент заслуговае на аднаковую доверлівасць, таму працэс складае канонічны кантэкст — падтверджаны істочнік правды, на які можна паспяржыцца для всіх вузлаў. Яго сыр'е залежыць ад задачы: гэта можа быць дакументы праекта, трэбаванні корыстувальніка, код, дакументы дызайну чы іншыя даны, якія вважаюцца надзеянымі.
Другі элементы ствараюць контракт. У зменшэнні да простага опісу задачы ў прозе, яны ствараюць структураваны контракт, у яком указваецца, што павінна даць кожная стадыя, як вузлы залежаць адзін ад другога і што павінна быць параболеная перад тым, як будзе продовжана експансія.
Калі оба элементы ўжо ўстановлены, працэс выканання компілюецца. Штадыя ініцыялізаціі нічога не выкананае; яе задача — планаванне. З яе выходзяць граф выканання, пакет кантэксту для кожнага вузла, можна перыяктавацьі маніфесты і спільныя навыкі, а таксама парадак выканання, вырахаваны на аднойчыні з контрактамі, без жаднага жорсткага парадку.
Выканання пасля чаго ёсць простым. Вузел отрымае толькі свой кантэкст, выкананае сваю задачу, праходзіць параболеную перакананне, зберагае прыйняты рэзультат і перадае кантроль далей. Калі перакананне не выйшла, толькі афектаваны вузел параболеную перакананае перад тым, як будзе продовжана експансія, таму нічога не пачынаецца з нуля.
Структура графа ў такім разе вынікае з кантэксту і умов, заданых на пачатку, а не з фіксаванага спосабу рэалізацыі. Той самы працэс компіляцыі можа складаць рабочыя практыкі для даследжэнняў, програмавання, документавання або чаго-небудзь абсалютна іншага, не змінюючы час выканання.
Тэставанне на большых і меньшых мадэлях
Праектаванне фрэймворку — гэта толькі палова задача. Складнейшы вопыт — чы рэшыцтва архітэктуры застойваюцца, калі рабочая практыка становіцца настолькі большай, што паказвае ўсе яе слабасі.
У першых эксперыментах была вікорыстана значна большая рабочая практыка, якая працавала ў Claude Code, з дынамічна створанымі вузламі выканання, вярнутымі ступенямі планавання і дугімі даследжэнчымі заданнямі. Якасць была выключнаюю, але завершэнне рабочай практыкі вымагала велікай колькасці вычысленняў мадэлі.
Гэта падзяліла ўзнёмленыя пытанні. Чы можа тая ж самая архітэктура графа даць надзеяныя робочыя працэсы на значна меньшым, дышчыцьму модэлі? У другім эксперыменце быў выкарыстоўваны робочы працэс стварэння плану навучэння, які выкананы быў за дапамогою OpenCode з Big Pickle заместо модэлі фронтыр. Механізмы засталіся тымі ж: робочы працэс компіляваўся дынамічна, ствараліся спецыялізаваныя вузлы, кожны этап пераверачваўся дэтэрміністычна, бракі лагодзіліся там, дзе было трэба, а гэтычны рэзультат выходзіў з той самай лініі апрацоўкі.
Мэтай не было пораўняння модэляў чы выбіранне паводлівага. Цэллю было выявіць, насколькі частка надзеянасці выходзіла з архітэктуры выканання, а не з первісных можаўносцей самага модэля. Нечаканым вынікам было тое, што найбольшыя проблэмы ўзагалі не былі бракамі модэля. Гэта былі бракі робочага працэса, і самэ гэта зробіла інжынерыю графа цікавай.
Дзе было зламанае
Эксперымент не паказаў, што інжынірынг графа запобегае абыякшым неудачам. Ён паказаў, што інжынірынг графа робіць неудачы віднымі.
Па дарозе з’явіліся розныя проблемы: непূরныя метаданы, відсутніе доказаў, нерашаныя апісанні, дуплікатываны контэнт, некарэктныя станы жыцёвага цыклу, неправільная інформацыя пра трэйсінг і нават простыя проблемы з кодаваннем. Граф не стаў прычыной ніякой з іх. Гэта тые неудачы, якія можна было б спакаўаць ад дзейнасці AI-процэсаў, якія працуюць дзяўно.
Змянілася тое, што кожная неудача мела точную локацыю. Уместа таго, каб вважаць усю дзейнасць адной неудачной екзекуцыяй, стала можлівая знаходка конкрэтнага вузла, які не выпанаў сваія зобав’язанні, апранацаванне толькі таго вузла, паўтарная перацэнка за дапамогою дэтэрміністычных методаў і продаж чыннасці з таго моменту. Рэшта процэсу засталася недыяранай, таму што кожны успешны этап ужо быў перакананы і запісаны.
Гэта змяніла спосаб, якім распрацоўшчык бачыў гэтую тэхніку. Гэта не быў спосаб зробіць мадэлі розумнейшымі. Гэта быў спосаб зробіць абыяковасці локальнымі, спостатэльнымі і можлівымі да відновлення. Граф не пазбавляў моцы бяперабоўкаў, але даваў кожнай бяперабоўцы адрэсу.
Чаму прабавка павінна быць дэтэрміністычная
Мадэль можа з абсалютным абавяжаннем сказаць, што задача завершана, але гэта не значыць, што гэта правда. Мадэлі мовы дужа добра рассуждаюць, ствараюць падсумкі і прыменяюць рашэнні, але яны ўсё ж не ўпэўненныя суддзі ў тым, чыі рабочы працэс выпанаў сваія власныя вакалідаты.
Самэтна прычына, чаму кожны вузел у ContractGraph завершаецца дэтэрміністычным пераканальнем. Ніхто не прасіць другога модэлю пра адказ пра рэзультат. Рабочы працэс пераканальвае об’ектыўныя умовы: чыі схема мае всі неабходныя поля? Чыі былі задовольненыя залежнасці? Чыі ёсць неабходныя артыфакты, і чыі рэферэнсы працуюць? Чыі вузел перадаў усё, на што яго контракт абяцаў? Гэтыя не ўсабоўчыя адказы; кожны з іх проста ўсё або нічога.
Гэтае раздзеленне паказалася аднам з найцэннейшых ідэяў у гэй канструкцыі. Модэль зосераджваецца на логічных выводах, а дэтэрміністычныя методы пераканальвання займаюця верыфікацыяй. Модэль можа стверджваць, што яго праца завершана, але толькі дэтэрміністычны пераканальвач можа падтвердзіць, што якое-небудзь неабходнае поле не ўсёрэшча.
Чаму дадатковыя зусілі можу прынесці плоды
Ёшчэ до гэтага эксперыменту распрацоўшчык спрыяў AI-агентам у кодаванні як малай камандзе, а не як аднаму асістэнту. Не было нічога нечыстае ў тым, калі Claude Code, Codex і OpenCode адночасна працавалі над разнымі часткамі аднаго рэпазітарыю.
Гэта створыла нечаканую проблему. Агенты моглі знадобіцца зменіць тыя ж файлы або павяржыцца ў тую ж рэалізацыю, і без коордынацыі адны моглі перазапісаць работу іншага або знецініць раней зробленыя прыпускі.
Рашэнне было простым: кожны заданнік мяў свога власніка. Калі агент быў адпаведальны за частку кодавой базы, іншыя не маглі чапацца за тые файлы, пакуль власнік не дазволіў. Пасля кожнага значнага крока трэба было адрабатваць перакананне, і такім чынам багато канфліктав ніколі не дасягалі рэпазітарыю.
Связь между выгодамі і недзеямі была ясная. Такі спосаб развіцця выкарыстоўвае значна большае колькасць рэсурсаў, чым калі прасіць аднае модэль адразу стварыць функцыю пад час адной розмовы, адтак кожны крок паўнай перапрацоўкі, прабавы, выправлення і коордынацыі дадае дапамогі. Аднак рэзультат быў іншы. У змену таму, што паўтараюча лагаць наследныя бяды, вызваныя пакульнімі выправленнямі, працэс стаў набліжэней прыкладным, а функцыі, створаныя такім спосабам, патрабавалі мінімальнай перапрацоўкі, адтак кожны этап перавераныя быў перш чым пачынаўся наступны.
Інжынерыя графаў — гэта не тое, чым трэба карыстацца для кожнага запіту, а для маленькіх змян гэта проста зайвая навантажэння. Для большых функцыяў, длігіх рэалізацый чы працы кальколькі агентаў дадатковыя вітраты прыносяць штосьц цэннейшае, чым дэшавыя вычысленні. Гэта прыносіць абавесць.
Што на самай працоўцы
Ніхто не павінен спрыяць гэтам як да таго, што інжынерыя графа ёсць абсалютны раўэль. Падготовка кантэксту, стварэнне контрактаў, складанне графа, атрыбутаванне, вылечэнне і агрэгатаванне кожнага элемента выклікае дадатковыя запыты да модэляў і вікорыстоўванне токэнаў. Паўстаецца, што працэс, кроме простага запыту, ўсё ж такі ўсё дорожы.
Першыя эксперыменты з модэлямі новай генерацыі далі чырвоныя рэзультаты, але займалі многа вычысловых рэсурсоў, што стало галоўной прычыной тэставання меншых, дышчыцых модэляў. Урок заключаўся у тым, што інжынерыя графа не зменшуе колькасць вычысловых рэсурсоў; ёй проста перэраспрытляе іх. Уместо таго, каб вітрачаць рэсурсы на вярнэнне пасля збоев, пачатак новых працэсаў пасля неудач або паўтарэнне прабав усунуць бягучыя бяды, сістэма вітрачае іх з самага пачатку на планаванне, перакананне і ізоляцыю бяд.
Гэта змінюе мету оптымацыі. Інжыніярство графаў не створана для атрымання найдэшавшага спосабу выканання. Яна створана для атрымання найбольш адказныяго спосабу. Одна запуск OpenCode пераробіла вялікі об’ём токенав. Гэтая цыфра не павінна спрыяць думцы, што такі падход ёсць дэшавым. Навпакі, яны паказваюць працоўнае прыклад, калі інжыніярство графаў свядома вітрачае больш вычыслювальных рэсурсоў, каб досягнуць ізоляцыі ад бядаў, можлівасці аўдытавання, возможнасці паўторнага запуску і большай надзеі на успех. Чы ўсё гэта ёсць хорашай замянай, залежыць абоўсюды ад проблемы.
Калі гэта мае сэнс
Інжыніярство графаў не ўсё час неабходна для кожнага працэсу працы з ШЫ. Для запыту SQL, маленькай функцыі чы калякоў правека інтэрфейса зазвычай достатньа добра напісанага запрошэння, а дадаванне контрактаў, шароў верыфікацыі і графаў выканання толькі сповільніць і ускладніць працу.
Гэта пачынае даваць рэзультаты, калі выкліканыя неудачай затраты перавышаюць затраты на дадзейннік. Гэта стосуецца дугагалошых даследаванняў, працы з велікім колікствам элементаў, рабочых практык з калькольнікамі, сістэм, чутлівых да безпекі, аўтаматызаціі падпрыемстваў і будзь-якога працэсу, вынік якога павінен быць пераканальны і воспавямлівы. Чым большэ ў рабочай практыцы крокаў, тым болей значным стае явныя коордынацыі.
Галоўны урок не стосуецца інтэлекту. Калі рабочая практыка ўскладнена, ўсё ж структура робіць яе простэйшай для адстэплення, пераканання, вяснавання і расшырэння. Ідэя таксама далёкая ад завершэння. Выкананне з урахоўваннем залежнасцей, розумнейшая планавання, оптымізацыя рэсурсаў, перэкомпіляцыя частковых графаў і болей развітая коордынацыя між калькольнікамі — усё гэта застаецца недаследжаным. Короткая версія урока: выкорыстоўваць падказкі для рашэння задач і выкорыстоўваць інжынерыю графаў для стварэння сістэм.
Заключныя думкі
Спачатку планавалася навука працаваць з графамі. Але на практыцы урок выучыў нас пра межы, перакананне і коордынацыю. Сам граф не быў галоўным — важным была чыстая мета кожнага крока, меры ўскладнення для таго, што агент можа прыймаць за правду, апісанне таго, што ён павінен стварыць, і доказ завершэння працы пры пераходзе да наступнага крока.
Гэты не ўсё спосабы стварэння сістэм AI, і не кожны працэс выканання працы патрабуе такой высокай структуры. Але для складных, дугага часу трываючых або багатоагентных задачынгаў інжынерыя графаў прыносіць практычны спосаб стварэння сістэм, якія ёсць болей прыемлівымі для працы і лёгкімі для розвітку.
Калі трэба запам’ятаць адну фразу, нехай гэта будзе такі ланцуг: запіт выказвае бажанне, кантэкст вярнівае, што агент можа спрыймаць як факт, угода апісвае рэзультат, а граф — гэты механізм, які паказвае, што праца завершана.
У часы гэтага эксперымента ContractGraph яшчэ развіваўся, а яго рэпазітарый не быў опублікованы, таму што спачатку планавалася спростаць яго архітэктуру. Чырвоныя вярсіі на гэту тэму можна знайсці ў загальных кансэльктаваннях па інжынерыі графаў, адколькі гэты матэрыял раскрывае толькі адну парадку, а не весь галузевы простор.
Супаўзвязаная літэратура
- Як агенты для кодавання на AI пераформатаваюць работу распрацоўшчыкаў у 2026 годзе — агенты для кодавання на AI перайшлі ад функцыі автодаполнення да выпання цэлых задач. Даныя пра ўжыцце, інжынерыя кантэкста, код з падтрымкай тыпаў, верыфікацыя і MCP, а таксама якія змяны адбуваюцца для младшых і старшых распрацоўшчыкаў.