Обзор инструментов

Инструменты — это возможности, которые агент PRX может вызывать во время своего цикла рассуждения. Когда LLM решает, что нужно выполнить действие — запустить команду, прочитать файл, выполнить поиск в интернете, сохранить запись в память — он вызывает инструмент по имени с структурированными JSON-аргументами. PRX выполняет инструмент, применяет политики безопасности и возвращает результат LLM для следующего шага рассуждения.

PRX поставляется с 46+ встроенными инструментами в 12 категориях, от базового файлового ввода-вывода до автоматизации браузера, делегирования мультиагентам и интеграции с протоколом MCP.

Архитектура инструментов

Каждый инструмент реализует трейт Tool:

rust

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: serde_json::Value) -> Result<ToolResult>;
}

Каждый инструмент предоставляет JSON Schema для своих параметров, которая отправляется LLM как определение функции. LLM генерирует структурированные вызовы, и PRX валидирует аргументы по схеме перед выполнением.

Реестр инструментов: `default_tools()` vs `all_tools()`

PRX использует двухуровневую систему реестра:

`default_tools()` — минимальное ядро (3 инструмента)

Минимальный набор инструментов для лёгких или ограниченных агентов. Всегда доступен, не требует дополнительной настройки:

Инструмент	Описание
`shell`	Выполнение команд оболочки с изоляцией песочницы
`file_read`	Чтение содержимого файлов (с учётом ACL)
`file_write`	Запись содержимого файлов

`all_tools()` — полный реестр (46+ инструментов)

Полный набор инструментов, собираемый на основе конфигурации. Инструменты условно регистрируются в зависимости от включённых функций:

Всегда регистрируются: основные инструменты, память, cron, планирование, git, зрение, узлы, pushover, canvas, прокси-конфигурация, схема
Условно регистрируются: браузер (требует browser.enabled), HTTP-запросы (требует http_request.enabled), веб-поиск (требует web_search.enabled), веб-извлечение (требует web_search.fetch_enabled + browser.allowed_domains), MCP (требует mcp.enabled), Composio (требует API-ключ), delegate/agents_list (требуют определений агентов)

Справочник по категориям

Основные (3 инструмента) — всегда доступны

Базовые инструменты, присутствующие как в default_tools(), так и в all_tools().

Инструмент	Описание
`shell`	Выполнение команд оболочки с настраиваемой изоляцией песочницы (Landlock/Firejail/Bubblewrap/Docker). 60-секундный таймаут, лимит вывода 1 МБ, санированное окружение.
`file_read`	Чтение содержимого файлов с валидацией путей. При включённом ACL памяти блокирует доступ к файлам markdown-памяти для обеспечения контроля доступа.
`file_write`	Запись содержимого в файлы. Подчиняется проверкам политики безопасности.

Память (5 инструментов)

Операции долговременной памяти для хранения, извлечения и управления постоянными знаниями агента.

Инструмент	Описание
`memory_store`	Сохранение фактов, предпочтений или заметок в долговременную память. Поддерживает категории: `core` (постоянные), `daily` (сессионные), `conversation` (контекст чата) или пользовательские.
`memory_forget`	Удаление конкретных записей из долговременной памяти.
`memory_get`	Получение конкретной записи памяти по ключу. С учётом ACL при включении.
`memory_recall`	Вызов воспоминаний по ключевым словам или семантическому сходству. Отключается при включённом ACL памяти.
`memory_search`	Полнотекстовый и векторный поиск по записям памяти. С учётом ACL при включении.

Cron / Планирование (9 инструментов)

Автоматизация задач по времени и движок планирования Xin.

Инструмент	Описание
`cron`	Устаревшая точка входа cron — создание или управление запланированными задачами.
`cron_add`	Добавление нового cron-задания с cron-выражением, командой и опциональным описанием.
`cron_list`	Список всех зарегистрированных cron-заданий с расписаниями и статусом.
`cron_remove`	Удаление cron-задания по ID.
`cron_update`	Обновление расписания, команды или настроек существующего cron-задания.
`cron_run`	Ручной запуск cron-задания немедленно.
`cron_runs`	Просмотр истории выполнения и логов запусков cron-заданий.
`schedule`	Планирование одноразовой или повторяющейся задачи с выражениями времени на естественном языке.
`xin`	Движок планирования Xin — продвинутое планирование задач с цепочками зависимостей и условным выполнением.

