AURA: Agent-Usable Resource Assertion (에이전트 사용 가능 리소스 선언)

AURA는 웹사이트의 기능을 기계가 읽을 수 있게(machine-readable) 만들고, 실행에 대해 명시적으로 권한을 부여하기 위한 오픈 프로토콜입니다. UI를 스크래핑(scraping)하는 대신, 에이전트(LLM tool callers, 자동화 클라이언트 또는 플러그인)는 매니페스트(manifest)를 읽고 서버에서 검증 및 승인된 선언된 HTTP 액션(actions)을 호출합니다.

사양 상태: 실험적 (v1.0 형식; 파괴적 변경 사항이 발생할 수 있음).

License

60초 만에 통합하기

• 선언된 기능(capabilities) 및 액션(actions)이 포함된 /.well-known/aura.json을 제공합니다 (공개 가능, 캐싱 가능, 비밀 정보 포함 금지).
• 기능 엔드포인트(capability endpoints)를 구현하고 인증/인가(auth/authorization) 및 입력 값 검증(input validation)을 강제합니다.
• 동적 가용성(dynamic availability)을 설명하기 위해 AURA-State를 방출합니다 (선택 사항이지만 권장됨).
• aura-validate를 사용하여 매니페스트를 검증합니다.

목차

• 60초 만에 통합하기
• AURA란 무엇인가?
• 철학
• 핵심 개념
• 작동 방식
• 퀵스타트: 로컬 데모
• 프로덕션 데모 (빌드 + 시작)
• 환경 변수
• 보안 모델 (협상 불가)
• 사이트에 AURA 통합하기
• 검증 및 툴링
• 참조 패키지
• FAQ
• 문제 해결
• 참조 문헌
• 라이선스

AURA란 무엇인가?

AURA (Agent-Usable Resource Assertion)는 웹사이트와 AI 에이전트 간의 작고 명시적인 계약입니다. 사이트는 /.well-known/aura.json에 기능(capabilities, 동사)과 선택적인 리소스(resources, 명사)를 구체적인 HTTP 액션과 함께 나열한 매니페스트를 게시합니다. 그러면 에이전트는 UI 흐름을 추측하거나 HTML을 스크래핑할 필요 없이 작업을 수행할 수 있습니다.

AURA는 인증 (Authentication) 또는 인가 (Authorization)를 대체하는 것이 아니며, 범용 API 기술 (API description)도 아닙니다. 이를 도구 매니페스트 (tool manifest)로 생각하십시오. 즉, 자동화된 실행을 목적으로 선별된 액션 (actions)의 집합입니다. 매니페스트는 기술적 (descriptive)인 것이지 허가적 (permissive)인 것이 아니며, 서버가 신뢰할 수 있는 단일 원천 (source of truth)으로 남습니다.

철학 (Philosophy)

• 암시적보다 명시적 (Explicit over implicit): 액션은 마크업에서 추론되는 것이 아니라 선언됩니다.
• 작고 감사 가능한 표면 (Small, auditable surface): 컴팩트한 매니페스트는 UI 자동화보다 검토하고 보안을 유지하기가 더 쉽습니다.
• 기본적으로 상태 인식 (권고 사항) (State-aware by default (advisory)): AURA-State 헤더가 컨텍스트 (context)를 전달하며, 서버가 신뢰할 수 있는 단일 원천 (source of truth)으로 남습니다.
• 서버 강제 (Server-enforced): 매니페스트는 기술적 (descriptive)입니다. 모든 액션은 서버 측에서 검증되며 필요에 따라 인증 및 인가 과정을 거칩니다.
• 대체가 아닌 호환성 (Compatibility, not replacement): AURA는 기존의 API 및 인증 체계를 보완합니다. 이를 대체하지 않습니다.

핵심 개념 (Core Concepts)

이 리포지토리에서 사용되는 핵심 용어입니다 (비공식적이며, 정식 필드는 스키마 (schema)를 참조하십시오):

• 매니페스트 (Manifest, /.well-known/aura.json): $schema, protocol, version, site, resources, capabilities (모두 필수)를 포함하는 기계 판독 가능 (machine-readable)한 계약입니다.
• 리소스 (Resources): 명사 그룹화 (필수, {} 가능)로, uriPattern, description, 그리고 기능 ID (capability IDs)로 매핑되는 HTTP 작업 (operations)을 포함합니다.
• 기능 (Capabilities): 동사 (필수, {} 가능)로, 파라미터 스키마 (parameter schema)와 HttpAction 정의를 포함합니다.
• HttpAction: 기능을 실행하는 방법 (method, RFC 6570 urlTemplate, 인코딩, 파라미터 매핑, 선택적 parameterLocation 및 cors)입니다.
• AURA-State 헤더: 컨텍스트와 사용 가능한 기능 ID를 설명하는 Base64 인코딩된 JSON입니다. 이는 권고 사항 (advisory)이며 권한 (permission)이 아닙니다.
• 정책 (Policy, 선택 사항): rateLimit (제한/윈도우) 및 authHint (none, cookie, bearer)와 같은 힌트입니다.

