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

2026-03-25 17:39:01 +03:00 · 2026-03-25 17:39:01 +03:00 · 5f5dd3e83e
commit 5f5dd3e83e
parent a5a6f2eca9
5 changed files with 366 additions and 2 deletions
--- a/api/README.md
+++ b/api/README.md
@ -0,0 +1,145 @@
+# Lambda Agent API
+
+WebSocket API SDK для взаимодействия с AI-агентом.
+
+## Установка
+
+```bash
+pip install .
+```
+
+Требуется Python 3.14+.
+
+## Быстрый старт
+
+```python
+import asyncio
+import websockets
+from api.models import OutgoingMessage, OM
+
+async def main():
+    uri = "ws://localhost:8000/ws"
+    
+    async with websockets.connect(uri) as ws:
+        # 1. Ждём STATUS - подтверждение готовности
+        status = await ws.recv()
+        print(f"Connected: {status}")
+        
+        # 2. Отправляем сообщение
+        await ws.send('{"type": "USER_MESSAGE", "text": "Привет!"}')
+        
+        # 3. Читаем ответ в виде потока событий
+        while True:
+            msg = await ws.recv()
+            data = OutgoingMessage.model_validate_json(msg)
+            
+            match data:
+                case OM.AgentEvent(subtype=OM.AgentEventType.TEXT_CHUNK):
+                    print(data.text, end="", flush=True)
+                case OM.EventEnd():
+                    print(f"\n[Завершено, использовано токенов: {data.tokens_used}]")
+                    break
+                case OM.Error():
+                    print(f"\n[Ошибка: {data.code}] {data.details}")
+                    break
+
+asyncio.run(main())
+```
+
+## Протокол
+
+### Клиент → Сервер
+
+#### 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
+}
+```
+
+| Поле        | Тип    | Описание              |
+|-------------|--------|-----------------------|
+| tokens_used | int    | Количество использованных токенов |
+
+#### ERROR
+
+Неопределенная ошибка в работе агента.
+
+```json
+{
+  "type": "ERROR",
+  "code": "error_code",
+  "details": "Описание ошибки"
+}
+```
+
+| Поле    | Тип   | Описание       |
+|---------|-------|----------------|
+| code    | string | Код ошибки    |
+| details | string | Подробности   |
+
+#### GRACEFUL_DISCONNECT
+
+Отправляется перед завершением работы контейнера с агентом. Например, при долгом бездействии. Нужно, чтобы отделять обрыв соединения из-за ошибки с необходимостью повторного подключения. Приход этого сообщения означает, что агент осознанно завершает работу с клиентом по какой-то причине. Для дальнейшего взаимодействия нужно снова обратиться к мастеру.
+
+```json
+{
+  "type": "GRACEFUL_DISCONNECT"
+}
+```
+
+![Схема взаимодействия](docs/schema.png)
+
+## Зависимости
+
+- Python 3.14+
+- pydantic >= 2.12.5