스키마 준수(A2A v1.0)
v1.0 사양에 따라 필수 필드를 확인합니다: name, description, version, 인터페이스별 protocolBinding과 protocolVersion을 가진 supportedInterfaces, capabilities, 콘텐츠 모드, 필수 태그가 있는 최소 하나의 스킬.
A2A Agent Card 검증기
Agent Card 검증기는 붙여넣은 JSON, 업로드된 Agent Card 파일, 공개 에이전트 URL을 A2A v1.0 검색 요구 사항에 따라 검사합니다.
Agent Card 유효성 검사기 사용
공개 에이전트 URL인 JSON을 붙여넣거나 JSON 파일을 편집기로 드래그하세요.
Agent Card 검증기 적용 범위
클라이언트가 당신의 에이전트를 검색하기 전에 Agent Card 검증기가 확인하는 것.
Agent Card 검증기는 A2A 에이전트를 게시하는 개발자, 에이전트 메타데이터를 검토하는 내부 플랫폼 팀, 제출된 Agent Card에 신뢰할 수 있는 호출을 위한 충분한 정보가 있는지 확인하는 마켓플레이스 운영자를 위해 설계되었습니다.
개발 중에는 로컬 JSON 문서를 붙여넣고, 저장소에서 Agent Card를 업로드하거나, 배포된 도메인에 대한 실시간 URL 검증을 사용하여 공개 검색 경로를 확인하세요.
의미론적 및 마이그레이션 문제
v1.0 이전 구조——최상위 url, preferredTransport, protocolVersion, provider.name, stateTransitionHistory——를 감지하고 각 필드가 v1.0에서 정확히 어디로 이동했는지 알려줍니다.
보안 및 비밀 스캔
비공개 엔드포인트에 securitySchemes와 보안 요구 사항이 선언되어 있는지 확인하고, HTTPS가 아닌 URL을 표시하며, 내장된 API 키, JWT, 또는 bearer 토큰처럼 보이는 값을 스캔합니다.
검색 준비 상태
실제 도메인에서 /.well-known/agent-card.json과 레거시 /.well-known/agent.json을 가져와 둘 다 파싱 가능한 Agent Card JSON을 반환하는지 확인합니다.
검증이 적용되는 곳
모든 단계에서 검증하기: 에디터, CI 파이프라인, 실제 도메인.
지난달 검토를 통과한 Agent Card가 오늘도 여전히 검색을 깨뜨릴 수 있습니다——엔드포인트가 이동하거나, 스킬이 변경되거나, 재배포로 well-known 경로가 사라질 수 있습니다. 플랫폼 팀과 마켓플레이스 검토자는 검증을 일회성 확인이 아닌 반복 가능한 게이트로 취급합니다.
가장 간단한 CI 가드는 curl만 있으면 됩니다: 트래픽이 새 배포로 전환되기 전에 well-known 경로가 파싱 가능한 JSON으로 응답하는지 확인하세요.
# deploy pipeline: fail if the published card breaks
curl -fsS https://your-domain/.well-known/agent-card.json \
| python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'수정 가이드
흔한 Agent Card 수정 사항
먼저 Agent Card 검증기 보고서를 사용하여 필수 필드를 처리한 다음, 검색성, 신뢰성, 마이그레이션 세부 사항을 개선하세요.
자리 표시자 엔드포인트 URL을 배포된 HTTPS A2A 서비스 URL로 교체하세요.
최상위 url과 preferredTransport를 순서가 있는 supportedInterfaces 배열로 옮기세요——첫 번째 항목이 선호되는 인터페이스입니다.
에이전트 자체를 설명하는 필수 최상위 version 필드를 추가하고, 모든 스킬에 태그를 추가하세요.
provider.name을 provider.organization으로 이름을 바꾸고, 클라이언트가 언제 에이전트를 호출해야 하는지 알 수 있도록 짧은 설명을 확장하세요.
에이전트 엔드포인트가 완전히 공개되지 않은 경우 항상 보안 메타데이터를 선언하고, 자격 증명 자체는 절대 포함하지 마세요.
동일한 유효한 Agent Card를 /.well-known/agent-card.json에 게시하세요(클라이언트가 여전히 두 경로를 모두 확인하는 동안에는 레거시 agent.json 경로에도 게시하세요).
검증기는 어떤 A2A 버전을 대상으로 하나요?
검사는 A2A v1.0 Agent Card 구조——supportedInterfaces, 인터페이스별 프로토콜 버전, 필수 스킬 태그, provider.organization——를 따릅니다. v1.0 이전 Agent Card가 즉시 거부되는 것은 아닙니다: 레거시 필드는 정확한 v1.0 대체와 함께 경고로 표시됩니다.
왜 두 well-known URL을 모두 확인하나요?
v1.0 사양은 /.well-known/agent-card.json을 등록하지만, 이전 A2A 구현은 /.well-known/agent.json을 사용했습니다. 둘 다 확인하면 클라이언트가 실패하기 전에 검색 격차를 포착할 수 있습니다.
경고는 무시해도 되나요?
경고는 차단하는 JSON 오류가 아니지만, 보통 에이전트를 더 쉽게 검색, 신뢰, 호출할 수 있게 하는 메타데이터——또는 최신 클라이언트가 더 이상 읽지 않을 v1.0 이전 필드——를 가리킵니다.
검증은 언제 실행해야 하나요?
세 가지 순간입니다: 개발 중 Agent Card를 편집할 때, 배포 전 CI 게이트로서, 그리고 게시 후——실제 서비스 URL을 붙여넣어 클라이언트가 두 검색 경로에서 실제로 무엇을 받는지 확인하세요.
검증 준비 완료
클라이언트가 검색하기 전에 당신의 Agent Card를 검증하세요.
통합된 검증기 작업 공간에서 JSON을 붙여넣거나, Agent Card 파일을 드롭하거나, 공개 URL을 확인하세요.