Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.
Практика Средний уровень До 12 минут

Надёжное выполнение AI-агента: чекпоинты и идемпотентность за 42 строки Python

Надёжное выполнение AI-агента: чекпоинты и идемпотентность за 42 строки Python
Temporary fallback cover; replace in editorial pass.

Агент может успешно оплатить заказ, упасть до отправки подтверждения и после перезапуска повторить оплату. Разберём минимальную схему, которая сохраняет прогресс в SQLite, возобновляет незаконченные шаги и защищает внешние операции с помощью идемпотентности.

Почему одного retry недостаточно

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

Последовательность выглядит так:

  1. агент читает состояние заказа;
  2. вызывает платёжный API;
  3. процесс завершается до записи ответа;
  4. после перезапуска агент считает шаг незавершённым и повторяет вызов.

Чекпоинт решает вопрос «где продолжить», а идемпотентный ключ — «как повторить безопасно». Для настоящей защиты нужны оба механизма.

Модель: шаги и ключи операций

Каждый шаг получает стабильный идентификатор. Например, order:123:charge. Он не должен меняться между повторами одного и того же намерения. В журнале хранятся статус, результат и время обновления.

Внешний сервис также должен принимать этот ключ и гарантировать, что повторный запрос с тем же ключом не создаст новый эффект. Если API не поддерживает идемпотентность, локальная SQLite-запись сама по себе не может доказать, что операция выполнена ровно один раз.

Воспроизводимый пример за 42 строки

Создайте чистую папку и файл:

mkdir durable-agent
cd durable-agent
python3 --version
touch durable.py

Вставьте следующий код. Функция run_step фиксирует успешный результат, а effect_key передаётся внешнему исполнителю. В примере внешний вызов заменён функцией charge; это демонстрационная заглушка, а не платёжная интеграция.

import json
import sqlite3
import time

DB = "agent.sqlite3"

def connect():
    db = sqlite3.connect(DB)
    db.execute("""
        CREATE TABLE IF NOT EXISTS steps (
            key TEXT PRIMARY KEY,
            status TEXT NOT NULL,
            result TEXT,
            updated_at REAL NOT NULL
        )
    """)
    return db

def run_step(step_key, effect_key, effect):
    db = connect()
    row = db.execute(
        "SELECT status, result FROM steps WHERE key = ?",
        (step_key,)
    ).fetchone()
    if row and row[0] == "done":
        db.close()
        return json.loads(row[1])
    db.execute(
        "INSERT OR REPLACE INTO steps VALUES (?, ?, ?, ?)",
        (step_key, "running", None, time.time())
    )
    db.commit()
    db.close()
    result = effect(effect_key)
    db = connect()
    db.execute(
        "UPDATE steps SET status = ?, result = ?, updated_at = ? "
        "WHERE key = ?",
        ("done", json.dumps(result), time.time(), step_key)
    )
    db.commit()
    db.close()
    return result

def charge(effect_key):
    print("external charge with key:", effect_key)
    return {"accepted": True, "effect_key": effect_key}

if __name__ == "__main__":
    print(run_step("order:123:charge", "order:123:charge", charge))

Запустите его дважды:

python3 durable.py
python3 durable.py
sqlite3 agent.sqlite3 'select key, status, result from steps;'

Ожидаемый результат для этого локального примера: сообщение о внешнем вызове появляется только при первом запуске, а в таблице остаётся одна строка со статусом done. Это проверяет чекпоинт. Реальную защиту от двойной оплаты нужно проверять на контракте конкретного платёжного API.

Что происходит при падении

Представьте, что процесс завершается после строки result = effect(effect_key), но до SQL-запроса UPDATE. В базе останется статус running. После перезапуска код повторит эффект с тем же ключом.

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

Улучшение для рабочих систем

В учебном коде застрявший статус running не отличается от активного. В рабочем варианте добавьте владельца попытки, срок аренды и число повторов. При истечении аренды новый воркер может повторить шаг с тем же ключом.

Также полезно хранить:

Не помещайте секреты в result, логи или идентификатор ключа. Ключ должен быть уникальным для бизнес-операции, но не обязан содержать персональные данные.

Типовые ошибки

Генерировать новый ключ на каждой попытке

UUID, созданный внутри retry-цикла, превращает повтор в новую операцию. Создавайте ключ до первой попытки и сохраняйте его вместе с шагом.

Помечать шаг выполненным до внешнего вызова

Так можно потерять эффект: процесс запишет done, а затем упадёт до отправки запроса. Сначала вызывайте внешний сервис, затем фиксируйте его результат.

Считать SQLite распределённым координатором

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

Обещать «ровно один раз» без поддержки провайдера

Между внешним эффектом и локальной записью нет универсальной атомарности. Честная гарантия здесь — «повторяемо безопасно при стабильном ключе и идемпотентном API».

Проверка результата

Минимальная ручная проверка состоит из трёх сценариев:

  1. запустить программу дважды и убедиться, что второй запуск читает done;
  2. искусственно завершить процесс между внешним вызовом и UPDATE;
  3. перезапустить процесс и проверить, что используется тот же ключ операции.

Для интеграции с настоящим API проверьте документацию провайдера: срок хранения ключей, правила повторной отправки, соответствие параметров и формат возвращаемого результата. Не используйте реальные платежи для проверки без отдельного безопасного тестового окружения.

Ограничения схемы

42 строки дают основу, но не заменяют очередь задач, транзакционный outbox, дедупликацию входящих событий и мониторинг. Если агент выполняет несколько зависимых действий, сохраняйте отдельный чекпоинт на каждый шаг и явно описывайте, можно ли компенсировать уже выполненный эффект.

Главная практическая мысль проста: локальный журнал отвечает за возобновление, а стабильный идемпотентный ключ — за безопасный повтор внешней операции. Вместе они закрывают наиболее неприятный класс сбоев: «эффект уже случился, но агент этого ещё не записал».

Дополнительные понятия собраны в глоссарии, а другие практические материалы — в разделе guides.