Обмен сообщениями

PRX предоставляет два инструмента обмена сообщениями, которые позволяют агентам отправлять сообщения обратно через каналы связи. Инструмент message_send -- это высокоуровневый интерфейс для отправки текстовых, медиа- и голосовых сообщений на любой настроенный канал, а инструмент gateway предоставляет низкоуровневый доступ к HTTP/WebSocket-шлюзу Axum для прямой доставки сообщений.

Инструменты обмена сообщениями регистрируются на уровне шлюза и доступны при наличии активного канала. Инструмент message_send автоматически маршрутизирует сообщения в активный канал (Telegram, Discord, Slack, CLI и т.д.), а инструмент gateway предлагает прямой доступ к протоколу шлюза для продвинутых сценариев.

Эти инструменты дополняют систему входящих каналов. В то время как каналы обрабатывают получение сообщений от пользователей и их маршрутизацию к агенту, инструменты обмена сообщениями обрабатывают исходящее направление -- отправку сгенерированного агентом контента обратно пользователям.

Конфигурация

Инструменты обмена сообщениями не имеют отдельного раздела конфигурации. Их доступность зависит от конфигурации каналов и шлюза:

# Конфигурация шлюза (инструменты обмена сообщениями зависят от неё)
[gateway]
host = "127.0.0.1"
port = 16830

# Конфигурация каналов (message_send маршрутизирует в активный канал)
[channels_config]
cli = true
message_timeout_secs = 300

[channels_config.telegram]
bot_token = "123456:ABC-DEF..."
allowed_users = ["alice", "bob"]
stream_mode = "partial"

Инструмент message_send доступен при наличии хотя бы одного активного канала. Инструмент gateway всегда регистрируется в all_tools().

Справочник инструментов

message_send

Отправляет сообщение на любой настроенный канал и получателю. Инструмент автоматически маршрутизирует в активный канал -- канал, через который происходит текущий разговор.

Отправка текстового сообщения:

{
  "name": "message_send",
  "arguments": {
    "text": "The build completed successfully. All 42 tests passed.",
    "channel": "telegram"
  }
}

Отправка медиа (изображение/файл):

{
  "name": "message_send",
  "arguments": {
    "media_path": "/tmp/screenshot.png",
    "caption": "Current dashboard state",
    "channel": "telegram"
  }
}

Отправка голосового сообщения:

{
  "name": "message_send",
  "arguments": {
    "voice_path": "/tmp/summary.mp3",
    "channel": "telegram"
  }
}

Параметр	Тип	Обязательный	По умолчанию	Описание
text	string	Условно	--	Текст сообщения (обязателен, если нет медиа/голоса)
channel	string	Нет	Активный канал	Имя целевого канала (определяется автоматически, если не указано)
recipient	string	Нет	Текущий пользователь	Идентификатор получателя (ID пользователя, ID чата и т.д.)
media_path	string	Нет	--	Путь к медиафайлу (изображение, документ, видео)
caption	string	Нет	--	Подпись для медиа-сообщений
voice_path	string	Нет	--	Путь к голосовому/аудиофайлу
reply_to	string	Нет	--	ID сообщения для ответа (зависит от платформы)

gateway

Низкоуровневый доступ к шлюзу для отправки необработанных сообщений через HTTP/WebSocket-шлюз Axum. Этот инструмент предназначен для продвинутых сценариев, где message_send недостаточен.

{
  "name": "gateway",
  "arguments": {
    "action": "send",
    "payload": {
      "type": "text",
      "content": "Raw gateway message",
      "target": "ws://localhost:16830/ws"
    }
  }
}

Параметр	Тип	Обязательный	По умолчанию	Описание
action	string	Да	--	Действие шлюза: "send", "broadcast", "status"
payload	object	Условно	--	Полезная нагрузка сообщения (обязательна для "send" и "broadcast")

Использование

Автоматическая маршрутизация каналов

