# Что такое инструменты (Tools) в AI-агентах

> [HTML-версия](https://learnvibecoding.ru/publiclessons/chto-takoe-instrumenty-tools-v-ai-agentakh) · [Индекс для LLM](https://learnvibecoding.ru/llms.txt) · [Политика использования материалов](https://learnvibecoding.ru/politika-materialov)
> Материалы защищены. Обучение LLM без согласия запрещено. При разрешённом использовании — обязательна прямая ссылка на страницу-источник.
> Использование инструментов (Tools) в агентах

**Курс:** Создание своего агента

Одна из ключевых особенностей AI-агентов — это **способность совершать действия**.

Как мы уже видели, это происходит через использование **инструментов (Tools)**.

В этом разделе мы разберём:

- что такое инструменты,
- как их проектировать,
- и как подключать их к агенту через **System Message**.

Если снабдить агента правильными инструментами и точно описать, как они работают,

его возможности можно увеличить **в разы**.

---

## Что такое AI Tools

**Инструмент (Tool)** — это функция, которую мы “даём” LLM, чтобы она могла выполнять конкретное действие.

Вот несколько распространённых примеров инструментов:

| Инструмент | Описание |
| --- | --- |
| **Web Search** | Позволяет агенту получать актуальные данные из интернета. |
| **Image Generation** | Создаёт изображения по текстовому описанию. |
| **Retrieval** | Извлекает информацию из внешнего источника или базы данных. |
| **API Interface** | Позволяет взаимодействовать с внешними API (например, GitHub, YouTube, Spotify). |
| **File Search** | поиск файлов  |
| **Code interpreter** | анализ данных/вычисления |
| **MCP/коннекторы** | доступ к внешним сервисам |

Разумеется, это только примеры — инструмент можно создать **для любой задачи**.

---

## Каким должен быть хороший инструмент

Хороший инструмент **дополняет** возможности модели, а не дублирует их.

Например, если вам нужно посчитать, лучше дать модели **калькулятор**, чем полагаться на её внутреннюю “математику” — LLM может ошибаться при арифметике.

Кроме того, модели знают только то, что было **до их обучения**.

Если нужно актуализировать данные (например, узнать погоду сегодня), без инструмента для поиска в интернете модель **придумает ответ** — так называемая *галлюцинация*.

## Что должен содержать инструмент

Каждый инструмент описывается четырьмя элементами:

1. **Описание (Description)** — что делает функция.
2. **Callable** — действие, которое выполняется (сама функция).
3. **Аргументы (Arguments)** — входные данные и их типы.
4. *(Необязательно)* **Выходные данные (Outputs)** — тип результата.

---

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

LLM могут принимать только текст и выдавать текст.

Они **не умеют сами вызывать функции**.

Поэтому, когда мы “даем” агенту инструменты,

мы на самом деле **учим модель**, что такие инструменты существуют, и просим её **генерировать текстовые вызовы** этих инструментов.

Например:

если у нас есть инструмент `weather_tool`, который получает погоду из интернета, и пользователь спрашивает:

> “Какая погода в Париже?”
> 

модель сгенерирует не ответ, а текст:

> call weather_tool("Paris")
> 

После этого **агент** (внешняя программа) увидит этот вызов, запустит нужный инструмент, получит реальные данные и добавит результат обратно в контекст разговора.

Для пользователя всё выглядит так, будто **модель сама знает погоду**, но на деле запрос обрабатывает агент “за кулисами”.

---

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

Для этого используется **system prompt** — в нём мы текстом описываем, какие инструменты доступны и как они устроены.

Чтобы модель понимала, важно:

- чётко указать, **что делает инструмент**,
- и какие **точно входные данные** он принимает.

Поэтому описания инструментов часто оформляют в **структурированном виде** — например, в виде JSON или кода.

### 🔢 Пример

Допустим, у нас есть простой калькулятор, который перемножает два числа:

```python
def calculator(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b

```

Тогда его описание для модели будет выглядеть так:

```
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int

```

Теперь LLM “знает”, что есть инструмент `calculator`,

какие аргументы ему нужны и какой результат он возвращает.

---

## Автоматизация описания инструментов

Так как инструменты обычно пишутся на Python, вся нужная информация уже есть в коде:

- имя функции,
- docstring-описание,
- аргументы и их типы,
- тип возвращаемого значения.

Значит, описание можно **генерировать автоматически**.

Для этого создаётся класс `Tool` и специальный **декоратор** `@tool`, который сам извлекает данные из функции и формирует текст для LLM.

---

### Пример класса `Tool`

```python
class Tool:
    def __init__(self, name, description, func, arguments, outputs):
        self.name = name
        self.description = description
        self.func = func
        self.arguments = arguments
        self.outputs = outputs

    def to_string(self):
        args_str = ", ".join([
            f"{arg_name}: {arg_type}" for arg_name, arg_type in self.arguments
        ])
        return (
            f"Tool Name: {self.name}, "
            f"Description: {self.description}, "
            f"Arguments: {args_str}, "
            f"Outputs: {self.outputs}"
        )

    def __call__(self, *args, **kwargs):
        return self.func(*args, **kwargs)

```

После этого можно создать инструмент:

```python
calculator_tool = Tool(
    "calculator",
    "Multiply two integers.",
    calculator,
    [("a", "int"), ("b", "int")],
    "int",
)

```

А затем просто вызвать:

```python
print(calculator_tool.to_string())

```

Результат:

```
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int

```

---

## Зачем это нужно

Когда модель получает описание инструмента через **system message** она знает, какие функции ей доступны и как их использовать.

Дальше агент может “заставить” модель решать задачи, требующие реальных действий — например, вызывать API, обрабатывать файлы, искать данные.

Всё это делается **в одном диалоге** с пользователем.

---

## Model Context Protocol (MCP): единый стандарт

**Model Context Protocol (MCP)** — это открытый протокол, который стандартизирует взаимодействие между LLM и внешними инструментами без необходимости делать самостоятельно API интеграцию.

MCP предоставляет:

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

Любой фреймворк, поддерживающий MCP, может использовать инструменты из этого протокола без необходимости реализовывать интерфейс заново.

## Пример работы Model Context Protocol (MCP)

Чтобы понять, как **MCP** помогает агентам использовать инструменты, рассмотрим конкретную ситуацию.

### Пример: агент с подключением к погодному API через MCP

Допустим, мы хотим, чтобы наш AI-агент мог отвечать на вопрос:

> «Какая погода в Париже сегодня?»
> 

Без инструмента LLM, скорее всего, **придумает ответ**,

так как её знания ограничены датой обучения.

Но с MCP агент может использовать внешний сервис — например, `OpenWeather API`.

---

### Как это выглядит на практике

1. **Регистрируем инструмент в протоколе MCP:**

```json
{
  "tool_name": "get_weather",
  "description": "Получает текущую погоду по названию города",
  "args": {
    "city": "string"
  },
  "returns": {
    "temperature": "float",
    "condition": "string"
  },
  "endpoint": "https://api.openweathermap.org/data/2.5/weather"
}

```

Этот JSON описывает инструмент в стандартизированном формате MCP.

Теперь любой агент, поддерживающий MCP, сможет “подключить” этот инструмент, даже если он работает на другой платформе или с другой моделью (GPT-4, Gemini, Mistral и т. д.).

---

1. **Передаём описание в системное сообщение LLM:**

```python
system_message = {
  "role": "system",
  "content": """
You have access to the following tool:
Tool Name: get_weather
Description: Получает текущую погоду по названию города.
Arguments: city (string)
Outputs: temperature (float), condition (string)
"""
}

```

---

1. **Модель делает вызов через MCP:**

Пользователь:

> «Какая погода в Париже?»
> 

Модель генерирует текстовый вызов:

```
call get_weather(city="Paris")

```

---

1. **Агент выполняет вызов и возвращает результат:**

```json
{
  "temperature": 21.4,
  "condition": "Clear sky"
}

```

1. **Модель формирует ответ пользователю:**

> «В Париже сейчас 21 °C и ясно ☀️.»
> 

---

### Почему это важно

- MCP **отделяет** логику модели (LLM) от реализации инструментов.
    
    Это значит, что если завтра вы решите перейти с GPT-4 на Gemini,
    
    вам не нужно переписывать весь код — MCP гарантирует совместимость.
    
- MCP делает возможным **единый каталог инструментов** для всех агентов в компании.
    
    Например, CRM-инструменты, базы знаний, аналитические сервисы и т.д.
    
    Всё это может быть зарегистрировано в одном протоколе и доступно любой LLM.
    

---

### Пример из корпоративного контекста

В компании можно создать MCP-каталог инструментов:

- `search_contracts` — поиск по договорам,
- `get_invoice` — выгрузка счёта из CRM,
- `update_status` — изменение задачи в Jira.

Тогда любой корпоративный AI-агент сможет взаимодействовать с бизнес-системами через общий, безопасный протокол,без необходимости вручную описывать каждую интеграцию.

---

## Краткое резюме

- **Что такое Tools:** функции, которые дают LLM новые способности — например, считать, искать или вызывать API.
- **Как их описывать:** имя, назначение, входные и выходные данные, callable.
- **Зачем они нужны:** чтобы расширить возможности модели, подключить её к реальному миру и устранить ограничения статического обучения.

> Инструменты превращают LLM из “говорящего текста” в действующего агента.
> 
> 
> Именно через Tools модель начинает **влиять на окружающий мир**.
>.........

[Все уроки](https://learnvibecoding.ru/publiclessons.md) · HTML: https://learnvibecoding.ru/publiclessons