Google Agent Registry 2026: Agent Card란 무엇인가. A2A 에이전트는 능력·Tools·Skills를 JSON으로 어떻게 쓰는가

카탈로그이지, 세 번째 프로토콜이 아니다

Agent Registry를 들으면 Google이 또 대화 프로토콜을 만들었다고 생각한다. 아니다. A2A는 여전히 에이전트가 자신을 어떻게 말하고 Task를 어떻게 받는지 정한다. Registry는 Google Cloud의 발견 가능한 구성 요소 카탈로그다. 이미 있는 에이전트를 검색 가능한 자원으로 만든다. 등록 뒤 같은 프로젝트의 오케스트레이터, Gemini Enterprise, Agent Gateway가 스킬 키워드로 찾는다. 프로토콜은 여전히 A2A다. 바뀐 것은 누가 Card를 대신 기억하느냐다. 카탈로그가 없으면 URL을 오케스트레이터 설정에 박는다. 그건 2025년 주소록이지 2026년 발견이 아니다.

등록은 자동이거나 수동이다. 같은 프로젝트의 Agent Runtime, AI 에이전트 라벨과 Card 어노테이션이 있는 GKE, 기능 유형이 있는 Cloud Run, Google 자체의 Workspace / Gemini 에이전트는 스스로 카탈로그에 들어간다. 자동 등록은 이 프로젝트만 본다. 프로젝트 밖, 온프레미스, 자동 발견이 없는 런타임은 손으로 쓴 Service가 필요하고, 그다음 읽기 전용 Agent가 생긴다. 중앙 거버넌스 프로젝트가 spoke 에이전트를 보려면 마법 같은 조직 전체 스캔이 아니라 수동 교차 등록이다. Register agents 페이지는 2026-09-22에 갱신됐다.

같은 카탈로그는 MCP 서버도 받는다. 파일 이름은 toolspec.json이고 모양은 tools/list 응답과 같다. 상한도 10KB. 그래서 Registry에는 가로의 동료와 아래의 손이 같이 있다. 두 항목 유형을 하나의 범용 검증기로 쓰지 마라. 호출 홉에서 인자를 어떻게 보는지는 MCP와 JSON Schema. 오늘은 카탈로그가 어떻게 기억하는지뿐이다.

Agent Card: 색인되는 소스 JSON

Agent Card는 A2A 서버의 디지털 명함이다. 명세 경로는 여전히 /.well-known/agent-card.json이다. A2A v1.0에서 바뀐 점을 보라. A2A를 따르는 항목에 대해 Registry는 그 카드를 가져와 skills를 키워드 색인에 넣는다. 카드 자체는 공식 A2A 스키마를 통과해야 한다. 1.0 모양은 전송을 supportedInterfaces에 두고, 각 항에 url, protocolBinding, protocolVersion을 둔다. 최상위 url과 protocolVersion은 0.3 계약이다. 1.0 클라이언트는 이를 주 필드로 읽지 않아야 한다.

사람을 위한 신원은 name, description, version이다. 여기 version은 에이전트 자신의 버전이지 프로토콜 버전이 아니다. 프로토콜 버전은 인터페이스와 같이 간다. skills[] 각 항에는 id, name, description이 필요하다. Registry가 검색하는 것은 tags다. examples는 사람용 프롬프트이지 인자 스키마가 아니다. 전체 필드 표는 다음 글. 오늘 기억할 것: 유효한 Card가 없으면 A2A 유형의 자동 추출은 일어나지 않는다. 10KB를 넘으면 Registry가 거절하고 오케스트레이터는 찾지 못한다.

아래는 저장소에 넣을 수 있는 1.0 카드다. 먼저 parse되게 하고, 공식 스키마를 돌린다. 런북 전체를 description에 부으면 상한에 먼저 걸린다. 발견면은 짧은 설명과 tags이지, 안내서를 명함에 집어넣는 일이 아니다.

