Найкращі практики використання AI-агентів: інженерія платформ готових до експлуатації

Використовуйте цей документ як оновлену версію ідей з книги „AI Agent Best Practices: Production-Ready Harness Engineering (2026 Guide)“ для співробітників, які працюють з операторами: чіткі етапи, впорядковані блоки коду та примітки щодо відновлення, які зберігаються після передачі обов’язків. Етап Огляду найкраще функціонує, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний запис, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.

Що таке Agent Harness (і чому він потрібен)?

На етапі «Що таке агент» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід зберігати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь код. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен не є межею окремого тенанту.

Принципи, які не підлягають обговоренню (з репозиторію)

Щодо принципів, які не підлягають переговорам на цьому етапі, необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.

Детальний огляд репозиторію agents-best-practices

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

Довідкові файли в одному погляді

Під час роботи з довідковими файлами на певному етапі спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Фіксуйте назву інструменту, хеш аргументів, час відгуку та результат кожного виклику. Без цих записів дебагування займає години.

Чому це не „ще один перелік порад“

Під час роботи над питанням «Чому це не є окремою стадією», спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Фіксуйте назву інструменту, хеш аргументів, час відгуку та результат кожного виклику. Без цих записів дебагування агента займає години.

Ключові принципи агентів, готових до експлуатації (витягнуті з матеріалу)

Під час роботи над етапом «Ключові принципи для продакшну» спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової несправності. Цей перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну ієрархію операцій. Для кожного виклику фіксуйте назву інструменту, хеш аргументів, час виконання та результат. Без цих даних пошук помилок займає години. Під час роботи над етапом «Ключові принципи для продакшну» спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової несправності. Цей перелік допомагає зберігати чесність пізніших змін у коді. Поруч із функціональними результатами записуйте час виконання та витрати на токени або запити. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.

1. Модель пропонує — інструмент виконує

Модель 1 пропонує, що етап використання інструментів працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний приклад роботи, один випадок збою та запис про скасування дій перед розширенням обсягу завдань. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Встановіть ліміти на кількість токенів за раунд та сесію. Інструменти з автономним керуванням активно розширюють контекст; жорсткі обмеження запобігають тому, що демонстрації перетворюються на несподівані рахунки.

2. Кожен виклик інструменту повертає результат — навіть у разі збою

Кожен етап виклику інструменту працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис виконання, один випадок збою та примітку про скасування дій перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Розкривайте інструменти з вузькими схемами та чіткими позначеннями побічних ефектів. Хостам потрібно знати, які виклики змінюють стан, перш ніж вони автоматично схвалюють їх.

3. Ризик змінює процес

Метод «3 Risk changes the stage» працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Використовуйте інструменти з вузькими схемами та чіткими позначеннями побічних ефектів. Адміністраторам потрібно знати, які виклики змінюють стан системи, перш ніж автоматично схвалювати їх. Метод «3 Risk changes the stage» працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.

4. Контекст складається поступово, а не завантажується одразу

На етапі підготовки контексту для 4-го кроку необхідно визначити вхідні дані, відповідального за цей крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід зберігати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь архітектурний план. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен не є межею окремого тенанта.

5. Довгі завдання мають бюджети

Для 5 довгих завдань із етапами необхідно перед зміною коду визначити вхідні дані, відповідального за кожен етап та критерії завершення. Оператори мають мати можливість перезапустити етап з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.

6. Постійні збої перетворюються на функції системи

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

Покроковий посібник: від ідеї до реалізації за допомогою цього інструменту

Під час роботи за покроковим посібником спочатку запишіть умови контракту: необхідні вхідні дані, сигнал успіху та наслідки часткової невдачі. Такий перелік допоможе зберегти чесність подальших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, щоб оператори могли їх перевіряти, не читаючи весь код. Фіксуйте назву інструменту, хеш аргументів, час виконання та результат кожного виклику. Без цих записів дебагування займає години.

Етап 1: Карта (ставте правильні запитання)

Під час роботи над картою першої фази спочатку запишіть умови контракту: необхідні вхідні дані, сигнал успіху та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Фіксуйте назву інструменту, хеш аргументів, час відгуку та результат кожного виклику. Без цих записів дебагування займає години.

Фаза 2: Визначення (вибір рівня MVP)

Під час роботи над етапом визначення та вибору у Фазі 2 спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Записуйте назву інструменту, хеш аргументів, час виконання та результат кожного виклику. Без цих даних пошук помилок займає години. Під час роботи над етапом визначення та вибору у Фазі 2 спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Відомі заздалегідь витрати запобігають несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ.

Етап 3: Креслення (створення дизайну кріплення)

