Урок 5.5. Event-Sourced Agent: лог как агент

Цель лекции

Показать архитектуру, где состояние агента восстанавливается из журнала событий.

Ожидаемый результат

Читатель понимает, почему append-only log является сильным основанием для долгоживущих агентов: события можно replay, audit, compact, checkpoint, branch и использовать для восстановления сессии.

Зачем это нужно

Многие агенты выглядят как диалог, но фактически являются процессом:

• пользователь ставит цель;
• агент строит план;
• вызывает инструменты;
• получает observations;
• принимает decisions;
• меняет файлы;
• запускает проверки;
• обновляет memory;
• формирует ответ.

Если хранить только final answer или текущий state, большая часть истории исчезает. Когда что-то пошло не так, трудно ответить:

• что агент видел;
• какие tools вызывал;
• какие results получил;
• почему выбрал действие;
• где возникла ошибка;
• какие данные попали в context;
• какую память использовал;
• как восстановить задачу после сбоя.

Event-Sourced Agent решает это через журнал событий. Вместо того чтобы считать текущее состояние единственным источником истины, система хранит append-only log, из которого состояние можно восстановить, проверить или сжать.

Основная идея

Append-only log делает поведение агента воспроизводимым: события можно проиграть, сжать, проверить или использовать для восстановления сессии.

В event-sourced architecture:

• каждое значимое изменение записывается как событие;
• события не перезаписываются;
• текущее состояние строится как projection из событий;
• snapshots ускоряют восстановление;
• replay помогает debugging;
• audit log объясняет поведение;
• branching позволяет исследовать альтернативные траектории.

Этот паттерн особенно полезен для enterprise agents, coding agents, long-running workflows и multi-agent systems, где важны traceability и recovery.

Ключевые термины

Что считается событием

Событие должно описывать то, что уже произошло.

Примеры agent events:

• user_message_received;
• assistant_message_generated;
• plan_created;
• memory_read_requested;
• memory_records_retrieved;
• tool_call_started;
• tool_call_completed;
• tool_call_failed;
• file_changed;
• test_run_started;
• test_run_completed;
• decision_recorded;
• memory_write_created;
• reflection_created;
• handoff_sent;
• task_completed.

Плохое событие:

Agent will probably fix bug by editing helper.

Хорошее событие:

event_type: tool_call_completed
tool: npm test
result: failed
timestamp: 2026-08-07T16:10:00+03:00
summary: invoice_totals.test.ts failed after discount_helper.ts edit.

Event log хранит observations, а не только conclusions.

Схема Event-Sourced Agent

Event log является raw history. Projections и snapshots делают эту историю пригодной для быстрого использования.

Append-only log как источник истины

В event-sourced подходе события не редактируются задним числом.

Если факт изменился, добавляется новое событие:

event_1:
- User preference extracted: detailed final answers.

event_2:
- User corrected preference: detailed lecture content, concise final reports.

projection:
- Active preference: concise final reports for file edits; detailed lecture content.

Это похоже на add-only подход из Module 03. История остается, а active view меняется.

Плюсы:

• audit trail;
• debugging;
• recovery;
• возможность пересчитать projections;
• легче понять, когда система узнала факт;
• можно исправлять extraction logic и replay.

Минусы:

• объем растет;
• sensitive data может попасть в log;
• deletion сложнее;
• replay может быть дорогим;
• нужно version event schemas.

Projections

Projection - представление состояния, вычисленное из events.

Примеры projections:

• current conversation summary;
• active task state;
• user profile;
• project memory view;
• list of changed files;
• latest test results;
• open questions;
• audit timeline;
• memory active view.

Пример:

Events:
1. User asks to write Module 05.
2. Agent reads lesson plans.
3. Agent writes lesson 5.1.
4. Agent writes lesson 5.2.

Projection:
- Module 05 writing task in progress.
- Completed lessons: 5.1, 5.2.
- Next lesson: 5.3.

Projection может быть пересчитана, если logic изменилась. Это сильная сторона event sourcing.

Checkpoints и snapshots

Replay всего log с начала может быть дорогим.

Checkpoint сохраняет точку продолжения.

Snapshot сохраняет сжатое состояние на момент времени.

Пример:

Snapshot after lesson 5.3:
- Completed: 5.1, 5.2, 5.3.
- Style: Russian technical Markdown.
- Remaining: 5.4, 5.5, 5.6.
- Do not update TODO unless requested.

При resume агент может загрузить snapshot и replay только события после него.

Это важно для:

• long-running tasks;
• crash recovery;
• multi-agent handoff;
• expensive context reconstruction;
• checkpoints in agent frameworks.

Replay для отладки

Replay позволяет воспроизвести поведение агента.

Вопросы, на которые отвечает replay:

• какие memory records были retrieved;
• какой prompt был собран;
• какой tool call был сделан;
• какой result пришел;
• какая запись memory была создана;
• где появилась ошибка;
• какой source был использован;
• почему context содержал stale fact.

Пример debugging:

Bug:
Agent answered from outdated project memory.

Replay shows:
1. Retrieval returned old "Project uses Jest" record.
2. Current package.json was not retrieved.
3. Reranker preferred old semantic memory over current file source.

Fix:
Boost current source freshness and mark old memory stale.

Replay делает memory failures наблюдаемыми.

