IAAM

Откуда взялся проект

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

У IAAM нет веб-интерфейса для владельца. В обычном использовании владелец разговаривает с агентом, а агент обращается к REST API. Первоначальная настройка и работа с ключами вынесены в консольную утилиту: если API поручает человеку отправить несколько технических запросов, то агентский интерфейс фактически перестаёт быть интерфейсом.

Это не означает, что агенту доверено всё подряд. Его токен доступа нужен для работы с API, но ключи брокеров, токен владельца и ключ шифрования не должны попадать в контекст модели. Секреты остаются на стороне CLI и самого сервиса.

Какую проблему решает agent-first подход

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

Поэтому инструкция агента в IAAM объясняет смысл системы и границы его роли, но не является второй копией контракта. Маршруты и текущее состояние меняются быстрее, чем текст. Источник ответа на вопрос «что делать сейчас» — сам экземпляр API, а не устаревший абзац в skill-файле.

Архитектура

Основной путь выглядит так:

владелец
   ↕
агент → api-catalog → OpenAPI-контракт → очередь действий → вызовы API
                                      ↓
                              журнал и отчёты

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

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

Финансовая часть отделена от этого агентского слоя. Факты попадают в журнал несколькими независимыми путями:

• брокерские отчёты и документы;
• операции, полученные через API брокера;
• корпоративные действия — например, амортизация, погашение и замещение.

Журнал остаётся источником истины. Сверка заново строится по интервалу и измерению — cash, positions, income и tax_basis. Для качества данных различаются предварительные, внутренне принятые, независимо подтверждённые и расходящиеся значения. Два отчёта, разобранные одним и тем же парсером, не считаются независимым подтверждением.

Поверх этого есть справочник инструментов с разрешением внешних кодов на дату документа, версионируемые правила классификации, исправления как новые факты и отчёты о доходности до налога с блоком data_quality. Рыночные данные можно синхронизировать из MOEX ISS или ЦБ РФ; сейчас этот запуск ручной, без периодического планировщика.

Что уже сделано

Сейчас IAAM умеет принимать разные виды финансовых фактов, строить отчёты и показывать, где результат подтверждён, а где остаётся пробел или расхождение. Агентский контур уже включает обнаружение API, машиночитаемый контракт, очередь действий и вопросы владельцу с объяснением того, что изменит его ответ.

Это важное различие: проект не пытается сделать агента финансовым источником истины. Агент передаёт данные и решения владельца, а утверждения о деньгах должны исходить из ответа IAAM. Если система не может вычислить показатель, она должна вернуть отказ с причиной, а не заставлять агента оценивать его самому.

Связанный разбор происхождения этих решений — в статье «Как я строил agent-first REST API и agent-first блог». Статья объясняет мотивацию и эксперименты, а эта страница фиксирует границы и текущее состояние самого проекта.

Чего пока нет

По текущему README и исходникам проект пока не умеет:

• считать налоги, TWR, NAV-ряд и доходность за произвольный подинтервал;
• моделировать экономику шортов, маржи и производных;
• восстанавливать потерянный ключ шифрования из одной базы;
• автоматически планировать периодическую синхронизацию;
• заменять депозитарный отчёт или справку налогового агента;
• покрывать все варианты облигаций: в частности, ставки флоатера, формулы купона, ряд RUONIA и опубликованные фиксинги;
• предоставлять веб-интерфейс.

Отсутствие веб-интерфейса здесь пока не выглядит незакрытым техническим долгом: agent-first интерфейс — сознательная ставка проекта. Но это граница, которую стоит проверять практикой, а не объявлять универсальным правилом.

Открытые вопросы

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

Есть и вопросы об эксплуатации: нужен ли периодический планировщик, какие источники действительно следует считать независимыми, и где проходит граница между действием агента и необратимым решением владельца. Ещё одна постоянная граница — контракт должен вычисляться из работающего экземпляра, иначе agent-first система снова начнёт жить по устаревшей инструкции.