arcjet

Arcjet

目录

• 为应用添加 Arcjet 防护
• 选择防护类型
• 资源

适用于 LangChain、CrewAI、OpenAI Agents、Claude Agent SDK、Claude Managed Agents、Strands Agents 和 Google ADK 的 Python Guard 适配器均为专用技能（参见第 3 步）。发布在 npm 上的 JS Guard 适配器按文件放在 references/guards_js_*.md 中。JS Cloudflare Think 是一项专用技能（发布为 @arcjet/guard，并依赖同级的 @cloudflare/think）。通用基础知识请参阅 references/guards_javascript.md 和 references/guards_python.md。

为应用添加 Arcjet 防护

检查清单

• **第 1 步：**确认语言受支持（仅限 JS/TS、Python 或 Go——如果不受支持，请停止）
• **第 2 步：**连接到 Arcjet 平台（CLI → MCP → 手动设置 Console）
• **第 3 步：**识别防护类型并阅读相应的参考文件
• **第 4 步：**实现防护（使用独立客户端文件、正确的 SDK 和正确的模式）
• **第 5 步：**验证决策是否正常触发（先发起一次实际调用，然后检查 CLI / MCP / Console）

第 1 步：检查语言支持情况

如果项目的服务端代码不是 JavaScript、TypeScript、Python 或 Go，请在聊天中告知用户 Arcjet 目前尚不支持该语言。不要修改项目，不要编写 NOTES.md，也不要虚构软件包。只需告知用户，然后停止。

第 2 步：将 ARCJET_KEY 写入项目的环境文件

编写任何代码之前，项目的环境文件中必须有一个有效的 ARCJET_KEY。不要先编写 Arcjet 代码，然后“把密钥留作 TODO”——这只会产生无法使用的代码。先获取密钥，再接入代码。

**Agent 身份（需要注册自己而非通过人工浏览器登录时）：**严格遵循 https://arcjet.com/auth.md。不要虚构注册、认领或令牌交换流程，也不要输出机密信息。

按优先顺序：

1. Arcjet CLI（首选）。先检查是否已登录，然后获取密钥。
2. Arcjet MCP 服务（端点：https://api.arcjet.com/mcp）——适用于内置 MCP 的客户端。参见 references/mcp.md。
3. 手动操作（最后手段）：告知用户从 https://console.arcjet.com 获取密钥。

CLI 引导（常规方式）

npx -y @arcjet/cli@latest auth status        # is the user already signed in?
# if not signed in:
npx -y @arcjet/cli@latest auth login         # browser device flow, see references/cli.md

npx -y @arcjet/cli@latest teams list --output json --fields id,name
npx -y @arcjet/cli@latest sites list --team-id <team_id> --output json --fields id,name
# if no suitable site exists:
npx -y @arcjet/cli@latest sites create --team-id <team_id> --name "<project>"

npx -y @arcjet/cli@latest sites get-key --site-id <site_id> --output json --fields key

将 key 值写入项目的环境文件，格式为 ARCJET_KEY=ajkey_...。遵循项目现有的做法，包括文件名、.env.example 配套文件和 .gitignore 条目。如果项目尚无约定，则采用框架预期的做法，并将环境文件添加到 .gitignore。绝不要在源代码中硬编码密钥。

有关 npx 以外的安装选项、Agent 模式标志和完整命令参考，请参阅 references/cli.md。

使用项目的包管理器安装 SDK

确定所需的 SDK（参见第 3 步）后，使用项目现有的包管理器进行安装：npm install、pnpm add、yarn add、bun add、pip install、uv add、poetry add 或 go get。不要手动编辑 package.json / requirements.txt / go.mod 并猜测版本：写死的版本会过时（@arcjet/next 当前版本为 1.13.0；Python arcjet 版本为 1.2.0；Go 必须使用模块标签，而非复制来的伪版本），而且锁文件和模块元数据也不会更新。让包管理器选择并锁定实际版本。

第 3 步：识别防护类型并阅读参考资料

确定适用的防护类型：

	基于请求	Guard