Браузер / Зрение (5 инструментов)

Веб-автоматизация и обработка изображений. Инструменты браузера требуют [browser] enabled = true.

Инструмент	Описание
`browser`	Полная автоматизация браузера с подключаемыми бэкендами (agent-browser CLI, Rust-нативный, computer-use sidecar). Поддерживает навигацию, заполнение форм, нажатия, скриншоты и действия на уровне ОС.
`browser_open`	Простое открытие URL в браузере. Ограничено доменами через `browser.allowed_domains`.
`screenshot`	Захват скриншотов текущего экрана или конкретных окон.
`image`	Обработка и трансформация изображений (изменение размера, обрезка, конвертация форматов).
`image_info`	Извлечение метаданных и размеров из файлов изображений.

Сеть (4 инструмента)

HTTP-запросы, веб-поиск, веб-извлечение и интеграция с протоколом MCP.

Инструмент	Описание
`http_request`	Выполнение HTTP-запросов к API. Запрет по умолчанию: доступны только `allowed_domains`. Настраиваемый таймаут и максимальный размер ответа.
`web_search_tool`	Поиск в интернете через DuckDuckGo (бесплатно, без ключа) или Brave Search (требуется API-ключ).
`web_fetch`	Извлечение содержимого веб-страниц. Требует `web_search.fetch_enabled` и `browser.allowed_domains`.
`mcp`	Клиент Model Context Protocol — подключение к внешним MCP-серверам (stdio или HTTP-транспорт) и вызов их инструментов. Поддерживает обнаружение локального `mcp.json` в рабочем пространстве.

Обмен сообщениями (2 инструмента)

Отправка сообщений обратно через каналы коммуникации.

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

Сессии / Агенты (8 инструментов)

Мультиагентная оркестрация: создание подагентов, делегирование задач и управление параллельными сессиями.

Инструмент	Описание
`sessions_spawn`	Создание асинхронного подагента, работающего в фоне. Немедленно возвращает ID запуска; результат автоматически объявляется по завершении. Поддерживает действия `history` и `steer`.
`sessions_send`	Отправка сообщения в работающую сессию подагента.
`sessions_list`	Список всех активных сессий подагентов со статусом.
`sessions_history`	Просмотр журнала разговоров запуска подагента.
`session_status`	Проверка статуса конкретной сессии.
`subagents`	Управление пулом подагентов — список, остановка или инспекция подагентов.
`agents_list`	Список всех настроенных делегат-агентов с их моделями и возможностями. Регистрируется только при определении агентов в конфигурации.
`delegate`	Делегирование задачи именованному агенту с собственным провайдером, моделью и набором инструментов. Поддерживает резервные учётные данные и изолированные агентные циклы.

Удалённые устройства (2 инструмента)

Взаимодействие с удалёнными узлами и push-уведомления.

Инструмент	Описание
`nodes`	Управление и коммуникация с удалёнными узлами PRX в распределённом развёртывании.
`pushover`	Отправка push-уведомлений через сервис Pushover.

Git (1 инструмент)

Операции контроля версий.

Инструмент	Описание
`git_operations`	Выполнение Git-операций (status, diff, commit, push, pull, log, branch) в репозитории рабочего пространства.

Конфигурация (2 инструмента)

Управление конфигурацией во время выполнения.

Инструмент	Описание
`config_reload`	Горячая перезагрузка файла конфигурации PRX без перезапуска процесса.
`proxy_config`	Просмотр и изменение конфигурации прокси/сети во время выполнения.

Сторонняя интеграция (1 инструмент)

Коннекторы внешних платформ.

Инструмент	Описание
`composio`	Подключение к 250+ приложениям и сервисам через платформу Composio. Требует API-ключ Composio.

Рендеринг (2 инструмента)

Генерация контента и форматирование вывода.

Инструмент	Описание
`canvas`	Рендеринг структурированного контента (таблицы, диаграммы, схемы) для визуального вывода.
`tts`	Синтез речи — конвертация текста в голосовое сообщение и отправка в текущий разговор. Автоматическая генерация MP3, конвертация в M4A и доставка.

