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

Hooky životního cyklu

Think vlastní streamText volání a poskytuje hooky v každé fázi kroku konverzace. Hooky se spouštějí při každém kroku bez ohledu na vstupní cestu: WebSocket chat, dílčí agent chat(), saveMessages(), trvalé submitMessages() provedení, continueLastTurn(), a automatické pokračování po výsledcích nástrojů.

Pro kolo se dvěma voláními nástrojů:

flowchart TD
    cfg["configureSession() — once at startup, not per-turn"] --> bt["beforeTurn() — inspect context, override model/tools/prompt"]
    bt --> bs

    subgraph loop ["streamText (repeats per step)"]
        bs["beforeStep()"] --> chunk["onChunk() — per streaming chunk"]
        chunk --> btc["beforeToolCall()"]
        btc --> exec["tool executes"]
        exec --> atc["afterToolCall()"]
        atc --> sf["onStepFinish()"]
        sf -->|"more steps"| bs
    end

    sf -->|"turn complete"| ocr["onChatResponse() — message persisted, turn lock released"]

Volá se před streamText. Přijímá kompletně sestavený kontext: systémový prompt, převedené zprávy, sloučené nástroje a model. Vraťte TurnConfig k přepsání libovolné části, nebo void pro přijetí výchozích hodnot.

beforeTurn(ctx: TurnContext): TurnConfig | void | Promise<TurnConfig | void>

Všechna pole jsou volitelná. Vraťte pouze to, co chcete změnit.

Přepněte na levnější model pro navazující kola:

beforeTurn(ctx: TurnContext) {
	if (ctx.continuation) {
		return { model: this.cheapModel };
	}
}

Omezte, které nástroje může model volat:

beforeTurn(ctx: TurnContext) {
	return { activeTools: ["read", "write", "getWeather"] };
}

Přidejte kontext pro každé kolo z těla klientského požadavku:

beforeTurn(ctx: TurnContext) {
	if (ctx.body?.selectedFile) {
		return {
			system: ctx.system + `\n\nUser is editing: ${ctx.body.selectedFile}`,
		};
	}
}

Skrytí uvažování u interních pokračovacích kol:

beforeTurn(ctx: TurnContext) {
	if (ctx.continuation) {
		return { sendReasoning: false };
	}
}

Vynuťte strukturovaný výstup pro dané kolo:

import { Output } from "ai";
import { z } from "zod";

const ResultSchema = z.object({ severity: z.enum(["low", "high"]) });

beforeTurn(ctx: TurnContext) {
	if (ctx.body?.mode === "structured-answer") {
		return {
			output: Output.object({ schema: ResultSchema }),
			activeTools: [],
		};
	}
}

output je nastavení pouze na úrovni kola. V AI SDK prepareStep nepřijímá output override, takže beforeStep nemůže přepínat strukturovaný výstup v rámci jednoho kroku.

Volá se před každým krokem AI SDK v agentní smyčce. Think tento hook předává do streamText jako prepareStep, takže dostává celý kontext prepare-step z AI SDK a může vracet přepisy pro jednotlivé kroky. Použijte beforeTurn pro sestavení napříč celým kolem a beforeStep když rozhodnutí závisí na čísle kroku nebo výsledcích předchozích kroků.

beforeStep(ctx: PrepareStepContext): StepConfig | void {
	if (ctx.stepNumber > 0) {
		return { activeTools: [] };
	}
}

Volá se před spuštěním funkce serverového nástroje execute funkce spustí. Think obalí každý nástroj na straně serveru tak, aby hook mohl volání povolit, upravit, zablokovat nebo nahradit ještě předtím, než model obdrží výsledek nástroje.

beforeToolCall(ctx: ToolCallContext): ToolCallDecision | void {
	if (ctx.toolName === "delete" && this.isReadOnlyMode) {
		return { action: "block", reason: "delete is disabled in read-only mode" };
	}

	if (ctx.toolName === "weather") {
		const cached = this.weatherCache.get(JSON.stringify(ctx.input));
		if (cached) return { action: "substitute", output: cached };
	}
}

Vrátí ToolCallDecision pro řízení běhu:

Pokud obalený nástroj vrátí AsyncIterable pro předběžné výsledky nástrojů. Think sbalí iterovatelný objekt na jeho poslední vrácenou hodnotu po beforeToolCall se spustí. Pokud od tohoto nástroje potřebujete opravdové předběžné streamování, nezachytávejte ho pomocí beforeToolCall.

Volá se poté, co je znám výsledek nástroje. Zahrnuje to skutečná spuštění, blokovaná volání, nahrazená volání a vyvolané chyby nástroje.

afterToolCall(ctx: ToolCallResultContext) {
	if (!ctx.success) return;

	this.env.ANALYTICS.writeDataPoint({
		blobs: [ctx.toolName],
		doubles: [JSON.stringify(ctx.output).length],
	});
}

Pro blokovaná a nahrazená volání nástrojů success je true protože model obdrží platný výsledek nástroje. Pouze chyby vyvolané (thrown) při původním spuštění nástroje se projeví jako success: false.

Volá se po dokončení každého kroku v agentní smyčce. StepContext je událost step-finish z AI SDK, takže obsahuje kompletní záznam kroku: vygenerovaný text, uvažování, soubory, zdroje, typovaná volání nástrojů a jejich výsledky, využití, upozornění, metadata požadavku a odpovědi a metadata poskytovatele.