适用场景	代码中有 HTTP 请求对象（Express req、Next.js Request、FastAPI Request）	没有 HTTP 请求（工具调用、MCP 处理程序、队列工作器、后台任务、Agent 循环）
JS/TS SDK	框架适配器，例如 @arcjet/next、@arcjet/node、@arcjet/fastify	@arcjet/guard
Python SDK	arcjet（使用 arcjet() / arcjet_sync()）	arcjet（使用 launch_arcjet() / launch_arcjet_sync()）
Go SDK	github.com/arcjet/arcjet-go（使用 NewClient）	github.com/arcjet/arcjet-go（使用 NewGuardClient）
入口点	protect(request) / Protect(ctx, r)	核心 JS guard({ label, rules })；Python guard(label, …)；Go Guard(ctx, request)。封装器使用 action，而不是 label。

单个项目可以同时使用两者——例如，在 API 路由中使用基于请求的方式，在 Agent 工具调用中使用 Guard。如果项目已经使用受支持的 Agent 框架，优先使用官方封装器，而不是手动封装每个工具。在 Python 中，加载专用技能（见下表）——不要对每个可调用对象都直接使用 guard()，也不要使用 JS @arcjet/guard/... 路径。在 JavaScript 中，加载基础指南以及 JS 表格中的恰好一个适配器——不要加载其他同级适配器。Cloudflare Think 应从该表加载 integrate-arcjet-guard-cloudflare-think，而不是 guards_js_*.md 文件，也不要使用 @arcjet/guard/vercel-ai/v7。安装已发布的 @arcjet/guard 以及对等依赖 @cloudflare/think。在 Go 中，如果项目使用 Microsoft Agent Framework，则加载该框架的技能；否则使用 Go Guard 参考中的 GuardAction。

编码 Agent 钩子（Claude Code / GitHub Copilot）是第三种路径。 这里没有 SDK，也不需要调用 guard()。发布一条附加到 Execute on（Tool call、Prompt 或 Model switch）的策略即可启用它。按照 https://docs.arcjet.com/coding-agents 中的说明安装 HTTP 钩子——复制模板，不要自行编造 URL。钩子 URL 不得包含策略名称，也不得带有 ?surface=（托管设置会触达 CLI、IDE、桌面应用和云端；硬编码 cli 会导致大多数流量标记错误）。通过 MCP 编写策略（references/mcp.md）。

请留意以下常见误分类：

• MCP 服务：“服务”这个词容易造成误解。MCP 工具不会接收 HTTP 请求——它们由 MCP 客户端通过 stdio 或 SSE 调用。应使用 Guard，而不是基于请求的方式。
• 后台任务／队列消费者：执行保护的位置没有 HTTP 请求。应使用 Guard。
• 服务器操作／基于 HTTP 的 RPC（Next.js 服务器操作、tRPC）：底层确实存在 HTTP 请求。应使用基于请求的方式。
• 请求处理程序中的 Agent 工具调用：如果要按用户和路由进行限流，基于请求的方式即可。如果要为每个工具设置独立于任何 HTTP 边界的预算，则应在工具调用处使用 Guard。

请阅读相应的参考文档：

• 基于请求的 JS/TS：references/requests_javascript.md
• 基于请求的 Python：references/requests_python.md
• 基于请求的 Go：references/requests_go.md
• Guard JS/TS 基础指南：references/guards_javascript.md — 然后从该文件的表格中加载恰好一个适配器文件（以该表为准；不要在此处复制）
• Guard Python：references/guards_python.md
• Guard Go：references/guards_go.md

如果项目已经使用官方 JS Agent 框架，请打开基础指南文件，并从其表格中加载恰好一个适配器。不要打开同级适配器。Cloudflare Think 是专用技能例外：请从表格中加载该技能。

如果项目已经使用官方 Python Agent 框架，请加载专用技能，而不是加载过去位于 Python Guard 参考文档中的冗长适配器章节：

