From 7aa0f80d4fe2d0121f88ab45ce9cc9fa5bfe1aa0 Mon Sep 17 00:00:00 2001
From: collhoun <2904yr@mail.ru>
Date: Wed, 8 Apr 2026 10:47:24 +0300
Subject: [PATCH] =?UTF-8?q?#7=20=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?=
 =?UTF-8?q?=D1=8C=20=D0=BE=D1=81=D0=BD=D0=BE=D0=B2=D0=BD=D1=8B=D0=B5=20?=
 =?UTF-8?q?=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D0=B8=20=D0=B8=D0=B2=D0=B5=D0=BD?=
 =?UTF-8?q?=D1=82=D0=BE=D0=B2=20=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D0=B0.=20?=
 =?UTF-8?q?=D0=9E=D0=B1=D0=BE=D0=BD=D0=BE=D0=B2=D0=BB=D0=B5=D0=BD=D0=B0=20?=
 =?UTF-8?q?=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86?=
 =?UTF-8?q?=D0=B8=D1=8F=20=D0=B2=20=D1=81=D0=BE=D0=BE=D1=82=D0=B2=D0=B5?=
 =?UTF-8?q?=D1=82=D1=81=D1=82=D0=B2=D0=B8=D0=B8=20=D1=81=20=D0=B8=D0=B2?=
 =?UTF-8?q?=D0=B5=D1=82=D0=B0=D0=BC=D0=B8=20=D0=B0=D0=B3=D0=B5=D0=BD=D1=82?=
 =?UTF-8?q?=D0=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 99 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 50769bd..f36c9b4 100644
--- a/README.md
+++ b/README.md
@@ -105,37 +105,97 @@ async def on_telegram_message(from_user: int, text: str):
 }
 ```
 
-#### AGENT_EVENT
-
-Базовый класс для ивентов, которые стримит агент во время генерации ответа. Конкретный класс для ивента определяется по `subtype`.
-
-##### TEXT_CHUNK
+#### AGENT_EVENT_TEXT_CHUNK
 
 Чанк текста ответа агента.
 
 ```json
 {
-  "type": "AGENT_EVENT",
-  "subtype": "TEXT_CHUNK",
-  "text": "Фрагмент текста"
+  "type": "AGENT_EVENT_TEXT_CHUNK",
+  "text": "Фрагмент текста",
+  "source": "main"
 }
 ```
 
-##### END
+| Поле   | Тип    | Описание                                      |
+|--------|--------|-----------------------------------------------|
+| type   | string | Всегда `AGENT_EVENT_TEXT_CHUNK`              |
+| text   | string | Фрагмент текста ответа агента                |
+| source | string | Источник события (по умолчанию "main")       |
+
+#### AGENT_EVENT_TOOL_CALL_CHUNK
+
+Агент решил использовать инструмент и генерирует аргументы.
+
+```json
+{
+  "type": "AGENT_EVENT_TOOL_CALL_CHUNK",
+  "tool_name": "имя_инструмента",
+  "args_chunk": "{\"key\": \"value\"}",
+  "source": "main"
+}
+```
+
+| Поле        | Тип     | Описание                                      |
+|-------------|---------|-----------------------------------------------|
+| type        | string  | Всегда `AGENT_EVENT_TOOL_CALL_CHUNK`         |
+| tool_name   | string  | Имя инструмента (может быть null в первом чанке) |
+| args_chunk  | string  | Кусок JSON-аргументов (может быть null)      |
+| source      | string  | Источник события (по умолчанию "main")       |
+
+#### AGENT_EVENT_TOOL_RESULT
+
+Инструмент отработал и вернул результат.
+
+```json
+{
+  "type": "AGENT_EVENT_TOOL_RESULT",
+  "tool_name": "имя_инструмента",
+  "result": "результат выполнения",
+  "source": "main"
+}
+```
+
+| Поле       | Тип    | Описание                                      |
+|------------|--------|-----------------------------------------------|
+| type       | string | Всегда `AGENT_EVENT_TOOL_RESULT`             |
+| tool_name  | string | Имя инструмента                              |
+| result     | any    | Результат выполнения (строка, объект или массив) |
+| source     | string | Источник события (по умолчанию "main")       |
+
+#### AGENT_EVENT_CUSTOM_UPDATE
+
+Кастомный прогресс (например, скачивание файла) изнутри инструмента.
+
+```json
+{
+  "type": "AGENT_EVENT_CUSTOM_UPDATE",
+  "payload": {"status": "in_progress", "progress": 50},
+  "source": "main"
+}
+```
+
+| Поле     | Тип             | Описание                                      |
+|----------|-----------------|-----------------------------------------------|
+| type     | string          | Всегда `AGENT_EVENT_CUSTOM_UPDATE`           |
+| payload  | object          | Любые данные о прогрессе                      |
+| source   | string          | Источник события (по умолчанию "main")       |
+
+#### AGENT_EVENT_END
 
 Агент закончил генерацию ответа.
 
 ```json
 {
-  "type": "AGENT_EVENT",
-  "subtype": "END",
+  "type": "AGENT_EVENT_END",
   "tokens_used": 42
 }
 ```
 
-| Поле        | Тип    | Описание              |
-|-------------|--------|-----------------------|
-| tokens_used | int    | Количество использованных токенов |
+| Поле        | Тип    | Описание                                      |
+|-------------|--------|-----------------------------------------------|
+| type        | string | Всегда `AGENT_EVENT_END`                     |
+| tokens_used | int    | Количество использованных токенов            |
 
 #### ERROR
 
@@ -164,4 +224,29 @@ async def on_telegram_message(from_user: int, text: str):
 }
 ```
 
+Неопределенная ошибка в работе агента.
+
+```json
+{
+  "type": "ERROR",
+  "code": "error_code",
+  "details": "Описание ошибки"
+}
+```
+
+| Поле    | Тип   | Описание       |
+|---------|-------|----------------|
+| code    | string | Код ошибки    |
+| details | string | Подробности   |
+
+#### GRACEFUL_DISCONNECT
+
+Отправляется перед завершением работы контейнера с агентом. Например, при долгом бездействии. Нужно, чтобы отделять обрыв соединения из-за ошибки с необходимостью повторного подключения. Приход этого сообщения означает, что агент осознанно завершает работу с клиентом по какой-то причине. Для дальнейшего взаимодействия нужно снова обратиться к мастеру.
+
+```json
+{
+  "type": "GRACEFUL_DISCONNECT"
+}
+```
+
 ![Схема взаимодействия](docs/schema.png)