155 lines
7.2 KiB
Markdown
155 lines
7.2 KiB
Markdown
# agentik
|
||
|
||
Локальный stateful LLM-агент с persistent-памятью, инструментами и
|
||
несколькими transport-фасадами (AG-UI, A2A, наш `:proto`).
|
||
Реализован на Kotlin Multiplatform, выполняется как single JVM-jar.
|
||
Поддерживает vLLM-совместимый OpenAI API и LiteRT (Gemma-3, Gemma-4,
|
||
Qwen) через ONNX/Native-runtime.
|
||
|
||
## Что внутри
|
||
|
||
```
|
||
agentik/
|
||
├── proto/ stateful KMP protocol: Agent / Conversation / Message / Event
|
||
├── server/ Ktor-фасад → /agentik (HTTP+JSON+SSE)
|
||
├── client/ Ktor-клиент → тот же /agentik, с KMP-native
|
||
├── skills/ парсер SKILL.md / *.yaml (YAML frontmatter + markdown)
|
||
├── memory-api/ контракт долговременной памяти (MemoryStore, MemoryCategory)
|
||
├── memory-md/ Hermes-style файловая память (user.md / world.md / ...)
|
||
├── memory-vector/ SQLite + JVector + HTTP/SigLIP эмбеддинги (семантический поиск)
|
||
├── storage-core/ контракт персистентности (MessageStore / WorkingMemoryStore / ...)
|
||
│ (исторический, см. journal-api / context-api / reflection-api ниже)
|
||
├── ~~storage-inmemory/~~ ~~in-memory реализация для тестов и Android~~ — упразднён 2026-09-22
|
||
├── ~~storage-sqlite/~~ ~~SQLite реализация для production~~ — упразднён 2026-09-22
|
||
├── agent-toolsets/ ядро tool-calls с cooperative cancel + concurrency budget
|
||
├── agentik-cli/ JVM one-shot CLI-клиент (kotlinx.cli) к /agentik
|
||
├── ~~agentik-tui/~~ ~~Compose-for-Mosaic TUI-клиент (desktop)~~ — исключён 2026-09-17
|
||
└── standalone/ single-jar HTTP-сервер со всеми transport'ами и движками
|
||
```
|
||
|
||
Каждый подмодуль имеет собственный `README.md` с деталями
|
||
(см. "Модули" ниже).
|
||
|
||
## Quickstart
|
||
|
||
### 1. Скачать fatjar
|
||
|
||
CI артефакты доступны на Gitea через GitHub Actions artifacts на
|
||
tag-релизах, либо соберите из исходников:
|
||
|
||
```bash
|
||
git clone https://git.binom.pw/subochev/agentik
|
||
cd agentik
|
||
./gradlew :standalone:shadowJar
|
||
```
|
||
|
||
Результат: `standalone/build/libs/agentik-0.1.0-all.jar` (~10–250 МБ,
|
||
зависит от LLM-backend'а).
|
||
|
||
### 2. Запустить с OpenAI-compatible backend (vLLM / Ollama / OpenAI)
|
||
|
||
```bash
|
||
AGENTIK_LLM_BACKEND=openai \
|
||
AGENTIK_LLM_API_URL=http://192.168.88.135:8001/v1 \
|
||
AGENTIK_LLM_MODEL=Qwen3.8-27B-NVFP4 \
|
||
AGENTIK_LLM_CONTEXT_TOKENS=115000 \
|
||
java --enable-native-access=ALL-UNNAMED -jar agentik-0.1.0-all.jar
|
||
```
|
||
|
||
### 3. Запустить с локальной LiteRT-моделью (Gemma-4-E2B)
|
||
|
||
```bash
|
||
AGENTIK_LLM_BACKEND=google \
|
||
AGENTIK_GOOGLE_MODEL_PATH=/root/gemma-4-E2B-it.litertlm \
|
||
java --enable-native-access=ALL-UNNAMED -jar agentik-0.1.0-all.jar pull-model # скачать
|
||
java --enable-native-access=ALL-UNNAMED -jar agentik-0.1.0-all.jar # запустить
|
||
```
|
||
|
||
Больше деталей по env'ам — в [`standalone/README.md`](standalone/README.md).
|
||
|
||
## Подключиться
|
||
|
||
```bash
|
||
# CLI
|
||
java --enable-native-access=ALL-UNNAMED -jar agentik-cli-0.1.0-SNAPSHOT-all.jar --help
|
||
|
||
# curl
|
||
curl http://localhost:8080/health
|
||
```
|
||
|
||
## Модули
|
||
|
||
- Запускаемые:
|
||
- [`:standalone`](standalone/README.md) — single-jar HTTP-сервер.
|
||
- [`:agentik-cli`](agentik-cli/README.md) — one-shot CLI-клиент (kotlinx.cli), JVM + 4 native.
|
||
- Библиотеки (контракты и реализации):
|
||
- [`:proto`](proto/README.md) — stateful KMP-протокол.
|
||
- [`:server`](server/README.md) — HTTP/SSE фасад `:proto`.
|
||
- [`:client`](client/README.md) — Ktor-клиент `:server`.
|
||
- [`:skills`](skills/README.md) — парсер SKILL.md.
|
||
- [`:memory-api`](memory-api/README.md) — контракт памяти.
|
||
- [`:memory-md`](memory-md/README.md) — Hermes-style файл.
|
||
- [`:memory-vector`](memory-vector/README.md) — SQLite + JVector.
|
||
- [`:storage-core`](storage-core/README.md) — контракт storage (исторический).
|
||
- ~~`:storage-inmemory`~~ — упразднён 2026-09-22.
|
||
- ~~`:storage-sqlite`~~ — упразднён 2026-09-22.
|
||
- [`:agent-toolsets`](agent-toolsets/README.md) — тулы и диспетчер.
|
||
|
||
## Где смотреть версии
|
||
|
||
Каталог `gradle/libs.versions.toml`. Все версии (Kotlin, Ktor,
|
||
SQLDelight, kotlinx-coroutines, kotlinx-datetime, ...) сгруппированы
|
||
в секции `[versions]`; все dep-aliases — в секции `[libraries]`.
|
||
|
||
Версия самого `agentik` (cм. `<version>` в nexus.pom) — тоже в
|
||
`gradle.properties` (через `$AgentikVersion` или env `AGENTIK_VERSION`).
|
||
На tag-релизе (например `v0.2.0`) — CI подставляет версию из
|
||
тега и публикует.
|
||
|
||
## Публикация
|
||
|
||
`./gradlew :<module>:publish` → в `caffeine` (Nexus).
|
||
Параметры через:
|
||
|
||
- `binom.repo.url` (`http://<your-nexus>/repository/caffeine/`)
|
||
- `binom.repo.user`
|
||
- `binom.repo.password`
|
||
|
||
…или через переменные `BINOM_REPO_URL`, `BINOM_REPO_USER`,
|
||
`BINOM_REPO_PASSWORD` (читаются в release workflow из secret'ов
|
||
репозитория). Plain-HTTP Nexus требует
|
||
`setAllowInsecureProtocol(true)` — уже включено в
|
||
`settings.gradle.kts`.
|
||
|
||
## CI/CD
|
||
|
||
Gitea Actions (`https://git.binom.pw/subochev/agentik/actions`):
|
||
|
||
- `.gitea/ci.yml` — PR-build, прогон тестов, проверка
|
||
shadowjar'ов.
|
||
- `.gitea/workflows/release.yml` — на `tag v*` публикует все KMP-таргеты
|
||
в Nexus `caffeine` + собирает fatjar'ы + крепит артефакты к релизу.
|
||
|
||
## Что отличает от других агентских фреймворков
|
||
|
||
- **Stateful protocol** — сервер сам владеет диалогом; переписка не
|
||
пересобирается клиентом на каждый `send` (в отличие от AG-UI).
|
||
- **Все три транспорта в одном процессе** — AG-UI, A2A, наш proto.
|
||
Один fatjar — три API.
|
||
- **Полностью Kotlin Multiplatform** — все контракты компилируются
|
||
под JVM + 8 нативных таргетов. Можно встроить в iOS / Android /
|
||
Desktop / CLI.
|
||
- **Прерывание tool-calls сохраняется в working memory** — нет
|
||
потери контекста, если пользователь нажал Ctrl-C во время
|
||
долгого tool-вызова.
|
||
|
||
## Лицензия
|
||
|
||
Apache-2.0 — смотрите [LICENSE](LICENSE).
|
||
|
||
## Участие в проекте
|
||
|
||
PR-ы приветствуются. Не забывайте синхронизировать версии в
|
||
`gradle/libs.versions.toml` и обновлять per-module README при
|
||
изменении API.
|