@dbx-tools/appkit-web-搜索

添加 web_search 财务报告和审定财务报表 web_fetch 到 AppKit 或 Mastra 后端. web_search 运行在 Databricks 模型服务本地网络搜索工具数字 : 模式搜索网络服务器侧并返回一个合成的答案加 它使用的源没有第三方搜索 API 密钥. web_fetch 读取单页 结束 被冲动。 。 。 .

快开始

注册插件并将其工具交给代理 :

import { createApp, server } from "@databricks/appkit";
import { webSearch } from "@dbx-tools/appkit-web-search";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const researcher = agents.createAgent({
  instructions: "Search the web, then read the most relevant sources.",
  async tools(plugins) {
    return { ...(await plugins["web-search"].toolkit()) };
  },
});

await createApp({
  plugins: [server(), webSearch(), mastra({ agents: { researcher } })],
});

登记规定:

• AppKit 插件注册可以解析并登录启动时的有效策略 .
• 两个马斯特拉工具: web_search (回答+引用)和 web_fetch (页) 作为可读文本或原始 HTML 的内容,加上与 AppKit 代理设备相同的一对 通过插件的工具 ToolProvider。 。 。 .
• web_search 解决一个专用的网络搜索能力模型(默认情况下的Gemini, 然后GPT)独立于呼叫代理聊天模式(可能不会) 支持网页搜索)。 闲置名称( O)"gemini", (中文(简体) ), "gpt"绒毛相接现场 通过目录 @dbx-工具/型号。 。 。 .
• 内置提供者 - > 请求分解地图( OpenAI Response API) {"tools":[{"type":"web_search"}]}双子聊天完成 {"google_search":{}}, (中文(简体) ), 每一供应商均享有 WEB_SEARCH_TOOLS 设置.
• 命名的 URL 策略 (S)allowlist 或者说 unrestricted) 在一个普通的许可列表之上 发展于 @dbx-tools/路径是因为 match 匹配者 : web_search 安静 过滤器不允许引用, web_fetch 拒绝不允许的 URL,并且 模式在启动时记录.
• 每个工具的审批标志:每一次呼叫的门,或(用于) web_fetch只有电话 其 URL 匹配图案, 映射到 Mastra 的 requireApproval。 。 。 .
• 每一次外出通话都通过AppKit execute() 链(用户缓存, 以颤抖的后退、超时和遥测方式重试) AbortSignal。每个插件实例都将其政策和执行器分开,所以 在一个过程中的多个应用仍然被隔离.
• 页面和倒置结果 HTML 使用解析器支持的文本转换和选择器, 包括完整的 HTML 实体解码和错误的标记恢复.

选择网络提供者

AppKit没有第一党的网页搜索或页面图面. 当 代理商需要在打开的网页上查找一些东西,或者读取用户粘贴的URL, 政策层( 允许列表 + 可选批准 ) , 围绕它进行部署 控制哪些站点可以到达 哪些站点需要暂停 这个 网络搜索工具解决自己的网络搜索能力模型,所以是一个代理 运行在任何聊天模式上(包括一个没有网络搜索)仍然可以搜索. 这个 提供 Mastra 工具和 AppKit 插件, 如 @dbx-tools/电子邮件。 。 。 .

当支持的 GPT 或双子座端点是时, 使用本地 Databricks 网络搜索 已部署。 使用 DuckDuckGo 刮后退 只有当没有能达到的终点时 可获取和未合成的搜索结果是可以接受的。 使用 web_fetch (单位:千美元) 特定的公用HTTPS页面. 对于索引化的应用程序数据,使用 @ dbx 工具/ 搜索 换句话说.

配置 AppKit 插件

import { createApp, lakebase, server } from "@databricks/appkit";
import { webSearch } from "@dbx-tools/appkit-web-search";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const researcher = agents.createAgent({
  instructions: "Research questions using web_search, then read sources with web_fetch.",
  async tools(plugins) {
    return { ...(await plugins["web-search"].toolkit()) };
  },
});

await createApp({
  plugins: [
    server(),
    lakebase(),
    webSearch({
      model: "gemini", // defaults to Gemini, then GPT, when omitted
      allowedUrls: ["*.databricks.com", "docs.example.com"],
    }),
    mastra({ agents: researcher, storage: true }),
  ],
});

plugin.webSearch() 解析配置( 覆盖) , 编译 URL 策略,以及 提供其工具所使用的执行器。 App-Integrated Mastra 代理可以消费 上面显示的本地插件工具包,它保留了该插件的政策, OBO范围,和AppKit执行链. 启用后批准需要 Mastra 存储,所以注册 lakebase() 或配置 Mastra 插件中的存储.

该插件也是 AppKit ToolProvider,所以本地代码代理可以 没有马斯特拉 就拿两个一样的工具 把定义放在 server/agents/researcher/agent.ts 所以AppKit发现了它:

import { createAgent } from "@databricks/appkit/beta";

