Практычныя нататкі: Text-to-SQL агент прадакшн-узроўню з Claude Code

Існавайце гэта як перадрук ідэй з дапіса “Production-Grade Text-to-SQL Agent with Claude Code, LangGraph, Langfuse, FastAPI and Qdrant” для аператараў: чыстыя этапы, арранжаваныя блакі коду і прыметкі па вяснаванню, якія застаюцца пасля перадачы.

Рэпазітарый

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

Тэхнічная структура

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

LLM & Agent

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

Эмбеддынгі і векторны пошук

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

API і бэкенд

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

Frontend

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

Спостэрагальнасць і трэйсінг

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

Адзінакаванне

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

Інфраструктура і налаштавання

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

Сервер MCP

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

Тэставанне

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

Інструменты для распрацоўшчыков

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

Чаму вы створылі агента Text-to-SQL з нуля

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

1. Набор дадзеных UDogRetail — праектаванне рэалістычнай тэстовай асяроддзя

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

2. Адміністрацыя – як усе складаецца ў цэласць

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

Тэхнічны стак, які вы выбралі, і прычыны:

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

3. Стварэнне пайплайна RAG — схема + адзыскванне дакументаў

Для пункта 3. Стварэнне каналу RAG — схема + адзысквэнне дакументаў: перад змянай коду неабходна задаць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння. Аператары должны магчымае перзапускаць крок з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Конфігурацыю трэба залічыць параду ад коду прыкладнення. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцыяй должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаючы весь граф. Паказваць трэба тыя часткі тэксту, якія фактычна ляглі в основу адпаведнай адказы. Без цых цітатаў аператары не можаць разлічыць галюцынацію ад працягу індэксавання. Для пункта 3. Стварэнне каналу RAG — схема + адзысквэнне дакументаў: перад змянай коду неабходна задаць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння. Аператары должны магчымае перзапускаць крок з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест абмежлёных скрыптаў. Калі крок не выйшоў, прычына неудачы должна быць чытальная.

Адзін абяскаванне заместа заплутанага ланцоўка.

Індэксаванне схемы

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

Індэксаванне базы знаёмых

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

Адзысканне

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

4. Агент LangGraph — вузлы, стан і самакорэкція

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

class AgentState(TypedDict):
  question: str
  session_id: str
  retrieved_schema: list[str]
  retrieved_docs: list[str]
  generated_sql: Optional[str]
  sql_reasoning: Optional[str]
  sql_assumptions: list[str]
  sql_confidence: float
  validation_error: Optional[str]
  execution_result: Optional[ExecutionResult]
  execution_error: Optional[str]
  retry_count: int
  correction_history: list[CorrectionRecord]
  needs_clarification: bool
  clarification_message: Optional[str]
  final_explanation: Optional[str]
  langfuse_trace_id: Optional[str]

СТВОРАЦЬ

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

ПАРАВЕРЫВАЦЬ → Выконаваць

Метод VALIDATE → EXECUTE дае найлепыя рэзультаты, калі яго спрыяваць як мераемую структуру. Перш чым расшырваць сферу дзеяння, зафіксавайце адны ідэальны прыклад працы, адну сітуацыю абяроны і прыметку па вярнэнні да пачатковага стану. Храніце настройкі за межамі кода прыемлі. Файлы сераўіснага сэрвісу, базы секрэтных даных і пазнакі функцый крануцца ў адным месцы, якое аператары можаць пераглядаць без неабясненага чытання всей структуры. Стан структуры трэба падтрымваць у простам і тыпаваным фармаце. Вярнутыя блокі даных маскуюць інфармацыю пра тое, канфігурацыйны вузел запісаў які поле, і спаказваюць продовжэнне працы пасля перэрываў. Метод VALIDATE → EXECUTE дае найлепыя рэзультаты, калі яго спрыяваць як мераемую структуру. Перш чым расшырваць сферу дзеяння, зафіксавайце адны ідэальны прыклад працы, адну сітуацыю абяроны і прыметку па вярнэнні да пачатковага стану. Вядомыя прывяліце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшаў, абяранне павінна вказваць на конкрэтную адпаведальнасць, а не на заплутаны ланцоўкі дзеяння.

FORBIDDEN_KEYWORDS = frozenset({
"INSERT", "UPDATE", "DELETE", "DROP",
"TRUNCATE", "ALTER", "CREATE", "GRANT", "REVOKE"
})

Цікл самакорэкцыі

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

def route_after_execute(state: AgentState) -> str:
  if state["execution_error"] is None:
    return "explain"
  if state["retry_count"] >= settings.max_retries:
    return "clarify"
    return "correct"

5. Прыготавленне да праўдзівай працы — FastAPI, Docker, Terraform

Для пункта 5. Падчыненне да працы ў працэйным сераўерэ — FastAPI, Docker, Terraform: перад зменай коду неабходна адзначыць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння. Аператары должны магчымае перзапускаты крок з вядомай точкі контролю, не прабуючы спадарацца прыватны стан. Запісваюць час выканання і вартасць токена або запыту разам з функцыйнальнымі рэзултатамі. Відразы вартасці з самага пачатку запобегае неспакоўным рахункам, калі працэс пераходзіць з дэмовай асяроддзя ў спакульную. Неабходна людская апрацоўка тых крокаў, якія вітрачаюць грошы або зменяюць даны ў працэйным сераўерэ. Падключэнне пад час компіляцыі не ўзначае повнасці бізнес-процэсу.