Етап створення креслення на Етапі 3 працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний приклад роботи, один випадок збою та примітки щодо скасування змін перед розширенням обсягу робіт. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та прапорці функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Запропонуйте інструменти з вузькими схемами та чіткими позначеннями побічних ефектів. Хостам потрібно знати, які виклики змінюють стан, перш ніж вони автоматично схвалять їх.

Етап 4: Впровадження (суворе дотримання креслення)

Фаза 4 «Впровадження» ефективно працює, якщо її розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування перед розширенням обсягу робіт. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Надавайте інструменти з вузькими схемами та чіткими позначеннями побічних ефектів. Хостам потрібно знати, які виклики змінюють стан, перш ніж вони автоматично схвалюють їх.

Фаза 5: Випуск (аудит перед запуском)

Етап аудиту під час запуску на фазі 5 працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Використовуйте інструменти з вузькими схемами та чіткими позначеннями побічних ефектів. Адміністраторам потрібно знати, які виклики змінюють стан системи, перш ніж автоматично схвалювати їх. Етап аудиту під час запуску на фазі 5 працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку щодо скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.

Реальний приклад: агент для аналізу ризиків у контрактах

У реальному світі на етапі укладення контракту необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.

Сценарій: Аудит існуючого дослідницького агента

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

Практичні поради щодо реалізації (з псевдокодом)

Щодо порад щодо практичної реалізації на кожному етапі, необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних. Аутентифікуйтеся біля шлюзу та знову авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею окремого тенанта.

Канонічний цикл агента (спрощений)

Для канонічної стадії агентного циклу необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цю стадію як контракт між вхідними даними та перевіреними результатами. Позначте елементи проекту, визначте критерії успіху та не допускайте беззвучного часткового завершення. Аутентифікуйтеся біля шлюзу та повторно авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею території користувача.

budgets = Budgets(step=25, time=120, tokens=8000, cost=0.50)
context = build_initial_context()
permissions = load_permission_matrix()while not budgets.exhausted():
    response = model.generate(context, tools=typed_tool_schemas)
    if response.finish_reason == "stop":
        break
    if response.tool_calls:
        for tool_call in response.tool_calls:
            if not permissions.is_allowed(tool_call):
                observation = "Permission denied: " + tool_call.name
            else:
                # Execute with risk‑appropriate checks
                if permissions.risk(tool_call) == "external_write":
                    approval = request_human_approval(tool_call.draft)
                    if not approval:
                        observation = "Human rejected: " + tool_call.name
                    else:
                        observation = execute_tool(tool_call)
                else:
                    observation = execute_tool(tool_call)
            context.append(observation)
        # Optional compaction trigger
        if context.token_count() > budgets.token_per_turn:
            context = compact_context(context, preserve_approvals=True)
    else:
        # No tool calls, just final answer
        break

Інструменти: від поганих до хороших

Щоб перевести інструменти з стадії «погано» на стадію «готово», необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок, починаючи з відомої точки контролю, без необхідності здогадуватися про прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні середовища. Аутентифікуйтеся біля шлюзу та повторно авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.

Шарування контексту для ефективності кешу

Для створення шарів контексту на етапі кешування необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід зберігати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь архітектурний план. Аутентифікуватися потрібно на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен не є межею окремого тенанта.

Layer 0: System policies (stable prefix) → Cached
Layer 1: Agent skill definitions (rarely change) → Cached
Layer 2: User session instructions (per conversation) → Not cached
Layer 3: JIT‑retrieved tool outputs (fresh) → Not cached

Розгортання вашого агента Harness: чому важлива інфраструктура

На етапі «Розгортання вашого агента Harness» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Аутентифікуйтеся біля шлюзу та повторно авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.

Саме тут вступає в гру Aeza.

На етапі «Це місце Aeza» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, тестовані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних. Аутентифікуйтеся біля шлюзу та знову авторизуйтесь на рівні обробки даних. Один лише токен не є межею окремого сервісу. На етапі «Це місце Aeza» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Відомі заздалегідь витрати запобігають несподіваним рахункам під час переходу з демо-середовища до спільних середовищ.

Чому саме Aeza для навантажень вашого агента?

Під час роботи над питанням «Чому саме Aeza для вашого етапу» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал успіху та наслідки часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретів та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Фіксуйте назву інструменту, хеш аргументів, затримку та результат кожного виклику. Без цих записів налагодження циклів агента займає години.

Безпека, спостережуваність та оцінка (не пропускайте це)

Під час роботи над етапом спостережуваності та оцінки безпеки спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Документуйте як шлях успішної роботи, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки.

Висновки та наступні кроки

Ваш план негайних дій

npx skills add DenisSergeevitch/agents-best-practices -g

git clone https://github.com/DenisSergeevitch/agents-best-practices.git ~/.codex/skills/

Перелік операційних кроків