﻿---
title: "Инструменты агента: контракты и ограничения"
description: Базовый набор инструментов агентного харнесса, внешние сервисы через MCP и API, и почему надёжность зависит от прав и ограничений, а не от количества функций.
---

## Что делает слой

Инструменты — функции, которые агент может вызвать: чтение файлов, запуск команд, поиск, работа с API, браузером, базой данных. Без них модель остаётся «говорящей головой»: она рассуждает, но ничего не проверяет и не меняет.

Разница между демо и production здесь видна сразу. Демо показывает, что агент умеет вызвать инструмент. Production определяется тем, **что именно** ему разрешено и **как** ограничен вызов.

## Харнесс и его базовый набор

Харнесс — среда вокруг модели, которая организует цикл работы, выдаёт инструменты и управляет контекстом и разрешениями. У разных харнессов набор называется по-разному, но роли совпадают.

| Операция | Для чего | Примеры в харнессах |
|---|---|---|
| **Read** | Читать код, документы, конфигурацию, в том числе по диапазону строк | Claude Code `Read`; OpenCode `read` |
| **Edit / apply patch** | Менять фрагменты, не перезаписывая файл целиком | Claude Code `Edit`; OpenCode `edit`, `apply_patch` |
| **Bash / exec** | Тесты, сборка, CLI, скрипты | Claude Code `Bash`; OpenCode `bash` |
| **Write** | Создавать файлы и результаты | Claude Code `Write`; OpenCode `write` |
| **Glob / list** | Находить файлы по имени и маске | OpenCode `glob` |
| **Grep** | Искать символы, ошибки, фрагменты текста | Claude Code `Grep`; OpenCode `grep` |
| **Web fetch** | Читать известную страницу по URL | Claude Code `WebFetch`; OpenCode `webfetch` |
| **Web search** | Находить актуальные источники и примеры | Claude Code `WebSearch`; OpenCode `websearch` |
| **Subagent / delegate** | Передать задачу агенту с отдельным контекстом | Claude Code `Agent` |
| **Ask user / approval** | Уточнить требование или остановить опасное действие | Claude Code `AskUserQuestion`; OpenCode `question` |

Список — по роли в работе, а не рейтинг популярности. Названия, доступность и права зависят от версии, платформы и конфигурации; сравнение конкретных ассистентов — в [Харнессы и код-ассистенты](https://wpcraft.ru/kb/ai/coding/harnesses.md).

## Внешние инструменты

Харнесс расширяется сервисами, которые дают специализированные возможности. «Внешний» не значит облачный: MCP-сервер может работать локально.

| Инструмент | Что добавляет |
|---|---|
| **Tavily** | Веб-поиск и извлечение контента для ИИ-приложений |
| **Exa** | Поиск веб-материалов и получение содержимого по URL |
| **Firecrawl** | Обход сайтов, скрейпинг, преобразование страниц в Markdown |
| **Playwright MCP** | Управление браузером: навигация и взаимодействие со страницей |
| **Browserbase / Stagehand** | Облачные браузерные сессии и автоматизация действий |
| **GitHub MCP Server** | Код, issues, pull requests, GitHub Actions |
| **SQLDatabaseToolkit** | Просмотр схемы, проверка и выполнение SQL-запросов |

Дальше — узкие функции поверх конкретной системы: `get_order_status`, `create_ticket`, `save_draft`. Это прикладные операции, а не универсальные названия.

Важно не путать **операцию и её реализацию**: `web_search` — то, что видит модель; Tavily или Exa могут быть её исполнителем. Браузер может быть встроен в харнесс или подключаться отдельно через Playwright. Не каждый харнесс поддерживает любой вариант без адаптера.

## Контракты важнее количества

Надёжность зависит не от числа инструментов, а от их ограничений:

- **Разрешённые каталоги и ресурсы.** Агент читает и пишет только там, где это ожидается.
- **Права.** Для аналитики SQL — доступ только на чтение; для GitHub — только нужные репозитории и операции.
- **Таймауты и лимиты вывода.** Один `find /` или гигантский лог съедают контекст и бюджет.
- **Подтверждение опасных действий.** Запись, публикация, отправка сообщений, изменение данных — отдельный контур.
- **Разделение чтения и записи.** Действия с внешними последствиями не должны быть доступны в том же режиме, что чтение.

Особый случай — **shell**. Ограничения файловых инструментов сами по себе не ограничивают команды терминала: если агенту разрешён `bash`, каталог «только для чтения» перестаёт быть ограничением. Это самая частая ошибка в настройке прав.

## Что проверить в проекте

- **Что агент может испортить.** Пройдите по списку инструментов и ответьте: какое худшее изменение возможно без подтверждения человека.
- **Не подменяет ли подтверждение вопрос.** Уточняющий вопрос пользователю не заменяет политику: авторизация — свойство среды, а не вежливость модели.
- **Логируются ли вызовы.** Без трассировки вызовов (см. [Наблюдаемость](https://wpcraft.ru/kb/ai/agents/observability.md)) инцидент не разобрать.
- **Сколько инструментов реально нужно.** Десяток узких функций с ясными контрактами работает лучше сотни универсальных.
- **Проверяются ли схемы вызовов.** Пересечение семантики и недоспецифицированные параметры ловит [tool-call eval](https://wpcraft.ru/kb/ai/evals/component-evals.md), а не чтение описаний.

## Материалы и источники

- [Системное мышление для агентного ИИ](https://wpcraft.ru/blog/systems-thinking-for-agentic-ai) — статья WPCraft, раздел «Tools»