Как мы научились строить AI-агентов на примере Shippy: архитектура для реальных решений
Команда Ai2 поделилась архитектурой морского AI-агента Shippy, который помогает аналитикам принимать решения в реальном времени. Главный урок: надёжность важнее модели. Агент состоит из трёх слоёв — «душа» (система промпт), навыки (markdown-файлы) и конфиг (LLM, фреймворк). Чтобы избежать ошибок, инструменты агента делают детерминированными: вместо прямых API-вызовов — CLI с типизацией и самодокументацией.
Это один из редких подробных разборов production-архитектуры AI-агента для критических задач. Подход Ai2 показывает, как строить надёжные системы там, где ошибка имеет реальные последствия — уроки применимы к любым агентам в медицине, финансах, безопасности.
Архитектура надёжности
Команда Allen Institute for AI (Ai2) опубликовала подробный разбор архитектуры Shippy — AI-агента для морской разведки, который работает с платформой Skylight. Проект показывает, как строить агентов для критических задач, где ошибка может стоить ресурсов или даже жизней.
Три слоя агента
Shippy устроен как комбинация трёх компонентов:
- Soul (душа) — системный промпт, который задаёт личность агента и границы поведения. Например, Shippy не делает юридические выводы и не додумывает за пределами данных.
- Skills (навыки) — набор markdown-файлов со структурированными инструкциями. Каждый навык описывает, как обрабатывать конкретный тип запроса: поиск судов, анализ траекторий, запросы к партнёрским базам данных.
- Config (конфигурация) — всё остальное: фреймворк (OpenClaw), модель (Claude Opus 4.6), API-ключи. Смена модели или фреймворка — это изменение конфига, а не перестройка агента.
Особенность подхода: soul и skills упакованы в Docker-образ — версионируемый артефакт, который можно развернуть в любой момент.
Детерминированные инструменты
Главная проблема агентов — недетерминированность. Нельзя предсказать, что решит сделать LLM, но можно сделать предсказуемыми инструменты, которыми она пользуется.
В ранних прототипах Shippy сам формировал API-запросы к Skylight. Результат: поток тонких багов — неправильная пагинация, ошибки в геометрии, корректно выглядящие запросы с неверными фильтрами.
Решение: Skylight CLI — обёртка над API с типизацией, подробной справкой и понятными ошибками. Агент вызывает одну команду (skylight events search), CLI берёт на себя аутентификацию, пагинацию и форматирование. Результаты пишутся в JSON-файл, а не передаются через pipe — это избавляет от переполнения буфера и делает данные доступными на следующих шагах.
Под CLI — типизированный API с едиными операциями (search/aggregate) для всех ресурсов: событий, судов, регионов, спутниковых снимков. Каждое поле описано в схеме.
Изоляция и тестирование
Трёхслойная архитектура (типизированный API → CLI → навыки агента) позволяет тестировать каждый уровень независимо. API имеет свой тестовый набор, CLI можно проверить вручную, навыки ссылаются на команды CLI, которые уже протестированы.
Важный момент: Skylight обслуживает сотни госорганов и НКО в 70+ странах. Каждый пользователь имеет свои данные, списки судов, настройки оповещений. Shippy работает в изолированной песочнице для каждого пользователя — данные не смешиваются.
Уроки для других агентов
Команда Ai2 переносит эти принципы на другие экологические платформы. Главный вывод: надёжность агента начинается не с промпта, а с архитектуры инструментов. Чем меньше степеней свободы у LLM на каждом шаге, тем меньше шансов на ошибку.
Ключевые выводы
- Надёжность агента важнее выбора модели — ключ в архитектуре инструментов и границах поведения
- Трёхслойная структура (soul/skills/config) делает агента версионируемым, тестируемым и легко обновляемым
- Детерминированные инструменты (CLI с типизацией) решают проблему недетерминированности LLM
- Markdown-файлы для навыков (по спецификации agent-skills) упрощают поддержку и аудит
- Изоляция пользовательских данных и независимое тестирование каждого слоя — обязательные требования для продакшена
Автор: Юлия Тарасова · Источник: HuggingFace Blog
Это тот самый текст, который стоит сохранить в закладки — не потому что там хайп, а потому что там настоящая работа. Команда Ai2 честно рассказывает, как они год мучались с багами, пока не поняли: проблема не в модели, а в том, что они дали ей слишком много верёвки. Решение оказалось контринтуитивным — больше ограничений, меньше свободы, детерминированные инструменты.
Особенно ценно, что они не продают фреймворк и не пиарят модель — они делятся архитектурой для критических задач, где цена ошибки измеряется не в токенах, а в человеческих жизнях. Подход с soul/skills/config можно взять прямо сейчас и применить к любому агенту, где нужна реальная надёжность. Вот только придётся смириться, что 80% работы — это не промпты, а инфраструктура вокруг модели. Зато оно работает.
Комментарии