5. Инструменты — вычисления и действия

🔵 Движки, которые что-то исполняют: скрипты, shell-команды, субагенты, воркфлоу, а также доставка результата (email, файлы). Сводную таблицу всех движков см. в «Справочник инструментов».

5.10 script_tool

Скрипт Rhai или JavaScript.

kind: script_tool
name: currency
description: Конвертация валют.
script: currency.rhai          # .rhai → Rhai, .js → JavaScript (QuickJS)
parameters: { ... }
max_operations: 10000000

Скрипт определяет fn run(args) (Rhai) или function run(args) (JS). Полный справочник — 07-scripts.

5.14 subagent_tool

Делегировать задачу субагенту. Спавнит дочерний агент-процесс, отдаёт задачу, ждёт завершения и возвращает его итоговый ответ. Траты дочернего списываются на сессию родителя (наследует группу бюджета), после — очистка.

kind: subagent_tool
name: delegate_research
description: Делегировать исследование субагенту.
template: trace-agent          # или inline instructions + tools:
# instructions: "You are a research assistant."
# tools: [http_fetch, fs_read]
# budget: { max_per_turn: 2000, max_per_minute: 20000, max_total: 20000 }

Рантайм-аргументы: task (обязателен), опциональные template/instructions.

5.16 email_tool

Отправить письмо (SMTP).

kind: email_tool
name: send_report
description: Отправить отчёт оператору.
smtp:
  host: smtp.example.com
  username: agent@example.com
  password_env: SMTP_PASSWORD     # или password: "..."
  from: agent@example.com
  tls: starttls                   # starttls (по умолч., 587) | ssl (465) | none (25)
  port: 587
to: ops@example.com
subject: "Agent report"

Аргументы: body (обязателен), опциональные to / subject.

5.17 vk_tool

Вызов VK API от имени сообщества (group access token) — универсальный шлюз плюс удобные действия для типовых бизнес-задач.

kind: vk_tool
name: vk_api
description: Вызвать VK API от имени сообщества.
token_env: VK_GROUP_TOKEN       # env с group access token (по умолч. VK_GROUP_TOKEN)
service_token_env: VK_SERVICE_TOKEN  # env с сервисным ключом (по умолч. VK_SERVICE_TOKEN)
api_version: "5.199"            # версия API (по умолч. "5.199")
owner_id: -123456789            # дефолтный владелец (для wall_post)

Два режима вызова. Generic-шлюз — любой метод VK API:

{ "method": "wall.get", "params": { "owner_id": -123456789, "count": 5 } }

Удобные действия (внутри движок сам подставляет обязательный random_id и параметры по умолчанию):

{ "action": "wall_post", "message": "Новый пост от агента" }
{ "action": "send_message", "peer_id": 123, "message": "Привет" }
{ "action": "search", "q": "бренд", "count": 10 }

Результат: content — pretty-JSON ответа, data — распарсенный response (для композиции с visualize_tool). Групповой токен нужен с правами messages, wall, photos, docs, market, groups. Читающие/поисковые методы (newsfeed.search, wall.get, groups.search) недоступны групповым токенам — для них нужен сервисный ключ (service_token_env).

5.18 shell_tool

Запустить команду CLI. Универсальный запуск внешней программы: команда, флаги, рабочая папка и окружение фиксируются в YAML автором агента; LLM лишь подставляет значения в input. В отличие от произвольного fs_read, LLM не выбирает команду — он выбирает только аргументы по заданной JSON Schema.

kind: shell_tool
name: git_log
description: Показать последние коммиты репозитория.
command: git
args: ["log", "--oneline", "-n", "{{ input.limit | default(10) }}"]
cwd: /srv/agent-os          # рабочая папка (по умолч. — папка сервера)
env:
  GIT_PAGER: "cat"          # доп. переменные окружения
stdin: "{{ input.text }}"   # текст в stdin (опционально)
timeout_secs: 30            # жёсткий таймаут (по умолч. 30)
capture: both               # stdout | stderr | both (по умолч.)
parse_json: false           # распарсить stdout как JSON в data.parsed
parameters: { ... }         # JSON Schema входа агента

Команда наследует окружение сервера + env, выполняется с лимитом по времени. Результат: content — захваченный вывод, success — нулевой код выхода, data — { exit_code, stdout, stderr, parsed? }.

Все строковые поля — шаблоны MiniJinja над input. Если на сервере задан logging.temp_dir, в шаблонах доступна переменная {{ temp_dir }} — scratch- каталог текущей сессии, куда можно нагенерировать файл (см. file_tool с источником temp).

5.19 workflow_tool

Запустить воркфлоу.

kind: workflow_tool
name: run_triage
description: Запустить воркфлоу триажа.
workflow: triage            # имя воркфлоу по умолчанию

Запускает воркфлоу и возвращает его run id. Имя воркфлоу можно перекрыть аргументом workflow; input — входной payload. Требует, чтобы в ядре был подключён WorkflowService (делается при старте сервера). См. 12-workflows.

5.20 file_tool

Отправить файл пользователю. Отправляет пользователю файл (отчёт, документ, экспорт данных) в виде скачиваемого блока file. Агент обычно не имеет доступа к файловой системе, поэтому содержимое берётся из одного из источников:

kind: file_tool
name: send_file
description: Отправить файл пользователю.
max_bytes: 10485760   # макс. размер файла в байтах (по умолч. 10 МиБ)

Источник выбирается по приоритету content → data → path → temp → state → source. Пример отчёта, собранного из результата предыдущего инструмента:

# вызвать: send_file { "name": "report.csv", "source": { "tool": "build_report" } }

LLM видит только компактную сводку в content; сами байты (base64) едут в visual и доходят до веб-виджета (ссылка скачивания), Android и Telegram (документ).

Временное хранилище (scratch) сессии

Если в конфигурации задан logging.temp_dir, ядро выделяет каждой сессии scratch-каталог <temp_dir>/<session_id>/. Инструмент-генератор (например, shell_tool, запускающий офисный CLI) пишет файл туда через {{ temp_dir }}, а file_tool забирает его по имени:

# shell_tool: нагенерить .xlsx в scratch сессии
kind: shell_tool
name: export_xlsx
description: Сгенерировать отчёт в Excel.
command: libreoffice
args: ["--headless", "--convert-to", "xlsx", "--outdir", "{{ temp_dir }}", "{{ input.docx }}"]

# вызвать: send_file { "name": "report.xlsx", "temp": { "name": "report.xlsx" } }

Каталог удаляется при закрытии/истечении сессии.