Think 在每轮次提供内置工作区文件工具,并提供自定义工具、代码执行与动态扩展的集成点。
每轮次 Think 从多个来源合并工具。若名称冲突,后出现的来源覆盖较早的:
- 工作区工具 —
read、ls、find、grep、write、edit、delete,以及配置后可用的exec和publish(内置) getTools()— 你的自定义服务端工具- 扩展工具 — 已加载扩展的工具(以扩展名前缀)
- 会话工具 —
set_context、load_context、search_context(来自configureSession) - 技能工具 —
activate_skill、read_skill_resource、run_skill_script(来自getSkills();请参阅 Agent Skills) - MCP 工具 — 当
includeMcpTools为true时,来自已连接 MCP 服务器 - 客户端工具 — 来自浏览器(请参阅 客户端工具)
工具归执行当前轮次的代理所有。对于父子代理编排,请使用将代理用作工具,而不是通过 chat() 传递一次性工具。
每个 Think 代理都会获得 this.workspace,这是来自 @cloudflare/computer ↗ 的 Workspace,存储在 Durable Object 的 SQLite 中。Think 无需配置即可在每一轮中添加 Computer 的 AI SDK 工具。
| 工具 | 描述 |
|---|---|
read |
通过行和字节分页读取文本;将图像和 PDF 传递给多模态模型 |
ls |
列出路径中的文件和目录,并支持分页 |
find |
按 glob 模式查找文件 |
grep |
按正则或固定字符串搜索文件内容 |
write |
将内容写入文件(创建父目录) |
edit |
对文件应用精确文本替换;失败时回退到容忍空白差异的搜索 |
delete |
删除文件或目录 |
exec |
在某个 Workspace 执行后端上运行命令或模块 |
publish |
当 Workspace 配置了资源时,通过预签名 URL 分享工作区文件 |
路径均为绝对路径。Computer 的工具和后端将 /workspace 视为工作根目录,Think 也会在此处写入自己的文件。
@cloudflare/computer 是 Think 的对等依赖项:
npm install @cloudflare/computer默认的 Workspace 没有执行后端,因此在添加后端之前不会提供 exec 工具。请在 Workspace 上配置后端及其提供的模块:
import { Think } from "@cloudflare/think";
import { Workspace } from "@cloudflare/computer";
import { WorkerJavaScriptBackend } from "@cloudflare/computer/backends/worker-javascript";
import { createGitClient } from "@cloudflare/computer/git";
import { createGitModule } from "@cloudflare/computer/modules/git";
export class MyAgent extends Think {
workspace = new Workspace({
storage: this.ctx.storage,
git: createGitClient(),
backends: [
new WorkerJavaScriptBackend({
id: "js",
loader: this.env.LOADER,
access: "read-write",
modules: { "ws:git": createGitModule() },
}),
],
});
getModel() {
/* ... */
}
}import { Think } from "@cloudflare/think";
import { Workspace } from "@cloudflare/computer";
import { WorkerJavaScriptBackend } from "@cloudflare/computer/backends/worker-javascript";
import { createGitClient } from "@cloudflare/computer/git";
import { createGitModule } from "@cloudflare/computer/modules/git";
export class MyAgent extends Think<Env> {
override workspace = new Workspace({
storage: this.ctx.storage,
git: createGitClient(),
backends: [
new WorkerJavaScriptBackend({
id: "js",
loader: this.env.LOADER,
access: "read-write",
modules: { "ws:git": createGitModule() },
}),
],
});
getModel() {
/* ... */
}
}JavaScript 后端在 Dynamic Worker 中运行代码,因此需要 Worker Loader 绑定:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"worker_loaders": [
{
"binding": "LOADER"
}
]
}[[worker_loaders]]
binding = "LOADER"Computer 还提供一个在 Dynamic Workers 中运行的 just-bash shell 后端,以及一个带完整 Linux 用户空间的容器后端。有关各后端所需的绑定,请参阅 Computer README ↗。
为 JavaScript 后端提供 ws:tools 模块后,模型通过 exec 运行的代码即可导入代理工具。代码通过 node:fs/promises 读取文件,因此应提供 getTools(),而不是工作区工具:
import { createToolBindings } from "@cloudflare/computer/modules/tools";
import { forAISDKTools } from "@cloudflare/computer/tools/ai-sdk";
new WorkerJavaScriptBackend({
id: "js",
loader: this.env.LOADER,
modules: {
"ws:tools": createToolBindings(forAISDKTools(() => this.getTools())),
},
});import { createToolBindings } from "@cloudflare/computer/modules/tools";
import { forAISDKTools } from "@cloudflare/computer/tools/ai-sdk";
new WorkerJavaScriptBackend({
id: "js",
loader: this.env.LOADER,
modules: {
"ws:tools": createToolBindings(forAISDKTools(() => this.getTools())),
},
});模型通过 exec 运行的代码:
import { readFile } from "node:fs/promises";
import { getWeather } from "ws:tools";
export default async function () {
const cities = JSON.parse(await readFile("/workspace/cities.json", "utf8"));
const reports = [];
for (const city of cities) reports.push((await getWeather({ city })).text);
return reports;
}ws:tools 不会导出需要审批或在浏览器中运行的工具,因为代码无法审批或运行这些工具。代码发起的调用不会经过 beforeToolCall。有关调用和结果的工作方式,请参阅 ws:tools ↗。
exec 会提供 Workspace 中的所有后端,每个后端都会向模型说明自身用途。若要更改内置工具,请从 getTools() 返回一个同名工具,它会替换内置工具。若要在某一轮中隐藏工具,请从 beforeTurn 返回 activeTools。
早期版本的 Think 使用来自 @cloudflare/shell 的 Workspace,该依赖现已弃用。Computer 会将文件存储在不同的表中,而 Think 不会迁移你的数据。若要保留现有工作区,请使用从 @cloudflare/shell 迁移到 @cloudflare/computer ↗中的脚本复制文件。
升级还会更改工具:
list现在改为ls。- 进程内的
bash工具已移除。向 Workspace 添加后端即可获得exec。 workspaceBash、createWorkspaceTools和@cloudflare/think/tools/workspace均已移除,且没有替代项。若要更改内置工具,请从getTools()返回一个同名工具。若要在某一轮中隐藏工具,请从beforeTurn返回activeTools。
完整列表请参阅升级到 Computer 工作区 ↗。
覆盖 getTools() 以添加自己的工具。这些工具是标准的 AI SDK tool() 定义,架构可由 Zod 或 Valibot 等库提供:
import { Think } from "@cloudflare/think";
import { tool } from "ai";
import { z } from "zod";
export class MyAgent extends Think {
getModel() {
/* ... */
}
getTools() {
return {
getWeather: tool({
description: "Get the current weather for a city",
inputSchema: z.object({
city: z.string().describe("City name"),
}),
execute: async ({ city }) => {
const res = await fetch(
`https://api.weather.com/v1/current?q=${city}&key=${this.env.WEATHER_KEY}`,
);
return res.json();
},
}),
};
}
}import { Think } from "@cloudflare/think";
import { tool } from "ai";
import type { ToolSet } from "ai";
import { z } from "zod";
export class MyAgent extends Think<Env> {
getModel() {
/* ... */
}
getTools(): ToolSet {
return {
getWeather: tool({
description: "Get the current weather for a city",
inputSchema: z.object({
city: z.string().describe("City name"),
}),
execute: async ({ city }) => {
const res = await fetch(
`https://api.weather.com/v1/current?q=${city}&key=${this.env.WEATHER_KEY}`,
);
return res.json();
},
}),
};
}
}自定义工具会自动与工作区工具合并。若自定义工具与工作区工具同名,自定义工具优先。
工具可在执行前通过 needsApproval 选项要求用户审批:
getTools(): ToolSet {
return {
deleteFile: tool({
description: "Delete a file from the system",
inputSchema: z.object({ path: z.string() }),
needsApproval: async ({ path }) => path.startsWith("/important/"),
execute: async ({ path }) => {
await this.workspace.fs.rm(path);
return { deleted: path };
},
}),
};
}当 needsApproval 返回 true 时,工具调用会发送到客户端等待审批。对话暂停,直到客户端以 CF_AGENT_TOOL_APPROVAL 响应。
beforeTurn 钩子可限制或添加特定轮次的工具:
beforeTurn(ctx: TurnContext) {
return {
activeTools: ["read", "write", "getWeather"],
tools: { emergencyTool: this.createEmergencyTool() },
};
}activeTools 限制模型可调用的工具。tools 仅在本轮次添加额外工具(合并到现有工具之上)。
Think 从 Agent 基类继承 MCP 客户端支持。默认 Think 将已连接 MCP 服务器的工具转换为 AI SDK 工具并添加到每轮次。
设置 waitForMcpConnections 以确保推理运行前 MCP 服务器已连接:
export class MyAgent extends Think {
waitForMcpConnections = true; // default 10s timeout
// or: waitForMcpConnections = { timeout: 5000 };
getModel() {
/* ... */
}
}export class MyAgent extends Think<Env> {
waitForMcpConnections = true; // default 10s timeout
// or: waitForMcpConnections = { timeout: 5000 };
getModel() {
/* ... */
}
}若通过 Code Mode 或 Think 自动工具集之外的机制暴露 MCP 工具,请关闭直接 AI SDK 工具暴露:
export class MyAgent extends Think {
includeMcpTools = false;
waitForMcpConnections = true;
getModel() {
/* ... */
}
}export class MyAgent extends Think<Env> {
includeMcpTools = false;
waitForMcpConnections = true;
getModel() {
/* ... */
}
}includeMcpTools 仅控制自动模型工具合并。MCP 连接仍会注册、恢复、发现并等待。原始目录访问、直接调用、Code Mode 连接器与显式 this.mcp.getAITools() 调用仍可用。
请使用此属性,而非在 beforeTurn 中通过 activeTools 移除 MCP 工具名称。Think 在调用 beforeTurn 之前转换 MCP schema,因此 activeTools 无法避免该转换。配置连接器运行时请参阅将 MCP 工具与 Code Mode 配合使用。
可通过编程或 @callable 方法添加 MCP 服务器:
import { callable } from "agents";
export class MyAgent extends Think {
getModel() {
/* ... */
}
@callable()
async addServer(name, url) {
return await this.addMcpServer(name, url);
}
@callable()
async removeServer(serverId) {
await this.removeMcpServer(serverId);
}
}import { callable } from "agents";
export class MyAgent extends Think<Env> {
getModel() {
/* ... */
}
@callable()
async addServer(name: string, url: string) {
return await this.addMcpServer(name, url);
}
@callable()
async removeServer(serverId: string) {
await this.removeMcpServer(serverId);
}
}让 LLM 在沙箱化 Worker 中编写并运行 JavaScript,记录在持久 Code Mode 运行时上(中止并重放、人工审批、审计追踪、可复用代码片段)。需要 @cloudflare/codemode 与 worker_loaders 绑定(binding)。
npm install @cloudflare/codemode这个单行写法会从 env.LOADER 推断执行器,并在绑定了 env.BROWSER 时从中获取实时浏览器(cdp.*)。为 tools.* 传入工具;如果沙箱需要访问工作区,也要传入工作区工具:
import { Think } from "@cloudflare/think";
import { createAITools } from "@cloudflare/computer/tools/ai-sdk";
import { createExecuteTool } from "@cloudflare/think/tools/execute";
export class MyAgent extends Think {
getModel() {
/* ... */
}
getTools() {
return {
execute: createExecuteTool(this, {
tools: createAITools({ workspace: this.workspace }),
}),
};
}
}import { Think } from "@cloudflare/think";
import { createAITools } from "@cloudflare/computer/tools/ai-sdk";
import { createExecuteTool } from "@cloudflare/think/tools/execute";
export class MyAgent extends Think<Env> {
getModel() {
/* ... */
}
getTools() {
return {
execute: createExecuteTool(this, {
tools: createAITools({ workspace: this.workspace }),
}),
};
}
}设置清单:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"worker_loaders": [
{
"binding": "LOADER"
}
],
"browser": {
"binding": "BROWSER"
}
}[[worker_loaders]]
binding = "LOADER"
[browser]
binding = "BROWSER" # optional — enables cdp.*// worker entry — the runtime lives in a Durable Object facet, so the class
// must be exported (the @cloudflare/codemode/vite plugin does this
// automatically; the Think framework's generated entry already includes it)
export { CodemodeRuntime } from "@cloudflare/codemode";// worker entry — the runtime lives in a Durable Object facet, so the class
// must be exported (the @cloudflare/codemode/vite plugin does this
// automatically; the Think framework's generated entry already includes it)
export { CodemodeRuntime } from "@cloudflare/codemode";缺少任一部分会以命名该步骤的错误失败。
沙箱内模型可见类型化命名空间及平台 SDK:
tools.*— 你的 AI SDK 工具(对象参数,按 schema 验证)。仅暴露带execute函数的工具——客户端工具无法在沙箱中运行。cdp.*— 配置 Browser Run 绑定时可用浏览器。execute 工具默认为session: { mode: "dynamic" }:除非模型用cdp.startSession()提升,否则每次执行一个会话。codemode.search/codemode.describe/codemode.step/codemode.run— 发现、副作用边界与保存代码片段。
也可以传入完全显式的选项(不推断代理配置):
createExecuteTool({
ctx: this.ctx,
tools: myDomainTools,
browser: this.env.BROWSER,
loader: this.env.LOADER,
});createExecuteTool({
ctx: this.ctx,
tools: myDomainTools,
browser: this.env.BROWSER,
loader: this.env.LOADER,
});带 needsApproval 的 AI SDK 工具在沙箱内不会立即运行——调用会持久化暂停 运行。暂停以普通工具输出返回({ status: "paused", executionId, pending }),模型告知用户所需内容,轮次结束。这与普通 getTools() 工具的客户端审批流程不同:沙箱内函数型 needsApproval 无法提前针对调用参数求值,因此保守地始终 需要审批。Think 提供内置可调用方法来解决:
approveExecution(executionId)— 从暂停处恢复运行。已完成工作重放,不重新执行。结果替换转录中的暂停输出,聊天自动继续。rejectExecution(executionId, reason?)— 以{ status: "rejected", reason }结束运行,供模型调整。pendingExecutions()— 待处理操作(含完整参数),用于渲染审批 UI。
可工作的审批卡片请参阅 assistant 示例 ↗。
当宿主需要的不止工具时,createExecuteRuntime 返回活动部件——从 agent 创建时句柄也会赋给 this.codemode:
import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
const { runtime, connectors, tool } = createExecuteRuntime(this);
await runtime.executions(); // audit trail
await runtime.expirePaused(); // reclaim stale never-approved pauses (call from a scheduled task)
await runtime.saveSnippet("name", { executionId }); // promote a script for reuseimport { createExecuteRuntime } from "@cloudflare/think/tools/execute";
const { runtime, connectors, tool } = createExecuteRuntime(this);
await runtime.executions(); // audit trail
await runtime.expirePaused(); // reclaim stale never-approved pauses (call from a scheduled task)
await runtime.saveSnippet("name", { executionId }); // promote a script for reuse为 agent 提供 Chrome DevTools Protocol (CDP) 访问,用于网页检查、抓取、截图与调试。需要 @cloudflare/codemode 与 Browser Run 绑定(binding)。
import { Think } from "@cloudflare/think";
import { createBrowserTools } from "@cloudflare/think/tools/browser";
export class MyAgent extends Think {
getModel() {
/* ... */
}
getTools() {
return {
...createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
}),
};
}
}import { Think } from "@cloudflare/think";
import { createBrowserTools } from "@cloudflare/think/tools/browser";
export class MyAgent extends Think<Env> {
getModel() {
/* ... */
}
getTools() {
return {
...createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
}),
};
}
}{
"$schema": "./node_modules/wrangler/config-schema.json",
"browser": {
"binding": "BROWSER"
},
"worker_loaders": [
{
"binding": "LOADER"
}
]
}[browser]
binding = "BROWSER"
[[worker_loaders]]
binding = "LOADER"存在 browser 绑定时,会添加持久 CDP 工具以及无状态 Quick Action 工具:
| 工具 | 描述 |
|---|---|
browser_execute |
通过 CDP 对实时浏览器运行 JavaScript(截图、DOM 读取、JS 求值)。 |
browser_markdown |
将页面或原始 HTML 读取为 Markdown。 |
browser_extract |
用 AI 从页面提取结构化数据。 |
browser_links |
列出页面链接。 |
browser_scrape |
按 CSS 选择器抓取特定元素。 |
传入 quickActions: false 仅保留 browser_execute,或传入 quickActions: { actions, maxChars, options } 配置无状态工具。Quick Action 工具共享 browser 绑定,无需 Worker Loader,并自动从当前 Agent 解析 ctx。仅使用无状态工具时,从 @cloudflare/think/tools/browser 导入 createQuickActionTools。
该工具由带 cdp 连接器的 Code Mode 运行时支持:模型编写在沙箱化 Worker isolate 中运行的 async 箭头函数,含 cdp.send()、cdp.attachToTarget()、cdp.spec()(实时规范化协议描述)、会话辅助(cdp.startSession()、cdp.sessionInfo()、cdp.closeSession())与调试日志辅助。执行被记录以支持中止并重放,浏览器会话可在审批暂停后继续存活。
默认每次执行获得全新浏览器会话(one-shot),运行结束时拆除。传入 session: { mode: "dynamic" } 让模型用 cdp.startSession() 提升会话,后续执行在同一浏览器中继续;或 session: { mode: "reuse", key } 使用命名长生命周期会话。过期会话由连接器的 sweep() 回收——从定时任务调用。
自定义 Chrome 端点可传入 cdpUrl 替代 browser:
createBrowserTools({
ctx: this.ctx,
cdpUrl: "http://localhost:9222",
loader: this.env.LOADER,
});createBrowserTools({
ctx: this.ctx,
cdpUrl: "http://localhost:9222",
loader: this.env.LOADER,
});完整 CDP connector API 请参阅浏览 Web。
扩展是运行时动态加载的沙箱化 Worker,可添加工具。LLM 可编写扩展源码、加载它,并在下一轮次使用新工具。
扩展需要 worker_loaders 绑定(binding):
import { Think } from "@cloudflare/think";
export class MyAgent extends Think {
extensionLoader = this.env.LOADER;
getModel() {
/* ... */
}
}import { Think } from "@cloudflare/think";
export class MyAgent extends Think<Env> {
extensionLoader = this.env.LOADER;
getModel() {
/* ... */
}
}定义启动时加载的扩展:
export class MyAgent extends Think {
extensionLoader = this.env.LOADER;
getModel() {
/* ... */
}
getExtensions() {
return [
{
manifest: {
name: "math",
version: "1.0.0",
permissions: { network: false },
},
source: `({
tools: {
add: {
description: "Add two numbers",
parameters: { a: { type: "number" }, b: { type: "number" } },
execute: async ({ a, b }) => ({ result: a + b })
}
}
})`,
},
];
}
}export class MyAgent extends Think<Env> {
extensionLoader = this.env.LOADER;
getModel() {
/* ... */
}
getExtensions() {
return [
{
manifest: {
name: "math",
version: "1.0.0",
permissions: { network: false },
},
source: `({
tools: {
add: {
description: "Add two numbers",
parameters: { a: { type: "number" }, b: { type: "number" } },
execute: async ({ a, b }) => ({ result: a + b })
}
}
})`,
},
];
}
}扩展工具有命名空间——math 扩展的 add 工具在模型工具集中变为 math_add。
向模型提供 createExtensionTools,使其可动态加载扩展:
import { createExtensionTools } from "@cloudflare/think/tools/extensions";
export class MyAgent extends Think {
extensionLoader = this.env.LOADER;
getModel() {
/* ... */
}
getTools() {
return {
...createExtensionTools({ manager: this.extensionManager }),
...this.extensionManager.getTools(),
};
}
}import { createExtensionTools } from "@cloudflare/think/tools/extensions";
export class MyAgent extends Think<Env> {
extensionLoader = this.env.LOADER;
getModel() {
/* ... */
}
getTools() {
return {
...createExtensionTools({ manager: this.extensionManager! }),
...this.extensionManager!.getTools(),
};
}
}这会向模型提供两个工具:
load_extension— 从 JavaScript 源码加载新扩展list_extensions— 列出当前已加载扩展
扩展可在清单中声明上下文块,自动注册到 Session:
getExtensions() {
return [{
manifest: {
name: "notes",
version: "1.0.0",
permissions: { network: false },
context: [
{ label: "scratchpad", description: "Extension scratch space", maxTokens: 500 },
],
},
source: `({ tools: { /* ... */ } })`,
}];
}上下文块注册为 notes_scratchpad(以扩展名命名空间)。