export default createAgent({
  name: "Researcher",
  default: true,
  model: "databricks-gpt-6-1-sol",
  instructions: "Research questions with web_search, then read sources with web_fetch.",
  tools: (plugins) => ({ ...plugins["web-search"].toolkit() }),
  skills: ["research-policy"],
});

将技能放在 server/agents/skills/research-policy/SKILL.md,注册本地 agents() 与 没有被贬值的代理映射,并构建一个编译的本地代理服务器:

import { appkitServerConfig } from "@databricks/appkit/tsdown";

export default appkitServerConfig();

两个工具都有说明 effect: "read" ,并且需要用户上下文,而不需要 是自动不可继承的:一个代理人必须要求它们,因为 web_fetch 达到 不管模型产生什么URL.

土著体积技能作为服务校长运作。 0.81号 skillCredentialMode: "obo" 选项没有带线。 保持请求范围可写 技术,远程来源,同步的Graphiti发现, Sandbox/Monty, 马斯特拉记忆 和持久的批准 @dbx-tools/appkit-mastra。 。 。 .

选择网络搜索模式

本地的网络搜索工具只运行在某些模型上,它是提供者- 具体。 此套件解决了部署的终点 @dbx-工具/型号 并应用此命令:

1. 排名最高的网络搜索能力 双子座。 。 。 .
2. 没有双子座,有能力 常规 匹配呼叫/请求的模型.
3. 排名最高的能力 常规。 。 。 .
4. 任何额外的 modelFallbacks 搜索顺序.

当Databricks报告双子座网络搜索无法进行时,因为 跨区域处理已禁用, 插件压制双子座24小时 在此运行时间中, 透明地重试同一工具调用下一个 GPT 候选人.

DATABRICKS_SERVING_ENDPOINT_NAME 是 AppKit 模型的标准名称 服务装订,插件显示的就是字段,所以 app.yaml / 捆绑接线以其他方式到达此插件 . 请求是 model, 插件 model,并使用环境模型值 匹配双子座可用性检查后的调用. 当工具通过时 @dbx-tools/appkit-mastra时,主机注入 解决聊天模式, 压倒生成的任何不同模式参数 根据LLM.

模型解析度与现场工作空间目录相悖 @dbx-工具/型号,所以它只选一个终点 实际部署。 所配置的不存在的代号从不叫.

倒计时

