跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

工具

最后更新 查看 MarkdownAgent 设置

Think 在每轮次提供内置工作区文件工具,并提供自定义工具、代码执行与动态扩展的集成点。

工具合并顺序

每轮次 Think 从多个来源合并工具。若名称冲突,后出现的来源覆盖较早的:

  1. 工作区工具 — read、ls、find、grep、write、edit、delete,以及配置后可用的 exec 和 publish(内置)
  2. getTools() — 你的自定义服务端工具
  3. 扩展工具 — 已加载扩展的工具(以扩展名前缀)
  4. 会话工具 — set_context、load_context、search_context(来自 configureSession)
  5. 技能工具 — activate_skill、read_skill_resource、run_skill_script(来自 getSkills();请参阅 Agent Skills)
  6. MCP 工具 — 当 includeMcpTools 为 true 时,来自已连接 MCP 服务器
  7. 客户端工具 — 来自浏览器(请参阅 客户端工具)

工具归执行当前轮次的代理所有。对于父子代理编排,请使用将代理用作工具,而不是通过 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

使用 exec 运行代码

默认的 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。

从 @cloudflare/shell 升级

早期版本的 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 仅在本轮次添加额外工具(合并到现有工具之上)。

MCP 工具

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 reuse
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 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。

LLM 驱动扩展

向模型提供 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(以扩展名命名空间)。

这篇文档对您有帮助吗?