[WIP] docs: update API documentation for ChatCompletionMessageParam format

docs/en/sgr-api/SGR-Description-API.md

@@ -112,7 +112,7 @@ Create a chat completion for research tasks. This is the main endpoint for inter
 **Parameters:**
 
 - `model` (string, required): Agent type or existing agent ID
-- `messages` (array, required): List of chat messages
+- `messages` (array, required): List of chat messages in OpenAI format (ChatCompletionMessageParam)
 - `stream` (boolean, default: true): Enable streaming mode
 - `max_tokens` (integer, optional): Maximum number of tokens
 - `temperature` (float, optional): Generation temperature (0.0-1.0)
@@ -140,6 +140,44 @@ curl -X POST "http://localhost:8010/v1/chat/completions" \
   }'
 ```
 
+**Example with Image (URL):**
+
+```bash
+curl -X POST "http://localhost:8010/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "sgr-agent",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "Analyze this chart and research the trends"},
+        {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
+      ]
+    }],
+    "stream": true
+  }'
+```
+
+**Example with Image (Base64):**
+
+```bash
+curl -X POST "http://localhost:8010/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "sgr-agent",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "What is shown in this image?"},
+        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}
+      ]
+    }],
+    "stream": true
+  }'
+```
+
+**Note:** Base64 image URLs longer than 200 characters will be truncated in responses for performance reasons.
+
 </details>
 
 ______________________________________________________________________
@@ -158,7 +196,12 @@ Get a list of all active agents.
   "agents": [
     {
       "agent_id": "sgr_agent_12345-67890-abcdef",
-      "task": "Research BMW X6 2025 prices",
+      "task_messages": [
+        {
+          "role": "user",
+          "content": "Research BMW X6 2025 prices"
+        }
+      ],
       "state": "RESEARCHING"
     }
   ],
@@ -195,7 +238,12 @@ Get detailed state information for a specific agent.
 ```json
 {
   "agent_id": "sgr_agent_12345-67890-abcdef",
-  "task": "Research BMW X6 2025 prices",
+  "task_messages": [
+    {
+      "role": "user",
+      "content": "Research BMW X6 2025 prices"
+    }
+  ],
   "state": "RESEARCHING",
   "iteration": 3,
   "searches_used": 2,
@@ -234,14 +282,19 @@ Provide clarification to an agent that is waiting for input.
 
 ```json
 {
-  "clarifications": "Focus on luxury models only, price range 5-8 million rubles"
+  "messages": [
+    {
+      "role": "user",
+      "content": "Focus on luxury models only, price range 5-8 million rubles"
+    }
+  ]
 }
 ```
 
 **Parameters:**
 
 - `agent_id` (string, required): Unique agent identifier
-- `clarifications` (string, required): Clarification text
+- `messages` (array, required): Clarification messages in OpenAI format (ChatCompletionMessageParam)
 
 **Response:**
 Streaming response with continued research after clarification.
@@ -252,7 +305,7 @@ Streaming response with continued research after clarification.
 curl -X POST "http://localhost:8010/agents/sgr_agent_12345-67890-abcdef/provide_clarification" \
   -H "Content-Type: application/json" \
   -d '{
-    "clarifications": "Focus on luxury models only"
+    "messages": [{"role": "user", "content": "Focus on luxury models only"}]
   }'
 ```
 

docs/en/sgr-api/SGR-Integration-&-Examples.md

@@ -101,6 +101,45 @@ if clarification_questions and agent_id:
 print("\n\nResearch completed!")
 ```
 
+### Example 3: Research Request with Image
+
+Send a research request with a local image file attachment.
+
+```python
+import base64
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:8010/v1", api_key="dummy")
+
+# Read local image file and encode to base64
+with open("chart.png", "rb") as image_file:
+    image_data = base64.b64encode(image_file.read()).decode("utf-8")
+    image_base64 = f"data:image/png;base64,{image_data}"
+
+# Research request with local image
+response = client.chat.completions.create(
+    model="sgr-agent",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Analyze this chart and research the trends shown"},
+            {"type": "image_url", "image_url": {"url": image_base64}}
+        ]
+    }],
+    stream=True,
+    temperature=0.4,
+)
+
+# Print streaming response
+for chunk in response:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="")
+```
+
+**Image Formats Supported:**
+- Image URLs (HTTP/HTTPS)
+- Base64 encoded images (`data:image/jpeg;base64,...` or `data:image/png;base64,...`)
+
 #### Usage Notes
 
 - Replace `localhost:8010` with your server URL

docs/ru/sgr-api/SGR-Description-API.md

