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

Хуки жизненного цикла

Think владеет streamText вызов и предоставляет хуки на каждом этапе хода чата. Хуки срабатывают на каждом ходу независимо от точки входа: WebSocket-чат, дочерний агент chat(), saveMessages(), устойчивый submitMessages() выполнения, continueLastTurn(), и автоматическое продолжение после результатов инструментов.

Для хода с двумя вызовами инструментов:

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"]

Вызывается перед streamText. Получает полностью собранный контекст: системный промпт, преобразованные сообщения, объединённые инструменты и модель. Верните TurnConfig чтобы переопределить любую часть, либо void, чтобы принять значения по умолчанию.

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

Все поля необязательны. Возвращайте только то, что хотите изменить.

Переключитесь на более дешёвую модель для ходов продолжения:

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

Ограничьте, какие инструменты может вызывать модель:

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

Добавьте контекст для каждого хода из тела клиентского запроса:

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

Скрыть рассуждения для внутренних ходов продолжения:

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

Принудительно задайте структурированный вывод для хода:

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 это настройка только на уровне хода. У AI SDK есть prepareStep не принимает output переопределение, поэтому beforeStep не может переключать структурированный вывод в рамках одного шага.

Вызывается перед каждым шагом AI SDK в агентном цикле. Think перенаправляет этот хук в streamText как prepareStep, чтобы он получал полный контекст prepare-step из AI SDK и мог возвращать переопределения для каждого шага. Используйте beforeTurn для сборки в рамках всего хода и beforeStep когда решение зависит от номера шага или результатов предыдущих шагов.

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

Вызывается перед выполнением серверного инструмента execute функция выполнится. Think оборачивает каждый инструмент на стороне сервера, чтобы хук мог разрешить, изменить, заблокировать или подменить вызов, прежде чем модель получит результат инструмента.

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

Возвращает ToolCallDecision чтобы управлять выполнением:

Если обёрнутый инструмент возвращает AsyncIterable для предварительных результатов инструмента Think схлопывает итерируемый объект до его финального переданного значения после beforeToolCall выполняется. Если вам нужен настоящий предварительный streaming от этого инструмента, избегайте его перехвата с помощью beforeToolCall.

Вызывается после того как становится известен результат работы инструмента. Сюда входят реальные выполнения, заблокированные вызовы, подменённые вызовы и выброшенные ошибки инструмента.

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

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

Для заблокированных и заменённых вызовов инструментов success это true потому что модель получает корректный результат инструмента. Только исключения, возникшие при исходном выполнении инструмента, проявляются как success: false.

Вызывается после завершения каждого шага в агентном цикле. StepContext это событие step-finish из AI SDK, поэтому оно включает полную запись шага: сгенерированный текст, рассуждения, файлы, источники, типизированные вызовы инструментов и их результаты, использование, предупреждения, метаданные запроса и ответа, а также метаданные провайдера.

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

Вызывается для каждого потокового чанка. Высокая частота: срабатывает на каждый токен. Используйте для потоковой аналитики, индикаторов прогресса или подсчёта токенов. Только для наблюдения.

Вызывается после того как ход чата создаёт и сохраняет сообщение ассистента. Блокировка хода снимается до запуска этого хука, поэтому в нём безопасно вызывать saveMessages или другие методы изнутри.

Срабатывает для всех путей хода, которые сохраняют сообщение ассистента: WebSocket, RPC дочернего агента, saveMessages, и автоматическое продолжение. Если ход завершается ошибкой до того, как создана хотя бы одна часть ответа ассистента, onChatError вместо этого обрабатывает ошибку.

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

Вызывается при возникновении ошибки во время хода чата. Верните ошибку, чтобы передать её дальше, либо верните другую ошибку. Необязательный контекст описывает, где произошёл сбой и были ли уже сохранены сообщения пользователя. Частичное сообщение ассистента (если оно есть) сохраняется до срабатывания этого хука.

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

ChatErrorContext включает:

Think также генерирует chat:request:failed на agents:chat канал наблюдаемости с той же информацией об этапе и сохранении.

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

Вызывается при возникновении ошибки во время хода, до onChatError. Преобразует необработанную ошибку провайдера в категорию, не зависящую от провайдера, чтобы Think мог реагировать, не встраивая специфичные для провайдера строки во фреймворк: то же разделение, что и у tokenCounter вы передаете в compactAfter(). Приложение владеет этим сопоставлением, поскольку знает, с каким провайдером и моделью оно взаимодействует.

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

ChatErrorClassification это "context_overflow" | "rate_limit" | "transient" | "fatal" | "unknown". Сегодня этот хук отвечает только за восстановление при переполнении контекста. Think вызывает его, когда в ходе возникает ошибка и contextOverflow.reactive включён. Если reactive отключён, он не вызывается.

Возврат "context_overflow" запускает защитный механизм compact-and-retry (см. Восстановление после переполнения контекстного окна). Если восстановление не может спасти ход, эта классификация проявляется в финальном onChatError вызов через ChatErrorContext.classification.

Остальные категории зарезервированы на будущее. Если сегодня вернуть одну из них, это не даст эффекта и не будет передано в onChatError. Возврат void (значение по умолчанию) сохраняет существующее поведение при завершении.

Аргументом может быть Error, AI SDK APICallError (с statusCode/responseBody), либо, для ошибок поставщика внутри потока, которые проявляются как часть потока с ошибкой, а не как исключение, строку с сообщением об ошибке. Сужайте тип соответствующим образом. Ошибки поставщика из-за переполнения контекста приходят как части потока с ошибкой, поэтому этот хук получает их в виде строки, а не как выброшенное исключение.

Вторым аргументом является ChatErrorContext. Во время восстановления после переполнения оно { stage: "stream", requestId }, чтобы классификатор мог сопоставить ошибку с выполняющимся ходом, например вызвать cancelChat(requestId) и прерывает восстановление.

В обычном случае назначьте встроенный defaultContextOverflowClassifier, что соответствует ошибкам переполнения контекста у Anthropic, OpenAI, Google, Bedrock и других:

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

Или напишите свой собственный вариант, при необходимости делегируя работу встроенному классификатору:

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