AURA：为 AI 代理构建机器可读网络的开放协议

引言：告别网页抓取，迎接声明式 API

Introduction: Beyond Web Scraping, Towards Declarative APIs

在当今由 AI 驱动的自动化浪潮中，一个核心挑战依然存在：如何让 AI 代理（如大型语言模型工具调用器、自动化客户端或插件）可靠、安全地与网站交互？传统方法依赖于脆弱的屏幕抓取技术，这不仅效率低下、容易出错，还常常违反服务条款。AURA（Agent-Usable Resource Assertion，代理可用资源声明）协议应运而生，旨在通过一个简单而强大的理念解决这一问题：让网站主动、声明式地将其功能暴露为机器可读的 API。

In today's wave of AI-driven automation, a fundamental challenge persists: how can AI agents (such as LLM tool callers, automation clients, or plugins) reliably and securely interact with websites? Traditional methods rely on fragile screen scraping, which is inefficient, error-prone, and often violates terms of service. The AURA (Agent-Usable Resource Assertion) protocol emerges to address this issue with a simple yet powerful idea: enabling websites to proactively and declaratively expose their capabilities as machine-readable APIs.

AURA 是一个开放协议，它通过在网站的标准位置（/.well-known/aura.json）提供一个名为“清单”的 JSON 文件，来明确声明网站支持哪些可由代理执行的操作。这为 AI 代理与网络交互提供了一种标准化、安全且高效的新范式。

AURA is an open protocol that enables websites to explicitly declare which actions can be performed by agents through a JSON file called a "manifest," served at a standard location (/.well-known/aura.json). This establishes a new paradigm for AI agents to interact with the web: standardized, secure, and efficient.

什么是 AURA？

What is AURA?

AURA 是网站与 AI 代理之间的一份简洁、明确的契约。网站发布一个清单文件，其中列出了其“能力”（动词，即操作）和可选的“资源”（名词，即操作对象），并为每个能力定义了具体的 HTTP 调用方式。代理无需猜测用户界面流程或解析 HTML，只需读取这份清单即可了解如何行动。

AURA is a small, explicit contract between a website and an AI agent. A site publishes a manifest file that lists its "capabilities" (verbs, i.e., actions) and optionally "resources" (nouns, i.e., objects of actions), defining concrete HTTP calls for each capability. Agents can act without guessing UI flows or parsing HTML; they simply read this manifest.

核心定位：AURA 并非用于替代身份验证、授权机制，也不是一个通用的 API 描述语言（如 OpenAPI）。它更像是一个“工具清单”——一套为自动化执行而精心策划的操作集合。清单本身是描述性的，而非授权性的；服务器始终是权限和验证的最终裁决者。

Core Positioning: AURA is not a replacement for authentication or authorization, nor is it a universal API description language (like OpenAPI). Think of it more as a "tool manifest"—a curated set of actions intended for automated execution. The manifest itself is descriptive, not permissive; the server remains the ultimate authority for permissions and validation.

核心设计理念

Core Design Philosophy

AURA 的构建遵循一系列关键原则，确保其安全性、可维护性和实用性：

AURA is built upon a set of key principles to ensure its security, maintainability, and practicality:

• 显式优于隐式：操作被明确声明，而非从标记语言中推断得出。

  • Explicit over Implicit: Actions are declared, not inferred from markup.

• 精简、可审计的表面：一个紧凑的清单比复杂的 UI 自动化脚本更易于审查和保护。

  • Small, Auditable Surface: A compact manifest is easier to review and secure than complex UI automation scripts.

• 默认状态感知（建议性）：通过 AURA-State 头部传递上下文信息，但服务器状态是唯一事实来源。

  • State-Aware by Default (Advisory): The AURA-State header communicates context, but the server state is the single source of truth.

• 服务器端强制执行：清单仅用于描述。每个操作都必须在服务器端进行验证，并根据需要实施身份验证和授权。

  • Server-Enforced: The manifest is for description only. Every action must be validated server-side, with authentication and authorization enforced as required.

• 兼容而非替代：AURA 旨在补充您现有的 API 和身份验证体系，而非取代它们。

  • Compatibility, not Replacement: AURA is designed to complement your existing APIs and auth systems, not to replace them.

