Створення надійних ШІ-агентів: ключові архітектурні уроки розробки асистента Shippy
Команда Skylight з AllenAI поділилася архітектурою Shippy — ШІ-агента для морського моніторингу на базі Claude Opus 4.6. Структурування агента за схемою «soul, skills, config» та обгортання складних API у детермінований CLI дозволили уникнути помилок через недетермінованість ШІ.
Вплив: Високий
Чому це важливо
Ви можете використати трикомпонентну архітектуру (soul, skills, config) та паттерн CLI-обгортки, щоб зробити власні агентні робочі процеси детермінованими та надійними.
TL;DR
- 01Огортайте складні API у типізований CLI з автодокументацією, щоб захистити систему від некоректних запитів агента.
- 02Структуруйте агента за трьома рівнями: soul (системні правила), skills (файли інструкцій) та config (налаштування).
- 03Для безпеки даних запускайте тимчасові, мережево ізольовані контейнери Kubernetes для кожної сесії користувача.
Ключові факти
- Активна модель
- Claude Opus 4.6
- Фреймворк агента
- OpenClaw
- Формат конфігурації
- Markdown з метаданими YAML
- Ізоляція сесій
- Контейнери Kubernetes
Трикомпонентна специфікація агента
Команда Skylight розділила структуру Shippy на три чіткі компоненти з підтримкою версіонування:
- Soul (Душа): Системний промпт, що визначає роль агента та жорсткі обмеження (наприклад, заборона робити юридичні висновки). Це дозволяє легко проводити аудит поведінки без тонкого налаштування (fine-tuning).
- Skills (Навички): Файли розмітки Markdown із YAML-метаданими на початку, які містять інструкції та відповідають специфікаціям інструментів на кшталт Claude Code та Codex.
- Config (Конфігурація): Параметри середовища виконання, що визначають фреймворк оркестрації (використовується open-source
OpenClaw), поточну LLM (Claude Opus 4.6) та секрети, що інжектуються під час запуску.
Спрощення API за допомогою CLI-обгортки
Ранні прототипи Shippy страждали від помилок пагінації та некоректного кодування координат при спробах формувати прямі HTTP-запити. Для вирішення цієї проблеми розробники створили детермінований CLI-інструмент. Замість виклику ендпоінтів, Shippy виконує локальні команди:
skylight events search --filter-flagsУся валідація схем, автентифікація та пагінація відбуваються всередині CLI. Результати записуються у локальні JSON-файли на диску, щоб уникнути переповнення буфера потоків (pipe buffer) при передачі великих масивів даних.
Динамічна пісочниця в Kubernetes
Для забезпечення ізоляції даних у більш ніж 70 країнах було створено платформу Mothership. Для кожної нової сесії користувача вона розгортає: 1. Окремий Kubernetes-pod із рантаймом агента, його навичками та локальним CLI. 2. Інжект індивідуального JWT-токена користувача під час ініціалізації для автоматичного обмеження прав доступу до даних. 3. Мережеві обмеження на рівні контейнера для безпеки інфраструктури.
Спробуй за 2 хвилини
---
title: query_events
description: "Query vessel events in an Exclusive Economic Zone"
tools:
- skylight_cli
---
# Skill Instructions
1. Resolve region name using regions API
2. Call `skylight events search --zone <polygon>`yaml
✓ Коли використовувати
- При створенні продакшн-агентів, які взаємодіють зі складними розгалуженими API.
- При проектуванні критично важливих бізнес-процесів, де галюцинації мають бути зведені до нуля.
- Для запуску агентів із жорсткою ізоляцією даних на рівні сесії користувача.
✕ Коли НЕ варто
- Для простих чат-ботів, які не виконують послідовних кроків із зовнішніми інструментами.
- Для прототипів, де розгортання ізольованих Kubernetes-контейнерів є надлишковим архітектурним ускладненням.
Що зробити сьогодні
- Винесіть системні обмеження агента (soul) окремо від логіки виконання для простоти аудиту.
- Впровадьте формат markdown-файлів із YAML-метаданими для опису навичок і команд інструментів.
- Зберігайте об'ємні відповіді інструментів у тимчасові локальні JSON-файли замість прямого перенаправлення потоків у консолі.
Джерела