← Создание агентов на Cloudflare / agents / harnesses / think

Мессенджеры

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

Установите пакет Think и адаптер провайдера, который вы используете:

npm install @cloudflare/think agents ai @chat-adapter/telegram

Адаптеры провайдеров экспортируются из подпутей для конкретных провайдеров, поэтому неиспользуемые адаптеры не попадают в сборку вашего Worker.

import { Think } from "@cloudflare/think";
import {
	defineMessengers,
	ThinkMessengerStateAgent,
} from "@cloudflare/think/messengers";
import telegramMessenger from "@cloudflare/think/messengers/telegram";

export { ThinkMessengerStateAgent };

export class SupportAgent extends Think {
	getMessengers() {
		return defineMessengers({
			telegram: telegramMessenger({
				token: this.env.TELEGRAM_BOT_TOKEN,
				userName: "support_bot",
				secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
			}),
		});
	}
}

import { Think } from "@cloudflare/think";
import {
	defineMessengers,
	ThinkMessengerStateAgent,
} from "@cloudflare/think/messengers";
import telegramMessenger from "@cloudflare/think/messengers/telegram";

export { ThinkMessengerStateAgent };

export class SupportAgent extends Think<Env> {
	getMessengers() {
		return defineMessengers({
			telegram: telegramMessenger({
				token: this.env.TELEGRAM_BOT_TOKEN,
				userName: "support_bot",
				secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
			}),
		});
	}
}

С значением по умолчанию telegram ключ, зарегистрируйте вебхук Telegram по адресу:

https://<your-worker>/messengers/telegram/webhook

telegramMessenger() требует secretToken в режиме вебхука, если вы не передадите собственный verifyWebhook функцию или явно откажитесь от неё с помощью verifyWebhook: false.

Если один агент Think управляет несколькими ботами Telegram, дайте каждому провайдеру собственное имя адаптера Chat SDK:

defineMessengers({
	support: telegramMessenger({
		adapterName: "support-telegram",
		token: this.env.SUPPORT_TELEGRAM_BOT_TOKEN,
		userName: "support_bot",
		secretToken: this.env.SUPPORT_TELEGRAM_WEBHOOK_SECRET_TOKEN,
	}),
	sales: telegramMessenger({
		adapterName: "sales-telegram",
		token: this.env.SALES_TELEGRAM_BOT_TOKEN,
		userName: "sales_bot",
		secretToken: this.env.SALES_TELEGRAM_WEBHOOK_SECRET_TOKEN,
	}),
});

defineMessengers({
	support: telegramMessenger({
		adapterName: "support-telegram",
		token: this.env.SUPPORT_TELEGRAM_BOT_TOKEN,
		userName: "support_bot",
		secretToken: this.env.SUPPORT_TELEGRAM_WEBHOOK_SECRET_TOKEN,
	}),
	sales: telegramMessenger({
		adapterName: "sales-telegram",
		token: this.env.SALES_TELEGRAM_BOT_TOKEN,
		userName: "sales_bot",
		secretToken: this.env.SALES_TELEGRAM_WEBHOOK_SECRET_TOKEN,
	}),
});

Дублирующиеся имена адаптеров вызывают сбой при запуске, поэтому провайдеры не могут перезаписать друг друга в общем рантайме Chat SDK.

Корневой агент Think обрабатывает маршруты вебхуков мессенджера после маршрутизации фреймворковых дочерних агентов и внутренних маршрутов Think, но перед пользовательскими onRequest резервный вариант. Маршруты Messenger доступны только на корневом уровне. Определение getMessengers() у класса суб-агента не создаёт маршруты вебхуков для этого суб-агента.

По умолчанию Think отвечает на прямые сообщения и упоминания. Новые упоминания подписывают тред Chat SDK, поэтому последующие упоминания в том же треде по-прежнему отслеживаются, но обычные сообщения из подписанного треда и действия кнопок игнорируются, если вы явно это не включите:

telegramMessenger({
	token: this.env.TELEGRAM_BOT_TOKEN,
	userName: "support_bot",
	secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
	respondTo: ["direct-message", "mention", "subscribed-thread", "action"],
});

telegramMessenger({
	token: this.env.TELEGRAM_BOT_TOKEN,
	userName: "support_bot",
	secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
	respondTo: ["direct-message", "mention", "subscribed-thread", "action"],
});