Python 框架	导入	技能
LangChain（BaseTool / create_agent）	arcjet.guard.langchain	集成 Arcjet Guard LangChain
CrewAI	arcjet.guard.crewai	集成 Arcjet Guard CrewAI
OpenAI Agents	arcjet.guard.openai_agents	集成 Arcjet Guard OpenAI Agents
Claude Agent SDK	arcjet.guard.claude_agent_sdk	集成 Arcjet Guard Claude Agent SDK
Claude Managed Agents	arcjet.guard.claude_managed_agents	集成 Arcjet Guard Claude Managed Agents
Strands Agents	arcjet.guard.strands_agents	集成 Arcjet Guard Strands Agents
Google ADK（LlmAgent / Runner）	arcjet.guard.google_adk	集成 Arcjet Guard Google ADK

如果项目使用 Go，且已经使用 Microsoft Agent Framework for Go，请加载专用技能：

Go 框架	接口	导入	技能
Microsoft Agent Framework	functool、mcptool、agent.Config.Middlewares	github.com/arcjet/arcjet-go/agentframework	集成 Arcjet Guard Agent Framework Go

这些参考资料说明了仅凭源代码无法推断的架构决策和模式。如需了解准确的 API 签名，请阅读已安装软件包的类型定义和文档注释。

第 4 步：实现防护

遵循第 3 步参考文件中的模式。核心原则：

基于请求（HTTP 路由）：

• 在处理程序外创建共享客户端，并将 Shield 作为基础规则。使用语言参考中规定的确切构造函数和规则名称。JS HTTP 规则若省略 mode，默认值为 DRY_RUN；若要强制执行，请传入 mode: "LIVE"。Python HTTP 工厂函数必须指定 mode=（省略时会触发 TypeError）。Go HTTP Protect 规则也默认采用试运行模式；若要强制执行，请设置 Mode: arcjet.ModeLive。
• 在 JavaScript/TypeScript 中，创建一个 arcjet() 客户端，并使用 withRule() 添加特定路由的额外规则，以便克隆客户端共享决策缓存。检查 decision.isDenied()。同级的 arcjet() 构造函数不会共享缓存。detectBot 必须且只能指定 allow 或 deny 中的一个（两者皆未指定或同时指定都会触发异常）。
• 在 Python 中，创建一个 arcjet() / arcjet_sync() 客户端，并使用 with_rule() 添加特定路由的额外规则，以便克隆客户端共享 DecisionCache。检查 decision.is_denied()。同级构造函数不会共享缓存。
• 在 Go 中，在包级别创建一个 NewClient。WithRule() 会派生出特定路由的客户端，这些客户端与父客户端共享缓存；它会返回 (*Client, error)，因此请处理初始化错误。检查 decision.IsDenied()。单独调用 NewClient 不会共享缓存。
• 在每个路由处理程序中调用一次 protect() / Protect()（每个请求一次），不要在应用级中间件中调用。
• 将拒绝原因映射到 HTTP 响应。只针对会返回不同响应的原因进行分支——如果 Shield 专属分支返回的状态码与默认的 403 相同，就没有意义。
• 将语言对应的 userId 特征选择器添加到需要它的特定规则中，然后在执行保护时传入可信且已通过身份验证的用户 ID。除非可信代理会剥离并重写客户端可控的标头，否则切勿按此类标头进行速率限制。
• 将客户端 IP 的来源视为安全配置。如果没有可用的公共地址，JavaScript、Python 和 Go 可能会回退到常见的转发标头，并在每个 SDK 客户端实例的生命周期内产生一条 client_ip_provenance="unverified-header" 警告。配置所有可信代理，并确认应用只能通过会覆盖或安全追加转发标头的基础设施访问。切勿将客户端可控的标头复制到手动覆盖项中来消除警告。
• 如果应用已有独立可信的客户端 IP，请显式传入：ipSrc（JS）、ip_src（Python；同时在构造客户端时设置 disable_automatic_ip_detection=True），或 WithIPSrc（Go）。SDK 会拒绝格式错误的值，但 JS 会将空的 ipSrc 视为未传入。语法校验不能证明来源可信。发布前，请使用 JS clientIpDetails() / findIpDetails()、Python client_ip_details() 或 Go ClientIPDetails() 检查有代表性的请求。
• protect() 接受嵌套 JSON 格式的 metadata（结构与 Guard 相同）。它不会影响指纹生成。请勿在其中放入机密或个人身份信息（PII）。提供此项时，请求决策还会公开可选的 IP 威胁情报（decision.ip.threat / ip_details.threat / IP.Threat）。