{
  "name": "Invoice Specialist",
  "description": "Finds and summarizes invoices for finance. Does not post payments.",
  "version": "1.2.0",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/invoice/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "search-invoices",
      "name": "Search invoices",
      "description": "Look up invoices by week, status, or counterparty.",
      "tags": ["invoices", "finance", "search"],
      "examples": ["Find overdue invoices for last week"]
    }
  ]
}

등록 이후: 카탈로그 항목은 이렇게 보인다

명세는 Google이 로컬 「카탈로그 스냅샷」을 내보내라고 하지 않는다. 리뷰는 색인된 내용을 보고 싶다. 결과를 픽스처로 접는다. displayName, specType(A2A_AGENT_CARD 또는 NO_SPEC), cardVersion, 뽑힌 skill id, interfaces, searchKeywords. 그 스냅샷은 A2A 스키마 인스턴스가 아니다. Card 스키마로 검증하지 마라. CI 어서션이다. 등록 성공은 검색 가능과 같지 않다.

{
  "registry": "google-cloud-agent-registry",
  "displayName": "Invoice Specialist",
  "specType": "A2A_AGENT_CARD",
  "cardVersion": "1.0",
  "skillsIndexed": ["search-invoices"],
  "searchKeywords": ["invoices", "finance", "search"],
  "interfaces": [
    {
      "url": "https://agents.example.com/invoice/a2a",
      "protocolBinding": "JSONRPC"
    }
  ]
}

자동 추출은 A2A를 따르는 항목에서만 일어난다. Registry는 /.well-known/agent-card.json을 조회하고 주장한 스킬을 카탈로그에 쓴다. NO_SPEC REST 엔드포인트는 카탈로그에 들어가지만 검색할 스킬이 없다. 오케스트레이터는 에이전트가 있다는 것만 보고, 「청구서를 조회하는 동료」와는 매칭하지 못한다. 검색되게 하려면 Card를 더하거나 독립 스킬 자원을 등록한다. Gemini Enterprise는 독립 스킬을 최상위 Skill 자원으로도 등록할 수 있다. 그건 다른 거버넌스 선이다. Card skills[]와 같은 파일에 합치지 마라.

스냅샷과 커밋한 Card를 나란히 diff한다. 키워드가 어긋나면 tags를 빠뜨렸거나 색인이 늦다. URL이 어긋나면 낡은 엔드포인트를 등록한 것이다. Card는 유효한데 skillsIndexed가 비면, Registry가 1.0 규칙으로 0.3 카드를 읽었는지 본다. supportedInterfaces가 없으면 추출이 조용히 얇아지고, 티켓에는 「찾을 수 없음」만 남는다.

Card의 skills는 MCP tools도, Plugin 스킬도 아니다

같은 단어, 세 층. Card 스킬은 이 에이전트가 맡는다고 주장하는 일이며 카탈로그 검색과 오케스트레이터 선택용이다. MCP tool은 결정적 호출이고 계약은 inputSchema다. Plugin / Agent Skills의 SKILL.md는 같은 에이전트 자신의 모델이 읽는 브리프다. Registry가 색인하는 것은 첫 번째다. MCP 도구 이름을 Card.skills[].id에 복사하면 검색은 우연히 맞을 수 있다. 위임 상대는 여전히 불투명한 에이전트이지 tools/call이 아니다. 여러 턴의 확인과 비동기 콜백은 함수 호출 모양을 터뜨린다.

어떤 Card 구현은 스킬에 inputSchema를 붙인다. 그건 힌트 모양이지 MCP 실행 계약이 아니다. Card를 plugin.schema.json으로 검증하지 말고, tools/call을 Card로 검증하지 마라. 세 JSON이 모두 「능력」이라고 쓰지만 실패 처리는 다르다. 나쁜 Card는 발견 실패. 나쁜 inputSchema는 호출 실패. 한 코딩 에이전트가 스킬과 손을 어떻게 기르는지는 Plugin Manifest 실전. 오늘은 다른 에이전트가 카탈로그에 어떻게 기억되는지만 본다.

