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

Каналы

Канал представляет собой способ связи, через который агент Think общается: WebSocket браузера, webhook мессенджера (Telegram, Slack и так далее), голос или ваш собственный транспорт. Каналы обобщают мессенджеры в единый словарь, чтобы можно было применять политику для каждого канала (другой системный промпт, суженный набор инструментов, ограничение числа шагов) и доставлять уведомления out-of-band независимо от того, через какую поверхность пришёл ход.

У каждого Think agent всегда есть неявный web канал (WebSocket-чат, которым пользуются ваши клиенты в браузере). Дополнительные каналы вы объявляете, а также переопределяете web политику: с configureChannels(). Messenger, возвращённые из getMessengers() автоматически поглощаются как messenger каналы, поэтому существующие приложения-мессенджеры продолжают работать без изменений.

Переопределить configureChannels() чтобы вернуть отображение идентификатора канала на ChannelDefinition. С помощью id вы выбираете канал в рамках хода:

import { Think, messengerChannel } from "@cloudflare/think";
import { telegram } from "@chat-adapter/telegram";

export class Assistant extends Think {
	configureChannels() {
		return {
			// Override policy for the built-in web channel.
			web: {
				kind: "web",
				ingress: { transport: "websocket" },
				instructions: "You are chatting in a web app. Use markdown freely.",
			},
			// A voice channel with tighter limits.
			voice: {
				kind: "voice",
				ingress: { transport: "voice" },
				instructions: "Keep replies short and speakable. No markdown.",
				maxTurns: 3,
			},
			// A messenger channel (Chat SDK webhook).
			telegram: messengerChannel(telegram({/* adapter config */})),
		};
	}
}

import { Think, messengerChannel } from "@cloudflare/think";
import { telegram } from "@chat-adapter/telegram";

export class Assistant extends Think<Env> {
	configureChannels() {
		return {
			// Override policy for the built-in web channel.
			web: {
				kind: "web",
				ingress: { transport: "websocket" },
				instructions: "You are chatting in a web app. Use markdown freely.",
			},
			// A voice channel with tighter limits.
			voice: {
				kind: "voice",
				ingress: { transport: "voice" },
				instructions: "Keep replies short and speakable. No markdown.",
				maxTurns: 3,
			},
			// A messenger channel (Chat SDK webhook).
			telegram: messengerChannel(
				telegram({
					/* adapter config */
				}),
			),
		};
	}
}

A ChannelDefinition содержит следующие поля:

Используйте defineChannels() вспомогательную функцию для вывода типов и messengerChannel() чтобы обернуть определение адаптера Chat SDK как kind: "messenger" канал.

Политика канала применяется как переопределяемое значение по умолчанию перед beforeTurn выполняется, поэтому beforeTurn переопределение всё равно имеет приоритет:

• instructions добавляется перед базовым системным промптом для этого хода.
• tools фильтрует собранный набор инструментов (он может только убирать инструменты: getTools() seam добавляет их).
• maxTurns ограничивает количество шагов модели: beforeTurn: maxSteps побеждает, тогда канал maxTurns, затем экземпляр maxSteps по умолчанию.

Передайте channel к runTurn() (или chat()) для запуска хода в определённом канале. ID канала впечатывается в сообщение пользователя, поэтому продолженный или восстановленный ход заново определяет тот же канал и повторно применяет его политику:

export class Assistant extends Think {
	async speak() {
		await this.runTurn({ input: "Read this out loud", channel: "voice" });
	}
}

export class Assistant extends Think<Env> {
	async speak() {
		await this.runTurn({ input: "Read this out loud", channel: "voice" });
	}
}

Внутри хода активный канал доступен как this.activeChannel ( ChannelContext с channelId, kind, и подробности мессенджера, если это уместно). Ход без channel выполняется без контекста канала и не применяет никакой политики канала.

deliverNotice() отправляет сообщение в канал без в начале хода модели. Используйте его для обновлений статуса («ваш импорт завершён») или чтобы показать ход выполнения действия вложение ответа : не выполняет инференс, не попадает в очередь ходов, и поэтому его безопасно вызывать изнутри execute:

export class Assistant extends Think {
	async notify() {
		await this.deliverNotice("Your export is ready to download.");

		await this.deliverNotice("Background research finished.", {
			informModel: true, // also record it in the transcript so the next turn knows
		});
	}
}

export class Assistant extends Think<Env> {
	async notify() {
		await this.deliverNotice("Your export is ready to download.");

		await this.deliverNotice("Background research finished.", {
			informModel: true, // also record it in the transcript so the next turn knows
		});
	}
}

type DeliverNoticeOptions = {
	channel?: string; // defaults to the active turn's channel, else "web"
	informModel?: boolean; // also write to the model-visible transcript (default false)
	kind?: "final" | "interim" | "notice" | "command"; // wire tag (default "notice")
	thread?: string; // required for out-of-turn delivery to a multi-thread messenger
};

Поведение зависит от целевого канала:

• web : уведомление всегда добавляется в транскрипт (это единственный способ его отображения). informModel тогда управляет только формулировкой.
• messenger : уведомление отправляется провайдеру. Вне хода передайте thread чтобы указать целевой разговор. С informModel: true, это также записывается в транскрипт.
• voice / custom : доставка вне хода вызывает исключение, поскольку у этих поверхностей ещё нет цели доставки.

Переопределить renderAttachment(attachment) чтобы превратить вложение с ответом на действие в уведомление; Think вызывает её в конце хода и передаёт отрисованный текст как завершающее interim уведомление. Верните undefined чтобы пропустить тип вложения.

configureChannels() оборачивает getMessengers() : не заменяет его. Каждое getMessengers() запись становится kind: "messenger" канал и всё, что в Мессенджеры руководство (настройка Telegram, маршрутизация вебхуков, цели диалогов, доставка и восстановление) продолжает действовать. ID канала в configureChannels() который конфликтует с getMessengers() id является ошибкой. Продолжайте использовать getMessengers() для приложений только для мессенджеров; используйте configureChannels() когда вам также нужен web/voice/custom политику или уведомления out-of-band.

Активность канала отображается на channel канал наблюдаемости:

import { subscribe } from "agents/observability";

const unsubscribe = subscribe("channel", (event) => {
	// event.type is one of:
	//   "channel:resolved"  — a turn resolved a registered channel
	//   "channel:delivered" — a turn's final reply was delivered
	//   "notice:delivered"  — deliverNotice() succeeded
	//   "notice:failed"     — deliverNotice() threw
});

import { subscribe } from "agents/observability";

const unsubscribe = subscribe("channel", (event) => {
	// event.type is one of:
	//   "channel:resolved"  — a turn resolved a registered channel
	//   "channel:delivered" — a turn's final reply was delivered
	//   "notice:delivered"  — deliverNotice() succeeded
	//   "notice:failed"     — deliverNotice() threw
});

• Мессенджеры : Подробно о настройке и доставке вебхуков Chat SDK.
• Действия : записывает вложения ответа для renderAttachment().
• Голос : поверхности для речи в реальном времени.