你的 API 知道 key，但不知道 actor。
每个 API request 都会带着某种关于付款方的凭证到达: API key、OAuth token、session。这个凭证能很好地回答一个问题。它告诉你哪个 account 对这次调用负责。但它不会告诉你现在到底是什么在发起调用。
同一个 API key 可以被在终端里测试的 developer 使用，可以被按计划运行的 backend job 使用，可以被借助 AI assistant 处理任务的人使用，也可以被拿到 key 并被要求完成任务的 autonomous agent 使用。这些都是非常不同的 actor。它们有不同的节奏、不同的 failure mode 和不同的 risk profile。把它们一视同仁，意味着你要么过度限制客户依赖的正当 automation，要么对本不应由 unattended agent 驱动的 API 部分保护不足。
面向 API 的 AI agent 识别填补了这个差距。你不再只从 key 去推断一切，而是得到每个 request 背后 actor 的分类，以及支持该分类的证据。(/product) 的设计目标就是交付这些能力，(/use-cases/apis) 展示了 API team 如何按 route 逐一应用它。
为什么 API team 现在需要 actor 上下文
发往 API 的自动化 traffic 并不新鲜。script、integration 和 crawler 一直都在其中。变化的是 automation 的类型。AI agent 可以阅读文档，把多次调用串联起来，创造性地重试，并代表那些不会盯着每一步的人执行操作。它们中的很多都很有用，也受欢迎。有些构建得很差。少数是恶意的。
如果没有 actor 上下文，API team 往往只能回到粗放工具:
- 按 key 限流，会同样拖慢好的 agent 和坏的 agent。
- User-agent 规则，只要 client 改了一个 header 就会失效。
- 一刀切阻止，会把合法 automation 逼去抓取你的 web app。
actor 上下文让你能够更精准地响应。来自你认可的 operator 的已签名 agent 可以在读路线获得更高的限额。命中写入 route 的未知调用者可以被要求提供更强的 credential。使用 AI assistant 的人可以保持正常体验。重点不是阻止 agent。重点是为每一种调用者提供合适的路径。关于已签名 request 能告诉你什么、不能告诉你什么，请阅读(/blog/what-signed-ai-agent-requests-prove)。
Proof of Actor 中的 AI agent 识别如何工作
Proof of Actor 对每个 request 都遵循相同的 evidence-first 流程。完整流程可以在(/how-it-works)的“如何工作”中查看；这里是面向 API team 的简版。
1. 来自你集成的 signals
你的集成会把该上下文中可用的 signals 传给 Proof of Actor。对于 API，这通常意味着 request context，例如 headers 和 protocol 细节、client 提供的任何 cryptographic request signatures，以及 client 对自身作出的任何声明。每个 signal 都会标明其来源。
2. 基于依据的分类
这些 signals 会被检查并组合为四个公开类别之一:
- Human: 可观察到的 signals 表明这是一个由人直接主导的 interaction。
- Human + AI: AI 辅助已被声明，或已被能够观察到它的 integration 检测到。
- Agent: 自动化或 agent 来源的 traffic，由可验证身份或经过谨慎限定的推断支撑。
- Unknown: 证据不足以支持可靠判断。
每个结果还会带上它的 basis: Verified、Declared、Inferred 或 Unknown。这正是 API team 最看重的部分。一个其 HTTP message signature 按 RFC 9421 的定义与已发布 key 验证通过的 request，会被报告为 Verified。一个只是自称为 agent 的 client 会被报告为 Declared。一个看起来像自动化的模式会被报告为 Inferred。你永远不必猜测某个结果是基于 cryptography 还是基于 heuristic。(/learn/glossary/evidence-basis) 就是答案的一部分。
3. 可由你的代码采取行动的结果
结果会连同 class、basis 和可读的 evidence summary 一起返回给你的应用。接下来由你的代码决定如何处理。在观察模式下，你只是记录它。当你准备好时，再基于它进行路由。
你的团队能得到什么: Detect、Understand、Route
Proof of Actor 是一个产品，提供三项能力。
Detect
收集你的 API 可以看到的 actor signals，并将已验证的断言与行为推断分开。已签名 agent request、已声明 client、automation signals 和 Unknown 结果都会被明确区分，因此不会被悄悄合并成单一分数。
Understand
查看哪些 actor 调用了哪些 route，这种情况如何随时间变化，以及每个分类背后有哪些证据。Unknown rate 始终可见，这能准确告诉你覆盖范围到哪里结束，以及哪里需要更强的 signal。
Route
按 route 和 risk tier 编写策略: allow、adapt、challenge、review 或 rate-limit。为只读 endpoint 上已验证的 agent 保留结构化、宽松的路径。对高影响操作要求更强的 credential。为 Unknown 和 timeout 定义明确的 fallback，这样无论发生什么，你的 API 都能以可预测的方式运行。你决定每项策略在失败时是 open 还是 closed，依据是该 route 上一次错误的代价。
身份证据、凭证和授权是三件不同的事
面向 agent 的 API 设计中最常见的错误，是把三个独立问题合并成一个。Proof of Actor 会把它们分开，你的设计也应该如此。
- 身份 evidence: 是什么类型的 actor 在调用，以及什么能证明这一点? 这正是 AI agent 识别所提供的内容。已验证的 signature 会把 request 与一个 key 及其已发布的 operator identifier 关联起来。IETF 的 Web Bot Auth working group 受命为这种面向 automated client 的 cryptographic authentication 制定标准，其范围覆盖的是对 agent 本身进行认证，而不是最终 user。
- Credentials: 这次调用由哪个 account 负责? 这是由你签发和管理的 API key、token 或 session。
- Authorization: 这个调用者是否被允许执行这项特定操作? 这是你的 permission model。
已验证的 agent 并不自动等于被授权的 agent。有效的 signature 并不能证明某个人已经把权限委托给了该 agent，也不能使所请求的操作天然安全。Proof of Actor 为第一个问题提供可信上下文，而把第二和第三个问题保留在它们应在的位置: 你的应用中。更多内容请阅读(/learn/glossary/agent-authorization)中的 agent authorization，以及(/evidence-and-limits)中关于证据能建立什么、不能建立什么的说明。
Unknown 是一项特性，不是失败
Request signing 是可选的，一个未签名 client 可以随意描述自己。如果系统把每个 request 都强行归入 Human 或 Agent，有时就会自信地出错，而且你不会知道什么时候出错。
当证据不足以支持判断时，Proof of Actor 会报告 Unknown。Unknown 永远不会被转换为 Human，也不会默认被视为恶意。你的 policy 会定义 Unknown 在每个 route 上意味着什么: 在公共读取场景中允许它，在账户变更时保留现有检查，在风险较高时将其排队复核。保持 Unknown 可见，正是让其他分类可信的关键。关于如何为它设计，可查看(/learn/guides/handle-unknown-traffic)中处理未知 traffic 的指南。
AI agent 识别在你的 stack 中适合放在哪里
Proof of Actor 与你现有的 gateway、authentication 和 rate limiting 并行工作。它不会替代其中任何一个。典型放置方式包括:
- Server-side middleware，位于 route handlers 之前，因此每个 request 都会在 business logic 执行前被评估。
- At the edge，这样 signals 会在 request 到达 origin 之前被评估。
- 通用 HTTP integration，使任何 stack 都可以发送 request context 并接收带有 basis 的结果。
每个 founding team 在 onboarding 期间都会获得手把手的 integration 支持，因此路径会适配你的架构，而不是反过来。(/developers)展示了当前可用的 integration path。如果你在为 agent 运行 tool，(/use-cases/mcp-servers)中的 MCP Servers use case 说明了 tool call 的具体模式。
从观察模式开始
安装 Proof of Actor 不会改变你的 API 如何响应。结果会被记录下来，以便你的团队将其与已知 outcome 对照，查看 agent 实际去了哪里，衡量每个 route 的 unknown rate，并复核任何看起来不对的分类。只有在那之后，你才会按 route 启用 policy，而且只在证据支持的地方启用。
这就是你在不打扰客户、也不破坏其依赖集成的前提下推出 AI agent 识别的方法。(/learn/guides/roll-out-actor-aware-policies-safely)中的“安全推出 actor-aware policy”的指南会逐步讲解整个顺序。
加入 founding developer program
Proof of Actor 目前处于 private beta，面向一小组 founding development team。入选团队可以在 onboarding 期间约定的使用限额内，获得最长 12 个月的免费访问，并享受我们工程师的直接 integration 支持，以及对我们下一步构建内容的实际影响力。
如果你运营着一个 API，并且想知道到底是谁在调用它，请(/early-access)申请 early access。告诉我们你的 API、你最关注的 route，以及如果有 actor 上下文，你会如何做出不同的决策。我们会告诉你 Proof of Actor 如何适配。