ard.json

에이전트 리소스 탐색 (ARD)은 에이전트 리소스를 분류하기 위한 사양입니다. ard.json 매니페스트는 MCP 서버, A2A 에이전트, 에이전트 스킬과 같은 도메인의 에이전트 리소스를 설명하여 AI 에이전트와 레지스트리가 이를 찾을 수 있도록 합니다.

Lighthouse 감사 작동 방식

탐색 프로세스: 감사는 ARD 사양 (§5.1)의 탐색 메커니즘을 기반으로 매니페스트를 찾습니다.

  • robots.txt 내에 Agentmap: 지시어가 있는지 확인합니다.
  • HTML에서 <link rel="ard" href="..."> 태그를 스캔합니다.
  • HTTP Link: <...>; rel="ard" 헤더 응답을 검사합니다.
  • 잘 알려진 엔드포인트 /.well-known/ard.json에서 가져오는 중입니다.

기본 탐색에 실패하면 Lighthouse는 기존 경로 (예: rel="ai-catalog" 또는 /.well-known/ai-catalog.json)를 확인합니다. 여기에서 찾은 콘텐츠는 여전히 검증되지만 표준 ARD 클라이언트는 지원 중단된 경로를 지원할 의무가 없으므로 경고가 표시됩니다.

검증 규칙: 검증은 ARD v0.91 적합성 평가 도구의 자바스크립트 포트를 사용하여 수행되며 다음 기준을 테스트합니다.

적합성 및 유효성 검사 오류:

  • 문법 및 스키마: 매니페스트는 유효한 JSON이며 ARD 매니페스트 스키마와 일치하고 각 항목은 ARD 항목 스키마와 일치합니다. Lighthouse는 진입점이 가리키는 아티팩트 (예: url의 MCP 서버 카드)를 가져오거나 검증하지 않습니다.
  • 필수 필드: 매니페스트에는 entries 배열이 포함되며 모든 항목에는 identifier, displayName, type가 포함됩니다.
  • 도메인 고정 URN: 각 identifier는 urn:air:<publisher>:<namespace>:<name> 형식을 따릅니다.
  • 위치 정의: 각 항목은 url 또는 인라인 data 중 하나만 정의하며 둘 다 정의하거나 둘 다 정의하지 않는 경우는 없습니다.
  • 트러스트 매니페스트 구조: trustManifest가 포함된 경우 identity 속성이 있는 객체입니다.

권장사항 경고:

  • 대표 쿼리: 각 항목에는 2~5개의 샘플 쿼리가 있는 representativeQueries 배열이 있습니다. 레지스트리는 이를 기반으로 검색 색인을 빌드하므로, 이러한 항목이 없는 항목은 검색 결과에 표시되지 않습니다. 있는 경우 문자열 배열이어야 합니다. 다른 항목은 오류입니다.
  • 미디어 유형: type은 올바른 형식의 미디어 유형이어야 합니다. Lighthouse는 지원 중단된 유형 (예: application/mcp-server+json에서 application/mcp-server-card+json), 매개변수가 누락되거나 추가된 표준 유형, application/* 외부의 인식할 수 없는 유형에 관해 경고합니다. 커스텀 application/* 유형이 허용됩니다.
  • 컬렉션: 최상위 collections 필드에 플래그를 지정합니다. 더 이상 ARD의 일부가 아니며 무시됩니다. 대신 entries 내의 모델 계층 구조입니다.
  • 기존 엔드포인트: 기존 ai-catalog 위치를 통해서만 찾을 수 있는 매니페스트에 플래그를 지정합니다.
  • 손상된 광고 위치: 매니페스트가 다른 위치에서 발견되었을 때 로드할 수 없는 광고 위치 (Agentmap:, rel="ard" 또는 rel="ai-catalog" 링크 또는 Link 헤더)를 신고합니다.

필요하지 않음:

  • specVersion 및 기타 추가 최상위 필드는 점수에 영향을 미치지 않습니다.
  • capabilities은(는) 선택사항이며 점수가 매겨지지 않습니다. 리소스가 이름이 지정된 도구나 기술을 노출하는 경우 레지스트리가 전체 아티팩트를 가져오지 않고도 필터링할 수 있도록 이를 나열하는 것이 좋습니다 (예: ["WeatherTool", "ForecastTool"]). 포함된 경우 문자열 배열이어야 합니다.

결과 테이블 읽기

매니페스트 전체에 문제가 있는 경우 요소 열에 Root가 표시됩니다. 항목에 문제가 있는 경우 항목의 displayName를 표시하고, 사용할 수 없는 경우 identifier 또는 Entry #n로 대체합니다. 단일 스키마 문제가 Root 아래에 한 번, 항목 아래에 한 번, 공식 적합성 테스트의 출력과 일치하는 두 번 표시될 수 있습니다.

점수 이해하기

감사 결과는 다음과 같은 방식으로 반영됩니다.

  • 통과 (1): 매니페스트가 발견되었으며 오류나 경고가 없습니다.
  • 부분 점수 (0.9): 매니페스트가 유효하지만 권장사항 경고가 하나 이상 있습니다.
  • 실패 (0): 잘못된 형식의 JSON, 스키마 위반, 잘못된 URN, url/data의 둘 다 또는 둘 다 아닌 경우와 같은 모든 적합성 오류입니다. 매니페스트가 robots.txt, rel="ard" 또는 rel="ai-catalog" 링크, Link 헤더를 통해 공지되었지만 로드할 수 없는 경우에도 감사가 실패합니다.
  • 해당 사항 없음: 어떤 방법으로도 매니페스트를 찾을 수 없습니다. 이는 Lighthouse 점수에 영향을 미치지 않습니다.

해결 방법

감사를 통과하려면 다음 단계를 따르세요.

  1. 매니페스트를 /.well-known/ard.json에 게재하거나 rel=ard와 연결하세요. ai-catalog.json 또는 rel=ai-catalog를 사용하는 경우 새 이름으로 이동합니다.
  2. 매니페스트가 ARD 스키마와 일치하도록 감사 표에 나열된 오류를 수정합니다.
  3. 모든 항목에 urn:air:... 식별자와 url 또는 data 중 하나를 정확하게 지정합니다.
  4. 해당하는 경우 type에 표준 ARD 미디어 유형을 사용합니다.
  5. 각 항목에 2~5개의 representativeQueries을(를) 추가하여 만점을 받으세요.