Агенттерді бұзбайтын құрал схемаларын нұсқалау

Неге агент өріс өзгергеннен кейін бұзылады

Агент құралды адам құжаттаманы оқығандай «түсінбейді». Ол үлгіні есте сақтайды: функция атауы, өріс атаулары, рұқсат етілген мәндер, промпттағы шақыру мысалдары және бұрын сәтті шыққан жауаптар. Команда контрактіні өзгерткенде, агент көбіне аргументтерді ескі схема бойынша жинай беретін болады.

Ең жиі болатын қате қарапайым көрінеді. Кеше get_order_status(order_id) жұмыс істеді, бүгін функция order_id мен channel күтеді. Агент әдетінше тек ескі аргументтер жиынын жібереді, ал тексеру шақыруды бірден кері қайтарады.

Бірақ бұзылу әрдайым бірден білінбейді. Өрістің типін өзгертсеңіз, модель де сүрінеді. Өріс сан еді, жолға айналды. Еркін мәтін еді, бірнеше мәннен тұратын enum болды. Агент әлі де ескі логикамен аргументтерді таңдап, бұрын өтетін нәрсені жібере бастайды.

Тағы бір тыныш түрі бар. Функция формалды түрде орындалады, бірақ мағынасы енді басқа болады. Мысалы, order_id өрісін external_order_id деп ауыстырдыңыз, ал агент ескі әдетпен ішкі нөмірді соған салады. JSON деңгейінде қате жоқ, жауап келеді, бірақ пайдаланушы бөтен тапсырыстың күйін көреді немесе бос нәтиже алады. Мұндай ақаулар ашық қателерден де жаман, өйткені олар кеш байқалады.

Көбіне мәселе төрт себептің біріне тіреледі: агент ескі өріс атауларын есте сақтап қалған, жаңа міндетті аргумент туралы білмейді, ескі типті немесе ескі enum мәнін қолдана береді, не промпттағы мысалдарды алады, олар енді схемаға сай келмейді.

Соңғы тармақты жиі бағаламайды. Схема кодта жаңарды, ал жүйелік промпт, few-shot мысалдар және сынақ сценарийлері ескі күйінде қалды. Сол сәтте модель екі түрлі сигнал алады да, көбіне жаңа сипаттамадан гөрі мысалдарға көбірек сенеді.

tool calling бар жүйелерде бұл әсіресе байқалады. Қоңыраулар бір OpenAI-үйлесімді шлюз арқылы өтсе де, құрал схемасы үйлесімді көшу болмай өзгерсе, endpoint тұрақтылығының өзі құтқармайды. Сондықтан құрал схемаларын нұсқалау - формалдылық емес, агент әрекетіндегі жасырын қателерден қорғаныс.

Құрал контрактына не кіреді

Құрал контракты - функция сипаттамасындағы JSON-схема ғана емес. Агент үшін бұл күтілетін нәрселердің толық жиыны: функция қалай аталады, қандай өрістерді беру керек, қандай дерек типтері рұқсат етіледі және жауаптан не алады.

Функция атауының өзі-ақ мағына береді. Егер құрал check_order_status деп аталса, агент тапсырыс күйін тексеруді күтеді, жеңілдік есептеуді не клиент іздеуді емес. Тіпті шағын ғана қайта атау да мінез-құлықты шатастырып жіберуі мүмкін, өйткені модель сипаттамаға ғана емес, атаудың өзіне де сүйенеді.

Кіріс бөлігінде агент өрістерді дерлік форма сияқты оқиды. Ол қандай аргументтер барын, қайсысы міндетті екенін және оларды қандай түрде толтыру керегін қарайды. Егер кеше order_id жол болса, ал бүгін санға айналса, бірқатар шақыру құлайды. Егер сіз region деген жаңа міндетті өріс қоссаңыз, сәтті шақыру ықтималдығы да төмендейді: ескі сценарийде агентте ол мәнді қайдан алатыны жоқ.

