Claude Agent SDK: де ламається агентна логіка в експлуатації
Агент на Claude Agent SDK у демонстрації виглядає надійно: викликає інструмент, отримує результат, відповідає. В експлуатації на потоці заявок картина змінюється — ламається не модель, а агентний шар навколо неї: управління контекстом, маршрутизація викликів, час життя сесії.
Перша за частотою відмова — втрата контексту діалогу. Коли листування зростає, історія виходить за вікно моделі, і агент перепитує вже названі дані або плутає номер поточної заявки з попередньою.
Клієнт бачить неуважного оператора, хоча причина — у стратегії ущільнення історії та в тому, які факти взагалі залишаються в пам'яті.
Другий клас — неправильний виклик інструменту: агент передає в облікову систему аргументи, яких там немає, або вибирає не той метод. Помилка не падає відразу, а спливає в даних пізніше, коли заявка вже пішла далі за процесом.
Третій — зависла сесія агента: зовнішній сервіс не відповів, граничний час очікування не задано, задача тримає виконавця і не звільняє чергу.
Четвертий — дублювання дій: повтор після мережевого збою створює другу заявку або повторну операцію, тому що крок не зроблено ідемпотентним.
Для процесу обробки заявок це обертається зростаючою чергою, ручним розбором і втратою довіри до автоматизації. Нижче розбираємо, як кожна з цих відмов закривається на рівні схеми агента, а не підпорками в інструкції.
Вимірюваний ефект: частка автоматичних відповідей і час відгуку
Спочатку фіксуємо базову лінію: скільки звернень зараз закривається без оператора, скільки часу займає типова заявка і як часто діалог обривається. Всі зміни порівнюємо тільки з цими значеннями — інакше «стало краще» не відрізнити від зміни навантаження. Для продакшен-агентів на Claude Agent SDK ми знімаємо ці метрики до і після кожного релізу.
Швидкість і частка автоматичних відповідей
- Час обробки типової заявки падає: агент сам піднімає контекст з історії звернення і не повертає людину до вже відповіді.
- Частка автоматичних відповідей зростає за рахунок сценаріїв, де раніше був обов'язковий оператор: людина підключається тільки на гілках з неоднозначними умовами.
- Клас відмов «агент мовчить» йде — на кожен крок задано явний результат, а несподіваний ввід веде діалог у запасну гілку, а не в тишу.
Передбачуваність під навантаженням і спостережуваність
- При піковому навантаженні поведінка не змінюється: черга звернень розбирається рівномірно, без «пощастить чи ні».
- Спостережуваність агента — по кожній заявці видно маршрут, спрацьовані кроки, точки запиту уточнень і підставу рішення.
- Регресії ловляться на тестовому наборі діалогів до викочування, тому правки логіки не перетворюються на сюрприз у продакшені.
Режими роботи агента: інтерактивний, пакетний, подієвий
Інтерактивний, пакетний і подієвий запуск розрізняються не тільки способом виклику, а й тим, як агент отримує контекст і коли повертає результат. Вибір режиму визначає, де взагалі можна зловити помилку.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Інтерактивний | Діалог з клієнтом, розбір заявки, уточнюючі питання | Сесія відкрита, є межа контексту, потрібна швидка відповідь |
| Пакетний | Масова обробка однотипних записів: документи, класифікація, збагачення даних | Діалогу немає — помилку не виправити на ходу, потрібен повторний прогін |
| Подієвий | Реакція на зміну в зовнішній системі: заявка, лист, статус | Залежить від джерела подій; при збої потрібна черга і повтор |
У всіх трьох режимах працює один агентний цикл у Claude Agent SDK — змінюється спосіб подачі задачі та політика зупинки.
Обмеження автономності
Автономність задається не режимом, а рамками: скільки кроків агент робить без підтвердження, які інструменти йому доступні, що він не має права змінити. Ми фіксуємо ліміт кроків, білий список дій і обов'язкове підтвердження для операцій, що змінюють дані в зовнішніх системах. Вихід за ліміт — не збій, а сигнал: задача сформульована занадто широко або не вистачає даних.
Передача діалогу людині
Передача діалогу людині — це заздалегідь спроектоване правило, а не аварійний сценарій.
Агент віддає діалог при низькій впевненості, повторюваному питанні або запиті, який він не уповноважений підтвердити, а оператор отримує зведення: що просив користувач, що агент встиг зробити, який крок не закритий. Без такого зведення передача перетворюється на повторний розбір з нуля.
Етапи впровадження агентного шару: від аудиту до передачі
Впровадження агентного шару на Claude Agent SDK починається не з коду, а з розбору того, як процес влаштований зараз. На цьому кроці ми фіксуємо операції, учасників, джерела даних і місця, де вже стоять ручні перевірки — саме вони стають точками контролю для агента. Робота йде ітераціями, і кожен етап закінчується артефактом, який замовник може перевірити.
- Аудит процесу і даних. Розбираємо потік задач, вхідні формати, власників результату і типові виключення — виходить перелік операцій, які агент може виконувати без ризику.
- Схема викликів інструментів. Визначаємо, які функції доступні агенту, які параметри він заповнює сам, а що приходить із системи; детерміновані перевірки залишаються в коді, а не в моделі.
- Обмеження і права доступу. Агент отримує тільки потрібні області видимості, ліміт кроків у ланцюжку і заборону на запис у критичні системи без підтвердження — так ціна помилки залишається низькою.
- Пілотний запуск на обмеженому потоці. Першу версію вмикаємо на частині звернень або на одному каналі, паралельно з поточним ручним контуром, і порівнюємо частку знятих з людей операцій.
- Перевірка на збоях. Окремий етап: відмова інструменту, порожня або суперечлива відповідь, дублюючі запити, повторні спроби, відкат. Дивимося, як агент деградує і що йде в ручний розбір по індивідуальному розрахункуПередача в супровід і навчання команди. Віддаємо схеми, конфігурації, регламент змін і розбір інцидентів; команда замовника вчиться сама правити інструкції агенту і читати його журнал.
Після передачі агент живе як звичайний сервіс: з власником, метриками і порядком змін. У цьому й різниця між прототипом, який вражає на показі, і рішенням, яке стабільно працює в промисловій експлуатації.
Конфігурації агентів, схеми інтеграцій і регламенти ескалації
Агент у продакшені живе не сам по собі, а всередині набору артефактів: конфігурацій, схем і регламентів. Ми передаємо їх разом з працюючим агентом на Claude Agent SDK — команда супроводу змінює поведінку і розбирає збої, не відновлюючи логіку по листуванню.
- конфігурація агента — роль, доступні інструменти, ліміти на крок і число ітерацій; зберігається в загальному репозиторії і версіонується разом з кодом;
- схема інтеграцій — карта зв'язків з системами і чергами: ініціатор виклику, таймаути, поведінка при недоступності суміжника;
- політики доступу до даних — які джерела агент читає, що закрито, де спрацьовує маскування і які дані не покидають контур;
- регламент ескалації — умови зупинки агента і передачі діалогу людині, відповідальний і термін реакції;
- документація супроводу — як підняти стенд, відкотити конфігурацію, де дивитися журнали і трасування;
- набір перевірок — сценарії та відмовні гілки, які проганяються до викочування нової версії агента.
Як читати схему інтеграцій
Схему читають за потоком запиту: точка входу, виклики інструментів, відповідь, запис у системи замовника. У кожного ребра відмічено, синхронний це виклик чи відкладений, хто відповідає за повтор при помилці і де стоїть обмеження за навантаженням.
Що робити при змінах
Перед правкою звіряються з політиками доступу і регламентом ескалації. Частина змін зачіпає тільки конфігурацію агента, інші вимагають прогону перевірок і погодження з власником даних.
Кейс: обробка заявок агентом — метрики до і після
Кейс — сервісна компанія з потоком однотипних вхідних заявок: частина звернень вимагає звірки даних у кількох облікових системах, частина — рішення людини.
Агента зібрали на Claude Agent SDK, описавши йому набір інструментів: читання заявки, пошук клієнта, вивантаження умов, формування відповіді і запис результату.
Вихідна ситуація
До впровадження заявку розбирав оператор: відкривав картку, звіряв дані в двох системах, вручну збирав відповідь. На одну заявку йшло 9–12 хвилин, у пікові години черга зростала, перша відповідь клієнту йшла через кілька годин. Заміри показали, що близько 70% звернень типові і не вимагають рішення людини.
Що змінилося в показниках
Агент закриває типові заявки повністю — знаходить дані, формує відповідь, фіксує результат в обліковій системі. На оператора йде тільки те, де умови неоднозначні.
Частка ручних операцій знизилася до 20–25%, середній час розбору заявки — до двох хвилин, перша відповідь клієнту йде в межах кількох хвилин.
Навантаження на операторів змістилося: замість потоку однотипних карток вони розбирають складні випадки, де потрібна експертиза.
Межі задали відразу: агент не приймає рішень за спірними нарахуваннями і не змінює умови договору — такі звернення йдуть людині з повним контекстом діалогу.
Чим Agent SDK відрізняється від самописного агентного циклу?
Самописний агентний цикл — це ваш код: ви самі реалізуєте виклик інструментів, обробку помилок моделі, переривання генерації, потокову віддачу відповіді і облік витрати контексту.
Claude Agent SDK закриває цей шар готовим рантаймом, тому старт зводиться до опису інструментів і правил, а не до відтворення механіки циклу.
| Критерій | Самописний цикл | Claude Agent SDK |
|---|---|---|
| Виведення в експлуатацію | тижні на каркас, поки не запрацює перший сценарій | цикл працює відразу, час йде на доменну логіку |
| Обсяг свого коду | весь: цикл, помилки, стан, повтори | інструменти, промпти і правила доступу |
| Контроль над логікою | абсолютний, аж до порядку кроків | повний у межах циклу, втручання через точки розширення |
| Підтримка | зростає з кожним новим сценарієм і правкою протоколу | оновлення рантайму бере на себе постачальник |
| Поріг входу | потрібен інженер, який впевнено веде асинхронний код | достатньо володіння моделлю і описом інструментів |
Межа відповідальності в обох варіантах одна: логіка рішень, набір інструментів, права доступу і обробка доменних помилок залишаються за вами. Різниця в тому, скільки ресурсу команда витрачає на обв'язку замість самої задачі — і як швидко ця обв'язка застаріває при зміні моделі.
Тому вибір частіше впирається не в техніку, а в режим розвитку: один агент з нестандартним протоколом дешевше вести своїм циклом, кілька агентів із загальною обв'язкою — на готовому рантаймі. Розбираємо на дзвінку ваші сценарії і називаємо, який варіант дасть менший обсяг коду в підтримці.
Часті технічні питання перед стартом проєкту
Старт інтеграції агентного шару впирається в п'ять інженерних питань, від відповідей на які залежить обсяг робіт. Нижче — як ми вирішуємо їх на практиці: ті ж рішення переносяться в проєкт майже без змін.
Як зрозуміти, що задача дійсно виконана?
Критерій завершення фіксуємо до початку розробки: набір перевірочних сценаріїв, очікуваний результат за кожним і припустима частка відхилень у серії прогонів. Приймання йде за повторюваним тестом, а не за одним вдалим діалогом — так видно, що агент стійкий, а не щасливий.
Що робити, якщо модель передала неправильні параметри виклику?
Схема виклику інструменту валідується до виконання: неповний або суперечливий набір аргументів не йде далі, а повертається агенту з описом помилки для уточнення. У журнал пишеться початкова спроба і причина відмови, руйнівних дій при невдалій валідації не відбувається.
Як обмежується доступ агента до наших систем?
Агент отримує тільки ті операції, які потрібні задачі, і працює під окремим службовим обліковим записом з урізаними правами. Область даних обмежуємо фільтрами на стороні сервісу, а не інструкцією в запиті, і ведемо журнал кожного виклику із зазначенням ініціатора.
Чи можна підключитися до працюючої системи заявок?
Так, через її штатний програмний інтерфейс. Перший етап — тільки читання: агент збирає дані і пропонує дії, нічого не змінюючи. Потім точково вмикаємо операції запису, по одній, з контролем результату. Ваша система при цьому не перебудовується.
Як відкочувати невдалі зміни?
Конфігурації агента, описи інструментів і підказки версіонуються, як код. Є рубильник для миттєвого відключення і перемикання на попередню версію — повернення займає хвилини, а не години. Записи у ваші системи йдуть з ключем запиту, тому повторний прогін не створює дублів.
Обговоримо задачу: що надіслати для оцінки і плану робіт
Оцінка і план робіт спираються на те, як процес влаштований зараз, а не на загальний опис задачі. Достатньо одного листа з вступними — і ми повернемося не з уточнюючими питаннями, а з етапами, термінами і переліком ризиків.
- Схема процесу: кроки від появи запиту до результату, хто приймає рішення на кожному кроці і де зараз втрачається час.
- 20–50 прикладів реальних звернень — включаючи нетипові і ті, що сьогодні вирішуються вручну всупереч регламенту.
- Доступні системи і дані: де лежать знання, в якому вигляді вивантажуються, чи є тестовий контур і обезличенная копія.
- Межі автономності: які дії агент виконує сам, а де обов'язкове підтвердження людини.
- Обмеження проєкту: терміни, вимоги до розміщення даних, політика доступу, погодження з безпекою.
- Склад команди замовника: хто відповідає за процес, хто видає доступи, хто приймає результат за етапами.
- Поточні метрики: частка ручних операцій, час відповіді, критичність помилки — щоб після запуску було з чим порівняти.
Якщо частина даних закрита або доступи видаються довго, це не блокує старт: розберемо доступне, а решту уточнимо по ходу робіт. Опишіть задачу і додайте те, що є, — повернемося з оцінкою і планом робіт.
