Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Mikhail Putilovskij 2026-04-28 03:23:56 +03:00
parent 4bbae9affa
commit 6d2d58f05d
2 changed files with 35 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -12,16 +12,19 @@ Matrix-бот для взаимодействия пользователя с AI
Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`.
Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`.
**2. Shared volume**
Бот пишет файлы пользователей в Docker volume, смонтированный как `/agents`.
Агент должен видеть тот же volume — как `/workspace`.
**2. Shared volume с per-agent поддиректориями**
Shared volume монтируется в бот как `/agents`. Каждый агент видит свою поддиректорию.
```
Bot container Agent container
/agents/ ←──── named Docker volume ────→ /workspace/
Bot container Agent containers
/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)

31
docs/deploy-architecture.md
View file

@ -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`.
Старый root compose harness больше не является primary runtime contract для Phase 05.
Production operators: `docker-compose.prod.yml`. Internal E2E: `docker-compose.fullstack.yml`.
---
@ -51,17 +51,19 @@ user_agents:
agents:
- id: agent-0
label: "Agent 0"
base_url: "ws://lambda.coredump.ru:7000/agent_0/"
workspace_path: "/agents/0/"
base_url: "http://lambda.coredump.ru:7000/agent_0/"
workspace_path: "/agents/0"
- id: agent-1
label: "Agent 1"
base_url: "ws://lambda.coredump.ru:7000/agent_1/"
workspace_path: "/agents/1/"
base_url: "http://lambda.coredump.ru:7000/agent_1/"
workspace_path: "/agents/1"
```
- `user_agents` — маппинг Matrix user_id → agent_id (статический, выдаётся платформой)
- `agents` — маппинг agent_id → URL агента и путь к его workspace на shared volume
- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка.
- `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. Уточнить у Азамата сроки мержа перед деплоем.
- `chat_id` — каждый Matrix chat room должен иметь собственный `platform_chat_id`. `!clear` должен ротировать `platform_chat_id` только для текущей комнаты, чтобы получить новый thread и чистый контекст без смены Matrix room.
- Composio `AGENT_ID` в `.env` для каждого агента — уточнить у платформы значения.
- Что происходит с историей при рестарте агента — `MemorySaver` не персистентный.
- `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока используем master. Уточнить у платформы сроки мержа перед деплоем.
- История при рестарте агента теряется — `platform-agent` использует `MemorySaver` (in-memory). Ограничение платформы.
- `AGENT_ID` и `COMPOSIO_API_KEY` для каждого агент-контейнера — значения предоставляет платформа.