Оған қоса мәндердің форматы мен жауап құрылымы да осы контракттың бөлігі. Адам үшін 2025-04-27 мен 27.04.2025 бірдей түсінікті болуы мүмкін. Агент үшін бұл - екі бөлек ереже. Сома, валюта және идентификаторлар да солай: 001234, 1234 және ORD-1234 әртүрлі тармақтарға әкелуі мүмкін.

Құралдың жауабы да контракттың бір бөлігі. Агент келесі қадамды сіздің ниетіңізбен емес, жауаптағы өрістермен құрады. Егер бұрын ол status: \"paid\" алатын болса, ал қазір payment.state түріндегі ішкі объект келсе, ол тапсырысты растау керек пе, төлем сұрау керек пе, әлде басқа құралды шақыру керек пе - түсінбеуі мүмкін.

Бұл әсіресе агенттік қабат бір ғана промпт нұсқасы мен бір ғана модельден ұзақ өмір сүретін жүйелерде жақсы байқалады. Команда SDK-ны өзгертпей, endpoint-ке тимей-ақ қоя алады, бірақ функция контрактының ауысуы бәрібір агенттің мінез-құлқын өзгертеді. Мұнда қарапайым ереже мынау: модель шақыруға дейін және шақырудан кейін оқитын нәрсенің бәрі - контракт.

Қашан жаңа нұсқа керек

Жаңа схема нұсқасы тәртіп орнату үшін емес, ескі шақыру енді бұрынғыдай өмір сүре алмай қалған кезде керек. Егер агент бұрынғыдай өрістер жиынын жіберіп, дәл сол түсінікті жауапты алса, жаңа нұсқа көбіне қажет емес. Бұл - API-дің қалыпты кері үйлесімділігі.

Ең қауіпсіз жағдай - жаңа міндетті емес өріс қосу. Ескі агенттер оны жібермейді де, ештеңе бұзылмайды. Жаңалары оны бірден қолдана алады, ал ескілері өзгеріссіз жұмысын жалғастыра береді.

Жаңа нұсқа функция контрактының өзі өзгергенде керек. Әдетте бұл төрт жағдайда көрінеді: өріс типі өзгереді, міндетті емес өріс міндеттіге айналады, өрістің мағынасы ауысады немесе функция жауабы ескі агент енді оқи алмайтындай болып өзгереді.

Өріс мағынасының ауысуы - ең жағымсыз сценарийлердің бірі. Егер status=\"paid\" бұрын төлем фактісін білдірсе, ал қазір ішкі өңдеу кезеңін білдіре бастаса, агент қате шешім қабылдайды. Ескі өріске жасырын түрде жаңа мағына беруге болмайды. Одан да жаңа өріс қосып, ескісін көшу кезеңі біткенше қалдырған дұрыс.

Нұсқаларға арналған пайдалы ереже қарапайым: алдымен қосыңыз, сосын ескі деп белгілеңіз, кейін ғана өшіріңіз. Керісінше емес. Схемада, құжаттамада және жүйелік промптта deprecated деген белгі қалдыру командаға ескі форматты ұмытуға жол бермейді.

Көбіне екі нұсқаны қатар қолдау да көмектеседі. Біраз уақыт құрал v1 мен v2 екеуін де қабылдайды, ал ішкі код оларды бір ортақ модельге келтіреді. Сол кезде команда ескі контрактта әлі кімдер отырғанын көреді де, көші-қонды асықпай жүргізе алады.

Бұл бір құралды әртүрлі модельдер мен әртүрлі промпттар шақыратын жерде әсіресе пайдалы. Жаңарту бір күнде барлық клиентке және барлық сценарийге бірдей жүрмейді. Қысқа уақыттық қосарланған қолдау әдетте продакшендегі қателерді жедел түзетуден арзанырақ.

Күмәндансаңыз, бір сұрақ қойыңыз: ескі агент функцияны өзгеріссіз шақырып, жауаптың дәл сол мағынасын ала ала ма? Егер жоқ болса, жаңа нұсқа шығарыңыз.

Схеманы қалай бұзбай өзгертуге болады