Guard（非 HTTP 代码）：

• 在模块作用域创建客户端：launchArcjet()（JS）、launch_arcjet() / launch_arcjet_sync()（Python——根据异步或同步选择），NewGuardClient（Go）。
• 在模块作用域定义规则。每个操作使用一个 guard()，并为其指定硬编码的 slug 标签（tools.get-weather）。插值生成的标签会导致 grep 和 Console 分组失效。Slug 仅允许使用 ASCII 大小写字母、数字、-、.、_；首尾必须是字母或数字；最长 256 字节。匹配区分大小写，因此 Order.looked-up 和 order.looked-up 是不同的标签。
• metadata 是仅供审计使用的嵌套 JSON。不得包含机密或个人身份信息。capture() 用于记录可见性，绝不用于做决策——请在关闭时刷新。Python 辅助函数 success 不代表“操作已执行”——请参阅 Python Guard 参考文档。
• 如果没有注册任何内容，免费的 guard()（JS/Python 注册）会选择放行。Go 没有注册 API。优先使用显式客户端。
• 优先使用官方封装，而不是手动封装。导入带版本号的 JS 路径，并加载步骤 3 中对应的适配器文件。加载步骤 3 中专用的 Python 技能。未带版本号的 @arcjet/guard/<adapter> 别名无法解析。
• 根据具体拒绝请求的规则进行分支处理，不要只检查 DENY。Guard 的 decision.reason 是一个纯字符串（"PROMPT_INJECTION"），在 ALLOW 时为 undefined。某条规则拒绝请求时，同一 rules 数组中其他规则的配额仍会被扣减——如果 PII 误报不得消耗速率限制配额，请拆分调用。
• 每条速率限制规则都必须设置 key 和 bucket。如果有可信的用户 / 会话 ID，请使用它；否则请使用由你控制的稳定标识符。

**JS 适配器：**封装会默认拒绝；核心 guard() 会默认放行。请加载步骤 3 中的文件（或 Cloudflare Think 技能），以适配项目使用的框架。对于所有已发布的适配器，执行 npm install @arcjet/guard 或 pnpm add @arcjet/guard 即可——此外还需使用 actor / inputs / validateGuardLabel。Cloudflare Think 使用相同的已发布 @arcjet/guard 安装包，并将 @cloudflare/think 作为对等依赖；请加载 integrate-arcjet-guard-cloudflare-think。不要固定 git SHA。

Python：guard_action / guard_action_sync 是核心 API。请加载对应技能，以使用项目所需的额外依赖（arcjet[langchain]、arcjet[langchain-agents]、arcjet[openai-agents]、arcjet[claude-agent-sdk]、arcjet[claude-managed-agents]、arcjet[strands-agents]、arcjet[google-adk]）。没有 arcjet[crewai] 额外依赖。PyPI 上的 arcjet 1.2.0 包含 validate_guard_label 及适配器的 actor / inputs。Google ADK 可使用 pip install "arcjet[google-adk]" 或 uv add "arcjet[google-adk]" 安装——请加载 integrate-arcjet-guard-google-adk-py。不要固定 git SHA。

不会报错但不执行任何强制措施的陷阱（完整说明见 Guard 参考文档和 https://docs.arcjet.com/llms.txt）：