작동 방식 (How It Works)

1. 클라이언트가 /.well-known/aura.json을 가져옵니다 (fetch).
2. 클라이언트가 기능 (capability)을 선택합니다 (AURA-State 컨텍스트에 의해 선택적으로 필터링됨).
3. 클라이언트는 JSON Pointer를 통해 에이전트가 제공한 입력 객체로부터 인자 (arguments)를 요청 본문(request body)/쿼리(query)/경로(path)로 매핑하고 URL 템플릿을 확장합니다.
4. 서버는 요청을 검증하고, 인증/인가 (auth/authorization) 및 속도 제한 (rate limits)을 적용하며, 설정된 대로 로그/감사 (logs/audits)를 수행하고 액션을 실행합니다.

빠른 시작: 로컬 데모 (Quickstart: Local Demo)

사전 요구 사항: Node.js 18 이상 (20 이상 권장) 및 pnpm (필요한 경우 corepack enable` 실행).

리포지토리 루트에서:

pnpm install
pnpm --filter aura-reference-server dev

매니페스트 (manifest) 확인:

curl http://localhost:3000/.well-known/aura.json

protocol, version, 그리고 capabilities가 포함된 JSON 객체가 보여야 합니다.

데모 자격 증명 (로컬 개발용으로만 사용):

• 이메일: demo@aura.dev
• 비밀번호: password123

로그인 및 인증된 액션 (curl, 직접 API 호출)

이는 매니페스트를 우회하며 단순히 직접적인 API 무결성 검사 (sanity check)를 위한 것입니다. 프로덕션 환경에서 쿠키 인증 (cookie auth)을 사용하는 경우, CSRF 보호 및 SameSite 쿠키를 추가하십시오.

# 로그인 후 인증 쿠키 저장
curl -i -c cookies.txt \
  -H "Content-Type: application/json" \
...

레퍼런스 클라이언트 사용하기 (Use the Reference Client)

레퍼런스 클라이언트는 액션을 계획하기 위해 OpenAI의 API를 사용하지만, AURA 프로토콜 자체는 모델 불가지론적 (model-agnostic)입니다.

packages/reference-client/.env 파일을 생성합니다:

OPENAI_API_KEY=YOUR_KEY_HERE

.env 파일은 커밋하지 마십시오.

agent 명령은 매니페스트를 가져오고, 기능을 선택하며, 선언된 HTTP 액션을 호출합니다 (UI 스크래핑 없음).

에이전트 실행:

pnpm --filter aura-reference-client agent -- http://localhost:3000 "log in and create a post titled Hello"

크롤러 (crawler)로 매니페스트 조사:

pnpm --filter aura-reference-client crawler -- http://localhost:3000

엔드 투 엔드 (end-to-end) 워크플로우 테스트 실행:

pnpm --filter aura-reference-client test-workflow http://localhost:3000

프로덕션 데모 (Production Demo) (빌드 + 시작)

프로덕션과 유사한 데모를 실행하려면:

pnpm --filter aura-reference-server build
pnpm --filter aura-reference-server start

서버는 http://localhost:3000에서 사용할 수 있습니다. 이는 여전히 데모 버전입니다. 인증 (auth)은 간소화되어 있으며 데이터는 인메모리 (in-memory) 방식입니다.

환경 변수 (Environment Variables)

레퍼런스 데모를 위해 다음 항목들만 필요합니다:

• packages/reference-client/.env: agent 스크립트를 위한 OPENAI_API_KEY.
• PORT: 선택 사항. 레퍼런스 서버의 기본 Next.js 포트를 재정의합니다.

보안 모델 (Security model) (협상 불가)

• AURA는 권한을 부여하지 않습니다. 대신 액션 (actions)과 입력 (inputs)을 기술합니다.
• 모든 기능 (capability)은 적절하게 서버 측에서 인증 (authenticated) 및 인가 (authorized)됩니다.
• 기능 호출에 대해 속도 제한 (Rate-limit)을 적용하고 로그를 남기며, 감사 가능성 (auditability)을 위해 요청 ID (request IDs)를 첨부합니다.
• AURA-State를 권고용 컨텍스트 (advisory context)로 취급하십시오. 이를 압축된 상태로 유지하고 비밀 정보 (secrets)를 절대 인코딩하지 마십시오.
• 사용자의 명시적인 동의나 확인 흐름 (confirmation flows) 없이 파괴적인 기능 (destructive capabilities)을 사용하는 것을 피하십시오.

사이트에 AURA 통합하기

1. /.well-known/aura.json에 매니페스트 (Manifest) 제공하기

Next.js를 사용하는 경우, public/.well-known/aura.json에 배치하십시오. 이를 공개 상태로 유지하고 비밀 정보를 포함하지 마십시오. 클라이언트가 안전하게 캐싱할 수 있도록 Content-Type: application/json 및 캐시 헤더 (ETag/Cache-Control)와 함께 제공하십시오.

스키마 (schema)에는 $schema, resources, 그리고 capabilities가 필요합니다. resources와 capabilities 중 하나만 필요한 경우 둘 다 빈 객체 ({})일 수 있습니다.

최소한의 예시:

{
  "$schema": "https://unpkg.com/aura-protocol@1.0.5/dist/aura-v1.0.schema.json",
  "protocol": "AURA",
...

기능 (capability)이 포함된 더 완전한 예시:

{
  "$schema": "https://unpkg.com/aura-protocol@1.0.5/dist/aura-v1.0.schema.json",
  "protocol": "AURA",
...

스키마 실태 (Schema reality): v1.0 매니페스트 (manifest)에는 $schema가 필수입니다. 스키마의 $id는 https://aura.dev/schemas/v1.0.json이지만, aura.dev 호스팅은 계획 중이며 아직 활성화되지 않았습니다. 현재는 위에 표시된 버전 관리된 Unpkg URL을 사용하거나 node_modules/aura-protocol/dist/aura-v1.0.schema.json에 포함된 스키마를 참조하십시오. aura-validate를 이용한 검증 (Validation)은 로컬 파일에서 오프라인으로 작동합니다.

상태 인식 동작 (state-aware behavior)을 시연하려면, 인증된 기능 (capabilities, 예: create_post)을 추가하고 사용자가 로그인했을 때만 AURA-State에 이를 포함하십시오.

2. 기능 엔드포인트 (Capability Endpoints) 구현

API 라우트는 매니페스트 (manifest)와 일치해야 합니다 (메서드 + URL 템플릿). JSON 스키마 (JSON Schema)를 사용하여 입력을 검증하고, 각 기능에 대해 인증 (authentication) 및 인가 (authorization) 규칙을 강제하십시오. 레퍼런스 서버 (reference server)의 경우, packages/reference-server/lib/validator.ts에 있는 validateRequest가 Ajv를 사용하여 기능 스키마를 강제합니다.

3. 동적 기능을 위한 AURA-State 방출 (Emit)

AURA-State 헤더는 Base64로 인코딩된 JSON입니다. 이는 인증 여부와 현재 사용 가능한 기능이 무엇인지 나타낼 수 있습니다. 클라이언트는 이를 권고용 컨텍스트 (advisory context)로 취급해야 하며, 실제 정보에 대해서는 서버 에러에 의존해야 합니다. 헤더 크기 제한에 맞도록 압축된 상태를 유지하고, 비밀 정보 (secrets)를 절대 인코딩하지 마십시오.

const auraState = {
  isAuthenticated: true,
  context: { path: "/api/posts", timestamp: new Date().toISOString() },
...

참고: 레퍼런스 서버는 표준 Base64를 사용합니다. 양측을 모두 제어할 수 있다면, 헤더 내의 + 및 /를 피하기 위해 Base64URL을 사용하는 것도 허용됩니다.

4. 검증 및 테스트

CLI 검증기 (validator)와 자체 테스트를 사용하십시오:

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

원격 매니페스트 (remote manifest)를 검증하려면 먼저 다운로드하십시오:

curl -fsSL https://example.com/.well-known/aura.json -o aura.json
npx -y -p aura-protocol aura-validate aura.json

참고: aura-validate는 현재 로컬 파일만 검증합니다. 검증하기 전에 원격 매니페스트를 파일로 다운로드하십시오.

5. 프로덕션 체크리스트 (Production Checklist)

• /.well-known/aura.json을 Content-Type: application/json 및 캐시 헤더(ETag/Cache-Control)와 함께 제공하십시오.
• 기능(capability) 변경 사항을 문서화하고, 파괴적 변경(breaking changes)이 발생하면 v 필드를 증가시키십시오.
• 모든 기능에는 권한 부여 규칙(authorization rule)과 속도 제한(rate limit)이 있어야 합니다.
• 감사 가능성(auditability)을 위해 요청 ID(request ID)와 함께 기능 호출을 로그로 남기십시오.
• AURA-State를 간결하고, 민감하지 않으며, 권고(advisory) 수준으로 유지하십시오.
• 브라우저 기반 에이전트가 매니페스트를 가져올 경우를 대비해 매니페스트에 CORS 헤더를 추가하십시오.

검증 및 도구 (Validation and Tooling)

aura-protocol 패키지는 다음을 제공합니다:

• AuraManifest, Resource, Capability, HttpAction, 그리고 AuraState를 위한 TypeScript 타입.
• dist/aura-v1.0.schema.json에 포함된 JSON Schema. 에디터 도구의 경우, 버전 관리된 CDN URL을 참조하십시오: https://unpkg.com/aura-protocol@1.0.5/dist/aura-v1.0.schema.json.
• 로컬 매니페스트 파일을 검증하고 리소스/기능 참조를 교차 확인하는 aura-validate CLI.

설치:

npm install aura-protocol

런타임 검증 예시 (ajv 필요):

import fs from "node:fs";
import path from "node:path";
import Ajv from "ajv";
...

참조 패키지 (Reference Packages)

• packages/aura-protocol: 통합 개발자를 위한 프로토콜 타입, 스키마 및 aura-validate CLI.
• packages/reference-server: 매니페스트, 인증(auth), AURA-State를 게시하는 Next.js 데모 서버.
• packages/reference-client: 에이전트 빌더를 위한 agent, crawler, test-workflow가 포함된 Node.js 데모 클라이언트.

FAQ

AURA가 OpenAPI를 대체하나요?
아니요. OpenAPI는 전체 엔드포인트 표면(endpoint surface)을 설명합니다. AURA는 매개변수 매핑(parameter mapping) 및 상태 힌트(state hints)와 함께 자동 실행을 목적으로 선별된 액션 세트를 선언합니다. 필요하다면 둘 다 사용하십시오.

악의적인 사이트가 매니페스트에서 거짓 정보를 제공할 수 있나요?
네. 매니페스트를 도메인 신뢰도와 연결된 주장(claims)으로 취급하십시오. 에이전트는 서버의 강제 적용(enforcement) 및 에러 처리에 의존해야 하며, 신뢰하는 사이트에서만 동작해야 합니다. 서명(Signing) 또는 증명(attestation)은 향후 가능한 방향입니다.

비공개 API (private APIs)를 노출해야 하나요?
아니요. AURA는 사용자가 노출하기로 선택한 것만을 기술합니다. 기존의 인증 (auth) 및 인가 (authorization) 체계는 그대로 유지됩니다.

에이전트 (agents)는 현재 무엇을 할 수 있는지 어떻게 알 수 있나요?
AURA-State 헤더를 사용하여 현재 세션에 대한 기능 목록 (capability list)을 반환하십시오. 이는 권고 사항이며, 서버가 진실의 원천 (source of truth)으로 남습니다.

엔드포인트 (endpoints)가 경로 (path) 및 쿼리 파라미터 (query parameters)를 사용하는 경우 어떻게 하나요?
urlTemplate에는 RFC 6570 URL 템플릿을 사용하고, parameterMapping에는 JSON Pointer를 사용하십시오.

매니페스트 (manifest)에 자체 필드를 추가할 수 있나요?
네. 현재 스키마 (schema)는 추가 필드를 허용합니다. 클라이언트는 알 수 없는 키를 무시해야 하며, 확장 기능을 위한 네임스페이스 (namespacing) 사용을 권장합니다 (예: x-your-org).

문제 해결 (Troubleshooting)

다음 문서를 참조하십시오:

• TROUBLESHOOTING.md: 일반적인 설정 및 런타임 (runtime) 문제.
• MANIFEST_VALIDATION.md: 검증기 (Validator) 사용 및 스키마 문제 해결.
• packages/reference-server/DEPLOYMENT.md: 레퍼런스 서버 (reference server) 배포 노트.

참고 문헌 (References)

AURA는 결정론적 파라미터 바인딩 (deterministic parameter binding)을 위해 URI 템플릿 (RFC 6570) 및 JSON Pointer (RFC 6901)를 기반으로 구축되었습니다.