Перейти к основному содержимому

Добавление инструментов

Прежде чем писать инструмент, спросите себя: не должен ли это быть навык?

Только встроенные основные инструменты

Эта страница предназначена для добавления встроенного инструмента VibeOS непосредственно в репозиторий. Если вам нужен личный, локальный для проекта или иной пользовательский инструмент без изменения ядра VibeOS, используйте вместо этого путь плагинов:

По умолчанию для большинства пользовательских инструментов используйте плагины. Следуйте этой странице только тогда, когда вы явно хотите добавить новый встроенный инструмент в tools/ и toolsets.py.

Сделайте это Навыком, когда возможность может быть выражена как инструкции + команды оболочки + существующие инструменты (поиск arXiv, рабочие процессы git, управление Docker, обработка PDF).

Сделайте это Инструментом, когда требуется сквозная интеграция с API-ключами, пользовательская логика обработки, работа с бинарными данными или потоковая передача (автоматизация браузера, TTS, анализ изображений).

Обзор​

Добавление инструмента затрагивает 2 файла:

  1. tools/your_tool.py — обработчик, схема, функция проверки, вызов registry.register()
  2. toolsets.py — добавьте имя инструмента в _VIBEOS_CORE_TOOLS (или в конкретный набор инструментов)

Любой файл tools/*.py с вызовом registry.register() на верхнем уровне автоматически обнаруживается при запуске — ручной список импорта не требуется.

Шаг 1: Создайте файл встроенного инструмента​

Каждый файл инструмента следует одной и той же структуре:

# tools/weather_tool.py
"""Инструмент погоды — получение текущей погоды для местоположения."""

import json
import os
import logging

logger = logging.getLogger(__name__)


# --- Проверка доступности ---

def check_weather_requirements() -> bool:
    """Возвращает True, если зависимости инструмента доступны."""
    return bool(os.getenv("WEATHER_API_KEY"))


# --- Обработчик ---

def weather_tool(location: str, units: str = "metric") -> str:
    """Получает погоду для местоположения. Возвращает строку JSON."""
    api_key = os.getenv("WEATHER_API_KEY")
    if not api_key:
        return json.dumps({"error": "WEATHER_API_KEY не настроен"})
    try:
        # ... вызов API погоды ...
        return json.dumps({"location": location, "temp": 22, "units": units})
    except Exception as e:
        return json.dumps({"error": str(e)})


# --- Схема ---

WEATHER_SCHEMA = {
    "name": "weather",
    "description": "Получить текущую погоду для местоположения.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Название города или координаты (например, 'London' или '51.5,-0.1')"
            },
            "units": {
                "type": "string",
                "enum": ["metric", "imperial"],
                "description": "Единицы измерения температуры (по умолчанию: metric)",
                "default": "metric"
            }
        },
        "required": ["location"]
    }
}


# --- Регистрация ---

from tools.registry import registry

registry.register(
    name="weather",
    toolset="weather",
    schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool(
        location=args.get("location", ""),
        units=args.get("units", "metric")),
    check_fn=check_weather_requirements,
    requires_env=["WEATHER_API_KEY"],
)

Ключевые правила​

Важно
  • Обработчики ОБЯЗАНЫ возвращать строку JSON (через json.dumps()), никогда не сырые словари
  • Ошибки ОБЯЗАНЫ возвращаться как {"error": "message"}, никогда не вызываться как исключения
  • check_fn вызывается при построении определений инструментов — если он возвращает False, инструмент молча исключается
  • handler получает (args: dict, **kwargs), где args — аргументы вызова инструмента от LLM

Шаг 2: Добавьте встроенный инструмент в набор инструментов​

В toolsets.py добавьте имя инструмента:

# Если он должен быть доступен на всех платформах (CLI + обмен сообщениями):
_VIBEOS_CORE_TOOLS = [
    ...
    "weather",  # <-- добавьте сюда
]

# Или создайте новый отдельный набор инструментов:
"weather": {
    "description": "Инструменты для поиска погоды",
    "tools": ["weather"],
    "includes": []
},

Шаг 3: Добавьте импорт для обнаружения (больше не требуется)​

Модули инструментов с вызовом registry.register() на верхнем уровне автоматически обнаруживаются функцией discover_builtin_tools() в tools/registry.py. Нет необходимости поддерживать ручной список импорта — просто создайте файл в tools/, и он будет подхвачен при запуске.

Асинхронные обработчики​

Если вашему обработчику нужен асинхронный код, отметьте его с помощью is_async=True:

async def weather_tool_async(location: str) -> str:
    async with aiohttp.ClientSession() as session:
        ...
    return json.dumps(result)

registry.register(
    name="weather",
    toolset="weather",
    schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool_async(args.get("location", "")),
    check_fn=check_weather_requirements,
    is_async=True,  # реестр автоматически вызывает _run_async()
)

Реестр прозрачно обрабатывает асинхронное bridging — вам никогда не нужно вызывать asyncio.run() самостоятельно.

Обработчики, которым нужен task_id​

Инструменты, управляющие состоянием сессии, получают task_id через **kwargs:

def _handle_weather(args, **kw):
    task_id = kw.get("task_id")
    return weather_tool(args.get("location", ""), task_id=task_id)

registry.register(
    name="weather",
    ...
    handler=_handle_weather,
)

Инструменты, перехватываемые циклом агента​

Некоторые инструменты (todo, memory, session_search, delegate_task) требуют доступа к состоянию агента сессии. Они перехватываются run_agent.py до того, как достигают реестра. Реестр всё ещё хранит их схемы, но dispatch() возвращает резервную ошибку, если перехват обойдён.

Опционально: Интеграция с мастером настройки​

Если ваш инструмент требует API-ключ, добавьте его в vibeos_cli/config.py:

OPTIONAL_ENV_VARS = {
    ...
    "WEATHER_API_KEY": {
        "description": "API-ключ погоды для поиска погоды",
        "prompt": "API-ключ погоды",
        "url": "https://weatherapi.com/",
        "tools": ["weather"],
        "password": True,
    },
}

Контрольный список​

  • Создан файл инструмента с обработчиком, схемой, функцией проверки и регистрацией
  • Добавлен в соответствующий набор инструментов в toolsets.py
  • Подтверждено, что это действительно должен быть встроенный/основной инструмент, а не плагин
  • Обработчик возвращает строки JSON, ошибки возвращаются как {"error": "..."}
  • Опционально: API-ключ добавлен в OPTIONAL_ENV_VARS в vibeos_cli/config.py
  • Опционально: Добавлен в toolset_distributions.py для пакетной обработки
  • Протестировано с помощью vibeos chat -q "Use the weather tool for London"