Практычныя прытамулкі: Агент для перакладу тексту на 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аннэй.