onStepFinish(ctx: StepContext) {
	console.log(
		`Step ${ctx.stepNumber} (${ctx.finishReason}): ` +
			`${ctx.usage.inputTokens}in/${ctx.usage.outputTokens}out`,
	);
}

Volá se pro každý streamovaný chunk: vysoká frekvence, spouští se pro každý token. Použijte pro analýzu streamování, ukazatele průběhu nebo počítání tokenů. Pouze pro pozorování.

Volá se poté, co kolo chatu vytvoří a uloží zprávu asistenta. Zámek kola se uvolní ještě před spuštěním tohoto hooku, takže je bezpečné zavolat saveMessages nebo jiné metody zevnitř.

Spouští se u všech průběhů kola, které ukládají zprávu asistenta: WebSocket, RPC subagenta, saveMessages, a automatické pokračování. Pokud kolo selže dříve, než vytvoří jakoukoli část odpovědi asistenta, onChatError místo toho zpracuje chybu.

onChatResponse(result: ChatResponseResult) {
	if (result.status === "completed") {
		console.log(`Turn ${result.requestId}: ${result.message.parts.length} parts`);
	}
}

Volá se, když během kola chatu dojde k chybě. Chybu vraťte, pokud ji chcete propagovat dál, nebo vraťte jinou chybu. Volitelný kontext popisuje, kde k selhání došlo a zda už byly zprávy uživatele uloženy. Částečná zpráva asistenta (pokud existuje) se uloží ještě před spuštěním tohoto hooku.

onChatError(error: unknown, ctx?: ChatErrorContext): unknown

ChatErrorContext zahrnuje:

Think také vyvolává chat:request:failed na agents:chat kanál pozorovatelnosti se stejnými informacemi o fázi a perzistenci.

onChatError(error: unknown, ctx?: ChatErrorContext) {
	console.error("Chat turn failed:", ctx?.stage, error);
	if (ctx?.classification === "context_overflow") {
		return new Error("This conversation is too long to continue. Please start a new one.");
	}
	return new Error("Something went wrong. Please try again.");
}

Volá se, když během kola dojde k chybě, před onChatError. Přemapuje surovou chybu poskytovatele na kategorii nezávislou na poskytovateli, díky čemuž Think může reagovat, aniž by musel mít v frameworku napevno zadané řetězce specifické pro poskytovatele: stejné rozdělení jako u tokenCounter které předáváte do compactAfter(). Mapování spravuje aplikace, protože ví, se kterým poskytovatelem a modelem komunikuje.

classifyChatError(error: unknown, ctx?: ChatErrorContext): ChatErrorClassification | void

ChatErrorClassification je "context_overflow" | "rate_limit" | "transient" | "fatal" | "unknown". Dnes tento hook řídí pouze zotavení po přetečení kontextu. Think ho volá, když v kole dojde k chybě a contextOverflow.reactive je zapnuto. Pokud je reactive vypnuté, nevolá se.

Vracení "context_overflow" spouští záložní mechanismus zhuštění a opakování (viz Obnovení po přetečení kontextového okna). Pokud obnova kolo nezachrání, tato klasifikace se projeví na konečném onChatError volání přes ChatErrorContext.classification.

Ostatní kategorie jsou vyhrazeny pro budoucí použití. Vrácení některé z nich dnes nemá žádný účinek a nepředává se do onChatError. Vrácení void (výchozí) zachovává stávající chování při ukončení.

Argumentem může být Error, AI SDK APICallError (s statusCode/responseBody), nebo, v případě chyb poskytovatele uvnitř streamu, které se projeví jako chybová část streamu a ne jako vyvolaná výjimka, řetězec s chybovou zprávou. Podle toho zúžete typ. Chyby poskytovatele způsobené přetečením kontextu přicházejí jako chybové části uvnitř streamu, takže je tento hook dostává jako řetězec, ne jako vyvolanou výjimku.

Druhý argument je ChatErrorContext. Během obnovy po přetečení je { stage: "stream", requestId }, takže klasifikátor může chybu spojit s právě probíhajícím tahem, například zavolat cancelChat(requestId) a předčasně ukončí zotavování.

V běžném případě přiřaďte sdružený defaultContextOverflowClassifier, což odpovídá chybám přetečení kontextu u Anthropic, OpenAI, Google, Bedrock a dalších:

import { Think, defaultContextOverflowClassifier } from "@cloudflare/think";

export class MyAgent extends Think {
	classifyChatError = defaultContextOverflowClassifier;
}

import { Think, defaultContextOverflowClassifier } from "@cloudflare/think";

export class MyAgent extends Think<Env> {
	override classifyChatError = defaultContextOverflowClassifier;
}

Nebo si napište vlastní, případně s delegováním na vestavěný klasifikátor:

import { Think, defaultContextOverflowClassifier } from "@cloudflare/think";

export class MyAgent extends Think {
	classifyChatError(error) {
		if (error instanceof Error && /rate.?limit/i.test(error.message)) {
			return "rate_limit";
		}
		return defaultContextOverflowClassifier(error);
	}
}

import type { ChatErrorClassification } from "@cloudflare/think";
import { Think, defaultContextOverflowClassifier } from "@cloudflare/think";

export class MyAgent extends Think<Env> {
	override classifyChatError(error: unknown): ChatErrorClassification | void {
		if (error instanceof Error && /rate.?limit/i.test(error.message)) {
			return "rate_limit";
		}
		return defaultContextOverflowClassifier(error);
	}
}