Агент дайындықтың өзінен емес, күтілімдердің сәйкес келмеуінен бұзылады. Кеше құрал order_id қабылдайтын, бүгін order.id күтеді, ал агенттің промпты мен коды әлі де ескі шақыруды жинап жүр. Соның нәтижесінде тексеру құлайды, жауап босап қалады немесе агент бір ғана tool call-ды қайта-қайта қайталай береді.

Алдымен бұзылған тұсты табыңыз. Нақты шақыруларды тексеріңіз: агент қазір қандай өрістерді жібереді, қайсысы міндетті, қай жерде бос жолдар, ескі атаулар және ескі типтер кездеседі. Сонда сіз деректер формасын жай ғана өзгерттіңіз бе, әлде бүкіл контрактты бұздыңыз ба - тез түсінесіз.

Жұмыс тәртібі әдетте мынадай болады:

1. v2-ні v1-дің қасына қосыңыз да, ескі схеманы бар үстінен қайта жазбаңыз.
2. Кірісте екі нұсқаны да қабылдаңыз. Егер бұрын order_id келсе, ал қазір order объектісі керек болса, екі форматты да қолдаңыз.
3. Екі кірісті бір ішкі модельге келтіріңіз. Бизнес-логика нұсқаларға бөлінбей, бірдей өрістер жиынымен жұмыс істеуі керек.
4. Ескі шақырулар үшін логқа ескерту жазыңыз. Сұранысты өңдеп жіберген, агенттің сценарийін бұзғаннан жақсы.
5. v1-ді тек нақты трафикті бақылағаннан кейін ғана өшіріңіз, жергілікті тесттен кейін емес.

Қарапайым мысал: check_order_status_v1 order_id: string қабылдайды, ал check_order_status_v2 { order: { id: string, source: string } } қабылдайды. Серверде екі түрлі өңдеу тармағын соңына дейін ұстап тұрудың қажеті жоқ. Екі форматты да бір normalized_order_id және normalized_source сияқты ішкі құрылымға бірден келтіріп, әрі қарай бір ғана кодты шақырған дұрыс.

Логтағы ескерту де пайдалы болуы керек. Құрал атауын, нұсқасын, клиентті, шақыру жиілігін және әлі келіп жатқан ескі өрістерді жазыңыз. Осындай деректерден қай агент немесе сервис әлі ескі контрактта отырғаны және бұл қанша трафик беріп тұрғаны көрінеді.

Жиі кездесетін қате қағазда әдемі көрінеді: команда жаңа схеманы жариялайды, құрал сипаттамасын жаңартады да, валидациядан ескі өрістерді бірден алып тастайды. Адамдарға бұл таза архитектура болып көрінеді. tool calling бар агенттер үшін бұл - кенеттен үзіліс. Өтпелі кезеңді ұстап, трафикті бірнеше күн не апта қарап, v1-ді тек ескі шақырулар дерлік жоғалғанда ғана өшірген әлдеқайда қауіпсіз.

Тапсырысты тексеру функциясының мысалы

Қолдау қызметінде check_order деген құрал бар. Бірінші нұсқада агент екі аргумент жібереді: phone және order_number. Бұлай чат-бот, дауыс көмекшісі және бірнеше ішкі сценарий жұмыс істейді. Бәрі осы контрактқа үйреніп қалған, сондықтан оны бірден ауыстыру продакшенге жиі соққы болып тиеді.

Уақыт өте команда ішкі дерек моделін өзгертеді. Енді жүйе тапсырысты телефон нөмірі мен тапсырыс нөмірі арқылы емес, customer_id және order_id арқылы іздейді. Жаңа логика үшін бұл жақсырақ: ID нөмір форматына тәуелді емес, қайталану азаяды, іздеу де жылдамырақ жүреді. v2-де құрал схемасы енді customer_id мен order_id сұрайды.

Жаман жол анық: v1-ді өшіріп, бәрі жаңарғанын күту. tool calling бар агент ескі өрістерді жібере береді, валидация шақыруды қабылдамайды, ал пайдаланушы бос жауапты немесе "тапсырыс табылмады" дегенді көреді - шын мәнінде мәселе деректе емес, бұзылған контрактта.

