Практычныя прытамулкі: Чаго я навучыўся перад стварэнням свога першага агента LangGraph

У гэтым карыце парадоксу перадстаўляецца шлях ад сыр'ёчных матэрыялаў да рабочай системы для тэмы: «Што я вывучыў пры стварэнні свага першага агента LangGraph». Акцэнт ставіцца на практычныя крокі, чыстае перакананне ў правильнасці дзействаў і код, які можна проста падключыць у репазітарый, не прабуючы здогадвацца пра намеры. У стадії агульнага апісання неабходна з'явіць вхідныя даны, адпаведальнага за крок і критэрыя завершэння пры перадзмене коду. Аперацыйныя працавнікі должны магчымае перадзначыць крок з вядомай точкі контролю, не прабуючы здагадвацца пра схованы стан. Конфігурацыю трэба залічыць парадзельной ад коду прыкладнення. Файлы сераўіса, хранільнікі секрэтных данных і флагі функцияў должны знаходзіцца ў аднам месцы, якое працавнікі можуць пераглядаць, не чытаючы весь граф.

Чаму саме LangGraph зараз?

Калі працюеце над стадзіяй «Why LangGraph now», спачатку запісайце контракт: неабяжлівыя вхідныя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі список пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкіе контралі і обработка некоректных паведамленняў ёсць частью продукту, а не пазнейшым дапрацоўкам. Стварайце контрольныя пункты пасля дорогіх крокаў. Програма не должна зноў выклікаць той самы календар LLM, калі аператар перапрыбуе пазнейшы вузел.

Tool calling
MCP
Remote tools
A small agent harness

What if the workflow is not just a loop?
What if it branches?
What if it must remember the conversation?
What if different steps should have different jobs?

Што такое LangGraph (вызначэнне, якое нарэшце стало зрозумелым)

Калі працуеце над тым, як выглядае стэйдж What LangGraph, спачатку запісайце умовы працы: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачваць будучыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшоў, прычына нявыпання павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцужок задач. Стварайце контрольныя пункты пасля дорогіх крокаў. Програма для продакцыі не павінна зноў стягваць плата за той самы вызов LLM, калі аператар праканае выконанне наступнага вузла.

Оркестрацыя

Калі працуеце на стадзіі оркестрацыі, спачатку запісайце контракт: неабяжлівыя даннэ, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладоў заходзіць пазнейшыя змены коду ў правільным направленні. Спрэцьвуйце да гэтай стадзіі як да контракту межа даннемі і перакананымі выходамі. Дайце назву артыфактам, задаць правілы пераканання успеху і не падтрымайце тыхі частковыя завершэння. Зробіце перакананне пасля дорогіх крокаў. Продовжэнне не павінна зноў выклікаць той самы вызов LLM, калі аператар прабуе зноў запрацаваць пазнейшы вузел. Калі працуеце на стадзіі оркестрацыі, спачатку запісайце контракт: неабяжлівыя даннэ, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладоў заходзіць пазнейшыя змены коду ў правільным направленні. Зберагаце настройкі праза код аплікацыі. Файлы сераў, хранільнікі секрэтных дадзеных і флагі функций павінны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всей структуры.

Customer orders
     ↓
Waiter takes the order
     ↓
Kitchen cooks
     ↓
Waiter brings food
     ↓
Cashier takes payment

User asks a question
     ↓
Understand / classify the request
     ↓
Maybe ask for clarification
     ↓
Search documentation
     ↓
Write an answer

Час выканання

Этап выконання працюе найэфектывней, калі яго розглядаць як вимерную плошчу. Зафіксавце адны ідеальны прыклад роботы, адну ситуацыю неудачы і прыметкі па поверненню да пачатковага стану пры розшырэнні масштаба. Дакументавце як шлях успеху, так і шлях вярнення да нормальнага стану разам. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў є часткай продукту, а не элементамі пазнейшай дапрацоўкі. Храніце стан графа ў простам і типаваным формате. Вкладаныя структуры маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакоююць продовжэнне роботы пасля перерываў.

You define nodes and edges
        ↓
You compile the graph
        ↓
You invoke it with a user message
        ↓
The runtime walks START → … → END

Агент з станам

Этап робота агента з станам работае наяўней, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выходзіць, прычына неудачы павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг дзеяння. Рэжым графа павінен застацца простым і з адначытаемымі дадзеннямі. Вярнутыя структуры дадзеных маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакшуюць продажчэнне роботы пасля перерываў.

User → “I teach at ABC School.”
Agent → answers, then forgets

User → “How do I enter grades?”
Agent → has no idea who you are

User → “I teach at ABC School.”
        ↓
      State remembers role / history
        ↓
User → “How do I enter grades?”
        ↓
Agent can use prior context

Чаму гэта мела значэнне для меня пасля Проекта 1