@@ -112,7 +112,7 @@ ______________________________________________________________________
 **Параметры:**
 
 - `model` (string, обязательный): Тип агента или существующий ID агента
-- `messages` (array, обязательный): Список сообщений чата
+- `messages` (array, обязательный): Список сообщений чата в формате OpenAI (ChatCompletionMessageParam)
 - `stream` (boolean, по умолчанию: true): Включить режим потоковой передачи
 - `max_tokens` (integer, опциональный): Максимальное количество токенов
 - `temperature` (float, опциональный): Температура генерации (0.0-1.0)
@@ -140,6 +140,44 @@ curl -X POST "http://localhost:8010/v1/chat/completions" \
   }'
 ```
 
+**Пример с изображением (URL):**
+
+```bash
+curl -X POST "http://localhost:8010/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "sgr-agent",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "Проанализируй этот график и исследуй тренды"},
+        {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
+      ]
+    }],
+    "stream": true
+  }'
+```
+
+**Пример с изображением (Base64):**
+
+```bash
+curl -X POST "http://localhost:8010/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "sgr-agent",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "Что показано на этом изображении?"},
+        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}
+      ]
+    }],
+    "stream": true
+  }'
+```
+
+**Примечание:** Base64 URL изображений длиннее 200 символов будут обрезаны в ответах для оптимизации производительности.
+
 </details>
 
 ______________________________________________________________________
@@ -158,7 +196,12 @@ ______________________________________________________________________
   "agents": [
     {
       "agent_id": "sgr_agent_12345-67890-abcdef",
-      "task": "Research BMW X6 2025 prices",
+      "task_messages": [
+        {
+          "role": "user",
+          "content": "Research BMW X6 2025 prices"
+        }
+      ],
       "state": "RESEARCHING"
     }
   ],
@@ -195,7 +238,12 @@ ______________________________________________________________________
 ```json
 {
   "agent_id": "sgr_agent_12345-67890-abcdef",
-  "task": "Research BMW X6 2025 prices",
+  "task_messages": [
+    {
+      "role": "user",
+      "content": "Research BMW X6 2025 prices"
+    }
+  ],
   "state": "RESEARCHING",
   "iteration": 3,
   "searches_used": 2,
@@ -234,14 +282,19 @@ ______________________________________________________________________
 
 ```json
 {
-  "clarifications": "Focus on luxury models only, price range 5-8 million rubles"
+  "messages": [
+    {
+      "role": "user",
+      "content": "Focus on luxury models only, price range 5-8 million rubles"
+    }
+  ]
 }
 ```
 
 **Параметры:**
 
 - `agent_id` (string, обязательный): Уникальный идентификатор агента
-- `clarifications` (string, обязательный): Текст уточнения
+- `messages` (array, обязательный): Сообщения уточнения в формате OpenAI (ChatCompletionMessageParam)
 
 **Ответ:**
 Потоковый ответ с продолжением исследования после уточнения.
@@ -252,7 +305,7 @@ ______________________________________________________________________
 curl -X POST "http://localhost:8010/agents/sgr_agent_12345-67890-abcdef/provide_clarification" \
   -H "Content-Type: application/json" \
   -d '{
-    "clarifications": "Focus on luxury models only"
+    "messages": [{"role": "user", "content": "Focus on luxury models only"}]
   }'
 ```
 

docs/ru/sgr-api/SGR-Integration-&-Examples.md

@@ -101,6 +101,45 @@ if clarification_questions and agent_id:
 print("\n\nИсследование завершено!")
 ```
 
+### Пример 3: Исследовательский запрос с изображением
+
+Отправка исследовательского запроса с локальным файлом изображения.
+
+```python
+import base64
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:8010/v1", api_key="dummy")
+
+# Прочитать локальный файл изображения и закодировать в base64
+with open("chart.png", "rb") as image_file:
+    image_data = base64.b64encode(image_file.read()).decode("utf-8")
+    image_base64 = f"data:image/png;base64,{image_data}"
+
+# Исследовательский запрос с локальным изображением
+response = client.chat.completions.create(
+    model="sgr-agent",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Проанализируй этот график и исследуй показанные тренды"},
+            {"type": "image_url", "image_url": {"url": image_base64}}
+        ]
+    }],
+    stream=True,
+    temperature=0.4,
+)
+
+# Вывести потоковый ответ
+for chunk in response:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="")
+```
+
+**Поддерживаемые форматы изображений:**
+- URL изображений (HTTP/HTTPS)
+- Изображения в формате Base64 (`data:image/jpeg;base64,...` или `data:image/png;base64,...`)
+
 #### Примечания по использованию
 
 - Замените `localhost:8010` на URL вашего сервера