API

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

Docker

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

#!/bin/bash
# backend/start.sh
set -e
echo "==> Running Alembic migrations…"
cd /app/backend && alembic upgrade head
echo "==> Starting uvicorn…"
exec uvicorn app.main:app - host 0.0.0.0 - port 8000

Канфігурацыя

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

class Settings(BaseSettings):
  anthropic_api_key: SecretStr
  voyage_api_key: SecretStr
  postgres_password: SecretStr
  langfuse_secret_key: SecretStr

6. Магчымасць абзірнасці з Langfuse — трэйсінг кожнага запуску агента

Калі працуеце над раздзелам 6. «Абсарбянасць з Langfuse» — адстэйроўванне кожнага запуску агента, спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выканаецца пад частым неудачам. Такі спіс пераканаецца падтрымае чыстасць будучых змян у кодзе. Зберагаюце настройкі праза код аплікацыі. Файлы сераўнавання, хранальнікі секрэтных дадзеных і флагі функцый должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць без неабяжнага чытання всіх элементаў. Стварайце контрольныя пункты пасля дорогіх крокаў. Функцыя вярнення до працы не должна зноў выклікаць той самы калект вызову LLM, калі аператар прабуюць зноў запустыць пазнейшы элемент. Калі працуеце над раздзелам 6. «Абсарбянасць з Langfuse» — адстэйроўванне кожнага запуску агента, спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выканаецца пад частым неудачам. Такі спіс пераканаецца падтрымае чыстасць будучых змян у кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, неудача должна адносіцца да адной конкрэтнай адпаведальнасці, а не да заплутанага ланца задач.

.

@observe(name="generate", as_type="generation")
def generate(state: AgentState) -> AgentState:
# Claude call happens here
# Langfuse auto-captures input, output, latency

lf = get_lf_client()
lf.update_current_observation(
model="claude-sonnet-4–6",
usage={"input": input_tokens, "output": output_tokens},
)

7. Аптэкстыранне — тэсты на элемент і інтэграцыйныя тэсты

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

Тэсты на элемент

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

@pytest.mark.parametrize("keyword", sorted(FORBIDDEN_KEYWORDS))
def test_forbidden_keyword_rejected(keyword: str) -> None:
  sql = f"{keyword} INTO orders VALUES ('x')"
  result = validate_sql(sql)
  assert not result.is_valid
  assert keyword in result.error_message
  def test_forbidden_keyword_in_cte_still_rejected() -> None:
  sql = "WITH x AS (DELETE FROM orders RETURNING id) SELECT * FROM x"
  result = validate_sql(sql)
  assert not result.is_valid

pytest tests/unit/ -v

Тэсты інтэграціі

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

pytest tests/integration/ -v

8. Адгукі агента за дапамойкай GEval

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

prompt = f"""
Score from 0.0 to 1.0 whether this explanation is faithful to the results.
Results: {json.dumps(rows[:5])}
Explanation: {explanation}
Return only JSON: {{"score": float, "reasoning": str}}
"""

python -m evaluation.harness --complexity simple
python -m evaluation.harness --limit 10

9. Сервер MCP — як зробіць яго часткаю Claude Code

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

mcp = FastMCP(name="udogretail-text2sql")
@mcp.tool()
def query_tool(question: str, session_id: str = "") -> str:
"""Run a natural-language question through the Text-to-SQL agent."""
…
@mcp.tool()
def schema_tool(keyword: str) -> str:
"""Look up tables and columns matching a keyword."""
…
@mcp.tool()
def history_tool(limit: int = 5) -> str:
"""Fetch the last N query runs from agent history."""
…

{
"mcpServers": {
  "udogretail-text2sql": {
    "type": "stdio",
    "command": ".venv/bin/python",
    "args": ["mcp_server/server.py"],
    "env": {"API_BASE_URL": "http://localhost:8000"}
    }
  }
}

10. Рэзультаты, урокі і тое, што бы вы зрабілі інакшэ

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

Адміністрацыя заместо заплутанага ланцуга працы.

Што бы вы зробілі інакшэ:

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

Што меня здывавало:

Калі працуеце над раздзелам «Што меня здзівіла», спачатку запісайце умовы выканання: неабяжлівыя даны, сігнал успеху і тое, што відбываецца у разе частковага невыпання. Такі спіс контролю дапамагае заліцвачваць пазнейшыя змены коду.

Чэк-ліст для эксплуатацыі

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

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

Пауза пасля дорогіх крокаў. Функцыя аднова не павінна знову нараховваць плата за той самы вызыв LLM, калі аператар праказвае спробу на пазнейшый вузел.

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

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

Пауза пасля дорогіх крокаў. Функцыя аднова не павінна знову нараховваць плата за той самы вызыв LLM, калі аператар праказвае спробу на пазнейшый вузел.

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

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