Branching

Branching позволяет создать альтернативную траекторию от точки журнала.

Пример:

At event 42:
- Agent chose broad refactor.

Branch B:
- Agent chooses minimal bug fix.

Полезно для:

• comparing strategies;
• what-if analysis;
• safe planning;
• human review before action;
• retry after failure;
• multi-agent proposals.

Branching требует аккуратного scope: события одной ветки не должны случайно стать active memory другой ветки.

Auditability для enterprise

Enterprise systems часто требуют traceability:

• кто запросил действие;
• какие данные использовались;
• какие permissions были проверены;
• какие tools вызваны;
• какие external systems затронуты;
• какой ответ был дан;
• какие memory writes произошли;
• кто подтвердил decision.

Event log дает основу для audit.

Но audit log не должен нарушать privacy. Нужно фильтровать secrets, управлять retention, шифровать sensitive fields и ограничивать доступ.

Связь с checkpointing в агентских фреймворках

Многие agent frameworks используют идеи checkpointing:

• сохраняют state graph;
• фиксируют messages;
• сохраняют tool outputs;
• позволяют resume;
• поддерживают human-in-the-loop;
• дают trace выполнения.

Важно понимать концептуально: checkpointing - частный механизм сохранения состояния, а event sourcing - более широкая архитектурная идея, где log является источником истины.

Система может использовать checkpoints без полного event sourcing. И наоборот, event-sourced agent может строить checkpoints как оптимизацию.

Event schema

Пример event:

event_id: evt_123
event_type: tool_call_completed
task_id: task_456
session_id: sess_789
actor: coding-agent
timestamp: 2026-08-07T16:10:00+03:00
payload:
  tool: npm test
  exit_code: 1
  summary: invoice_totals.test.ts failed
related_entities:
  - test:invoice_totals.test.ts
  - file:src/pricing/discount_helper.ts
visibility:
  project: billing-service
source:
  kind: tool_result
schema_version: 1

Event schema должна иметь version. Иначе replay старых событий после изменения формата станет сложным.

Мини-кейс: coding agent

Задача:

"Исправь баг в скидках."

Event log:

1. user_message_received
2. project_instructions_loaded
3. memory_retrieved: pricing procedures
4. file_read: discount_helper.ts
5. file_changed: discount_helper.ts
6. tool_call_started: npm test
7. tool_call_completed: failed
8. memory_write_created: test failure event
9. reflection_created: dependent tests needed
10. file_changed: invoice total adjustment
11. tool_call_completed: passed
12. final_response_sent

Если позже пользователь спрашивает "что ты изменил и почему?", агент может построить explanation из log и projections.

Мини-кейс: writing agent

Задача:

"Напиши последовательно лекции в модуле 5."

Event log:

1. request_received
2. skill_loaded: technical-markdown-lectures
3. content_plan_read
4. lesson_plan_read: 5.1
5. lesson_written: 5.1
6. lesson_written: 5.2
7. lesson_written: 5.3
...

Projection:

Module 05 progress:
- Completed: 5.1, 5.2, 5.3
- Current: 5.4
- Remaining: 5.5, 5.6

Если сессия прерывается, snapshot позволяет продолжить без перечитывания всего.

Ограничения

Event-sourced architecture не бесплатна.

Ограничения:

• объем логов;
• storage cost;
• privacy risk;
• deletion complexity;
• replay latency;
• schema evolution;
• noisy logs;
• need for compaction;
• operational complexity;
• access control on historical events.

Event log не должен становиться помойкой raw data. Нужны:

• event schema;
• redaction;
• retention;
• snapshots;
• compaction;
• permissions;
• derived projections;
• deletion strategy.

Типичные ошибки

Ошибка 1: логировать все raw данные без фильтров.

Secrets и sensitive data не должны попадать в event log без необходимости.

Ошибка 2: считать log удобным active memory.

Raw log - источник истины, но active context должен строиться через projections и summaries.

Ошибка 3: не версионировать event schema.

Replay старых событий станет хрупким.

Ошибка 4: не делать snapshots.

Replay с начала для long-running agents может быть слишком дорогим.

Ошибка 5: смешивать branches.

Альтернативные траектории должны иметь отдельный scope.

Ошибка 6: забывать deletion.

Удаление должно учитывать log, projections, snapshots, indexes и backups.

Ошибка 7: не отделять observation от interpretation.

Событие должно фиксировать observed outcome, а выводы лучше хранить как reflection или decision.

Краткое резюме

Event-Sourced Agent рассматривает состояние агента как append-only журнал событий. Текущее состояние строится через projections, snapshots ускоряют recovery, replay помогает debugging, branching поддерживает альтернативные траектории, audit log делает поведение проверяемым.

Паттерн особенно силен для долгоживущих и enterprise agents, но требует строгой дисциплины: schema, privacy, retention, compaction, access control и deletion.

Вопросы для самопроверки

1. Почему append-only log может быть source of truth для агента?
2. Чем event отличается от projection?
3. Зачем нужны checkpoints и snapshots?
4. Как replay помогает отлаживать memory failures?
5. Какие privacy риски создает event log?

Что дальше

В следующей лекции мы завершим Module 05 паттерном Declarative Memory: как проектные файлы, спецификации, инструкции и conventions становятся частью memory layer.