# 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)