• Guard 没有 sensitiveInfo 规则——该规则仅适用于 HTTP protect()。请使用 localDetectSensitiveInfo / LocalDetectSensitiveInfo。
• Python 中，LocalDetectSensitiveInfo() 未传入 allow 或 deny 时会默认放行（AJ1203）。请始终传入列表。JS 不传参数也能运行，但仍请传入列表。
• 敏感信息规则不会继承客户端的后端。对于 EMAIL / PHONE_NUMBER / IP_ADDRESS / CREDIT_CARD_NUMBER 以外的实体类型，规则需要设置 backend。请与客户端共用同一个 Rampart 实例。
• 服务不会匹配的标签会显示为 ALLOW，且 hasFailedOpen() / has_failed_open() 为 false，因此 Guard 会静默地不运行。@arcjet/guard 1.13.0 和 PyPI arcjet 1.2.0 会预先拒绝这类标签：适配器工厂会抛出 / 引发 ArcjetInvalidLabelError，而捕获会发出 AJ1023 警告并继续发送。请使用 validateGuardLabel / validate_guard_label 检查自行构建的标签。
• 声明了 actor 或类型化 inputs 的远程策略，只有在此次调用传入这些内容时才会触发。请从 @arcjet/guard 导入 policyInput（不要从适配器路径导入）。Python 使用 server_input / local_input。请检查已安装的类型定义——不要传入辅助函数未声明的字段。
• 缺少决策不代表拒绝。如果模型自行提问或屏蔽值，Guard 就不会运行。请在 Console/CLI 中确认。
• 保护单个工具只有在它是唯一的调用路径时才有用。Claude Agent SDK 需要同时设置 settingSources: [] / setting_sources=[] 和 strictMcpConfig: true / strict_mcp_config=True。
• HITL（needsApproval、human_input、can_use_tool、event.interrupt()、always_ask）不是策略关卡。

Arcjet 流程之外的约定

对于所有不是 Arcjet 特定决策的内容——开发脚本、文件 / 模块布局、命名导出与默认导出、注释风格、环境文件命名、类型提示、错误类模式——请遵循项目现有约定。如果项目尚无约定，请采用该语言的现代最佳实践。本技能对Arcjet 应放在哪里以及如何使用其 API有明确主张；除此之外，不应越界。

第 5 步：验证决策

接入保护后，请确认它确实在运行。分为三个步骤：

1. 先进行类型检查 / 构建。 运行 tsc、next build、python -m py_compile，或项目使用的其他检查命令。这样可以在用户发现之前，捕获错误导入、错误规则名称和过时的类型签名。

2. 触发一次真实调用，以便有决策可供检查。 没有调用时，Console 和 CLI 都是空的，你无法判断保护是否已正确接入。

• 基于请求：启动开发服务器（npm run dev、uvicorn main:app --reload），然后使用路由实际接受的方法对受保护路由执行 curl（curl -I 使用的是 HEAD——仅支持 GET 的 FastAPI 路由会返回 405，而不是文档所述的 403）。空的 bots.allow / allow=[] 会在后续规则运行前拒绝 CURL——需要检查电子邮件或速率限制时，临时设置 allow: ["CURL"] 以继续执行，然后再移除。要触发速率限制：for i in {1..50}; do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/your-route; done。
• Guard：调用受保护的函数，以便产生可供检查的决策。缺少决策不代表拒绝——请查看 Console/CLI，而不是根据副作用是否发生来判断。不要通过对任何内容执行 curl 来测试 Guard。

3. 在 Arcjet 平台中确认决策。

• CLI：npx -y @arcjet/cli@latest requests list --site-id <id>（基于请求）或 ... guards list --site-id <id>（Guard）
• MCP：list-requests / list-guards
• Console：https://console.arcjet.com

若要深入调查：arcjet requests explain --site-id <id> --request-id <id> 或 arcjet guards explain --site-id <id> --guard-id <id>。

如果你无法在当前环境中运行应用，请明确告诉用户需要执行什么操作（运行哪条命令、在输出中查看什么），不要默默跳过验证。

易错点

