docs: update deploy-architecture and README for per-agent routing

README.md

@@ -12,16 +12,19 @@ Matrix-бот для взаимодействия пользователя с AI
 Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`.
 Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`.
 
-**2. Shared volume**
+**2. Shared volume с per-agent поддиректориями**
-Бот пишет файлы пользователей в Docker volume, смонтированный как `/agents`.
+Shared volume монтируется в бот как `/agents`. Каждый агент видит свою поддиректорию.
-Агент должен видеть тот же volume — как `/workspace`.
 
 ```
-Bot container          Agent container
+Bot container                  Agent containers
-  /agents/   ←──── named Docker volume ────→  /workspace/
+  /agents/0/  ←── volume ──→  agent_0: /workspace/
+  /agents/1/  ←── volume ──→  agent_1: /workspace/
+  /agents/N/  ←── volume ──→  agent_N: /workspace/
 ```
 
-Бот кладёт входящие файлы по пути `surfaces/matrix/{user}/{room}/inbox/{file}` и передаёт агенту этот относительный путь. Исходящие файлы агент пишет в свой `/workspace/`, бот читает их оттуда же.
+- Бот сохраняет входящий файл в `{workspace_path}/incoming/{stamp}-{file}` и передаёт агенту `attachments=["incoming/{stamp}-{file}"]`
+- Агент пишет исходящий файл в свой `/workspace/output/file`, бот читает его из `{workspace_path}/output/file`
+- `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml`
 
 **3. Конфиг агентов**
 Файл `config/matrix-agents.yaml` — маппинг Matrix-пользователей на агентов. Вы заполняете его под свою инфраструктуру. Пример в `config/matrix-agents.example.yaml`.
@@ -109,11 +112,20 @@ user_agents:
 agents:
   - id: agent-0
     label: "Agent 0"
+    base_url: "http://lambda.coredump.ru:7000/agent_0/"
+    workspace_path: "/agents/0"
   - id: agent-1
     label: "Agent 1"
+    base_url: "http://lambda.coredump.ru:7000/agent_1/"
+    workspace_path: "/agents/1"
 ```
 
-Если `user_agents` не задан или пользователь не найден — используется первый агент из списка.
+- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент.
+- `base_url` — HTTP URL агент-эндпоинта (path-based routing через reverse proxy).
+- `workspace_path` — путь к воркспейсу агента внутри бот-контейнера на shared volume.
+  Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, агент пишет исходящие в свой `/workspace/`.
+
+Полный пример с комментариями: `config/matrix-agents.example.yaml`
 
 ### Production (bot-only)
 

docs/deploy-architecture.md

@@ -7,12 +7,12 @@
 ## Compose Artifacts
 
 - **Production deploy:** `docker-compose.prod.yml`
-  Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`, требует внешний `AGENT_BASE_URL`.
+  Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`.
+  Платформа предоставляет агент-контейнеры отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`.
 - **Internal full-stack E2E:** `docker-compose.fullstack.yml`
-  Внутренний harness. Поднимает `matrix-bot` и `platform-agent`, использует тот же volume name и health-gated startup через `condition: service_healthy`.
+  Внутренний harness для тестирования. Поднимает `matrix-bot` и один `platform-agent`, health-gated startup.
 
-Production operators should run the bot with `docker-compose.prod.yml`; internal verification should use `docker-compose.fullstack.yml`.
+Production operators: `docker-compose.prod.yml`. Internal E2E: `docker-compose.fullstack.yml`.
-Старый root compose harness больше не является primary runtime contract для Phase 05.
 
 ---
 
@@ -51,17 +51,19 @@ user_agents:
 agents:
   - id: agent-0
     label: "Agent 0"
-    base_url: "ws://lambda.coredump.ru:7000/agent_0/"
+    base_url: "http://lambda.coredump.ru:7000/agent_0/"
-    workspace_path: "/agents/0/"
+    workspace_path: "/agents/0"
 
   - id: agent-1
     label: "Agent 1"
-    base_url: "ws://lambda.coredump.ru:7000/agent_1/"
+    base_url: "http://lambda.coredump.ru:7000/agent_1/"
-    workspace_path: "/agents/1/"
+    workspace_path: "/agents/1"
 ```
 
-- `user_agents` — маппинг Matrix user_id → agent_id (статический, выдаётся платформой)
+- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка.
-- `agents` — маппинг agent_id → URL агента и путь к его workspace на shared volume
+- `agents[].base_url` — HTTP URL агент-эндпоинта. Бот подключается через AgentApi.
+- `agents[].workspace_path` — абсолютный путь к воркспейсу агента **внутри контейнера бота** (т.е. на shared volume).
+  Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, читает исходящие из `{workspace_path}/`.
 
 ---
 
@@ -150,9 +152,8 @@ AgentApi(
 
 ---
 
-## Что НЕ решено / открытые вопросы
+## Открытые вопросы
 
-- Ветка `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока игнорируем, используем master. Уточнить у Азамата сроки мержа перед деплоем.
+- `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока используем master. Уточнить у платформы сроки мержа перед деплоем.
-- `chat_id` — каждый Matrix chat room должен иметь собственный `platform_chat_id`. `!clear` должен ротировать `platform_chat_id` только для текущей комнаты, чтобы получить новый thread и чистый контекст без смены Matrix room.
+- История при рестарте агента теряется — `platform-agent` использует `MemorySaver` (in-memory). Ограничение платформы.
-- Composio `AGENT_ID` в `.env` для каждого агента — уточнить у платформы значения.
+- `AGENT_ID` и `COMPOSIO_API_KEY` для каждого агент-контейнера — значения предоставляет платформа.
-- Что происходит с историей при рестарте агента — `MemorySaver` не персистентный.