agentik/proto/README.md

:proto — протокол общения с агентом (KMP, jvm + native)

Что это

Типы и контракт in-house протокола agentik, заменившего AG-UI:

• stateful — сервер сам владеет диалогом; клиент шлёт только новые сообщения, а не всю историю (в отличие от AG-UI, где клиент обязан повторять messages[] каждый раз).
• declarative история vs. события — Message это то, что уже легло в БД, Event это live-стрим от агента во время send() или events().
• чистые интерфейсы — никаких сетевых и storage зависимостей внутри :proto; это контракт.

Решает проблему: AG-UI клиент вынужден каждый раз знать и пересобирать полную историю, а его серверная часть (AbstractAgent) — постоянно сериализовать-десериализовать всю переписку. В :proto сервер один, контракт тонкий, переписка персистится нативно (SQLite, файлы, что хотите). Можно подменить front-end или back-end, протокол остаётся.

Где используется

• :server — Ktor-фасад, маппит Agent ↔ HTTP/SSE.
• :client — Ktor-клиент, маппит HTTP/SSE ↔ Agent/Conversation.
• :agentik-cli, :agentik-tui — оба работают поверх :client, а следовательно поверх :proto.
• :standalone — реализует Agent (через ChatAgent) и пишет/читает Message/Event напрямую через storage.

Как подключить

// build.gradle.kts
kotlin {
    sourceSets.commonMain.dependencies {
        api("pw.binom.agentik:proto:0.1.0")
    }
}

Артефакт pw.binom.agentik:proto:0.1.0 живёт в Nexus-репозитории caffeine (HTTP http://<your-nexus>/repository/caffeine/, plain-HTTP, credentials — через переменные binom.repo.user/password/url).

Версии

Каталог gradle/libs.versions.toml, секция [versions] → agentik-proto. Поднять версию → переопубликовать все KMP-таргеты через ./gradlew :proto:publish -Pversion=... (или триггернуть Gitea release).

Текущие KMP-таргеты: jvm + macosX64/macosArm64 + iosX64/iosArm64/iosSimulatorArm64 + linuxX64/linuxArm64 + mingwX64.

Публикация

Настройки в gradle.properties / env: binom.repo.url, binom.repo.user, binom.repo.password. ./gradlew :proto:publish публикует все target-specific артефакты + общий kotlinMultiplatform.

Основные типы

interface Agent {
    fun id: String
    suspend fun createConversation(title: String? = null): Conversation
    suspend fun getConversation(id: String): Conversation?
    suspend fun getConversations(offset: Int = 0): Flow<Conversation>
    suspend fun events(after: Instant): Flow<AgentEvent>   // created/deleted/renamed
}

interface Conversation : AutoCloseable {
    val id: String
    val updatedAt: Instant
    val isSupportImageInput: Boolean
    val isSupportImageOutput: Boolean
    suspend fun send(content: List<Content>): Flow<Event>     // write+read вместе, как раньше
    suspend fun events(after: Instant): Flow<Event>           // отдельная live-подписка
    suspend fun getMessages(offset: Int = 0): Flow<Message>
    suspend fun rename(title: String): Boolean
    fun interrupt()
}

sealed interface Content {
    class Text(val body: String) : Content
    class Image(val data: ByteArray, val mime: String) : Content
}

sealed interface Message {
    val id: String
    val date: Instant
    interface Body : Message { val content: List<Content> }
    interface System : Message
    class UserMessage(...) : Body
    class AssistantMessage(...) : Body
    class ToolCall(...) : System
    class ToolResult(...) : System
}

sealed interface Event {
    enum ResponseType { TEXT, IMAGE }
    class StartReasoning(...) : Event
    class StartResponse(val type: ResponseType) : Event
    class AppendText(val body: String) : Event
    class AppendImage(val body: ByteArray, val mime: String) : Event
    class End(...) : Event
    class Interrupted(...) : Event
    class Error(val message: String, val code: Int? = null) : Event
    class ToolCall(...) : Event
    class ToolResult(...) : Event
}

Чего здесь НЕТ

• Никакого HTTP/SSE/JSON. Это контракт. Сериализация живёт в :server и :client.
• Никакого хранения. Реализации MessageStore живут в :storage-*.
• Никакой логики прерывания / инструментов / LLM-вызовов. Это всё внутри :standalone (ChatAgent) и выше.

Тесты

./gradlew :proto:jvmTest
./gradlew :proto:allTests     # дополнительно linuxX64 (если Linux) / iosSimulator (если macOS)

Текущий статус

Используется продакшеном. Иммутабельный API (после рефакторинга из AG-UI). Возможные будущие расширения: typed tool-result, multi-modal contents, server-pushed references — все обсуждаются через общий IRC-QUESTIONS.md.