配置 · Cloudflare Agents docs

Think 通过在 Think 子类上重写方法与属性来配置。大多数 Agent 仅重写 getModel()。

配置覆盖

方法 / 属性	默认值	描述
`getModel()`	抛出异常	返回要使用的 `LanguageModel`
`getSystemPrompt()`	`"You are a helpful assistant."`	系统提示词（无上下文块时的回退）
`getTools()`	`{}`	智能体循环的 AI SDK `ToolSet`
`getScheduledTasks()`	`{}`	代码声明的周期性提示词或处理函数 — 请参阅定时任务
`getDefaultTimezone()`	`undefined`	挂钟定时任务的默认时区
`getMessengers()`	`{}`	信使入口与投递声明 — 请参阅信使
`maxSteps`	`10`	每轮最大工具调用步数
`sendReasoning`	`true`	向聊天客户端发送推理片段
`configureSession()`	恒等变换	添加上下文块、压缩、搜索、技能 — 请参阅会话
`getSkills()`	`[]`	返回按需技能激活的 Agent Skills 源 — 请参阅Agent Skills
`getSkillScriptRunner()`	`null`	启用可选的 `run_skill_script` 工具
`workspaceBash`	`true`	包含或配置默认工作区 `bash` 工具 — 请参阅工具
`messageConcurrency`	`"queue"`	重叠提交的行为 — 请参阅客户端工具
`includeMcpTools`	`true`	将已连接的 MCP 工具转为 AI SDK 工具并加入模型轮次。请参阅MCP 工具
`waitForMcpConnections`	`false`	推理前等待 MCP server
`chatRecovery`	`true`	将 WebSocket、子 Agent、程序化与续写轮次包装在 `runFiber` 中以实现持久执行。设为含 `maxAttempts`、`stableTimeoutMs`、`terminalMessage`、`onExhausted` 的配置对象以调整有界恢复
`chatStreamStallTimeoutMs`	`0`（关闭）	可选的不活动看门狗：模型流在此时间内无片段则中止轮次（测量片段间隔，含工具执行）。开启 `chatRecovery` 时，停滞进入有界恢复
`contextOverflow`	`undefined`	可选的轮中上下文溢出处理，含 `reactive`、`maxRetries`、`proactive`。需要 `classifyChatError` 加会话压缩函数 — 请参阅上下文窗口溢出恢复

chatRecovery 与 chatStreamStallTimeoutMs 行为请参阅持久恢复。

动态配置

Think 的类泛型与 Agent<Env, State, Props> 一致。持久化运行时配置在 configure<T>() 与 getConfig<T>() 调用点带类型，存储在 SQLite，可经受休眠与重启。

export class MyAgent extends Think {
	getModel() {
		const tier = this.getConfig()?.modelTier ?? "fast";
		const models = {
			fast: "@cf/moonshotai/kimi-k2.6",
			capable: "@cf/meta/llama-4-scout-17b-16e-instruct",
		};
		return createWorkersAI({ binding: this.env.AI })(models[tier]);
	}
}

type MyConfig = { modelTier: "fast" | "capable"; theme: string };

export class MyAgent extends Think<Env> {
	getModel() {
		const tier = this.getConfig<MyConfig>()?.modelTier ?? "fast";
		const models = {
			fast: "@cf/moonshotai/kimi-k2.6",
			capable: "@cf/meta/llama-4-scout-17b-16e-instruct",
		};
		return createWorkersAI({ binding: this.env.AI })(models[tier]);
	}
}

方法	描述
`configure<T>(config: T)`	持久化带类型的配置对象
`getConfig<T>(): T \| null`	读取持久化配置，从未配置则为 null

通过 @callable 向客户端暴露配置：

import { callable } from "agents";

export class MyAgent extends Think {
	getModel() {
		/* ... */
	}

	@callable()
	updateConfig(config) {
		this.configure(config);
	}
}

import { callable } from "agents";

export class MyAgent extends Think<Env> {
	getModel() {
		/* ... */
	}

	@callable()
	updateConfig(config: MyConfig) {
		this.configure<MyConfig>(config);
	}
}

Session 集成

Think 将对话存储在 Session — 保存消息并为模型提供可写记忆的存储层。此处有两个概念：上下文块是模型可读写的系统提示词标注段落（例如关于用户的 memory 块）；压缩会摘要较早消息，使长对话留在模型上下文窗口内。重写 configureSession 以添加持久记忆、压缩、搜索与技能：

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

export class MyAgent extends Think {
	getModel() {
		/* ... */
	}

	configureSession(session) {
		return session
			.withContext("soul", {
				provider: { get: async () => "You are a helpful coding assistant." },
			})
			.withContext("memory", {
				description: "Important facts learned during conversation.",
				maxTokens: 2000,
			})
			.withCachedPrompt();
	}
}

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

export class MyAgent extends Think<Env> {
	getModel() {
		/* ... */
	}

	configureSession(session: Session) {
		return session
			.withContext("soul", {
				provider: { get: async () => "You are a helpful coding assistant." },
			})
			.withContext("memory", {
				description: "Important facts learned during conversation.",
				maxTokens: 2000,
			})
			.withCachedPrompt();
	}
}

当 configureSession 添加上下文块时，Think 从这些块构建系统提示词，而非使用 getSystemPrompt()。Think 的 this.messages 访问器直接从 Session 的树形存储读取。

完整 Session API — 上下文块、压缩、搜索、技能、多会话 — 请参阅会话文档。

包导出

导出	描述
`@cloudflare/think`	`Think`、`Session`、`Workspace` 与 `skills` 命名空间
`@cloudflare/think/messengers`	Messenger 契约、Chat SDK 桥接、状态 Agent、投递
`@cloudflare/think/messengers/telegram`	Telegram messenger 提供方与投递辅助
`@cloudflare/think/workflows`	`ThinkWorkflow`、`step.prompt()` — Workflow 提示词步骤
`@cloudflare/think/tools/workspace`	`createWorkspaceTools()` — 自定义存储后端
`@cloudflare/think/tools/execute`	`createExecuteTool()` — 通过 Code Mode 的沙箱代码执行
`@cloudflare/think/tools/browser`	`createBrowserTools()` — 基于 Chrome DevTools Protocol 的工具
`@cloudflare/think/tools/extensions`	`createExtensionTools()` — LLM 驱动的扩展加载
`@cloudflare/think/extensions`	`ExtensionManager`、`HostBridgeLoopback` — 扩展运行时

依赖

需你提供的对等依赖：

包	必需	说明
`agents`	是	Cloudflare Agents SDK
`ai`	是	AI SDK v6
`zod`	是	Schema 验证（v4）
`@chat-adapter/telegram`	可选	使用 Telegram messenger 时必需

与 @cloudflare/think 捆绑：

包	说明
`@cloudflare/shell`	`Workspace` 文件系统
`@cloudflare/codemode`	`createExecuteTool()` 的代码执行
`just-bash`	默认工作区 `bash` 工具的沙箱 shell

Agent Skills 引擎及其脚本运行器位于 agents/skills，因此技能脚本通过 agents 拉取 @cloudflare/worker-bundler 与 just-bash，而非 Think。