别再让 Agent 从网页残渣里猜答案：用 Agentize 为文档站建立可控的语义查询接口
给 AI Agent 接入产品文档，看似只要给它一个网站地址；真正跑起来后，问题往往出在网页并不是为机器检索设计的。Agent 得先从搜索结果或 sitemap 猜测入口，下载 HTML，去掉导航、页脚、弹窗和脚本，再判断一段文字是否仍然有效。一次问答可能变成多次页面请求，最终拿到的还是缺少出处、混着页面装饰的片段。
Agentize 提供的是另一条路径：网站所有者在构建阶段声明哪些内容可以被索引，工具在本地计算嵌入并生成索引；部署后，站点在自己的域名下提供 /agents/* 路由。Agent 通过发现、搜索和资源读取三步获得规范化 Markdown、canonical URL 与匹配片段，而不是自己爬站、清洗 HTML。这不是要取代浏览器或搜索引擎，而是为“我控制的网站，希望 Agent 准确读取我声明的资料”建立一层一手接口。
为什么 llms.txt 还不够
把概要写进 llms.txt 对小型站点很有用，但它更像人工维护的目录或说明书：内容一多，就会遇到分段、筛选、更新和精确引用的问题。Agentize 的目标不是让模型读一份更长的静态文本，而是把站点内已选择的资源做成可查询集合。
一次 POST /agents/search 的返回可包含资源 ID、页面 URL、标题、描述、类型、集合、更新时间、相关度分数及命中摘录；随后 GET /agents/resources/:id 可以返回完整资源，客户端还可通过 Accept: text/markdown 请求 Markdown。这样，检索结果不只告诉 Agent“可能在哪一页”，还保留了发布者给出的规范链接，方便后续引用或再核验。
这里有一个重要边界：索引结果对“发布者声明的内容”具有一手性，并不自动证明其中每一句话都客观正确。涉及价格、合规、兼容性或安全承诺时，Agent 仍应打开 canonical URL、查看当前条款，必要时交叉验证独立来源。把这层边界写进 Agent 的工作流，能避免把内部检索接口误当作事实裁判。
从 Markdown 文档开始，先跑通最小闭环
Agentize 当前 npm 包为 @nicolasakf/agentize，需要 Node.js 22 或更高版本，并使用 pnpm。下面的流程适合已把文档放在仓库 content/ 目录的 Node/Next.js 项目：
pnpm add @nicolasakf/agentize pnpm agentize init
初始化后，在 agentize.config.ts 中声明站点身份与允许索引的 Markdown/MDX 源。不要把“能被构建工具读到”的目录全部塞进索引；这里应该是有意公开、且由团队维护的知识范围。
import { defineConfig, markdown } from "@nicolasakf/agentize";
export default defineConfig({
site: {
name: "Example Docs",
origin: "https://docs.example.com",
description: "Example 的官方产品文档",
},
sources: [
markdown({
root: "content",
include: ["**/*.{md,mdx}"],
}),
],
});
接着先检查、再构建、最后启动服务：
pnpm agentize check pnpm agentize build pnpm agentize serve
check 的价值不只是“配置能否通过”。它会验证资源、隐私排除规则、资源关系以及 Next.js 路由覆盖；应把它放进 CI，而不是等部署后才发现某个敏感目录或动态页面没有按预期处理。首次构建会下载固定版本的本地嵌入模型；后续构建会复用模型及内容寻址的嵌入，因此修改少量文档时不必对全部内容重复嵌入。
本地服务启动后，可先访问发现端点确认路由已经由宿主应用暴露：
curl http://127.0.0.1:4242/agents
再做一次真实搜索。查询请求只发送到你部署的站点接口；README 明确说明，Agentize 不会把受索引内容或 Agent 查询发送给托管 AI 提供商，嵌入在构建时本地计算。
curl https://docs.example.com/agents/search \
-H "content-type: application/json" \
-d '{"query":"是否支持企业单点登录？","limit":5}'
搜索得到资源 ID 后，再读取对应资源，而不要让 Agent 根据摘录直接下结论：
curl -H "Accept: text/markdown" \ https://docs.example.com/agents/resources/docs:saml
这套“搜索定位、读取原文、保留 URL”的顺序尤其适合支持工程和文档问答 Agent。它降低了从页面噪声中抽取答案的成本，也让调用链能记录查询对应了哪个一手页面。
把接口接进 Agent 前，定义检索策略与失败回退
接口存在不等于 Agent 就会正确使用它。比较稳妥的做法是在系统提示或工具说明中定义优先级：遇到站点内的产品文档、集成说明和支持问题时，先访问 /agents 做能力发现；用搜索端点取得候选；对准备引用或据此执行的结论，必须再读取资源全文与 canonical URL。搜索摘录适合召回，不适合替代上下文。特别是“是否支持”“默认是否开启”“当前限制是什么”这类问题，很容易因摘录只命中旧段落而被过度概括。
过滤器是减少这种错误的关键。协议支持按资源类型、集合、标签和语言筛选；站点设计时应让这些元数据对应真实的信息架构。例如将产品文档、API 参考、迁移指南和博客文章划为不同 collection，让 Agent 处理故障排查时优先选 documentation，而不是把营销页或旧公告与当前接口说明混在同一结果集。updatedAt 可以帮助客户端提示资料新旧，但它不能代替发布流程：内容更新后仍要重新 build 并部署索引，才能让检索结果反映最新状态。
还要保留失败回退。/agents/* 临时不可用、资源未被站点纳入索引、或 Agent 需要查看真实渲染页面时，应允许它回到普通浏览，而不是把“接口没有结果”解释成“站点没有该功能”。反过来，页面爬取得到的结论也不应覆盖受控接口提供的规范资源，除非明确记录了冲突和复核原因。将这两条路径都记入调用日志，团队才能分辨答案来自发布者声明、网页解析，还是外部检索。
对于多语言文档，建议把语言作为资源元数据而非仅靠文件目录猜测。中文提问可以先查中文 collection；没有命中时再降级到英文原文，并在回答中明确指出原始资料的语言。对带版本的 API，资源 ID 与 canonical URL 也应稳定且可追踪；不要让同一 ID 在不同发布中悄悄改指向另一个版本，否则引用记录会失去可复现性。
动态数据、Next.js 与受保护知识库的取舍
Markdown 只是起点。产品目录、状态页或数据库里的已发布条目可以通过 defineResources 显式映射为资源。关键是映射函数必须输出路由、canonical URL、标题、摘要和 Markdown 内容；Agentize 故意不扫描任意 UI 源码并猜测哪些渲染文本“算官方”。这项限制看起来保守，实际避免了把测试文案、未上线组件或后台字段误暴露给检索接口。
对 Next.js，初始化会生成 App Router 的 catch-all 路由；构建脚本应把 agentize build 放在应用构建之前，并用 withAgentize 把生成产物和原生向量依赖带进服务端输出。由于本地查询嵌入与 USearch 依赖 Node 兼容环境，纯静态或 edge-only runtime 不在当前目标范围内。部署前应在目标平台实测构建产物，而不是只在开发机上验证。
内网场景更需要克制。设置 access: { mode: "protected" } 后，宿主应用必须保护完整的 /agents/* 路由族；Next.js 集成可在 authorizeRequest 中复用公司自己的鉴权逻辑。若把 sidecar 放在反向代理后，只有当代理确实覆盖 /agents 及其所有子路径时，才使用 --trust-upstream-protection。工具不会替你实现账号、角色和文档级权限，因此不应把 HR、财务或团队专属资料混入“所有已登录员工都可读”的共享索引。
另一个容易遗漏的风险是构建产物。生成 bundle 包含完整索引文本与嵌入；对受保护站点，它应按私有应用数据处理，绝不能作为静态文件公开。文档里的 draft: true 默认不进入索引，noindex: true 也默认排除；即便如此，发布前仍要把 check 输出和实际 bundle 纳入安全审查。
适合什么团队，不适合什么团队
如果你的站点规模很小、资料不常变，维护清晰的 llms.txt 或直接给 Agent 几个稳定页面，可能更简单。若内容本来就不可信、没有明确 owner，先解决文档治理也比先做语义索引重要。
但当团队同时满足三个条件时，Agentize 值得尝试：有持续维护的官方文档或产品数据；希望 Agent 在自己的域名内查询；并且愿意明确公开范围、鉴权边界和部署责任。它将“让 Agent 访问网站”从无约束爬取变成一个可构建、可校验、可审计的接口。先从一组公开 Markdown 文档和一个具体问答场景开始，确认资源 URL、更新策略与权限模型，再逐步接入动态资源，通常比一开始把整站交给 Agent 更可靠。