NO_SPEC 항목에는 그런 주장이 없다. 카탈로그에서는 호스트 이름만 있는 주소록 줄처럼 보인다. 키워드로는 찾을 수 없다. 독립 스킬을 등록하거나 Card를 더하지 않으면. 먼저 찾아져야 하는지를 정하고, 그다음 A2A를 쓸지를 정한다. 카탈로그용 빈 Card는 빈 스킬 배열을 색인한다. 등록하지 않는 것보다 나쁘다.

0.3과 1.0: 두 계약을 섞어 검증하지 말 것

Registry는 0.3과 1.0을 모두 받는다. 새 카드는 1.0이어야 한다. 1.0은 프로토콜 버전과 주 URL을 supportedInterfaces로 옮겼다. extendedAgentCard는 capabilities 아래다. 0.3의 stateTransitionHistory는 더 이상 핵심 능력이 아니다. 두 필드 집합을 섞으면 클라이언트는 각자 반쪽을 읽고 카탈로그 색인은 반을 잃는다. A2A 자신의 breaking list는 v1.0 변경 페이지에 있다. Google 사설 포크가 아니다.

리뷰에 카드를 적어도 두 장 둔다. 위의 합법 1.0과, url을 최상위에 두고 1.0으로 등록하는 음례. 두 번째는 1.0 검증에서 실패하거나 주 엔드포인트가 무시되어야 한다. CI가 두 스키마를 「범용 에이전트 검사」 하나로 뭉개면 클라이언트보다 더 지저분하다. Registry는 선언한 버전으로 규칙을 고르고, 로드 중에 스키마를 가져오지 않는다. Plugin Manifest와 같은 규율이다.

서명, 확장 카드, GetExtendedAgentCard는 인증 이후 보안 층이지 카탈로그 진입 조건이 아니다. 공개 카드가 먼저 스킬을 내놓고, 오케스트레이터가 인증된 두 번째 사본을 가져올지 정한다. 서명은 오늘 범위 밖이다. 먼저 tags를 검색 가능하게 하라.

픽스처는 JSONVue에 남긴다

리뷰 픽스처는 적어도 세 장. 위의 1.0 Card, 카탈로그 스냅샷, 0.3/1.0을 섞은 음례. 첫 장은 A2A 1.0 스키마를 통과해야 한다. 둘째는 자체 스냅샷 스키마거나 skillsIndexed와 tags 어서션. 셋째는 반드시 실패한다. 닫힌 Plugin 필드를 Card에 베끼거나 MCP inputSchema 표 전체를 skills[]에 부으면 diff에서 바로 보인다.

MCP 대조 한 장을 더한다. 합법 toolspec.json으로 카탈로그의 두 번째 소스 파일을 증명한다. Card 스키마를 그 위에 돌리지 마라. tools[].name은 런타임용, skills[].tags는 검색용이다. 비밀을 커밋된 픽스처에 넣지 마라. Card는 공개 명함이다. 가져와질 것처럼 쓴다.

브라우저에서 이렇게 하면 된다.JSON 포맷터로 Card와 스냅샷이 parse되는지 보고,JSON Schema 검증기로 1.0 supportedInterfaces와 skills를 보고,JSON Diff로 커밋한 Card와 스냅샷 사이 tags / URL 어긋남을 잡는다. 데이터는 기기를 떠나지 않는다. 더 읽을 글:A2A vs MCP, MCP 검증, Plugin Manifest.

관련: A2A vs MCP, MCP와 JSON Schema, Plugin Manifest 실전.

자주 묻는 질문

정리와 다음 단계

2026년 Google Agent Registry는 한 줄로 접힌다. 카탈로그이고, Card가 색인되는 소스 JSON이다. 오케스트레이터가 찾는 것은 tags와 스킬 이름이지 슬라이드의 토폴로지가 아니다.

내는 순서: 합법 1.0 Card. 등록 때 specType을 본다. 스냅샷으로 스킬이 진짜 올라갔는지 어서트한다. MCP는 별도 toolspec.json. 세 계약을 JSONVue에서 확인한다. 층은 A2A vs MCP 글. 필드는 다음 글. 걷는 법은 그다음 글.