В большинстве случаев агенту не нужно указывать канал. Когда пользователь отправляет сообщение через Telegram, ответ агента автоматически маршрутизируется обратно в Telegram:

Пользователь (через Telegram): Какая погода?
Агент: [вызывает message_send с text="Currently 22C and sunny in Shanghai."]
       → Автоматически отправлено в Telegram, в тот же чат

Межканальные сообщения

Агент может отправлять сообщения в другой канал, отличный от того, в котором происходит разговор:

{
  "name": "message_send",
  "arguments": {
    "text": "Build failed! Check CI logs.",
    "channel": "discord",
    "recipient": "111222333"
  }
}

Это полезно для сценариев уведомлений, когда агент мониторит один канал и отправляет оповещения в другой.

Доставка медиа

Агент может отправлять файлы, изображения и аудио через каналы обмена сообщениями:

1. Сгенерировать или загрузить медиафайл
2. Сохранить его во временный путь
3. Отправить через message_send с media_path

Агент размышляет: Пользователь попросил график данных.
  1. [shell] python3 generate_chart.py --output /tmp/chart.png
  2. [message_send] media_path="/tmp/chart.png", caption="Monthly revenue chart"

Голосовые сообщения

Для каналов с поддержкой голоса (Telegram, WhatsApp, Discord) агент может отправлять аудио-сообщения:

Агент размышляет: Пользователь попросил голосовое резюме.
  1. [tts] text="Here is your daily summary..." output="/tmp/summary.mp3"
  2. [message_send] voice_path="/tmp/summary.mp3"

Детали маршрутизации каналов

При вызове message_send без явного параметра channel PRX определяет целевой канал по следующей логике:

1. Канал активной сессии: Канал, связанный с текущей сессией агента (устанавливается при создании сессии входящим сообщением)
2. Канал по умолчанию: Если канал сессии не установлен, переключается на первый активный канал
3. Резервный CLI: Если каналы не настроены, вывод идёт в stdout

Поддерживаемые транспорты каналов

Канал	Текст	Медиа	Голос	Ответ
Telegram	Да	Да	Да	Да
Discord	Да	Да	Да	Да
Slack	Да	Да	Нет	Да
WhatsApp	Да	Да	Да	Да
Signal	Да	Да	Нет	Да
Matrix	Да	Да	Нет	Да
Email	Да	Да (вложение)	Нет	Да
CLI	Да	Нет	Нет	Нет

Безопасность

Авторизация каналов

Исходящие сообщения подчиняются тем же политикам каналов, что и входящие сообщения. Агент может отправлять сообщения только в настроенные и активные каналы. Попытка отправки в ненастроенный канал возвращает ошибку.

Валидация получателей

При указании recipient PRX проверяет, что получатель доступен через целевой канал. Для каналов со списками allowed_users исходящие сообщения к незарегистрированным получателям блокируются.

Ограничение частоты

Исходящие сообщения подчиняются ограничениям частоты канала (настраиваемым для каждой платформы). Например, Telegram применяет ограничения API, которые PRX соблюдает с автоматической задержкой.

Политика безопасности

Инструментами обмена сообщениями можно управлять через политику безопасности:

[security.tool_policy.tools]
message_send = "allow"
gateway = "supervised"     # Требовать одобрение для прямого доступа к шлюзу

Журнал аудита

Все исходящие сообщения записываются в журнал аудита:

• Целевой канал и получатель
• Тип сообщения (текст, медиа, голос)
• Метка времени
• Статус доставки

Пути к медиафайлам логируются, но содержимое файлов не сохраняется в журнале аудита.

Связанные разделы

• Обзор каналов -- все 19 поддерживаемых платформ обмена сообщениями
• Шлюз -- HTTP API и архитектура WebSocket
• HTTP API шлюза -- REST API эндпоинты
• WebSocket шлюза -- потоковая передача в реальном времени
• Инструменты рендеринга (TTS) -- синтез речи для голосовых сообщений
• Обзор инструментов -- все инструменты и система реестра