Surfaces_team/surfaces

Fork 0

Mikhail Putilovskij 6d2d58f05d docs: update deploy-architecture and README for per-agent routing

2026-04-28 03:23:56 +03:00

10 KiB

Raw Blame History

Lambda Lab 3.0 — Surfaces

Matrix-бот для взаимодействия пользователя с AI-агентом Lambda.

Интеграция для платформы

Бот — это один Docker-контейнер (matrix-bot), который вы добавляете в свою инфраструктуру рядом с агентами.

Что бот ожидает от вас

1. HTTP-эндпоинт агента Бот подключается к агенту через lambda_agent_api.AgentApi по адресу AGENT_BASE_URL. Протокол — WebSocket поверх HTTP, контракт описан в docs/deploy-architecture.md.

2. Shared volume с per-agent поддиректориями Shared volume монтируется в бот как /agents. Каждый агент видит свою поддиректорию.

Bot container                  Agent containers
  /agents/0/  ←── volume ──→  agent_0: /workspace/
  /agents/1/  ←── volume ──→  agent_1: /workspace/
  /agents/N/  ←── volume ──→  agent_N: /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.

Что бот не делает

Не управляет lifecycle агент-контейнеров (запуск/остановка — на вашей стороне)
Не хранит историю разговоров (это в памяти агента)
Не обрабатывает аутентификацию пользователей — любой Matrix-пользователь, который пишет боту, получает доступ

Минимальный чеклист

Заполнить .env (по шаблону .env.example)
Заполнить config/matrix-agents.yaml (ID агентов и маппинг пользователей)
Убедиться что AGENT_BASE_URL доступен из контейнера бота
Смонтировать один и тот же named volume в бот (/agents) и в агент (/workspace)
Запустить: docker compose -f docker-compose.prod.yml up -d --build

Статус

Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff.

Архитектура

surfaces-bot/
  core/                  — общее ядро, не зависит от транспорта
    protocol.py          — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
    handler.py           — EventDispatcher: IncomingEvent → OutgoingEvent
    store.py             — StateStore Protocol + InMemoryStore + SQLiteStore
    chat.py              — ChatManager
    auth.py              — AuthManager
    settings.py          — SettingsManager

  adapter/
    matrix/              — matrix-nio адаптер

  sdk/
    interface.py         — PlatformClient Protocol (контракт к SDK)
    real.py              — RealPlatformClient (через AgentApi)
    mock.py              — MockPlatformClient (заглушка для тестов)

  config/
    matrix-agents.yaml   — реестр агентов

  docs/                  — документация

Подробнее: docs/surface-protocol.md

Деплой

Переменные окружения

cp .env.example .env

Переменная	Обязательна	Описание
`MATRIX_HOMESERVER`	✓	URL Matrix-сервера
`MATRIX_USER_ID`	✓	`@bot:example.org`
`MATRIX_PASSWORD`	✓	пароль (или `MATRIX_ACCESS_TOKEN`)
`MATRIX_PLATFORM_BACKEND`	✓	`real` для продакшна
`AGENT_BASE_URL`	✓	HTTP-URL агента, например `http://platform-agent:8000`
`MATRIX_AGENT_REGISTRY_PATH`	✓	путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml`
`SURFACES_WORKSPACE_DIR`		путь к shared volume в контейнере (по умолчанию `/agents`)
`SURFACES_SHARED_VOLUME`		имя Docker volume (по умолчанию `surfaces-agents`)

Реестр агентов

config/matrix-agents.yaml — статический маппинг пользователей на агентов:

user_agents:
  "@user0:matrix.lambda.coredump.ru": agent-0
  "@user1:matrix.lambda.coredump.ru": agent-1

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 — маппинг 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)

docker compose --env-file .env -f docker-compose.prod.yml up -d --build

Поднимает только matrix-bot. Монтирует shared volume в /agents. Требует внешний AGENT_BASE_URL.

Fullstack E2E (bot + agent)

docker compose --env-file .env -f docker-compose.fullstack.yml up --build

Поднимает matrix-bot вместе с локальным platform-agent. AGENT_BASE_URL перекрывается на http://platform-agent:8000. Shared volume виден как /agents в боте и /workspace в агенте.

Сброс состояния (локально)

rm -f lambda_matrix.db && rm -rf matrix_store

Shared volume: передача файлов

Bot (/agents)                       Agent (/workspace)
  └── surfaces/matrix/{user}/{room}/inbox/file  ←── одно и то же хранилище

Бот пишет входящие файлы в /agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename} и передаёт агенту относительный путь. Исходящие файлы агент пишет в /workspace/..., бот читает из /agents/....

Онбординг пользователя

Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере
Бот создаёт private Space Lambda — {display_name} и комнату Чат 1
Дальнейшее общение — в рабочих комнатах, не в DM

Требование: незашифрованные комнаты. E2EE не поддержан.

Команды Matrix

Работающие

Команда	Действие
(любое сообщение)	Диалог с агентом, стриминг ответа
`!new [название]`	Создать новый чат
`!chats`	Список активных чатов
`!rename <название>`	Переименовать текущую комнату
`!archive`	Архивировать чат
`!clear`	Сбросить контекст текущего чата
`!yes` / `!no`	Подтвердить / отменить действие агента
`!list`	Файлы в очереди вложений
`!remove <n>` / `!remove all`	Удалить вложение из очереди
`!help`	Справка

Не работают / заглушки

Команда	Статус
`!save` / `!load` / `!context`	Нестабильны: зависят от агента, сессии теряются при рестарте
`!settings` и подкоманды	Заглушки MVP, требуют готового SDK платформы

Отправка файлов агенту

Matrix-клиент отправляет файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь.

[отправил файл]
!list
  1. report.pdf

прочитай и сделай summary   ← файл уйдёт агенту вместе с этим текстом

Известные ограничения

Проблема	Причина
История теряется при рестарте агента	`platform-agent` использует `MemorySaver` (in-memory)
E2EE	`python-olm` не собирается на macOS/ARM

Разработка

uv sync
pytest tests/ -v
pytest tests/adapter/matrix/ -v   # только Matrix

Документация

Файл	Содержание
`docs/deploy-architecture.md`	Читать первым. Топология деплоя, volume-контракт, AgentApi, конфигурация
`docs/matrix-prototype.md`	Команды бота, UX, передача файлов
`docs/known-limitations.md`	Известные ограничения и обходные пути
`docs/surface-protocol.md`	Внутренний протокол событий (для расширения)

10 KiB Raw Blame History Unescape Escape