Журнал решений для ИИ-агентов: принципы и схема

Зачем нужен журнал решений для ИИ-агентов

Когда ИИ-агент принимает решение, важно не только что он решил, но и почему. Без этого невозможно отладить поведение, провести аудит или объяснить пользователю логику. В этой статье мы разберем принципы проектирования журнала решений (Reasoning Ledger) и покажем, как построить схему записи, которая выдержит проверку временем.

Принцип 1: Журнал — свидетель, а не исполнитель

Журнал решений не должен блокировать или одобрять действия. Его задача — фиксировать факты и контекст. Если журнал может предотвратить действие, он становится частью механизма, который описывает, и теряет объективность. Вместо этого журнал должен содержать результат оценки политики (policy_evaluated), но не само решение о применении.

# Пример: фиксация проверки политики
record = {
    'decision': 'approve_deployment',
    'policy_evaluated': {
        'policy': 'security-policy',
        'version': 7,
        'result': 'pass'
    }
}

Принцип 2: Замена решения — новое событие, а не перезапись

Если решение изменилось, создается новая запись, которая ссылается на старую, но не перезаписывает её. Это позволяет восстановить историю и понять, было ли решение рациональным в тот момент. Аналог — append-only структура, как в Forensic Receipts.

# Старая запись остается неизменной
old_record = {'decision': 'A', 'timestamp': '2026-03-14'}
# Новая запись ссылается на старую
new_record = {'decision': 'B', 'supersedes': old_record['id']}

Принцип 3: Фиксируйте, как получен источник, а не только его версию

Версия 7 политики может быть получена из разных источников: свежий запрос, кэш, состояние сессии. Это разные уровни доверия. В записи нужно указывать, когда и откуда получен источник, был ли использован кэш. Это поможет выявить устаревшие данные.

# Запись о том, как получен источник
evidence = {
    'artifact': 'ADR-014',
    'version': 3,
    'obtained': {
        'source': 'adr-service',
        'timestamp': '2026-03-14T09:22:00Z',
        'cache': False
    }
}

Принцип 4: Двойные метки времени для связей

Для восстановления контекста решения нужны две метки: valid_time (когда факт стал истинным в мире) и asserted_at (когда система узнала о нем). Это стандартная битемпоральная модель. Без этого можно ошибочно судить о прошлом решении, используя будущую информацию.

# Связь с суперседией
relationship = {
    'supersedes': 'dep-2026-03-14-0922',
    'valid_time': '2026-08-01T00:00:00Z',
    'asserted_at': '2026-08-01T10:00:00Z'
}

Принцип 5: Сохраняйте проигравшие варианты

Журнал должен фиксировать не только выбранный путь, но и альтернативы, которые были отклонены, с причинами. Это позволяет оценить, насколько решение было обоснованным. Включайте поля alternatives_considered, disconfirmed_by, unknowns.

# Альтернативы и причины отклонения
record = {
    'alternatives_considered': [
        {'option': 'tool_B', 'rejection_reason': 'policy_violation'}
    ],
    'unknowns': ['future_regulatory_changes']
}

Принцип 6: Триггер — отдельное поле

Триггер — это событие, которое вызвало решение. Оно должно быть отдельным полем, чтобы можно было быстро найти, почему произошло изменение. Это облегчает поиск и аудит.

record = {
    'trigger': {
        'type': 'incident',
        'ref': 'INC-2291',
        'observed_at': '2026-03-14T08:55:00Z'
    }
}

Принцип 7: Некоторые механизмы — вне журнала

Ревалидация (периодическая проверка актуальности источников) и извлечение (предоставление истории решений при запросе артефакта) должны быть реализованы вне журнала, но их результаты фиксироваться в журнале. Это сохраняет независимость журнала и обеспечивает его полезность.

# Внешний процесс ревалидации
def revalidate(artifact_id):
    # Проверяет актуальность и создает новую запись
    pass

Пример полной записи

Соберем все принципы в единую запись для решения о развертывании.

reasoning_ledger = {
    'decision_id': 'dep-2026-03-14-0922',
    'decision': 'approve_deployment',
    'decided_at': '2026-03-14T09:22:00Z',
    'trigger': {
        'type': 'incident',
        'ref': 'INC-2291',
        'observed_at': '2026-03-14T08:55:00Z'
    },
    'evidence': [
        {
            'artifact': 'ADR-014',
            'authority': 'architecture-review',
            'version': 3,
            'obtained': {
                'source': 'adr-service',
                'timestamp': '2026-03-14T09:20:00Z',
                'cache': False
            }
        },
        {
            'artifact': 'security-policy',
            'authority': 'security-team',
            'version': 7,
            'obtained': {
                'source': 'policy-service',
                'timestamp': '2026-03-14T09:21:00Z',
                'cache': True
            }
        }
    ],
    'alternatives_considered': [
        {'option': 'rollback_plan', 'rejection_reason': 'not_required'}
    ],
    'unknowns': ['performance_under_load'],
    'approvals': ['release_manager'],
    'outcome': 'approved'
}

Практический вывод

Начните с малого: добавьте в свой текущий журнал поле trigger и фиксируйте способ получения источника. Затем постепенно внедряйте остальные принципы. Помните: главное — не слепо копировать схему, а понять, какие проблемы она решает.