Администрирование (1 инструмент)

Внутренняя схема и диагностика.

Инструмент	Описание
`schema`	Очистка и нормализация JSON Schema для кросс-провайдерной совместимости LLM. Разрешение `$ref`, объединение union-типов, удаление неподдерживаемых ключевых слов.

Полная матрица инструментов

Инструмент	Категория	По умолчанию	Условие
`shell`	Основные	Да	Всегда
`file_read`	Основные	Да	Всегда
`file_write`	Основные	Да	Всегда
`memory_store`	Память	--	`all_tools()`
`memory_forget`	Память	--	`all_tools()`
`memory_get`	Память	--	`all_tools()`
`memory_recall`	Память	--	`all_tools()`, отключается при `memory.acl_enabled = true`
`memory_search`	Память	--	`all_tools()`
`cron`	Cron	--	`all_tools()`
`cron_add`	Cron	--	`all_tools()`
`cron_list`	Cron	--	`all_tools()`
`cron_remove`	Cron	--	`all_tools()`
`cron_update`	Cron	--	`all_tools()`
`cron_run`	Cron	--	`all_tools()`
`cron_runs`	Cron	--	`all_tools()`
`schedule`	Планирование	--	`all_tools()`
`xin`	Планирование	--	`all_tools()`
`browser`	Браузер	--	`browser.enabled = true`
`browser_open`	Браузер	--	`browser.enabled = true`
`screenshot`	Зрение	--	`all_tools()`
`image`	Зрение	--	`all_tools()` (неявно, через ImageTool)
`image_info`	Зрение	--	`all_tools()`
`http_request`	Сеть	--	`http_request.enabled = true`
`web_search_tool`	Сеть	--	`web_search.enabled = true`
`web_fetch`	Сеть	--	`web_search.fetch_enabled = true` + `browser.allowed_domains`
`mcp`	Сеть	--	`mcp.enabled = true` + серверы определены
`message_send`	Сообщения	--	Канал активен (регистрируется на уровне шлюза)
`gateway`	Сообщения	--	`all_tools()`
`sessions_spawn`	Сессии	--	`all_tools()`
`sessions_send`	Сессии	--	`all_tools()`
`sessions_list`	Сессии	--	`all_tools()`
`sessions_history`	Сессии	--	`all_tools()`
`session_status`	Сессии	--	`all_tools()`
`subagents`	Сессии	--	`all_tools()`
`agents_list`	Агенты	--	Секции `[agents.*]` определены
`delegate`	Агенты	--	Секции `[agents.*]` определены
`nodes`	Удалённые	--	`all_tools()`
`pushover`	Удалённые	--	`all_tools()`
`git_operations`	Git	--	`all_tools()`
`config_reload`	Конфигурация	--	`all_tools()`
`proxy_config`	Конфигурация	--	`all_tools()`
`composio`	Сторонние	--	`composio.api_key` задан
`canvas`	Рендеринг	--	`all_tools()`
`tts`	Рендеринг	--	Канал активен (регистрируется на уровне шлюза)
`schema`	Администрирование	--	Внутренний (модуль нормализации схемы)

Включение и отключение инструментов

Инструменты с гейтами функций

Многие инструменты включаются через соответствующие секции конфигурации. Добавьте их в config.toml:

toml

# ── Инструменты браузера ────────────────────────────────────
[browser]
enabled = true
allowed_domains = ["github.com", "stackoverflow.com", "*.openprx.dev"]
backend = "agent_browser"   # "agent_browser" | "rust_native" | "computer_use"

# ── Инструмент HTTP-запросов ─────────────────────────────────
[http_request]
enabled = true
allowed_domains = ["api.github.com", "api.openai.com"]
max_response_size = 1000000  # 1 МБ
timeout_secs = 30

# ── Инструмент веб-поиска ───────────────────────────────────
[web_search]
enabled = true
provider = "duckduckgo"      # "duckduckgo" (бесплатно) или "brave" (требуется API-ключ)
# brave_api_key = "..."
max_results = 5
timeout_secs = 10

# Также включить web_fetch для извлечения содержимого страниц:
fetch_enabled = true
fetch_max_chars = 50000

# ── Интеграция Composio ─────────────────────────────────────
[composio]
enabled = true
api_key = "your-composio-key"
entity_id = "default"

