Агентный цикл

Как execute() вызывает модель, исполняет код и работает с инструментами.

execute() запускает агентный цикл. Модель читает инструкции и историю диалога, вызывает доступные инструменты и формирует результат.

src/conversations/index.ts

import { Conversation } from '@holocronlab/botruntime-runtime'

export default new Conversation({
  channel: '*',
  handler: async ({ execute }) => {
    await execute({
      instructions: 'Помогай пользователю проверить статус заказа.',
    })
  },
})

В обработчике диалога цикл сам отправляет обычный текстовый ответ. Не вызывайте conversation.send() после execute() для того же ответа.

Параметры

await execute({
  instructions,
  tools,
  knowledge,
  hooks,
  objects,
  exits,
  model,
  temperature,
  reasoningEffort,
  iterations,
  signal,
})

Обязателен только instructions. Историю сообщений добавлять в это поле не нужно: диалог передаёт её автоматически.

Chat и worker

Режим	Где используется	Результат
`chat`	`Conversation`	Цикл видит транскрипт и отвечает пользователю.
`worker`	`Workflow`	Цикл возвращает данные и не пишет в чат.

Рантайм выбирает режим по месту вызова. В большинстве проектов поле mode указывать не требуется.

Инструменты

Инструмент — типизированная функция с zod-схемами. Модель выбирает функцию и аргументы, а ваш код выполняет операцию.

const result = await execute({
  instructions: 'Отвечай только по данным каталога.',
  tools: [findProduct, checkAvailability],
  iterations: 8,
})

Действия и воркфлоу подключаются через .asTool(). Подробные примеры находятся на странице «Инструменты».

Бюджет итераций

По умолчанию цикл ограничен десятью итерациями. Допустимый диапазон — от 1 до 100. Если лимит исчерпан, execute() завершится с LoopExceededError.

Не увеличивайте лимит до проверки инструментов и инструкций. Частая причина зацикливания — инструмент, который возвращает пустой результат без объяснения.

Модель

Модель по умолчанию задаётся в agent.config.ts через defaultModels. Конкретный вызов может переопределить её полем model.

reasoningEffort принимает none, low, medium, high или dynamic. Поддержка зависит от выбранной модели. Значение temperature по умолчанию — 0.7.

Ключи модельного провайдера хранятся на платформе. Бот обращается к модели через LLM-шлюз и не содержит provider credentials.

Управление циклом

Autonomous.ThinkSignal останавливает текущий вызов инструмента и возвращает модели инструкцию. Хуки позволяют проверять входы, выходы и каждую итерацию.

throw new Autonomous.ThinkSignal(
  'Требуется подтверждение',
  'Попроси пользователя подтвердить действие перед повторным вызовом.',
)

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

Результат

execute() возвращает ExecuteResult с причиной завершения, числом итераций и типизированным выходом, если вы передали exits.

Обрабатывайте отмену через AbortSignal, превышение лимита и ошибки инструментов. Логируйте техническую причину без содержимого сообщений и секретов.