核心概念解析

Core Concepts Explained

理解 AURA 协议，需要掌握以下几个基本术语：

To understand the AURA protocol, grasp the following fundamental terms:

• 清单：位于 /.well-known/aura.json 的机器可读契约。必须包含 $schema、protocol、version、site、resources 和 capabilities 字段。

  • Manifest: The machine-readable contract located at /.well-known/aura.json. Must include fields like $schema, protocol, version, site, resources, and capabilities.

• 资源：名词分组（必需，但可以是空对象 {}），包含 uriPattern、description 以及映射到能力 ID 的 HTTP 操作方法。

  • Resources: Noun groupings (required, may be empty {}) containing uriPattern, description, and HTTP operations that map to capability IDs.

• 能力：动词（必需，但可以是空对象 {}），包含参数模式定义和一个 HttpAction 定义。

  • Capabilities: Verbs (required, may be empty {}) containing a parameter schema definition and an HttpAction definition.

• HttpAction：定义如何执行一个能力，包括 HTTP 方法、RFC 6570 urlTemplate、编码方式、参数映射，以及可选的 parameterLocation 和 cors 设置。

  • HttpAction: Defines how to execute a capability, including the HTTP method, RFC 6570 urlTemplate, encoding, parameter mapping, and optional parameterLocation and cors settings.

• AURA-State 头部：Base64 编码的 JSON 字符串，用于描述当前上下文和可用的能力 ID。它是建议性的，不代表权限。

  • AURA-State Header: A Base64-encoded JSON string describing the current context and available capability IDs. It is advisory and does not represent permission.

• 策略：可选的提示信息，例如 rateLimit（限制/窗口）和 authHint（none、cookie、bearer）。

  • Policy (Optional): Hints such as rateLimit (limit/window) and authHint (none, cookie, bearer).

AURA 如何工作：交互流程

How AURA Works: The Interaction Flow

AURA 代理与网站之间的标准交互遵循一个清晰的四步流程：

The standard interaction between an AURA agent and a website follows a clear four-step process:

1. 获取清单：客户端（代理）获取目标网站的 /.well-known/aura.json 文件。

   1. Fetch Manifest: The client (agent) fetches the target website's /.well-known/aura.json file.

2. 选择能力：客户端根据任务从清单中选择一个合适的能力（可参考 AURA-State 头部进行筛选）。

   2. Select Capability: The client selects an appropriate capability from the manifest based on the task (optionally filtered by the AURA-State header context).

3. 构建请求：客户端将代理提供的输入参数，通过 JSON Pointer 映射到请求体、查询参数或路径中，并展开 URL 模板。

   3. Construct Request: The client maps the input parameters provided by the agent into the request body, query parameters, or path using JSON Pointer, and expands the URL template.

4. 执行与验证：服务器接收请求，验证输入，强制执行身份验证、授权和速率限制，记录审计日志，最后执行实际操作。

   4. Execute and Validate: The server receives the request, validates the input, enforces authentication, authorization, and rate limits, logs for audit, and finally executes the actual action.

快速集成指南（60秒概览）

Quick Integration Guide (60-Second Overview)

将 AURA 集成到您的网站，可以概括为三个核心步骤：

Integrating AURA into your website can be summarized in three core steps:

1. 提供清单：在 /.well-known/aura.json 路径提供声明了能力和操作的清单文件（公开、可缓存、不包含秘密信息）。

   1. Serve the Manifest: Serve a manifest file at /.well-known/aura.json that declares capabilities and actions (public, cacheable, no secrets).

2. 实现端点：实现清单中声明的能力对应的 API 端点，并在其中强制执行身份验证、授权和输入验证。

   2. Implement Endpoints: Implement the API endpoints corresponding to the capabilities declared in the manifest, enforcing authentication, authorization, and input validation within them.

3. 声明动态状态：发送 AURA-State 头部来描述能力的动态可用性（可选但推荐）。

   3. Declare Dynamic State: Emit the AURA-State header to describe the dynamic availability of capabilities (optional but recommended).

4. 验证清单：使用 aura-validate 工具验证清单文件的格式和有效性。

   4. Validate the Manifest: Use the aura-validate tool to verify the format and validity of the manifest file.