Што ўзначальвае значэнне гэтага этапу, лепш усвядомляць, калі яго рассматроўваць як вимерную паверхню. Зафіксавайце адны ідеальны прыклад, адзін прыклад неудачы і прыметку па адвярненню роботы перш чым расширваць масштаб. Рассматрайце гэты этап як кантракт межаў вхідных дадзеных і перакананых выходных рэзультатаў. Дайце назвы артыфактам, задаць критэрыя успеху і не падзеўляйцеся частым, непূরным выкананнем задач. Рэзультаты графа трэба зберагаць у простам і типаваным формате. Вярнутыя структуры дадзеных маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць возз'яднанне пасля перерываў. Што ўзначальвае значэнне гэтага этапу, лепш усвядомляць, калі яго рассматроўваць як вимерную паверхню. Зафіксавайце адны ідеальны прыклад, адзін прыклад неудачы і прыметку па адвярненню роботы перш чым расширваць масштаб. Канфігурацыю трэба зберагаць паза кодам прыкладнай програмы. Файлы сяродовішча, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць аудытаваць іх, не чытаючы весь граф.

Памяць агента (тая частка, яку вы постаўлялі памешчаць)

Для памяці агента на стадыі выканання крока неабяжна пазначыць вхідныя даны, адпаведальнага за гэты крок і критэрыі завершэння пры перадзеяванні коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не прабуючы спадарацца прыватны стан системы. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія перакрыцці та обробка некоректных паведамленняў є часткай продукту, а не элементамі пазнейшага доўрабкі. Неабяжна прыняць людзкую згоду для тых крокаў, якія выкарыстоўваюць грошы чы выконвуюць змяны ў продакшн-данных. Підключэння элементаў у час компілявання не є гарантыяй полнай адпаведнасці продукту выклікам бізнесу.

Короткая память

Для стадіі кашточнай памяці неабходна перад зменым коду адзначыць вхідныя даны, абавесніка крока і крытэрыі завершэння. Аперацыяныя працавнікі павінны магчымае перадзягаць крок з вядомай точкі контролю, не падозрываючы схованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшае, прычына неудачы павінна вказываць на адзінную абавесніцу, а не на заплутаны ланцужок задач. Пры роботах, якія выкалічваюць грошы або зменяюць даны для працы, неабходна людская апраўдка. Компіляцыйныя наладкі не ўзроўнаваліся з повнасцю бізнес-процэса.

User: I am a teacher at ABC School.
…
User: How do I enter grades?

Short-term memory ≈ working memory for this conversation

Даўгастраўная памяць

Для стадіі дзейнаеўскай памяці, перш чым зменяць код, неабходна адзначыць вхідныя даны, адпаведальнага за этап і крэтырыя завершэння. Аперацыёныя працавнікі должны магчымае запускаць этап з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Спрыяйце цій стадіі як даговору межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, адзначыце крэтырыя успеху і не прымайце часткова завершаныя рэзультаты без падтверджэння. Заставьце людзкія падтверджэння для тых крокаў, якія выкарыстоўваюць грошы або зменяюць даны для працы. Компіляцыйныя налашчэння не ўзроўнаўцуюцца з пачатковым станом бізнес-процэсаў. Для стадіі дзейнаеўскай памяці, перш чым зменяць код, неабходна адзначыць вхідныя даны, адпаведальнага за этап і крэтырыя завершэння. Аперацыёныя працавнікі должны магчымае запускаць этап з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Зберагачыце налашчэння парадульна да коду прыкладнага програмнага забезпечэння. Файлы сераўіса, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое працавнікі можуць пераглядаць, не чытаючы весь структураны лянцуг.

Short-term ≈ RAM for this session
Long-term  ≈ persistent storage across sessions

Найважлівэе разлікаванне

Калі працуеце над этапам «Найважлівэе разлікаванне», спачатку запісайце умовы контракту: неабяжлівыя даны, сигнал успеху і тое, што выканаецца у разы ўзельнага нявыпалення. Такі чэк-ліст дапамагае захаваць чыстасць пазнейшых змян у кодзе. Документавайце як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў є частью самага продукту, а не пазнейшых доработак. Зробіце контрольны пункт пасля дорогіх крокаў. Система вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел.

Оркестрацыя калькольнікаў (без перагантавання)

Калі працуеце з оркестрацыяй калькоўкаў без стадзій, спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выходзіць пад час частковага абякання. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Валічыце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок абякае, абяканне павінна вказваць на адную адпаведальнасць, а не на заплутаны ланцужок задач. Зробіце перапактаванне пасля дорогіх крокаў. Функцыя адновлення не павінна зноў выклікаць той самы калект раз, калі аператар праканае пазнейшы вузел.

Electrician
Plumber
Painter
Inspector

User
  ↓
Intake          (who is speaking? teacher / admin?)
  ↓
Classify / route
  ↓
Knowledge       (find the right docs)
  ↓
Support         (write the reply)

Участка чалавека (HITL)