Конвейер политик инструментов

Для тонкой настройки используйте секцию [security.tool_policy] для разрешения, запрета или контроля отдельных инструментов или групп:

toml

[security.tool_policy]
# Политика по умолчанию: "allow", "deny" или "supervised"
default = "allow"

# Политики на уровне групп
[security.tool_policy.groups]
sessions = "allow"
automation = "allow"
hardware = "deny"

# Переопределения для отдельных инструментов (высший приоритет)
[security.tool_policy.tools]
shell = "supervised"     # Требует одобрения перед выполнением
gateway = "allow"
composio = "deny"        # Отключить Composio, даже если API-ключ задан

Порядок разрешения политик (от высшего приоритета):

Политика инструмента (security.tool_policy.tools.<name>)
Политика группы (security.tool_policy.groups.<group>)
Политика по умолчанию (security.tool_policy.default)

Ограничения инструментов делегат-агентов

При настройке делегат-агентов можно ограничить доступные им инструменты:

toml

[agents.researcher]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
system_prompt = "You are a research assistant."
agentic = true
max_iterations = 10
allowed_tools = ["web_search_tool", "web_fetch", "file_read", "memory_store"]

Интеграция инструментов MCP

PRX реализует клиент Model Context Protocol (MCP), позволяющий подключаться к внешним MCP-серверам и предоставлять их инструменты агенту.

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

Определите MCP-серверы в config.toml:

toml

[mcp]
enabled = true

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
transport = "stdio"

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
transport = "stdio"
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

[mcp.servers.remote-api]
url = "https://mcp.example.com/sse"
transport = "streamable_http"

Локальный `mcp.json` рабочего пространства

PRX также обнаруживает MCP-серверы из локального файла mcp.json рабочего пространства, следуя тому же формату, что VS Code и Claude Desktop:

json

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./my-mcp-server/index.js"],
      "env": { "API_KEY": "..." }
    }
  }
}

Команды в mcp.json ограничены белым списком безопасных запускателей: npx, node, python, python3, uvx, uv, deno, bun, docker, cargo, go, ruby, php, dotnet, java.

Динамическое обнаружение инструментов

MCP-инструменты обнаруживаются во время выполнения через метод протокола tools/list. Инструменты каждого MCP-сервера получают пространства имён и предоставляются LLM как вызываемые функции. Инструмент mcp поддерживает хук refresh(), который переобнаруживает инструменты перед каждым ходом агента.

Опасные переменные окружения (LD_PRELOAD, DYLD_INSERT_LIBRARIES, NODE_OPTIONS, PYTHONPATH и т.д.) автоматически удаляются из процессов MCP-серверов.

Безопасность: песочница и ACL

Песочница инструментов

Инструмент shell выполняет команды внутри настраиваемой песочницы. PRX поддерживает 4 бэкенда песочницы и резервный режим без операций:

toml

[security.sandbox]
enabled = true           # None = автоопределение, true/false = явно
backend = "auto"         # "auto" | "landlock" | "firejail" | "bubblewrap" | "docker" | "none"

# Пользовательские аргументы Firejail (при backend = "firejail")
firejail_args = ["--net=none", "--noroot"]

Бэкенд	Платформа	Уровень изоляции	Примечания
Landlock	Linux (kernel LSM)	Файловая система	Нативный для ядра, без дополнительных зависимостей
Firejail	Linux	Полный (сеть, файловая система, PID)	Пользовательское пространство, широко доступен
Bubblewrap	Linux, macOS	На основе пространств имён	Пользовательские пространства имён, лёгкий
Docker	Любая	Контейнер	Полная контейнерная изоляция
None	Любая	Только на уровне приложения	Без изоляции на уровне ОС

Режим автоопределения (backend = "auto") проверяет доступные бэкенды по порядку: Landlock, Firejail, Bubblewrap, Docker, затем переключается на None с предупреждением.

Санация окружения оболочки

Инструмент shell передаёт дочерним процессам только строгий белый список переменных окружения: PATH, HOME, TERM, LANG, LC_ALL, LC_CTYPE, USER, SHELL, TMPDIR. API-ключи, токены и секреты никогда не раскрываются.

ACL памяти