Қалыпты көшу бұлай көрінеді. Кірісте үйлесімді бейімдеу қабаты қалады. Ол ескі де, жаңа да аргументтерді қабылдап, сосын оларды бір ішкі форматқа аударады. Егер phone және order_number келсе, адаптер CRM мен тапсырыстар жүйесі арқылы customer_id және order_id іздейді. Егер customer_id және order_id келсе, сұрау әрі қарай түрлендірілмей өтеді. Егер агент аралас өрістер жиынтығын жіберсе, код жаңа өрістерді алады да, логқа ескерту жазады.

Сонда агент тағы бір ай бойы v1 жіберіп жүрсе де құламайды. Пайдаланушы ештеңе сезбейді, ал команда логтардан нақты көріністі байқайды: қай агент әлі ескі схемаға сүйеніп отыр, ондай шақырулар қанша қалды, адаптер сәйкестікті табуда қай жерде жиі қателеседі.

Бұл үшін журналға бірнеше белгі жеткілікті: агент атауы, схема нұсқасы, адаптер іске қосылды ма, ескі өрістерге жаңа өрістермен сәйкестік табылды ма. Осындай деректермен команда v1-ді қашан өшіру керегін болжай салмайды. Ол фактіге қарайды.

Тәжірибеде схема өзінен-өзі сирек бәрін бұзады. Әдетте мәселені асығыстық тудырады. Ескі өрістер әлі керек болып тұрғанда, оларды жүйенің шетінде ұстап, іште тек жаңа модельмен жұмыс істеңіз. Сонда көші-қон жай өтеді, ал v1-ді өшіру мерзімі үмітке емес, логқа сүйенеді.

Кодта, схема мен промптта үйлесімділік

Функция контракты өзгергенде, агент көбіне схеманың өзінен емес, код, құрал сипаттамасы және промпттағы мысалдар арасындағы ұсақ айырмашылықтардан бұзылады. Ескі және жаңа өрістерді бір үйлесімділік қабатымен байланыстыру әдетте бәрін бірден v2-ге көшіруден жақсырақ көмектеседі.

Бір үйлесімділік қабаты

Ескі және жаңа өрістердің бір сәйкестік кестесін сақтаңыз. Команданың басында емес, жазбада емес, кодтың өзінде және схема жанында. Егер бұрын агент customer_id жіберсе, ал қазір функция client_id күтсе, өңдеуші екі нұсқаны да қабылдап, оларды бір ішкі өріске келтіруі керек.

Ескі өрістерге бұрынғыдай әдепкі мәндерді беріңіз. Егер v1-де include_details өрісінің әдепкі мәні false болса, оны v2-де үнсіз түрде true етіп өзгертпеңіз. Агент бұл өрісті әрдайым ашық жібермеуі мүмкін, сонда мінез-құлық ең ыңғайсыз сәтте өзгеріп кетеді.

Жауапты да функция мәні өзгермесе, v1 мен v2 үшін бірдей ұстаған дұрыс. Егер агент status, message және result оқуға үйренсе, жаңа нұсқада тек data қайтару және оның өзі қайта бейімделеді деп күту дұрыс емес. Сервис ішінде жаңа формат сақталуы мүмкін, бірақ сыртқа бірдей құрылымды беру қауіпсіз.

Қарапайым ереже мынадай: ішкі іске асыруды қалағанша өзгертуге болады, ал сыртқы жауапты мүмкіндігінше ұзақ тұрақты ұстаған дұрыс.

Мысалдар мен тесттер

Промпт кодтан жылдамырақ ескіреді. Схеманы жаңартсаңыз, мысал шақыруларды да бірден жаңартыңыз. Агент көбіне сипаттаманы мұқият оқығаннан гөрі, дәл мысалды қайталайды.

Релиз алдында кем дегенде төрт нәрсені тексеріңіз: ескі шақыру мысалы әлі де қате шықпай өте ме, жаңа мысал дәл сондай типтегі жауап бере ме, агент ескі өріс атауын да, жаңасын да түсіне ме, әрі әдепкі мәндер нәтижені үнсіз өзгертіп жібермей ме.

