knownagents/node-sdk
GitHub: knownagents/node-sdk
Known Agents 官方 Node.js SDK，用于追踪和分析网站及 API 的 AI agent 与机器人流量，并提供动态 robots.txt 生成与 agent 身份验证功能。
Stars: 8 | Forks: 0
# 已知 Agents SDK
[](https://npmjs.org/package/@knownagents/sdk)
本库为使用 TypeScript 或 JavaScript 编写的服务端 Node.js 应用程序提供了访问 [Known Agents](https://knownagents.com/) 的便捷方式。
## 安装包
通过 NPM 下载并引入该包：
```
npm install @knownagents/sdk
```
## 初始化客户端
[注册](https://knownagents.com/sign-up) Known Agents，创建一个项目，并从项目的设置页面复制您的访问 token。然后，创建一个 `KnownAgents` 实例。
```
import { KnownAgents } from "@knownagents/sdk"
const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
```
## 如何设置 Agent 与 LLM 分析（[完整文档](https://knownagents.com/docs/analytics)）
实时洞察浏览您网站、REST API 和 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器的 [AI agent 和其他机器人](https://knownagents.com/agents) 的隐藏生态系统。衡量来自 ChatGPT、Perplexity 和 Gemini 等 AI 聊天和搜索平台的人类流量。
### 跟踪页面浏览和 REST 调用
要收集页面浏览和 REST API 分析数据，请使用传入的 Node.js 请求和响应调用 `trackPageviewOrRESTCall`。
```
knownAgents.trackPageviewOrRESTCall(request, response)
```
对于返回 [ACP (Agentic Commerce Protocol)](https://www.agenticcommerce.dev/) 或 [UCP (Universal Commerce Protocol)](https://ucp.dev/) 商业元数据的 REST API，请包含响应主体：
```
knownAgents.trackPageviewOrRESTCall(request, response, {
restACPResponseBody: acpResponseBody
})
```
```
knownAgents.trackPageviewOrRESTCall(request, response, {
restUCPResponseBody: ucpResponseBody
})
```
SDK 会等待响应完成后，发送状态、标头、持续时间以及任何商业元数据。敏感标头会被自动过滤。
#### 尽可能使用中间件
如果您的框架支持中间件，请在中间件中调用 `trackPageviewOrRESTCall`，以便在一个统一的位置跟踪页面浏览和 REST 调用。[MCP](https://modelcontextprotocol.io/) 请求会被自动跳过。
```
import express from "express"
import { KnownAgents } from "@knownagents/sdk"
const app = express()
const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
app.use((request, response, next) => {
knownAgents.trackPageviewOrRESTCall(request, response)
next()
})
app.get("/", (request, response) => {
response.send("Hello, world!")
})
app.listen(3000, () => console.log("Server running on port 3000"))
```
### 跟踪 MCP 调用
对于使用 `StreamableHTTPServerTransport` 的 [MCP](https://modelcontextprotocol.io/) 服务器，请在连接 transport 之后、transport 处理请求之前调用 `trackMCPCall`。
对于返回 [ACP](https://www.agenticcommerce.dev/) 或 [UCP](https://ucp.dev/) 商业元数据的 MCP 调用，SDK 会自动捕获相关的货币和总金额。
请在您的 MCP HTTP 处理程序中按以下顺序使用：
```
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined
})
await mcpServer.connect(transport)
knownAgents.trackMCPCall(request, response, transport)
await transport.handleRequest(request, response, parsedBody)
```
如果同一个 transport 实例处理并发请求，请改用 `trackVisits`。
### 批量处理
对于高流量网站，请使用 `trackVisits` 将多个访问批量处理并定期发送（例如每 30 秒一次）。`trackVisits` 也可以批量处理 MCP 访问；如果这样做，请在每个 `VisitRequest` 中包含 MCP 字段，并且不要对相同的请求重复调用 `trackMCPCall`。以下是一个 Express 示例：
```
import express from "express"
import { KnownAgents, type VisitRequest } from "@knownagents/sdk"
const app = express()
const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
const visits: VisitRequest[] = []
app.use((request, response, next) => {
const created = new Date()
response.once("finish", () => {
visits.push({
request_path: request.url,
request_method: request.method,
request_headers: request.headers,
response_status_code: response.statusCode,
response_headers: response.getHeaders(),
response_duration_in_milliseconds: Date.now() - created.getTime(),
created: created.toISOString()
})
})
next()
})
setInterval(() => {
const batch = visits.splice(0)
if (batch.length > 0) {
knownAgents.trackVisits(batch)
}
}, 30000)
```
### 测试您的集成
- 打开您项目的设置页面
- 点击 **Send a Test Visit**
- 点击 **Realtime**
如果您的网站已正确连接，您应该会在几秒钟内在实时时间轴中看到来自 Known Agent 的访问。
## 如何设置自动 Robots.txt（[完整文档](https://knownagents.com/docs/robots-txt)）
保护敏感内容免受未经授权的访问和抓取。生成一个持续更新的 robots.txt，使其自动与指定类别中[所有当前和未来的机器人](https://knownagents.com/agents)保持同步。
使用 `generateRobotsTXT` 函数。选择您想要屏蔽的 `AgentType`，并指定一个字符串来标明哪些 URL 是被禁止访问的（例如使用 `"/"` 禁止所有路径）。
```
import { AgentType } from "@knownagents/sdk"
const robotsTxt = await knownAgents.generateRobotsTXT([
AgentType.AIDataScraper,
AgentType.AIDataProvider,
AgentType.Scraper,
AgentType.SEOCrawler
], "/")
```
返回值是一个纯文本的 robots.txt 字符串。定期生成 `robotsTxt`（例如每天一次），然后将其缓存并由您网站的 `/robots.txt` endpoint 提供服务。
## 如何使用 Agent 识别（[完整文档](https://knownagents.com/docs/identification)）
使用 `identifyAgent` 和 `identifyAgents` 函数，通过 Web Bot Auth（HTTP 消息签名）、IP 匹配或其他可用方法，从网络请求中识别和验证 [AI agent 和机器人](https://knownagents.com/agents)。这对于实施基于已验证 agent 身份的访问策略或丰富您自己的数据集非常有用。
### 识别单个请求
使用传入的请求调用 `identifyAgent`。
```
const identification = await knownAgents.identifyAgent(request)
if (identification.result === "verified") {
handleVerifiedAgent(identification)
} else if (identification.result === "verification_failed") {
handleFailedVerification(identification)
}
```
### 识别多个请求
使用 `identifyAgents` 一次性识别多个请求：
```
const identifications = await knownAgents.identifyAgents([
{
id: "request-1",
request_headers: request1.headers
},
{
id: "request-2",
request_headers: request2.headers
}
])
```
这些函数会返回一个（或一组）包含以下字段的对象：
- `id`：来自请求的标识符（如果提供）
- `result`：识别结果：
- `"verified"`：该 agent 已被识别并验证
- `"verification_failed"`：该 agent 已被识别，但无法验证
- `"unknown_agent"`：该 agent 不在我们的数据库中
- `"not_verifiable"`：该 agent 无法被验证（没有可用的验证方法）
- `agent_id`：该 agent 的唯一 ID（如果已识别）
- `agent_token`：该 agent 的名称（例如 `"Googlebot"`）（如果已识别）
- `agent_url`：该 agent 的文档 URL（如果已识别）
- `agent_type_name`：该 agent 的类型（例如 `"AI Agent"`）（如果已识别）
- `operator_name`：该 agent 背后的公司（例如 `"Google"`）（如果已识别）
## 环境要求
支持 TypeScript >= 4.7。
支持以下运行时：
- Node.js 18 LTS 或更高版本（[非 EOL 版本](https://endoflife.date/nodejs)）
## 支持
如有任何问题、Bug 或建议，请[提交 issue](https://github.com/knownagents/node-sdk/issues)。
标签：AI分析, GNU通用公共许可证, LLM跟踪, MITM代理, Node.js, 机器人流量, 自动化攻击