← Vytvářejte agenty na Cloudflare / agents / harnesses / think

Messengery

Použijte messengery, pokud má agent Think přímo přijímat webhooky Chat SDK a odpovídat na ně. Think vlastní trasu webhooku, trvalý fiber pro odpovědi, směrování konverzace a streamované doručování zpět poskytovateli.

Nainstalujte balíček Think a adaptér poskytovatele, který používáte:

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

Adaptéry poskytovatelů se exportují z podcest specifických pro daného poskytovatele, takže se nepoužívané adaptéry nezahrnou do vašeho Workeru.

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,
			}),
		});
	}
}

S výchozí telegram klíč zaregistrujte webhook Telegramu na:

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

telegramMessenger() vyžaduje secretToken v režimu webhooku, pokud nezadáte vlastní verifyWebhook funkci nebo se explicitně odhlaste pomocí verifyWebhook: false.

Pokud jeden agent Think spravuje více botů Telegram, přidělte každému poskytovateli vlastní název adaptéru 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,
	}),
});

Duplicitní názvy adaptérů způsobí selhání při spuštění, takže se poskytovatelé nemohou navzájem přepsat ve sdíleném runtime Chat SDK.

Kořenový agent Think zpracovává trasy messenger webhooků po směrování rámcových sub-agentů a interních tras Think, ale před uživatelsky definovanými onRequest záložní řešení. Trasy Messengeru jsou pouze kořenové. Definování getMessengers() na třídě subagenta nevytvoří trasy webhooků pro daný subagent.

Ve výchozím nastavení Think odpovídá na přímé zprávy a zmínky. Nové zmínky přihlásí vlákno Chat SDK k odběru, takže pozdější zmínky ve stejném vlákně jsou stále zaznamenány, ale běžné zprávy z odebíraného vlákna a akce tlačítek jsou ignorovány, pokud se k tomu nezapojíte:

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"],
});

Události Actions se převádějí na uživatelské zprávy Think s ID akce, hodnotou, ID zdrojové zprávy a iniciujícím uživatelem. Použijte getMessengerContext()?.action uvnitř hooků nebo nástrojů, když potřebujete podrobnosti akce specifické pro poskytovatele. Akce jsou volitelné (opt-in), takže interaktivní karty nespouštějí kola modelu nedopatřením.

Výchozí režim konverzace je jeden podřízený agent Think na vlákno Chat SDK. Díky tomu skupinové chaty, přímé zprávy a kanály neúmyslně nesdílejí paměť.

Použijte kořenového agenta jako konverzaci, pokud má veškerý provoz messengeru sdílet jednu relaci 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",
});

Použijte resolver, pokud směrování závisí na tenantovi, kanálu, vlákně nebo uživateli:

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}`,
		};
	},
});

Stav Messengeru je podporován agents/chat-sdk. Exportujte ThinkMessengerStateAgent z modulu Workeru, aby ho směrování sub-agenta mohlo přeložit. Produkční aplikace nepotřebují pro tuto třídu stavu určenou pouze pro facety samostatnou vazbu ani migraci Durable Object. Testovací prostředí mohou stále potřebovat explicitní vazby.

Think odpovídá streamovaným chat() cestu. Kořenový agent spustí idempotentní managed fiber, určí cíl konverzace, zavolá target.chat(message, callback), a umožňuje doručovací zásadě poskytovatele publikovat nebo upravovat viditelné zprávy.

Snímky obnovení ukládají pouze serializovatelná data událostí a vlákna Chat SDK. Pokud dojde k restartu před zahájením streamování, může Think odpověď přehrát. Pokud dojde k restartu až po zahájení streamování, Think místo rizika duplicitní částečné odpovědi odešle nakonfigurovanou zprávu o přerušení.

Chyby při doručování ve výchozím nastavení používají obecnou zprávu určenou uživateli, aby se podrobnosti interní výjimky nedostaly do externích chatů. Přepsat lze pomocí delivery.errorResponseText když chcete vlastní bezpečnou zprávu.

Během kola messengeru, getMessengerContext() vrátí poskytovatele, vlákno, autora, zprávu, schopnosti a metadata příloh pro iniciační událost. Použijte ho z promptů, nástrojů nebo hooků, které potřebují chování specifické pro kanál.

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.
}

Použijte chatSdkMessenger() pro poskytovatele, kteří zatím nemají helper 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;
	},
});

Každý vlastní messenger musí poskytovat verifyWebhook nebo explicitně použijte verifyWebhook: false.

examples/think-chat-sdk příklad ukazuje nativní variantu Think s využitím getMessengers() cestu s malým dashboardem Vite, který sleduje kořenovou konverzaci Think přes Agent WebSocket.

examples/chat-sdk-messenger příklad ukazuje rozsáhlejšího ručně řízeného ingress agenta s administrátorským dashboardem, zpracováním nabídky a reply fibery vlastněnými aplikací. Použijte getMessengers() pro jednoduchou cestu nativní pro Think. Příklad použijte, pokud potřebujete mít plně pod kontrolou runtime Chat SDK a UI řídicí roviny. Viz Stav Chat SDK pro podkladový adaptér stavu.