За межамі палеткі для чату: архітектура AI-агента WhatsApp на Google ADK

Большасць дэманаў ШІ — это проста полье для тэксту, з’ўязанае з моделлю: уводзіцца запит, выходзіць паводлівы адпаведжанне, і аудыянцы задоволены. Продукт, на які пакладаюцца рэальныя кліенты, мае длейшы список трэбаванняў. Ён должен памяцаць ход размовы, працаваць з актуальнымі даннымі компаніі, выконваць дзеяння, перажываць неудачы і перадаваць кліента чалавеку, калі аўтаматызацыя недастаткова.

У этай статыце прадстаўленая архітэктура асистента для працы ў WhatsApp для рынку заряджання АВТ у Шрі-Ланцы. Ён служыць водзілам АВТ, власнікам нерухомасці, якія могу размістіць зарядныя станцыі, і людзям, які проста хочуць дазнацца пра заряджання АВТ. У канцы вы будете мяць конкрэтны план элементаў, якіе абрамляюць модель, і набор правіл дызайну, якія можна перадаўжваць использоваць у вашым сабе агенте, незалежна ад канала, у якім ён працуе.

Чаму канал адначасова формуе і продукт

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

Гэты выбар таксама створыў абмежэнні, з якімі ніколі не сталкаецца веб-чатбот:

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

Мэтаем была розмова, яка адаптавана да стандартам WhatsApp, а не чат-бот на комп’ютере, які прымусова ўтрымваны ў дапаможным прыстрое для перадачы паведамленняў. Хацябы для якога-небудзь каналу, памяркуйце пра гэта: стандарты інтарфейсу платформы ёсць часткай спецыфікацыі, а не дэкоратывамі.

Шлях запыту ад webhook да адпаведзі

Бэкенд напісаны на Python за дапамогою кіту развіцця агентаў Google (ADK) і FastAPI. ADK можа стварыць готовы сервер API для агента, які включае в сябе падтрымку запуску агентаў, керавання сесіямі і передачу рэзультатаў у вигляде запаведамленняў. Шырока вжываны сервер API працюе на FastAPI і Uvicorn, што значна спрыяе дадатковаму расшырэнню за дапамогою спецыяльных WhatsApp webhook і канцаўак, прызначанных для конкрэтных бізнес-праблем.

Агент ADK складаецца з чатырох элементаў:

• Модель, напрыклад Gemini.
• Інструкцыі, якія визначаюць ролю і межы агента.

Адыяваны, які дазваляюць яму шукаць даныя або выканаць дзеянні.

Сесыя, якая зберагае памятку пра размову.

Працэўнае адраджэнне ад першага паведамлення да канцала робіць дыяграму болей зрозумелай:

1. Пользователь адправляе паведамленне у WhatsApp, і Meta перадае яго на webhook FastAPI.
2. Бэкенд парсуе паведамленне і перадае яго ў Chatwoot, каб каманда падтрымкі магла стежыць за размовай.
3. Бэкенд шукае сесыю для гэтага пользователя і перадае паведамленне ADK.
4. ADK запускае коордынатора, які направляе запит: тэхнічныя запытанні — да агента EV, запытанні пра заробкі — да агента цэнаў, пошук станцый — да агента станцый.
5. Выбраны агент альбо шукае ў базе знання Vertex AI, альбо вызывае адыяван, напрыклад, для запыту дакументаў станцый, аблікавання заробкаў, адправкі карточкі контакту чыя запыту месцаположэння пользователя.

Калі адказ гатовы, FastAPI яго фарматавае ў короткія паведамленні WhatsApp, апрацоўвае іх через API Meta і копіюе адказ у Chatwoot.

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

Аднаго координатора, трое спецыялістаў

Асистент організаваны як координатор, який дазваляе трохці спецыялістам выпалняць задачы:

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

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

Альтэрнатыўнае рашэнне — адны большы агент з дазволеннем да системы і ўсіма прыўязанымі інструментамі. Гэта падходзіць для пратыпа, але калі збіраўся большы набор інструментоў і форматаў размовы, раздзелэнне абавясцей дала плоды троха способамі: кожна інструкцыя заставалася короткай, было лёгка з’ясаваць, який агент можа выкорыстоўваць які інструмент, і кожны формат размовы мог быць працаваны окрема. Раздзелэнне координатора ад яго спецыялістаў, аднаго з задокументаваных шаблонаў керування агентамі, таксама зменшыла вартасць змян, адколі логіку цэнавак можна было перазначыць без змены процесу пошуку станцый.

Існуе цена, якую варта назваць. Кожна рашынка па маршруту ўособлівае ўтворэнне моделі, якае можа паспяліцься, таму неправильна рашынка па маршруту прыводзіць да невялікосці так, як гэта ніколі не стануцься з адным агентам. Гэта адна з прычын, чаму стратэгія ацэнкі, описаная пазней, пераконтвалюецца, калькі агента і інструмента былі выбраны, а не толькі фінальная формулюванне. Чыба глэбэйшага аналізу таго, як маршрутызацыя і спецыялістычныя агенты супрацоўнаюць, паглядзіце спецыялістычныя агенты, кэйворд-маршрутызатор і перерыв у LangGraph.

