модели передаваемых сообщений

2026-03-25 17:39:01 +03:00 · 2026-03-25 17:39:01 +03:00 · b46e24f7c3
commit b46e24f7c3
parent a5a6f2eca9
5 changed files with 329 additions and 1 deletions
--- a/api/README.md
+++ b/api/README.md
@ -0,0 +1,109 @@
+from api.models import IncomingMessage
+
+# SDK для взаимодействия с агентом
+
+Этот пакет представляет собой SDK для клиентской библиотеки, предназначенной для упрощения взаимодействия с сервером агента через WebSocket-соединение. Ниже приведены ключевые аспекты, которые следует учитывать при разработке клиентской библиотеки.
+
+## Архитектура взаимодействия
+
+### WebSocket-соединение
+
+Все взаимодействие происходит через WebSocket-соединение. Клиент должен:
+
+1. Установить соединение с сервером
+2. Дождаться получения сообщения `STATUS`, подтверждающего готовность сервера
+3. Начать отправку сообщений
+
+### Асинхронная природа
+
+Сервер отправляет ответы в виде потока событий (streaming). Это означает, что ответ на сообщение пользователя приходит не единым блоком, а по частям (чанкам) по мере генерации.
+
+## Сообщения
+
+### Пример десериализации
+```python
+message = OutgoingMessage.model_validate_json(json_data)
+```
+Pydantic самостоятельно приведет в нужному типу в зависимости от `type`.
+
+### Входящие сообщения (от клиента к серверу)
+
+#### USER_MESSAGE
+
+Текстовое сообщение от пользователя.
+
+```json
+{
+  "type": "USER_MESSAGE",
+  "text": "Текст сообщения"
+}
+```
+
+Поля:
+- `type` (string) - тип сообщения, всегда "USER_MESSAGE"
+- `text` (string) - текст сообщения от пользователя
+
+### Исходящие сообщения (от сервера к клиенту)
+
+#### STATUS
+
+Отправляется при установке соединения с клиентом. Сигнализирует о готовности агента принимать сообщения.
+
+```json
+{
+  "type": "STATUS"
+}
+```
+
+#### AGENT_EVENT
+
+Событие в процессе генерации ответа. Конкретный тип события определяется по полю `subtype`.
+
+##### TEXT_CHUNK
+
+Чанк текста ответа агента.
+
+```json
+{
+  "type": "AGENT_EVENT",
+  "subtype": "TEXT_CHUNK",
+  "text": "Фрагмент текста"
+}
+```
+
+##### END
+
+Сигнализирует о завершении генерации ответа.
+
+```json
+{
+  "type": "AGENT_EVENT",
+  "subtype": "END",
+  "tokens_used": 42
+}
+```
+
+#### ERROR
+
+Сигнализирует об ошибке в работе агента.
+
+```json
+{
+  "type": "ERROR",
+  "code": "error_code",
+  "details": "Подробное описание ошибки"
+}
+```
+
+#### GRACEFUL_DISCONNECT
+
+Осознанное завершение соединения агентом. Например, при долгом бездействии.
+
+```json
+{
+  "type": "GRACEFUL_DISCONNECT"
+}
+```
+
+
+![Схема взаимодействия](docs/schema.png)