← Создание агентов на Cloudflare / agents / concepts
Инструменты
Инструменты позволяют моделям получать информацию, обрабатывать данные и выполнять действия. Каждый инструмент определяет интерфейс, описывающий его входные данные, выходные данные и поведение.
Турагент может использовать инструменты для поиска рейсов, проверки цен на отели, обработки платежей и отправки писем с подтверждением. Интерфейс инструментов позволяет модели понимать, когда и как использовать каждую возможность.
Проектирование инструментов включает три независимых решения:
- Интерфейс модели : предоставляет инструменты как прямые вызовы инструментов или через Code Mode.
- Место выполнения : запускает реализации инструментов в Worker, браузере или другом Agent.
- Источник инструмента : определяйте инструменты в приложении или подключайтесь к внешним размещённым инструментам через Model Context Protocol (MCP).
Например, инструменты браузера можно предоставить напрямую или через Code Mode. Точно так же инструмент MCP можно предоставить через любой из этих двух интерфейсов модели.
Выберите интерфейс модели
Прямые вызовы инструментов и Code Mode определяют, как модель видит инструменты и вызывает их. Но они не определяют, где выполняются базовые реализации инструментов.
| Интерфейс | Как это работает | Когда использовать |
|---|---|---|
| Прямые вызовы инструментов | Модель получает отдельные определения инструментов. Каждый результат возвращается модели, прежде чем она выбирает следующий вызов. | Задача простая и использует небольшой, известный набор инструментов. |
| Code Mode | Модель получает один code-инструмент и пишет код на основе типизированных интерфейсов инструментов. | Задаче требуется композиция, зависимые вызовы, фильтрация, ветвление, повторяемая логика или обнаружение инструментов. |
Прямые вызовы инструментов
В большинстве примеров использования инструментов применяются прямые вызовы инструментов, даже если сам паттерн не называется явно. Вы определяете каждый инструмент и передаёте модели его схему. Модель выбирает инструмент, ваше приложение его выполняет, а результат возвращается модели.
Модель видит каждый промежуточный результат перед выбором следующего инструмента. Благодаря этому путь выполнения легко проверить. Однако зависимые операции требуют повторных ходов модели и расходуют контекст на промежуточные данные.
Code Mode
Code Mode даёт модели один инструмент для выполнения кода. Модель пишет JavaScript, который вызывает типизированные инструменты, передаёт результаты между ними и управляет потоком выполнения.
Сгенерированный код может фильтровать большие ответы и возвращать только то итоговое значение, которое нужно модели. Промежуточные результаты остаются внутри sandbox, а не попадают в контекст модели после каждой операции. Это делает Code Mode более эффективным для составных workflow и больших каталогов инструментов.
Code Mode также поддерживает постепенное обнаружение. Модель может искать доступные коннекторы и запрашивать подробные типы только для нужных ей методов. Успешные программы можно сохранять как переиспользуемые фрагменты кода.
Сведения о поведении во время выполнения, подтверждениях, воспроизведении и фрагментах см. в Как работает Code Mode.
Выберите, где выполняются инструменты
Место выполнения определяет, где выполняется реализация инструмента. Оно не зависит от интерфейса модели. Инструменты в каждом месте выполнения могут быть предоставлены напрямую или через Code Mode.
| Расположение | Когда использовать | Начните здесь |
|---|---|---|
| Worker | Инструмент вызывает API, выполняет SQL-запросы или использует биндинги и секретные ключи на стороне сервера. | Инструменты на стороне сервера |
| Браузер | Инструменту нужны геолокация, буфер обмена, локальное хранилище или другие API браузера. | Инструменты на стороне клиента |
| Другой Agent | Agent с поддержкой чата должен выполняться как удерживаемый потоковый инструмент. | Agents как инструменты |
При прямых вызовах инструментов модель вызывает инструмент, а фреймворк направляет выполнение в настроенное место.
В режиме Code Mode сгенерированный код выполняется в sandbox. Вызовы из этого кода пересекают границу sandbox и попадают в реализацию соответствующего инструмента. Серверные инструменты выполняются в хост-Worker, инструменты браузера выполняются на родительской странице, а инструменты агента могут делегировать работу другому агенту.
Подключение внешних инструментов через MCP
Model Context Protocol (MCP) ↗ стандартизирует то, как AI-приложения обнаруживают и вызывают внешне размещённые инструменты. MCP описывает источник и транспорт инструмента, а не то, как модель должна его вызывать.
Agent может предоставлять инструменты MCP через любой из следующих интерфейсов модели:
- Передайте инструменты MCP напрямую модели с помощью MCP-клиент Agents.
- Предоставлять инструменты MCP внутри Code Mode для композиции и постепенного обнаружения с помощью MCP-коннекторы.
MCP-сервер также может сам предоставлять Code Mode. Например, он может представить один code инструмент или отдельные search и execute инструменты. Об этих паттернах на стороне сервера см. Паттерны MCP-серверов Code Mode.
Управление побочными эффектами
Политика подтверждения также не зависит от места выполнения и источника инструмента. Любой инструмент, изменяющий внешнее состояние, может требовать подтверждения пользователя.
Прямые инструменты могут использовать стандартный паттерн подтверждения с участием человека.
Устойчивый runtime Code Mode может приостановить выполнение сгенерированного кода перед вызовом аннотированного метода коннектора. Подтверждение воспроизводит завершённые вызовы из журнала выполнения, применяет подтверждённое действие и продолжает выполнение той же программы.