Апоўненне адказаў кантролюемай базой знаёмых

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

Адпаведнае рашэньне — генераванне з падтрымкай пошуку. Ведамасці храняцца як корпус у RAG Engine версіі Vertex AI, і перад тым, як адпаведзець на тэхнічны запыт, агент можа з’явіцца ў гэты корпус, каб знайсці найболей актуальныя фрагменты. Існуе два окольныя шляхі пошуку: адны для загальнай інфраструктуры заряджання электрычных автамобіляў, а другі — для запытаў пра моделі автамобіляў і час заряджання. Такое раздзелэнне корпуса дапамагае зберагчы фокус на рэзультатах, адколі запыт пра тое, сколькі часу патрэбна для заряджання конкретнага автамобіля, не конкуруець з дакументамі пра правілы за першасце ў рэзультатах.

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

Ператварэнне размовы на дзеяння

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

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

Чаму расчыткі заробкаў адбываюцца за дапамогою простага Python

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

Гэтыя вырахункі адбываюцца за дапамою дэтэрміністычнага Python, а не за дапамою мовнага модэлю. Модэлі не ўпэўненныя у арыфметыцы, і фінансавыя паказнікі, якія прадаюцца потэнцыйным кліентам, должны быць воспроўжненныя і перапрацаваныя. Модэль караце розмову і выкарыстоўвае інфармацыю, якая была аднароўвана; код жа вырабляе цыфры. Рэзультат дастаўляецца чераз структураваны шаблон WhatsApp, а інформацыя пра кліента заносится у Google Sheets.

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

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

Стан сесіі — это логіка продукту

Хорашая розмова залежыць ад таго, што было раней. Асістэнт трывае адзелёную сесію для кожнага номера WhatsApp, і ў гэтай сесіі зберагаецца імя корыстніка, номер тэлфона, выбраны варыянт меню, апошніе паведамленні, стан месцаположэння і ID апошнага паведамлення.

Зберагачыць ID апошнага паведамлення дапамагае системе разумець адпаведзі на конкрэтнае паведамленне з меню, што корыстнікі WhatsApp робяць сталяк. Стан сесіі таксама дапамагае многакрокавым процесам продовжвацца па-прыроднаму. Напрыклад, перадача месцаположэння вядзецца так:

1. Запытайце, чы хоча бы корыстнік павінен раздзеліцца сваім месцаположэнням.

Чакайце, пакі з’явіцца паведамленне пра месцазнаходжэння з WhatsApp.

Зберажыце координаты ў сесіі.

Аднова запускайце розмову на тым месцы, дзе яна была перывучана.

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

Фарматаванне для малага экрана

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

Для рашэння гэтай проблемы існуе спецыяльны слой фарматавання. Ён:

• Перакладае тэкст у формате Markdown у саёму синтаксісе фарматавання WhatsApp.
• Выяўляе спісы, якія знаходзяцца ўсередине прозы.

Перакладае іх у чытальныя пункты-спискі.

Раздзеляе дугі адказы на калькі корачэйых паведамленняў.

Короткія паузы между часткамі даюць чытачу час прыняць кожную ідею. Мета не ў тым, чтобы выдаваць за тое, што чалавек пішчырае; гэта проста регулюванне темпу. Індыкаторы пішчырання, якія надаюцца через Meta API, паказваюць, што адказ готуецца.

Асистэнт таксама реагуе на дзеякі паведамленні за дапамою эмодзі, прычому робіць гэта выборча. Легкі модель, такі як Flash Lite, вяршыць рашэнне, чыя паведамлення заслуговае на рэакцію, а як толькі так, рэакцыя надаецца через Meta API. Эмоцыйныя, захоплівыя, кумедныя або значымыя паведамленні могу отрымаць такую рэакцыю; звычайныя паведамленні, такія як „згодна“, „дзякую“ або простыя інструкціі, зазвычай яе не отрымаюць. Іспользованне малага, дешавога модэля для такага выборчага рашэння дапамагае зменшыць час адпаведзення та витраты, пакуль основныя агенты займаюцца сутніснаю часткаю задачы. Такія деталі поодзельна ўжо не такі важлівыя, але разам яны вяршыць рашэнне, чы робот выглядае натуральна.

Заліканне шляху да людзя

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

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

Автаматызацыя павинна абмежыць павтаральную работу, а не закрыць доступ да людзі.

Робота з надзеяйаннем параду розмовы

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

Навакол гэтага распалююцца не такі вже й прыгожыя функцыі, якія патрэбны кожнай службе:

• Усуненне дуплікацыі прыходзячых паведамленняў, адколі webhooks можа доставіць той самы запуск больш чым раз.
• Кантроль стану сістэмы.
• Обработка паўнаваго запуску токена доступу.
• Кантроль CORS на HTTP-канцах.
• Размешчэнне на базе Docker.
• Адстежэнне абохакоў за дапамогою Sentry.

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

Тэставанне поведзення, а не толькі тексту

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

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

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

Ключовыя выводы

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

З’єднанне запиту з виклікам API дозволяе стварыць дэманстрацыю. Надзеяны агент — цэлая система, у якой мовныя моделі, даны, інструменты, дизайн продукту та стандартная архітектура бэкенду кожны виконвае тую ролю, у якой ён найкращы.