首选的是本地工具 。 当工作空间没有部署时 GPT/ Gemini 端点( 所以本地网络搜索完全无法运行), 工具掉入 回到鸭子去刮去 got-scraping 因此它仍然返回结果 而不是错误。 设定倒计时结果 model 改为 "scrape:duckduckgo" 财务报告和审定财务报表 将物质装入 citations (没有模型合成一个答案, 这样 answer 是一个领先的结果。 默认启用 。 设定 scrapeFallback: false (或 WEB_SEARCH_SCRAPE_FALLBACK=0要求当地人 没有部署模型和出错.

插件从解析模型中选择提供者请求片段 : OpenAI GPT 使用响应 API {"tools":[{"type":"web_search"}]}双子座 使用顶级聊天补全字段 {"google_search":{}}。覆盖或扩展每个提供者的地图 页:1 webSearchTools 设置( env) WEB_SEARCH_TOOLS作为平台 进化 :

plugin.webSearch({
  model: "databricks-gemini-3-pro",
  webSearchTools: { gemini: { request: { google_search: {} } } },
});

没有代理搜索和获取

import { search, fetch, runtime, tool } from "@dbx-tools/appkit-web-search";
import { getExecutionContext } from "@databricks/appkit";

const webRuntime = runtime.createWebSearchRuntime({
  model: "gemini",
  allowedUrls: ["*.databricks.com"],
});

// web_search needs the OBO client + host from the active execution context:
const ctx = getExecutionContext();
const host = (await ctx.client.config.getHost()).toString();

const result = await search.runWebSearch(
  { query: "unity catalog lineage best practices" },
  webRuntime,
  { client: ctx.client, host },
);
// result.answer, result.citations, result.model

const page = await fetch.runWebFetch({ url: result.citations[0]!.url, format: "text" }, webRuntime);

使用直接的调用, 用于运行中的外观、 测试或管理流 不参与。 独立的Mastra工具厂也接受 runtime 或者说 config。它们从未发现或附加到进程-全局插件上 :

const webRuntime = runtime.createWebSearchRuntime({
  allowedUrls: ["*.databricks.com"],
});

const tools = {
  web_search: tool.webSearchTool({ runtime: webRuntime }),
  web_fetch: tool.webFetchTool({ runtime: webRuntime }),
};

明确传递运行时间或提供执行器给 createWebSearchRuntime。 。 。 .

限制可达到的 URL

import { allowlist } from "@dbx-tools/appkit-web-search";

const list = allowlist.toUrlAllowList(
  allowlist.parseAllowedUrls(["*.databricks.com", "docs.example.com/api/**"]),
);

list.allows("https://docs.databricks.com/aws/en/index.html"); // true
list.allows("https://evil.example.com/"); // false

每个条目都是由 @dbx-tools/路径是因为 match 选手. 主机条目( 无路径, 例如 ) databricks.com 或者说 *.databricks.com匹配 URL的主机名,而赤色主机也与其子域相匹配. 路径条目 (单位:千美元)docs.example.com/api/**)匹配主机+路径名. 执法不对称 设计 : web_search 引用被悄悄地过滤到允许的集合(即: 模型从不显示它无法取取的来源,而显式 web_fetch 以出错(一个可见的、可更正的错误)拒绝不允许使用的 URL . web_fetch 仅接受HTTPS中决心公开地址的目标 在每个重定向请求前重新应用两个检查 .

两种模式中哪一种是有效的,由 urlPolicy,并有效 模式在启动日志中 :

离开 urlPolicy 未设并随行 allowedUrls数字 : "allowlist" 当那里 是条目, "unrestricted" 当没有。 设定它来说明你是谁 意为. 两个矛盾在启动时失败 而不是悄悄地挑一个 边 : "allowlist" 没有条目,以及 "unrestricted" 包含条目.

// An open deployment, said out loud:
plugin.webSearch({ urlPolicy: "unrestricted" });

// A closed one:
plugin.webSearch({ urlPolicy: "allowlist", allowedUrls: ["*.databricks.com"] });

门呼叫请求批准

两个工具都默认运行,未经批准. 过 approval 到工具(或设置) 需要批准. true 每一个呼叫都关上门 一个 URL 模式(或 列表)只调用其 URL 匹配的门。 A 类 web_fetch 准确评价 相对于目标 URL,而 web_search (结果 URL 未知) 在呼叫之前)将一个图案门当作"接通每一个呼叫".

import { tool } from "@dbx-tools/appkit-web-search";

// Every fetch requires approval:
tool.webFetchTool({ approval: true });

// Only fetches of an internal domain require approval:
tool.webFetchTool({ approval: "*.internal.example.com" });

// The same thing, with the mode named:
tool.webFetchTool({ approval: { mode: "urls", patterns: ["*.internal.example.com"] } });

// Plugin toolkit default:
plugin.webSearch({ approval: ["*.internal.example.com", "*.corp.example.com"] });

// Standalone tool config:
tool.webFetchTool({ config: { approval: ["*.internal.example.com"] } });

每种拼写都符合三种模式之一({ mode: "none" }, (中文(简体) ), { mode: "always" },或 { mode: "urls", patterns }),这是什么 解析了配置载体和启动日志报告。 批准语法与 允许列表,所以两种策略读取相同.

配置

分辨率顺序是明确的配置,先是环境变量,再是a 内建默认值.

该插件的 maxCitations 编号 : fetchMaxLength 硬盖:每一次呼叫请求 可能缩小范围,但不会超过范围.

每一次外出通话,包括服务POST,一个页面取取取,和刮取 倒置,通过插件运行 execute() 链,所以所有三个都缓存, 重审了紧张的后退 超时 追踪 缓存已命名空格 每个用户,所以一个半结果 从来没有交叉身份。 见 defaults.ts 用于TTL和重试预算以及为什么选择每个预算.

OpenAI 响应网页搜索流本地搜索、页面阅读和完成 状态通过 Mastra 工具写入器。 常用工具片片片更新 在搜索运行时。 已完成的应对有效载荷仍然是工具成果.

要求: 本地网络搜索工具运行在付费的 GPT / 双子座 为跨区域处理的终点服务。 无法使用 为外部型号或根据HIPAA/BAA规定提供的吞吐量。 见 页:1 数据砖文件。 。 。 .

模块

• plugin - 说吧 WebSearchPlugin, (中文(简体) ), webSearch() AppKit 插件厂,以及 应用程序 ToolProvider 执行.
• tool - 说吧 webSearchTool() 编号 : webFetchTool() 马斯特拉的工具.
• defaults - 缓存/ 重试/ 超时设置 和每一个背后的推理.
• search - 说吧 runWebSearch() 在 Databricks 本地网络搜索工具之上.
• provider - 提供者检测 + 提供者 - > 工具谱图.
• scrape - 说吧 runScrapeSearch() Duck Duck 退后加解析器后置 parseDdgHtml() 对没有本地网络搜索模式的工作空间进行结果提取.
• fetch - 说吧 runWebFetch() 被冲了过来.
• html-text - 说吧 htmlToText() 编号 : htmlFragmentToText() 编号 : decodeHtmlEntities()共享 fetch 鸭子去刮倒回落.
• runtime - 单独的运行时间建造和执行: createWebSearchRuntime(), (中文(简体) ), createResolvedWebSearchRuntime(), (中文(简体) ), 财务报告和审定财务报表 executeRead()。 。 。 .
• config JSON计划, resolveWebSearchConfig(), URL 策略 和批准帮助者.
• allowlist - URL 允许列表解析/编译 @dbx-tools/path。 。 。 .
• schema - zod工具合同和推断类型.

给这个包配对 @dbx-tools/appkit-mastra (英语) 应添加 工具,并通过 @dbx-工具/型号。 。 。 . 使用 @dbx-tools/电子邮件 对兄弟批准的工具模式.