События Action преобразуются в пользовательские сообщения Think с ID действия, значением, ID исходного сообщения и инициировавшим пользователем. Используйте getMessengerContext()?.action внутри хуков или инструментов, когда вам нужны специфичные для провайдера детали действия. Действия являются опциональными (opt-in), поэтому интерактивные карточки не запускают ходы модели по ошибке.

Режим разговора по умолчанию: один дочерний агент Think на каждый поток Chat SDK. Это исключает случайное совместное использование памяти между групповыми чатами, личными сообщениями и каналами.

Используйте корневого агента как разговор, если весь трафик мессенджеров должен использовать одну сессию Think:

telegramMessenger({
	token: this.env.TELEGRAM_BOT_TOKEN,
	userName: "support_bot",
	secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
	conversation: "self",
});

telegramMessenger({
	token: this.env.TELEGRAM_BOT_TOKEN,
	userName: "support_bot",
	secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
	conversation: "self",
});

Используйте резолвер, если маршрутизация зависит от тенанта, канала, треда или пользователя:

telegramMessenger({
	token: this.env.TELEGRAM_BOT_TOKEN,
	userName: "support_bot",
	secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
	conversation(event) {
		return {
			target: "subagent",
			name: `tenant:${event.thread.channelId ?? event.thread.id}`,
		};
	},
});

telegramMessenger({
	token: this.env.TELEGRAM_BOT_TOKEN,
	userName: "support_bot",
	secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
	conversation(event) {
		return {
			target: "subagent",
			name: `tenant:${event.thread.channelId ?? event.thread.id}`,
		};
	},
});

Состояние мессенджера опирается на agents/chat-sdk. Экспортируйте ThinkMessengerStateAgent из модуля Worker, чтобы маршрутизация к дочерним агентам могла его найти. Для этого класса состояния, предназначенного только для граней, продакшен-приложениям не нужны отдельная привязка или миграция Durable Object. Тестовым каркасам могут по-прежнему требоваться явные привязки.

Think отвечает потоковым chat() путь. Корневой агент запускает идемпотентный managed fiber, определяет цель разговора, вызывает target.chat(message, callback), и позволяет политике доставки поставщика публиковать или редактировать видимые сообщения.

Снимки восстановления хранят только сериализуемые данные событий и треда Chat SDK. Если перезапуск происходит до начала потоковой передачи, Think может воспроизвести ответ заново. Если перезапуск происходит после начала потоковой передачи, Think вместо риска дублирования частичного ответа отправляет настроенное сообщение о прерывании.

Ошибки доставки по умолчанию используют универсальное сообщение для пользователя, чтобы сведения о внутреннем исключении не попадали во внешние чаты. Переопределите delivery.errorResponseText когда нужно собственное безопасное сообщение.

Во время хода мессенджера, getMessengerContext() возвращает provider, thread, author, message, capabilities и метаданные вложений для инициирующего события. Используйте его в prompts, tools или hooks, которым нужно поведение, специфичное для канала.

const messenger = this.getMessengerContext();
if (messenger?.thread.isDirectMessage === false) {
	// Adjust behavior for group chats.
}

const messenger = this.getMessengerContext();
if (messenger?.thread.isDirectMessage === false) {
	// Adjust behavior for group chats.
}

Используйте chatSdkMessenger() для провайдеров, для которых ещё нет вспомогательной функции Think:

chatSdkMessenger({
	adapter,
	provider: "custom",
	userName: "custom_bot",
	verifyWebhook(request) {
		return request.headers.get("x-custom-signature") === expectedSignature;
	},
});

chatSdkMessenger({
	adapter,
	provider: "custom",
	userName: "custom_bot",
	verifyWebhook(request) {
		return request.headers.get("x-custom-signature") === expectedSignature;
	},
});

Каждый пользовательский мессенджер должен предоставлять verifyWebhook или явно использовать verifyWebhook: false.

examples/think-chat-sdk пример демонстрирует нативный для Think getMessengers() путь с небольшим дашбордом Vite, который отслеживает корневой разговор Think через Agent WebSocket.

examples/chat-sdk-messenger пример показывает более крупного вручную управляемого ingress-агента с административной панелью, обработкой меню и reply fiber, принадлежащими приложению. Используйте getMessengers() для простого пути на основе Think. Используйте пример, если вам нужно самостоятельно управлять средой выполнения Chat SDK и UI плоскости управления. См. Состояние Chat SDK для базового адаптера состояния.