검색 도구 · A2A v1.0

A2A Agent Card 검색 URL 확인

A2A 클라이언트는 well-known URL에서 JSON Agent Card를 가져와 에이전트를 검색합니다. 실제 도메인에서 두 가지 명명 규칙을 모두 테스트하고 클라이언트가 실제로 받는 내용을 확인하세요.

동일한 기본 도메인에서 두 후보 검색 URL을 모두 생성합니다.

반환된 JSON을 가져와 상태 코드와 콘텐츠 타입을 보고합니다.

가능하면 응답을 Agent Card JSON으로 파싱합니다.

인터페이스, 스킬, 제공자, 모드, 기능, 보안 메타데이터에 대한 준비 상태를 검사합니다.

공개 에이전트 도메인 확인

기본 도메인을 입력하세요. 검사기는 두 검색 경로를 가져와 반환된 JSON을 파싱하고 Agent Card 준비 상태를 검사합니다.

검색 방식

하나의 well-known URL이 모든 A2A 통합의 시작점입니다.

다른 에이전트가 당신의 서비스를 호출하기 전, 먼저 도메인의 well-known URI(RFC 8615)에서 Agent Card를 가져와 스킬과 보안 요구 사항을 평가한 후 우선 인터페이스를 호출합니다. Agent Card가 없거나 오래되었거나 리디렉션 뒤에 숨겨져 있으면 통합은 시작도 되기 전에 실패합니다.

이 사이트는 스스로 점검하는 것을 실천합니다. AgentCard.net은 두 경로 모두에 자체 Agent Card를 게시하며, 오른쪽 예시가 실제 문서입니다.

실시간 Agent Card 보기
agentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

검색 경로

두 가지 규칙, 하나의 Agent Card.

전체 검증기 열기
A2A v1.0 표준

/.well-known/agent-card.json

A2A v1.0 사양에 등록된 well-known URI입니다. 새 클라이언트는 이 경로를 먼저 가져오므로 콘텐츠 타입 application/a2a+json으로 제공하세요.

레거시(v1.0 이전)

/.well-known/agent.json

초기 A2A 구현과 코드랩 예제에서 사용됩니다. 배포된 많은 클라이언트가 여전히 이 경로만 확인하므로 여기에 동일한 Agent Card를 제공하는 것이 안전한 전환 전략입니다.

게시 패턴

Agent Card 검색을 견고하게 만들기.

검색 실패는 대개 단순합니다. 리디렉션, 캐시된 오류 페이지, 혹은 한쪽 경로만 배포하고 다른 쪽을 잊는 경우입니다. 이 게시 루틴은 두 규칙 모두 항상 동일한 최신 Agent Card를 제공하도록 유지합니다.

  1. 1

    표준 경로에 게시하기

    A2A 서비스와 동일한 도메인에서 검토된 Agent Card를 HTTPS로 /.well-known/agent-card.json에, 콘텐츠 타입 application/a2a+json으로 제공하세요.

  2. 2

    레거시 경로 미러링하기

    이전 클라이언트가 아직 사용 중인 동안 /.well-known/agent.json에서도 동일한 문서를 반환하세요. 두 경로의 Agent Card가 다르면 라우팅이 혼란스러워집니다.

  3. 3

    Agent Card 동기화 유지하기

    엔드포인트, 스킬, 기능, 인증 중 하나라도 변경되면 Agent Card를 업데이트하고 version 필드를 올린 후 두 경로를 함께 재배포하세요.

  4. 4

    변경할 때마다 다시 확인하기

    배포, DNS 변경, 게이트웨이 마이그레이션, 마켓플레이스 수정 후 이 검사기를 실행하세요. 실패의 원인은 대개 리디렉션, HTML 오류 페이지, 혹은 잊혀진 한쪽 경로입니다.

자주 묻는 질문

Well-known Agent JSON 자주 묻는 질문

무엇을 어디에 게시해야 하는지, 그리고 두 규칙의 클라이언트 모두 계속 작동하게 하는 방법.

어떤 well-known Agent Card 경로를 사용해야 하나요?

A2A v1.0은 /.well-known/agent-card.json을 표준 검색 경로로 등록합니다. 레거시 /.well-known/agent.json은 v1.0 이전 것이지만 여전히 많은 배포된 클라이언트가 확인하므로, 전환 기간 동안 두 경로 모두에 동일한 Agent Card를 게시하는 것이 실용적인 선택입니다.

두 경로가 동일한 JSON을 반환해야 하나요?

예. 두 경로에서 동일한 공개 Agent Card를 반환하면 한 가지 규칙만 지원하는 클라이언트도 일관되게 유지됩니다. 문서가 다르면 클라이언트가 어느 경로를 가져오는지에 따라 에이전트가 다르게 보입니다.

Agent Card는 어떤 콘텐츠 타입으로 제공해야 하나요?

사양은 Agent Card용으로 application/a2a+json을 등록합니다. 실무에서는 일반 application/json도 널리 허용되지만, 콘텐츠 타입이 HTML이면 그 경로가 Agent Card 대신 오류 페이지를 반환하고 있다는 확실한 신호입니다.

공개 Agent Card가 비공개 기능을 숨길 수 있나요?

예. 공개 Agent Card에는 검색에 안전한 메타데이터만 게시하고, capabilities.extendedAgentCard를 true로 설정한 후 인증된 GetExtendedAgentCard 작업을 통해 민감한 스킬을 노출하세요.

배포 후 검색 확인이 실패하는 이유는 무엇인가요?

흔한 원인은 로그인 페이지나 마케팅 페이지로의 리디렉션, 상태 200으로 반환되는 HTML 404 페이지, CDN에 캐시된 오래된 JSON, 또는 두 well-known 경로 중 하나만 배포된 경우입니다. 검사기는 각 경로의 상태 코드와 콘텐츠 타입을 보고하므로 문제가 즉시 드러납니다.

게시하기 전에

Agent Card를 검증한 후 URL을 확인하세요.

먼저 JSON을 전체 검증기에 통과시키고, 두 well-known 경로 모두에 게시한 후 이 검사기로 검색을 확인하세요.

검증기 열기Agent Card 생성하기