安全模型：不可妥协的原则

Security Model: Non-Negotiable Principles

AURA 的设计将安全置于核心地位，遵循以下不可妥协的原则：

AURA's design places security at its core, adhering to the following non-negotiable principles:

• 描述而非授权：AURA 清单仅描述可用的操作和所需的输入，它本身不授予任何执行权限。

  • Description, Not Permission: The AURA manifest only describes available actions and required inputs; it does not grant any execution permissions itself.

• 服务器端强制：每个能力的调用都必须在服务器端进行适当的身份验证和授权检查。

  • Server-Side Enforcement: Every capability call must undergo proper authentication and authorization checks on the server side.

• 监控与审计：对能力调用实施速率限制和日志记录，并附加请求 ID 以确保可审计性。

  • Monitoring and Auditing: Implement rate limiting and logging for capability calls, attaching request IDs for auditability.

• 审慎的状态声明：将 AURA-State 视为建议性上下文信息；保持其简洁，绝不编码任何秘密信息。

  • Prudent State Declaration: Treat AURA-State as advisory context; keep it compact and never encode any secrets within it.

• 危险操作确认：避免在没有明确用户同意或确认流程的情况下，暴露具有破坏性的能力。

  • Dangerous Action Confirmation: Avoid exposing destructive capabilities without explicit user consent or confirmation flows.

为您的网站集成 AURA：详细步骤

Integrating AURA Into Your Site: Detailed Steps

1. 在 /.well-known/aura.json 提供清单文件

1. Serve a Manifest at /.well-known/aura.json

清单文件必须是公开可访问的，并设置正确的 Content-Type: application/json 和缓存头（如 ETag、Cache-Control），以便客户端安全缓存。

The manifest file must be publicly accessible, served with the correct Content-Type: application/json and cache headers (e.g., ETag, Cache-Control) to allow clients to cache it safely.

一个最简单的示例如下：

A minimal example is as follows:

{
  "$schema": "https://unpkg.com/aura-protocol@1.0.5/dist/aura-v1.0.schema.json",
  "protocol": "AURA",
  "version": "1.0",
  "site": {
    "name": "Example Site",
    "url": "https://example.com"
  },
  "resources": {},
  "capabilities": {}
}

2. 实现能力对应的 API 端点

2. Implement the Capability Endpoints

您的 API 路由必须与清单中声明的 HTTP 方法和 URL 模板匹配。务必在端点内使用 JSON Schema 验证输入，并为每个能力强制执行身份验证和授权规则。

Your API routes must match the HTTP methods and URL templates declared in the manifest. Be sure to validate input using JSON Schema within the endpoints and enforce authentication and authorization rules for each capability.

3. 发送 AURA-State 头部以支持动态能力

3. Emit the AURA-State Header for Dynamic Capabilities

AURA-State 头部是一个 Base64 编码的 JSON 对象，用于指示当前会话的上下文（如用户是否登录）以及当前可用的能力列表。客户端应将其视为建议信息，并以服务器返回的错误为最终依据。

The AURA-State header is a Base64-encoded JSON object used to indicate the context of the current session (e.g., whether a user is logged in) and the list of capabilities currently available. Clients should treat it as advisory information and rely on server errors as the final authority.

// 示例：在 Node.js 服务器中设置 AURA-State 头部
// Example: Setting the AURA-State header in a Node.js server
const auraState = {
  isAuthenticated: true,
  context: { path: "/api/posts" },
  capabilities: ["list_posts", "create_post"]
};
const headerValue = Buffer.from(JSON.stringify(auraState)).toString("base64");
res.setHeader("AURA-State", headerValue);

4. 验证与测试

4. Validate and Test

使用官方 CLI 工具验证您的清单：

Use the official CLI tool to validate your manifest:

npx -y -p aura-protocol aura-validate public/.well-known/aura.json

5. 生产环境清单

5. Production Checklist

• 缓存与内容类型：确保清单文件具有正确的 JSON 内容类型和缓存头。

  • Caching and Content-Type: Ensure the manifest file has the correct JSON content type and cache headers.