Содан кейін бір ғана промптты ескі және жаңа контрактта да іске қосыңыз. Тек JSON-ға емес, агенттің мінез-құлқына да қараңыз: ол сол бір құралды таңдады ма, керек аргументтерді жіберді ме, жауапты артық түсіндірусіз түсінді ме.

Егер сіз LLM-трафикті бір шлюз арқылы жүргізіп жатсаңыз, мұндай тексерістерді ортақ құралдар қабатына енгізу ыңғайлырақ. Мысалы, AI Router ішінде бір OpenAI-үйлесімді endpoint арқылы бір сценарийді өткізіп, SDK-ны ауыстырмай-ақ түрлі модельдердің құрал шақыруды қалай толтыратынын салыстыруға болады. Бірақ бөлек шлюз болмаса да ереже сол күйінде қалады: үйлесімділікті кодта, схемада және мысалдарда бірдей ұстау керек. Осы қабаттардың біреуі қалып қойса, агент қателесе бастайды.

Агенттерді жиі бұзатын қателер

Агенттер сирек күрделі себептен бұзылады. Әдетте команда схеманы оны адам оқығандай өзгертіп жібереді, ал модель мен оның айналасындағы кодты есепке алмайды. Агент үшін тіпті шағын түзету де бұзылу болуы мүмкін.

Ең жиі қате - өтпелі кезеңсіз өрісті міндетті ету. Кеше агент customer_id жіберіп, бәрі жұмыс істеп тұрды. Бүгін сіз міндетті region қостыңыз, бірақ ескі промпт пен ескі код бұл туралы білмейді. Нәтиже алдын ала белгілі: шақырулар құлай бастайды, ал модель мәнді өзінен-өзі болжайды.

Екінші қате де аз ауырмайды: команда бір нұсқаның ішінде өріс типін string-нен object-ке ауыстырады. Адам үшін бұл функцияның қалыпты дамуы сияқты көрінеді. Агент үшін бұл сол шақырудың басқа форматы болып қалады. Егер бұрын ол address: \"Алматы\" жіберсе, ал сіз енді { city, street } күтсеңіз, ескі шақырулар валидациядан өтпей қалады.

enum-мен жұмыс та жиі бұзады. Айталық, құрал new, paid, cancelled күйін қабылдайтын. Сосын сіз new енді керек емес деп, тек paid және cancelled қалдырдыңыз. Бірақ ескі агенттер, тесттер немесе сақталған сценарийлер әлі де new жібере береді. Егер рұқсат етілген мәндерді тарылтсаңыз, ескі мәндерді ең болмаса көшу кезеңінде қабылдап, анық түрлендірген дұрыс.

Тағы бір тыныш бұзылу бар: өріс сипаттамасы формасы жағынан өзгермеді, бірақ мағынасы ауысты. date өрісі бастапқыда тапсырыс жасалған күнді білдірсе, түзетуден кейін жеткізу күнін білдіре бастады. Схема сырттай сол күйде, валидация үндемейді, бірақ функция енді басқа нәрсе істейді. Мұндай өзгеріс ашық қатеден де қауіпті, өйткені ол кеш байқалады.

Жеке мәселе - логсыз және қарапайым метрикаларсыз релиз жасау. Егер агент шын мәнінде қандай аргументтер жіберіп жатқанын көрмесеңіз, ақауды бірінші күні байқамайсыз. Жаңарту шыққаннан кейін кемінде төрт белгіге қараған пайдалы: әр құрал бойынша валидация қателерінің үлесі, белгісіз және жетіспейтін өрістер, әлі келіп жатқан ескі enum мәндері, және схема нұсқалары бойынша сәтті шақырулар үлесі.

Мұнда жақсы ереже қарапайым: егер деректер формасы немесе өріс мағынасы өзгерсе, оны ұсақ түзету сияқты көрсетпеңіз. Жаңа нұсқаға ескімен қатар өмір сүруге мүмкіндік беріңіз, логтарды жинаңыз да, ескі контрактты тек оның үстіндегі трафик дерлік жойылғанда ғана алып тастаңыз.

Релиз алдында қысқа тексеріс