При memory.acl_enabled = true контроль доступа применяется к операциям с памятью:

file_read блокирует доступ к файлам markdown-памяти
memory_recall полностью отключается (удаляется из реестра инструментов)
memory_get и memory_search применяют ограничения доступа по принципалам

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

Каждый вызов инструмента проходит через слой SecurityPolicy перед выполнением. Движок политик может:

Блокировать операции на основе правил политики инструментов
Требовать одобрения супервизора для инструментов supervised
Аудировать все вызовы инструментов
Применять лимиты частоты и ограничения ресурсов

toml

[security.resources]
max_memory_mb = 512
max_cpu_percent = 80
max_open_files = 256

Расширение: написание пользовательских инструментов

Для добавления нового инструмента:

Создайте новый модуль в src/tools/, реализующий трейт Tool
Зарегистрируйте его в all_tools_with_runtime_ext() в src/tools/mod.rs
Добавьте записи pub mod и pub use в mod.rs

Пример:

rust

use super::traits::{Tool, ToolResult};
use async_trait::async_trait;
use serde_json::json;

pub struct MyTool { /* ... */ }

#[async_trait]
impl Tool for MyTool {
    fn name(&self) -> &str { "my_tool" }

    fn description(&self) -> &str {
        "Does something useful."
    }

    fn parameters_schema(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": {
                "input": { "type": "string", "description": "The input value" }
            },
            "required": ["input"]
        })
    }

    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
        let input = args["input"].as_str().unwrap_or_default();
        Ok(ToolResult {
            success: true,
            output: format!("Processed: {input}"),
            error: None,
        })
    }
}

См. AGENTS.md раздел 7.3 для полного руководства по изменениям.

Обзор инструментов ​

Архитектура инструментов ​

Реестр инструментов: default_tools() vs all_tools() ​

default_tools() — минимальное ядро (3 инструмента) ​

all_tools() — полный реестр (46+ инструментов) ​

Справочник по категориям ​

Основные (3 инструмента) — всегда доступны ​

Память (5 инструментов) ​

Cron / Планирование (9 инструментов) ​

Браузер / Зрение (5 инструментов) ​

Сеть (4 инструмента) ​

Обмен сообщениями (2 инструмента) ​

Сессии / Агенты (8 инструментов) ​

Удалённые устройства (2 инструмента) ​

Git (1 инструмент) ​

Конфигурация (2 инструмента) ​

Сторонняя интеграция (1 инструмент) ​

Рендеринг (2 инструмента) ​

Администрирование (1 инструмент) ​

Полная матрица инструментов ​

Включение и отключение инструментов ​

Инструменты с гейтами функций ​

Конвейер политик инструментов ​

Ограничения инструментов делегат-агентов ​

Интеграция инструментов MCP ​

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

Локальный mcp.json рабочего пространства ​

Динамическое обнаружение инструментов ​

Безопасность: песочница и ACL ​

Песочница инструментов ​

Санация окружения оболочки ​

ACL памяти ​

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

Расширение: написание пользовательских инструментов ​

Обзор инструментов

Архитектура инструментов

Реестр инструментов: `default_tools()` vs `all_tools()`

`default_tools()` — минимальное ядро (3 инструмента)

`all_tools()` — полный реестр (46+ инструментов)

Справочник по категориям

Основные (3 инструмента) — всегда доступны

Память (5 инструментов)

Cron / Планирование (9 инструментов)

Браузер / Зрение (5 инструментов)

Сеть (4 инструмента)

Обмен сообщениями (2 инструмента)

Сессии / Агенты (8 инструментов)

Удалённые устройства (2 инструмента)

Git (1 инструмент)

Конфигурация (2 инструмента)

Сторонняя интеграция (1 инструмент)

Рендеринг (2 инструмента)

Администрирование (1 инструмент)

Полная матрица инструментов

Включение и отключение инструментов

Инструменты с гейтами функций

Конвейер политик инструментов

Ограничения инструментов делегат-агентов

Интеграция инструментов MCP

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

Локальный `mcp.json` рабочего пространства

Динамическое обнаружение инструментов

Безопасность: песочница и ACL

Песочница инструментов

Санация окружения оболочки

ACL памяти

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

Расширение: написание пользовательских инструментов