• 错误的 SDK／客户端：@arcjet/guard、arcjet.guard 和 Go 的 NewGuardClient 用于非 HTTP 代码。@arcjet/node / @arcjet/next / Python arcjet() / Go NewClient 用于 HTTP 路由。
• 位置错误：不得在 Express 中间件或 Next.js 中间件中调用 protect()。应在每个路由处理程序内部调用。
• guard() 放错层：不要在通用分发器中放置 guard()。使用上表中的官方封装器，或在具体工具内部放置 guard()。请改为加载专用的 Python 技能，而不是手动封装。
• **Python 适配器的拒绝和 HITL：**请加载专用技能。捕获处理程序绝不会阻止请求。HITL 不是策略关卡。辅助函数 metadata.outcome 的详细信息位于 Python Guard 参考文档中。
• 手动编辑依赖清单：运行项目的包管理器，确保使用的是真实版本（@arcjet/* 1.13.0，Python arcjet 1.2.0）。
• 重复计数：对同一操作多次调用 protect() 或 guard() 会多次计入速率限制。
• 绕过客户端 IP 警告：绝不要通过将 X-Forwarded-For 复制到 ipSrc / ip_src / WithIPSrc 来“修复”unverified-header 警告。
• JS 拒绝响应封装：只有一个 ArcjetDenialResult 载荷；如何传递取决于框架。在自行设定状态码或抛出错误之前，请先阅读步骤 3 中的适配器文件。guardTool 和 guardAction 是不同的处理程序。
• 切勿硬编码 ARCJET_KEY——始终使用环境变量。

选择保护措施

需要选择哪些规则来解决用户关注的问题——机器人滥用、速率限制、提示词注入、注册垃圾信息、PII 或 IP 过滤——请加载 references/choosing_protections.md。该文档将常见问题对应到 Arcjet 规则，并说明不同策略之间的权衡（例如令牌桶与滑动窗口）。后续工作流程不需要在上下文中保留此对应关系。

资源

如需查看准确的 API 签名、参数名称以及完整的规则和辅助工具，请阅读已安装 SDK 的源代码——类型定义和文档字符串是权威依据：

• Python SDK：https://github.com/arcjet/arcjet-py – arcjet 包（请求保护）和 arcjet.guard 子包（非 HTTP 防护）。
• Python Guard 集成技能：integrate-arcjet-guard-langchain-py、integrate-arcjet-guard-crewai、integrate-arcjet-guard-openai-agents-py、integrate-arcjet-guard-claude-agent-sdk-py、integrate-arcjet-guard-claude-managed-agents-py、integrate-arcjet-guard-strands-agents-py、integrate-arcjet-guard-google-adk-py。
• JS Cloudflare Think 技能：integrate-arcjet-guard-cloudflare-think。
• JavaScript / TypeScript SDK：https://github.com/arcjet/arcjet-js – 单一代码库，包含特定框架的包（@arcjet/next、@arcjet/node、@arcjet/fastify、@arcjet/sveltekit、@arcjet/guard）。JS Guard 适配器文件：references/guards_js_vercel_ai.md 及第 3 步中列出的同类文件。
• Go SDK：https://github.com/arcjet/arcjet-go – github.com/arcjet/arcjet-go 模块，包含请求和 Guard 客户端。go get github.com/arcjet/arcjet-go 会解析到 v1.0.0（Go 1.25+）。Microsoft Agent Framework 辅助工具位于单独的模块中：go get github.com/arcjet/arcjet-go/agentframework 会解析到 v0.1.0，并需要 Go 1.26+。
• Guard 策略：通过 MCP 编写并发布（list-guard-policies / describe-guard-policy / validate-guard-policy / put-guard-policy）。CLI 没有策略命令。应用策略通过 label / action 选择。编码 Agent 策略通过 Execute on（工具调用、提示词或模型切换）进行关联；发布后策略即会启用——hook URL 不得指定策略名称，且必须省略 ?surface=。安装模板：https://docs.arcjet.com/coding-agents。
• Agent 注册：https://arcjet.com/auth.md — 按照该文件操作；此处不重复相关流程。
• 文档：https://docs.arcjet.com – 叙述性指南、蓝图和产品参考。
• 控制台：https://console.arcjet.com – 站点、密钥和决策历史。