• 版本管理：记录能力的变更，并在发生破坏性变更时递增 v 字段。

  • Versioning: Document capability changes and increment the v field for breaking changes.

• 安全策略：每个能力都应定义授权规则和速率限制。

  • Security Policies: Every capability should have an authorization rule and a rate limit defined.

• 审计日志：记录能力调用日志，并包含请求 ID。

  • Audit Logging: Log capability calls with request IDs included.

• CORS 配置：如果基于浏览器的代理需要获取清单，请为其添加 CORS 头。

  • CORS Configuration: Add CORS headers for the manifest if browser-based agents will need to fetch it.

常见问题解答

Frequently Asked Questions

AURA 是 OpenAPI 的替代品吗？

Is AURA a replacement for OpenAPI?
不。OpenAPI 用于描述完整的 API 端点表面，而 AURA 声明的是为自动化执行而策划的一组操作，包含参数映射和状态提示。两者可以共存并用。
No. OpenAPI describes the full surface of API endpoints, while AURA declares a curated set of actions intended for automated execution, with parameter mapping and state hints. The two can coexist and be used together.

恶意网站可以在清单中撒谎吗？

Can a malicious site lie in the manifest?
可以。应将清单视为与域名信任绑定的声明。代理应依赖服务器的强制措施和错误处理，并且只在其信任的网站上执行操作。未来可能引入签名或认证机制。
Yes. Treat manifests as claims tied to domain trust. Agents should rely on server enforcement and error handling, and only act on sites they trust. Signing or attestation is a possible future direction.

我必须暴露私有 API 吗？

Do I have to expose private APIs?
不。AURA 只描述您选择暴露的内容。您现有的身份验证和授权机制保持不变。
No. AURA only describes what you choose to expose. Your existing authentication and authorization mechanisms remain in place.

代理如何知道当前可以执行什么操作？

How do agents know what they can do right now?
使用 AURA-State 头部返回当前会话的能力列表。它是建议性的，服务器状态才是最终事实来源。
Use the AURA-State header to return the list of capabilities for the current session. It is advisory; the server state is the ultimate source of truth.

总结

Conclusion

AURA 协议代表了一种构建机器可读网络的务实且安全的路径。它通过将网站从被动的信息源转变为主动的、声明式的服务提供者，为 AI 代理与万维网之间架起了一座更可靠、更高效的桥梁。对于网站开发者而言，集成 AURA 意味着以标准化的方式开放可控的自动化接口；对于 AI 代理开发者而言，则意味着告别脆弱的抓取，拥抱稳定、经授权的交互。随着该协议的不断发展和采用，我们有望看到一个更易于智能体理解和操作的互联网。

The AURA protocol represents a pragmatic and secure path towards building a machine-readable web. By transforming websites from passive sources of information into proactive, declarative service providers, it builds a more reliable and efficient bridge between AI agents and the World Wide Web. For website developers, integrating AURA means opening up controlled automation interfaces in a standardized way; for AI agent developers, it means moving beyond fragile scraping towards stable, authorized interactions. As the protocol evolves and gains adoption, we can anticipate an internet that is more intelligible and operable by intelligent agents.

常见问题（FAQ）

AURA协议Agent-Usable Resource Assertion的缩写，是一种使网站能力对AI代理机器可读的开放协议。如何帮助AI代理安全地访问网站功能？

AURA通过网站主动提供标准化的aura.json清单位于/.well-known/aura.json的JSON文件，包含网站资源和能力的声明式描述。，明确声明可执行的操作和调用方式，使AI代理无需依赖脆弱的屏幕抓取，而是通过服务器端验证的安全API进行交互。

AURA清单与OpenAPI有什么区别？

AURA清单是专门为AI代理自动化执行设计的“工具清单”，聚焦于声明可执行的操作集合，而非通用的API描述。它不替代身份验证或授权，服务器始终保持最终控制权。

集成AURA协议Agent-Usable Resource Assertion的缩写，是一种使网站能力对AI代理机器可读的开放协议。需要哪些基本步骤？

在网站标准位置（/.well-known/aura.json）提供JSON清单文件，明确声明网站的能力（操作）和资源，定义具体的HTTP调用方式，并确保服务器端对每个操作进行验证和权限控制。