Перейти к содержанию

Инструменты

Это подпрограммы, которые ИИ-модель может вызывать для выполнения действий в окружении пользователя.

Они расширяют возможности языковой модели, позволяя ей взаимодействовать с файловой системой, терминалом, API и другими сервисами.

Аналогия

Для простоты понимания, можно сравнить агента с человеком: если ИИ-модель это его мозг, который ищет решение, то инструменты — руки, которые это решение применяют.

Устройство инструментоа

Любой инструмент есть программная функция с чётко определённой сигнатурой, которую модель может вызвать по имени.

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

  • Уникальное имя — идентификатор для вызова
  • Описание — текст, объясняющий назначение инструмента
  • Параметры — аргументы с типами и описаниями (в формате JSON Schema)
  • Реализацию — код, выполняющий действие при вызове

Ключевая идея

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

Как работают инструменты

Процесс вызова инструмента состоит из нескольких этапов:

Информация об инструментах передаётся модели в системном промпте.

Модель «видит» только описание инструмента, но не его реализацию.

{
  "name": "read_file",
  "description": "Читает содержимое файла",
  "parameters": {
    "type": "object",
    "properties": {
      "filepath": {
        "type": "string",
        "description": "Путь к файлу"
      }
    },
    "required": ["filepath"]
  }
}

Модель анализирует запрос пользователя и решает, какой инструмент вызвать.

Если инструмент нужен, модель генерирует вызов с параметрами.

{
  "tool_call": {
    "name": "read_file",
    "arguments": {
      "filepath": "src/main.py"
    }
  }
}

Система перехватывает вызов и выполняет код инструмента.

Результат возвращается модели для продолжения диалога.

{
  "tool_result": "def main():\n    print('Hello')"
}

Модель использует результат инструмента для формирования финального ответа.

Пользователь видит осмысленный ответ, основанный на полученных данных.

Типы инструментов

Инструменты можно классифицировать по назначению:

  • Чтение

    Получение данных из файлов, баз данных, API

  • Запись

    Создание и редактирование файлов, запись в БД

  • Выполнение

    Запуск команд в терминале, скриптов, процессов

  • HTTP-запросы

    Взаимодействие с внешними API и сервисами

  • Поиск

    Поиск по коду, документации, базам знаний

  • Планирование

    Создание задач, напоминаний, расписаний

Расширение через MCP

Koda поддерживает протокол MCP (Model Context Protocol) для подключения внешних инструментов.

Это позволяет добавлять инструменты для работы с базами данных, облачными сервисами и другими ресурсами.

См. также: MCP-серверы

Инструменты vs Контекст-провайдеры

Эти концепции часто путают, но они решают разные задачи:

Характеристика Инструменты Контекст-провайдеры
Назначение Выполнение действий Добавление данных в контекст
Инициатор ИИ-модель (автоматически) Пользователь (вручную)
Результат Изменение состояния Информация для модели
Пример Создать файл, запустить тест @files, @codebase

Взаимодополняемость

Инструменты и контекст-провайдеры работают вместе.

Провайдеры дают модели информацию для принятия решений.

Инструменты позволяют модели действовать на основе этих решений.

Практический сценарий работы

Часто агент действует примерно так:

  1. читает несколько файлов и ищет нужные места;
  2. предлагает план или сразу начинает локальные изменения;
  3. показывает вам изменения там, где это требуется;
  4. при необходимости просит разрешение на следующий шаг или сразу его выполняет (в зависимости от выставленных разрешений).

Примеры использования

Пример 1: Чтение файла

  • Пользователь: Покажи содержимое main.py
  • Модель: [вызывает read_file("main.py")]
  • Система: 
    def main():
    print("Hello")
  • Модель: Вот содержимое файла main.py: 
    def main():
    print("Hello, World!")

Пример 2: Редактирование кода

  • Пользователь: Добавь обработку ошибок в функцию read_file
  • Модель: [вызывает edit_file с заменой кода]
  • Система: Файл успешно изменён

  • Модель: Я добавил блок try-except для обработки ошибок. Вот что изменилось:

    - content = open(filepath).read()
+ try:
+     with open(filepath, 'r') as f:
+         content = f.read()
+ except FileNotFoundError:
+     return None

Пример 3: Запуск тестов

  • Пользователь: Запусти тесты и покажи результат
  • Модель: [вызывает run_terminal_command("pytest")]
  • Система: ====== 42 passed in 1.23s ======
  • Модель: Все 42 теста успешно пройдены за 1.23 секунды.

См. также