Практычныя прытамулкі: ваш агент не ведае, як чакаць

Практычныя прыказкі: ваш агент не ведае, як чакаць – контракты, чекі та слоты для коду для команд, якія використоўваюць гэты патэрн.

1857 слоў

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

{
  "name": "operations/abc-123",
  "status": "RUNNING",
  "done": false
}

Закрытыя выкладкі чакання

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

Настройка тэстовага стандарта

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

Тры спосабы чакання

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

1. get_operation: Поллінг унутрь цыклу агента

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

create_instance()      → operations/abc-123
get_operation(abc-123) → RUNNING
get_operation(abc-123) → RUNNING
... ×10 ...
get_operation(abc-123) → DONE

2. wait_for_operation: Блакаванне на серверы

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

create_instance()           → operations/abc-123
wait_for_operation(abc-123) → DONE   (one call, eleven minutes later)

3. Задачы: Перадача адліку на механізм выконання

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

Bash(cmd, run_in_background: true)  → task_id: task-8921
... agent configures network rules, audits schemas, writes migration scripts ...
TaskOutput(task-8921, block: true)  → done

Які ўсё-такі ўскладнення: тэст клонавання

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

while true; do
  st=$(cloud-cli operations list --project=production-db \
       --instance=staging-replica --format='value(status)' | head -1)
  [ "$st" = "DONE" ] && break
  sleep 20
done

Аптальнейшыя практыкі для дизайнераў API і інструментаў

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

1. Адкручыце цэлісную, ступеневую модель чакання

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

create_instance()                       → { "operation": "operations/abc-123", "done": false }
get_operation(id)                       → Tier 1: inspect status, resume after interruption
wait_for_operation(id, timeout_seconds) → Tier 2: the 90% single-instance case
create_instance(async)                  → Tier 3: durable handle for parallel, fleet-wide work

2. Уключыце ідэнтыфікаторы аперацый у тэла JSON

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

3. Адкладзіце часавыя таймауты з структураванымі частковымі рэзультатамі

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

{
  "done": false,
  "operation": "operations/abc-123",
  "elapsed_seconds": 300,
  "status": "RUNNING",
  "metadata": { "percent_complete": 65 }
}

4. Дзяржаба для выканання задач і асінхронных механізмаў

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

5. Працаваце з вашымі схемамі

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

Усьго калі

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

Чэк-ліст для аператараў

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

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

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

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

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

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

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

Усе артыкулы Даслаць брыф