Егер релиз кем дегенде бір өріс бойынша контрактты өзгертсе, агент бірден емес, бірнеше күннен кейін де бұзылуы мүмкін. Мәселе көбіне схеманың өзінде емес, ескі шақырулардың кодта, промпттарда және кэштерде әлі де өмір сүріп жатқанында жатады.

Жаңарту алдында қысқа тексерістен өткен пайдалы:

• Ескі шақыруды қолдан жаңартусыз іске қосыңыз. Логтан немесе тесттен нақты payload алып, сол күйінде жіберіңіз.
• API жауабын ғана емес, бизнестегі соңғы нәтижені де салыстырыңыз. Жаңа шақыру ескісімен бірдей нәтиже беруі керек.
• Логтарды нұсқа бойынша бөліңіз. Трассировкада, метрикада және аудит жазбасында v1 ме, v2 ме - көрініп тұруы керек.
• Лас кірістерге тест қосыңыз: бос жолдар, өрістердің ескі атаулары, күтпеген enum және артық аргументтер.
• Ескі нұсқаны өшіру күнін бекітіп, оны әзірлеушілерге, интеграция иелеріне және қолдау тобына жеткізіңіз.

Егер кемінде бір тармақ өтпесе, релизді кейінге ысырыңыз. Жариялауға дейінгі бір қосымша күн продакшенде тыныш бұзылудан әлдеқайда арзан, әсіресе функция формалды түрде жауап беріп тұрса да, сіз күтпеген нәрсені істеп тұрған кезде.

Әрі қарай не істеу керек

Барлық құралды бірден реттеуге тырыспаңыз. Соңғы айларда ең жиі өзгерген бір функцияны алыңыз. Әдетте агент дәл сонда қателескен болады: өрістің ескі атауын шатастырған, жаңа міндетті аргументті өткізіп алған немесе ескі контракт бойынша шақыру құрған.

Содан кейін команда үшін қарапайым ереже бекітіңіз. Егер сіз міндетті емес өріс қоссаңыз, ескі атаулар мен жауаптың ескі мағынасын сақтасаңыз, сол нұсқада қала беруге болады. Егер өріс типін өзгертсеңіз, оны міндетті етсеңіз, аргументті қайта атаған болсаңыз немесе нәтиженің мағынасын ауыстырсаңыз, v2 шығарыңыз. Мұндай ереже ревьюдегі дауды азайтады да, құрал схемаларын нұсқалауды кәдімгі инженерлік әдетке айналдырады.

Бір қысқа спринтке лайық ең аз жоспар мынадай: бір проблемалы функцияны таңдау, оның қазіргі контракты бір жерде сипаттау, схема нұсқасы мен валидация қателеріне логтарды қосу, содан кейін бірнеше модельде 10-15 нақты сценарийді өткізу. Соңғы қадам әсіресе маңызды. Бір модель артық өрісті тыныш қабылдап, шақыруды өзі толықтырады, ал екіншісі міндетті аргументті өткізіп жібереді немесе ескі формат жібереді. Бір ғана модельдегі тест онша көп кепіл бермейді.

Логтарды да күрделендірудің қажеті жоқ. Схема нұсқасын, құрал атауын, валидация қатесінің мәтінін және сезімтал деректерді жасырып алынған кіріс аргументтерді сақтаңыз. Сонда ақау промпттан, модельден немесе жаңа контракттан шыққанын тез түсінесіз.

Егер команда қазірдің өзінде LLM-трафикті AI Router арқылы өткізіп жүрсе, жаңа схеманы бір endpoint-та тексеріп, әртүрлі модельдердің мінез-құлқын клиент кодын өзгертпей салыстыру ыңғайлы. Бірақ қарапайым архитектурада да мәні бір: алдымен үйлесімділік, сосын ескі нұсқаны жою.

Осысының өзі келесі өзгерістердің агенттерді кездейсоқ бұзбауына жеткілікті. Құрал схемаларын нұсқалау ең жақсы нәтижені ол релиздің кәдімгі бөлігіне айналғанда береді, апаттан кейінгі шұғыл шараға айналмағанда.