Калі працуеце на стадзіі HITL з участю чалавека, спачатку запісайце контракт: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладзець пазбярэгчык будучыя змены коду. Спрыятлівае ставленне да гэтай стадзіі як да контракта межа данымі і перакананымі выходамі. Дайце назвы элементам, задаце критэрыя успеху і не падзельвайцеся на частковыя завершэння без паведамлення. Зробіце перапактаванне пасля дорогіх крокаў. Програма не должна зноў выклікаць той самы LLM-званак, калі аператар прабуе зноў выконаць пазнейшы вузел. Калі працуеце на стадзіі HITL з участю чалавека, спачатку запісайце контракт: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладзець пазбярэгчык будучыя змены коду. Зберагачыце настройкі за межамі коду прыемленае. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всей структуры.

User request
     ↓
AI prepares an action
     ↓
Sensitive?
     ↓
Pause → human approval → continue

Як взаімна прыяжосць канцэпцый

Этап анаізу взаімной прыяжосці канцэпцый работае наўлучней, калі яго розглядаць як вимерную паверхню. Зафіксавайце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Задокументавайце як шлях успеху, так і шлях вярнэння. Перапрыбуткі, людзкія контрольны пункты і обработка некоректных паведамленняў є частью продукту, а не наступным етапам дапрацоўкі. Зберагаюце стан графа ў простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакшуюць продовжэнне роботы пасля перарываў.

Orchestration  → who does what, and in what order?
Runtime        → what executes that plan?
State          → what do we remember while running?
Short-term mem → how does a multi-turn chat continue?
Long-term mem  → what should survive across sessions? (later)
Multi-agent    → when should steps be specialized?
HITL           → when must a human approve? (later)
Tools          → how does the agent reach outside knowledge?

Што вы будете ствараць: Агент падтрымкі LEPA

Процес, якім вы прыходзитеце, работае наяўней, калі яго спрыяваць як мерыемую паверхню. Запісаце адна «золатая» версія, адин прыклад неудачы і прыметкі па вярнэнню да пачатковага стану пры расшырэнні масштаба. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, прычына неудачы павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцюг задач. Рэзультаты роботы графа трэба зберагаць у простаму, типаваным формате. Вкладзеныя структуры маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакшуюць продовжэнне роботы пасля перерываў.

Вывад

Этап Takeaway працюе найкраща, калі яго спрыяваць як до меркавання. Зберагчыце адны ідеальны прыклад, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Спрыяйце гэтам этапу як кантракту межа вхіднымі даннымі і пераканаленымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце критэрыя успеху і адмовіцеся ад тых падчасовых завершэнняў, якія не зафіксаваны. Храніце стан графа ў простам і типаваным формате. Вярнутыя структуры дадзеных маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць возможнасць продажы роботы пасля перарываў. Этап Takeaway працюе найкраща, калі яго спрыяваць як до меркавання. Зберагчыце адны ідеальны прыклад, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Храніце настройкі параду з кодам прыемліка. Файлы сяродавішча, хранальнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабяжнага чытання всего графа.

Спялунакі

Для стадіі «Спянькі» неабходна прадзеўжэнне вхідных дадзенняў, апыліканнія власніка крока і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перапрацаваць крок пачынаючы з вядомага контрольнага пункту, не прымушаныя здогадвацца пра схованы статус. Неабходна аддзеўжэнне дакументацыі пра стандартны ход роботы і працэўку ў разы выклікаў. Перапрыбуткі, людзкія пераказы і адрабатка некоректных паведамленняў ёсць часткай продукту, а не пасляднім элементам дапрацоўкі. Неабходна людзкая апрацавка тых крокаў, якія ведуць да выдаткаў грошаў або зменыння дадзенняў у прыемным режыме. Працэўка ў часе компілявання не абавязкова значыць повную готовасць продукту для выкарыстання.

Чэк-ліст аперацыйнай працы

Стадія чэк-ліста аперацыйнай працы работае наякша, калі яе спрыймаюць як мерыемую плошчу. Перад расширэнням масштаба неабходна зафіксаваць адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра можлівасць анулявання змян.

Неабходна фіксавацыя часу выкарыстання тэстоў, а таксама косту токенаў чы супылакоў праз адзіны з рэзультатаў функцыональных тэстаў. Візуабілізацыя костоў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмовай среды ў спяльнаныя сераўы.

Зберагаюце стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакошуюць продовжэнне роботы пасля перерываў.

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

Конфігурацыю трэба зберагаць паза кодам прыкладнай програмы. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функцыяй должны знаходзіцца ў аднам месцы, куда аператары можуць аудытувать іх без неабяжнага чытання всего графа.

Зберагаюце стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакошуюць продовжэнне роботы пасля перерываў.

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

Запіскі для пакета f1b1f96d9570: не класты ключі прадаўцоў у репазітарыю, задаць максымальны ліміт токена на сесію, а таксама зберагчы транскрыпціі праза фіксатуры адлічэння, каб пазнейшыя замены моделяў заставаліся пораўнанымі.