109 lines
No EOL
3.3 KiB
Markdown
109 lines
No EOL
3.3 KiB
Markdown
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"
|
||
}
|
||
```
|
||
|
||
|
||
 |