From c7a9d3446d42dcbed6849387d1ebc95635179037 Mon Sep 17 00:00:00 2001
From: collhoun <2904yr@mail.ru>
Date: Mon, 30 Mar 2026 10:30:28 +0300
Subject: [PATCH] =?UTF-8?q?=D0=98=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB?=
 =?UTF-8?q?=D0=B5=D0=BD=20=D1=80=D0=B8=D0=B4=D0=BC=D0=B8=20=D0=B2=20=D1=81?=
 =?UTF-8?q?=D0=BE=D0=BE=D1=82=D0=B2=D0=B5=D1=82=D1=81=D1=82=D0=B2=D0=B8?=
 =?UTF-8?q?=D0=B8=20=D1=81=20=D0=B8=D0=B7=D0=BC=D0=B5=D0=BD=D0=B5=D0=BD?=
 =?UTF-8?q?=D0=B8=D1=8F=D0=BC=D0=B8=20=D0=B2=20agent=5Fapi?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 api/README.md | 69 +++++++++++++++++++++++++++++----------------------
 1 file changed, 39 insertions(+), 30 deletions(-)

diff --git a/api/README.md b/api/README.md
index a13bce4..4818566 100644
--- a/api/README.md
+++ b/api/README.md
@@ -16,22 +16,24 @@ pip install .
 import asyncio
 from agent_api import AgentApi, OM
 
+def my_callback(message):
+    if isinstance(message, OM.Error):
+        print(f"\n[Ошибка: {message.code}] {message.details}")
+    elif isinstance(message, OM.Status):
+        print("✓ Agent status update")
+
 async def main():
     # Автоматическое управление соединением через контекстный менеджер
-    async with AgentApi("ws://localhost:8000") as agent:
-        # Отправляем сообщение
-        await agent.send_user_message("Привет, агент!")
+    async with AgentApi("ws://localhost:8000", callback=my_callback) as api:
+        # Отправляем сообщение и получаем итератор ответа
+        response = await api.send_message("Привет, агент!")
 
-        # Читаем ответ потоком событий
-        async for message in agent.listen():
-            if isinstance(message, OM.EventTextChunk):
-                print(message.text, end="", flush=True)
-            elif isinstance(message, OM.EventEnd):
-                print(f"\n[Завершено, использовано токенов: {message.tokens_used}]")
-                break
-            elif isinstance(message, OM.Error):
-                print(f"\n[Ошибка: {message.code}] {message.details}")
-                break
+        # Читаем ответ потоком чанков
+        async for chunk in response:
+            if isinstance(chunk, OM.EventTextChunk):
+                print(chunk.text, end="", flush=True)
+        
+        print(f"\n[Завершено, использовано токенов: {response.tokens}]")
 
 asyncio.run(main())
 ```
@@ -44,7 +46,8 @@ asyncio.run(main())
 
 - ✅ **Асинхронный клиент** на основе `aiohttp`
 - ✅ **Контекстный менеджер** для управления соединением
-- ✅ **Асинхронный генератор** `listen()` для потокового получения сообщений
+- ✅ **ResponseIterator** для асинхронной итерации по чанкам ответа
+- ✅ **Callback** для обработки событий вне генерации ответа (ошибки, статусы)
 - ✅ **Типизированные сообщения** через Pydantic с дискриминированными объединениями
 - ✅ **Обработка ошибок** с кастомным исключением `AgentException`
 - ✅ **Логирование** на всех уровнях операций
@@ -53,25 +56,31 @@ asyncio.run(main())
 ### Использование
 
 ```python
-from agent_api import AgentApi, AgentException, OM
+from agent_api import AgentApi, OM
 
 # Использование с контекстным менеджером
-async with AgentApi("ws://localhost:8000") as agent:
-    # Отправка сообщения
-    await agent.send_user_message("Your question here")
+async with AgentApi("ws://localhost:8000", callback=my_callback) as api:
+    # Отправка сообщения и получение итератора
+    response = await api.send_message("Your question here")
 
-    # Получение потока ответов
-    try:
-        async for message in agent.listen():
-            if isinstance(message, OM.Status):
-                print("✓ Agent is ready")
-            elif isinstance(message, OM.EventTextChunk):
-                print(message.text, end="", flush=True)
-            elif isinstance(message, OM.EventEnd):
-                print(f"\nDone! Tokens: {message.tokens_used}")
-                break
-    except AgentException as e:
-        print(f"Agent error ({e.code}): {e.details}")
+    # Итерация по чанкам ответа
+    async for chunk in response:
+        if isinstance(chunk, OM.EventTextChunk):
+            print(chunk.text, end="", flush=True)
+    
+    print(f"\nDone! Tokens: {response.tokens}")
+```
+
+Callback функция для обработки событий вне генерации:
+
+```python
+def my_callback(message):
+    if isinstance(message, OM.Status):
+        print("Agent status update")
+    elif isinstance(message, OM.Error):
+        print(f"Agent error: {message.code} - {message.details}")
+    elif isinstance(message, OM.GracefulDisconnect):
+        print("Agent disconnecting gracefully")
 ```
 
 ## Классический подход (низкоуровневый)