Как агент решает, какой инструмент вызвать?

Question

Никита Вихров · Answer

# Как агент решает, какой инструмент вызвать

Агент не выбирает инструмент по коду — он выбирает по описанию. Модель читает `description` каждого инструмента и на основе задачи решает, что вызвать. Это значит: плохое описание — плохой выбор.

---

**Как модель видит инструменты**

При каждом запросе модели передаётся список инструментов в виде JSON-схем:

```python
tools = [
    {
        "name": "search_codebase",
        "description": "Ищет файлы и код в проекте по ключевому слову или регулярному выражению",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Строка поиска или regex-паттерн"
                },
                "file_extension": {
                    "type": "string",
                    "description": "Фильтр по расширению файла, например '.py' или '.ts'"
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "read_file",
        "description": "Читает полное содержимое файла по пути",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Абсолютный или относительный путь к файлу"
                }
            },
            "required": ["path"]
        }
    },
    {
        "name": "run_tests",
        "description": "Запускает тесты и возвращает результат. Используй только после изменения кода.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Путь к тест-файлу или директории. Если не указан — запускает все тесты."
                }
            }
        }
    }
]
```

Модель получает этот список и задачу — например, «найди все места где используется функция parseUser». Она рассуждает: нужен поиск по кодовой базе → вызывает `search_codebase`.

---

**Почему описание важнее кода**

Вот два варианта описания одного инструмента:

```python
# Плохо
{"name": "db_query", "description": "Делает запрос к базе данных"}

# Хорошо
{"name": "db_query", "description": """Выполняет SQL-запрос к PostgreSQL базе данных.
Используй для получения данных, проверки структуры таблиц, подсчёта записей.
Не используй для INSERT, UPDATE, DELETE — только SELECT."""}
```

С плохим описанием модель может вызвать инструмент не к месту или не вызвать там, где нужно. С хорошим — понимает контекст и ограничения.

---

**Что делать когда агент выбирает не тот инструмент**

Сначала смотри на описания. Чаще всего проблема там.

Если два инструмента похожи — явно укажи разницу в описании:

```python
{
    "name": "search_files",
    "description": "Ищет файлы по имени. Используй когда знаешь имя файла или его часть. НЕ ищет внутри содержимого файлов."
},
{
    "name": "search_content",
    "description": "Ищет текст внутри файлов. Используй когда нужно найти строку кода, функцию или паттерн. НЕ ищет по именам файлов."
}
```

Если это не помогает — добавь в system prompt явное правило: «Для поиска по содержимому файлов всегда используй search_content, не search_files».

Ещё один приём — уменьшить количество инструментов. Чем их больше, тем сложнее модели выбрать правильный. Если инструмент используется редко — убери его из дефолтного набора.

Как агент решает, какой инструмент вызвать?

Ответы

Как агент решает, какой инструмент вызвать

Каталог