한 에이전트가 다른 에이전트에게 작업을 위임하기 전에, 먼저 해당 에이전트를 찾아내고 무엇을 할 수 있는지 알아야 합니다. 에이전트 카드(The Agent Card)가 바로 그 역할을 합니다.

에이전트 카드(The Agent Card)는 A2A(Agent-to-Agent) 에이전트를 설명하는 JSON 문서입니다. 즉, 에이전트의 정체성(identity), 엔드포인트(endpoint), 인증 요구사항(authentication requirements), 그리고 가장 중요한 요소인 제공 가능한 기술(skills)을 담고 있습니다.

이 문서는 /.well-known/agent-card.json이라는 잘 알려진 경로(well-known path)에 게시되므로, 에이전트의 기본 주소(base address)를 아는 클라이언트라면 누구나 이를 가져와서 해당 에이전트와 어떻게 협업해야 하는지 즉시 파악할 수 있습니다.

이는 클라이언트가 가장 먼저 가져오는 정보이자, 상호작용을 계획하기 위한 계약(contract)입니다. 카드를 제공하지 않는 에이전트는 발견될 수 없으며, 기술(skills)이 모호하게 설명된 에이전트 역시 실질적으로 발견될 수 없습니다.

발견(Discovery)이 최우선이어야 하는 이유

클라이언트가 작업을 보내기 전에 반드시 알아야 할 세 가지가 있습니다: 원격 에이전트가 존재하는지, 무엇을 할 수 있는지, 그리고 어떻게 통신하는지입니다. 이러한 질문에 답할 표준화된 방법이 없다면, 다시 엔드포인트를 하드코딩하거나 타인의 문서를 일일이 수동으로 읽어야 하는 상황으로 돌아가게 됩니다.

에이전트 카드는 단 한 번의 호출(fetch)로 이 세 가지 질문에 모두 답합니다. 이는 원격 에이전트가 게시하는 JSON 문서로, 귀하의 팀과 대화해 본 적 없는 팀이 구축한 클라이언트를 포함한 모든 클라이언트가 별도의 사적인 협의 없이도 에이전트의 정체성과 역량을 읽을 수 있게 해줍니다.

카드가 위치하는 곳

관례에 따라, 에이전트는 웹의 well-known URL과 동일한 개념인 잘 알려진 경로(well-known path)에 카드를 제공합니다. 이를 통해 발견(discovery) 과정은 여기저기 물어봐야 하는 문제가 아니라 예측 가능한 과정이 됩니다.

# 원격 에이전트의 공개 카드를 가져오기
curl https://agent.example.com/.well-known/agent-card.json

만약 카드를 curl로 가져올 수 없다면, 다른 어떤 것도 작동하지 않습니다. 이는 초기 실행 시 가장 흔히 발생하는 실수입니다. 에이전트는 완벽하게 잘 작동하고 있음에도 불구하고, 카드가 클라이언트가 찾는 위치에 제공되지 않아 어떤 클라이언트도 찾을 수 없는 상황이 발생하는 것입니다.

카드가 포함하는 내용

• Identity (정체성) — 에이전트의 이름, 설명, 제공자(provider) 및 버전.
• Endpoint (엔드포인트) — 에이전트가 A2A 요청을 받는 URL.
• Skills (기술) — 에이전트가 제공하는 개별적인 기능들로, 각 기술은 ID, 설명, 그리고 종종 예시 입력 및 출력을 포함합니다.
• Authentication (인증) — 에이전트가 요구하는 보안 체계로, 이를 통해 클라이언트는 작업을 보내기 전에 어떻게 인증해야 하는지 알 수 있습니다.
• Capabilities (역량) — 스트리밍(streaming)이나 푸시 알림(push notifications)과 같이 에이전트가 지원하는 프로토콜 기능.

최소한의 카드 (A minimal card)

{
  "name": "Research Agent",
  "description": "Gathers and summarizes sources on a topic",
...

기술(Skills)이 가장 중요한 부분입니다

기술(skills) 목록은 카드의 핵심입니다. 이는 클라이언트 — 또는 여러 에이전트 중 하나를 선택하는 오케스트레이션 에이전트(orchestrating agent) — 가 이 에이전트가 특정 작업에 적합한지 결정할 수 있게 해줍니다.

"처리(processing)"라고 기술된 기술은 호출자에게 아무런 정보도 주지 못합니다. 반면 "송장 PDF에서 항목을 추출하여 구조화된 데이터(structured data)로 반환"이라고 기술된 기술은 호출자에게 모든 것을 알려줍니다. 이 차이가 바로 당신의 에이전트가 실제로 사용될지 여부를 결정합니다.

• 각 기술에 **고정된 ID (stable id)**와 평이한 언어로 된 설명을 부여하세요.
• **기대하는 입력값(inputs)**과 반환되는 값의 형태(shape)를 명시하세요.
• 동작이 명확하지 않은 경우 **구체적인 예시(concrete example)**를 포함하세요.

기술 설명을 공개 API 문서처럼 취급하세요. 생태계의 나머지 구성원들에게 기술 설명은 정확히 그것이기 때문입니다.

공개 카드와 인증된 카드

에이전트는 누구에게나 노출되는 기본적인 공개 카드(public card)와, 신원을 증명한 클라이언트에게 제공되는 더 풍부한 인증된 카드(authenticated card)를 노출할 수 있습니다.

공개 카드는 에이전트를 발견하고 인증 방법을 배우기에 충분합니다. 인증된 카드는 신뢰할 수 있는 호출자만을 위해 예약된 추가 기술이나 상세 정보를 공개할 수 있습니다. 이러한 2단계 접근 방식(two-tier approach)을 통해 에이전트는 자신이 할 수 있는 모든 것을 인터넷 전체에 노출하지 않으면서도 발견 가능성을 유지할 수 있습니다.

서명된 카드와 신뢰

프로토콜이 성숙함에 따라 암호학적으로 서명된(cryptographically signed) 에이전트 카드(Agent Card) 지원이 추가되었으며, 이를 통해 클라이언트는 카드가 주장하는 에이전트의 실제 소유인지 확인할 수 있습니다.

이는 생각보다 훨씬 중요합니다. 카드는 클라이언트에게 작업을 어디로 보낼지, 그리고 어떻게 인증(authenticate)할지를 알려줍니다. 설득력 있는 카드를 제공할 수 있는 공격자는 해당 작업을 가로챌 수 있습니다. 신뢰가 중요한 모든 환경에서는 액면 그대로 받아들이는 카드보다 검증 가능한(verifiable) 카드를 선호해야 합니다.

카드 최신 상태 유지하기

에이전트 카드는 살아있는 문서입니다. 기술(skill)을 추가하거나, 엔드포인트(endpoint)를 변경하거나, 인증 요구 사항을 수정할 때 카드는 에이전트와 함께 업데이트되어야 합니다. 오래된(stale) 카드는 클라이언트를 잘못된 곳으로 안내하거나 새로운 능력을 숨기게 됩니다.

에이전트와 함께 카드의 버전을 관리하고, 카드 변경을 사후 처리가 아닌 배포(shipping)의 일부로 취급하십시오. 클라이언트는 당신이 광고하는 버전과 기능(capabilities)을 읽기 때문에, 이를 정직하게 유지하는 것이 상호 운용성(interoperability)을 유지하는 길입니다.

대규모 발견(Discovery at scale)

에이전트의 수가 증가함에 따라 엔드포인트를 하드코딩(hard-coding)하는 방식은 확장성을 유지할 수 없습니다. 바로 이 지점에서 카드의 진가가 발휘됩니다. 오케스트레이터(orchestrator)는 고정된 주소를 아는 대신, **작업을 광고된 기술과 매칭(matching a task to advertised skills)**함으로써 에이전트를 선택할 수 있습니다.

A2A 에이전트의 레지스트리(Registries)와 디렉토리(directories)는 이를 더욱 확장하여, 시스템이 역량 있는 에이전트를 동적으로 찾을 수 있게 해줍니다. 이는 마이크로서비스(microservices)의 서비스 디스커버리(service discovery)와 유사한 에이전트 버전의 기능입니다. 실질적인 결과는 다음과 같습니다. 새로운 전문 에이전트가 오케스트레이터를 수정하는 사람 없이도 당신의 시스템에 합류할 수 있습니다.

자주 묻는 질문 (FAQ)

A2A 에이전트 카드란 무엇인가요?
A2A 에이전트의 신원(identity), 엔드포인트(endpoint), 인증 요구 사항 및 기술(skills)을 설명하는 JSON 문서입니다. 이는 /.well-known/agent-card.json에 게시되어 어떤 클라이언트라도 에이전트를 발견하고 어떻게 협업할지 학습할 수 있습니다.

에이전트 카드는 어디에서 제공되나요?
웹의 다른 well-known URL들과 동일한 관례를 따라, 에이전트 호스트의 well-known 경로인 /.well-known/agent-card.json에서 제공됩니다.

내 에이전트가 카드를 제공하지 않으면 어떻게 되나요?
발견할 수 없게 됩니다. 클라이언트(Client)는 well-known 경로를 확인하는데, 그곳에 아무것도 없다면 에이전트가 내부적으로 아무리 잘 작동하더라도 해당 에이전트를 찾거나, 기술(skills)을 학습하거나, 인증(authenticate) 방법을 알 수 없습니다.

서명된 에이전트 카드(Signed Agent Card)란 무엇인가요?
클라이언트가 카드가 주장하는 에이전트의 실제 소유인지 검증할 수 있도록 암호학적으로 서명된 카드입니다. 카드는 클라이언트에게 작업을 어디로 보낼지 알려주기 때문에, 신뢰가 필요한 모든 곳에서 검증은 중요합니다.

좋은 기술(skill) 설명을 작성하려면 어떻게 해야 하나요?
공개 API 문서와 같이 작성하세요. 안정적인 ID, 해당 기술이 수행하는 작업에 대한 평이한 언어 설명, 예상되는 입력값(inputs), 반환값의 형태(shape), 그리고 동작이 명확하지 않을 경우 구체적인 예시를 포함해야 합니다. 모호한 기술은 실제 환경에서 에이전트를 보이지 않게 만듭니다.

이 시리즈의 다른 글들

• A2A vs MCP — A2A vs MCP: 모든 진지한 AI 에이전트 시스템 뒤에 있는 두 가지 프로토콜
• What Is A2A? — Agent2Agent 프로토콜이란 무엇인가? A2A에 대한 완전한 입문서
• The Task Lifecycle — A2A 작업 생명주기(Task Lifecycle) 이해하기 (그리고 모든 클라이언트를 멈추게 하는 버그)

더 깊이 알고 싶으신가요?

이 주제에 대해 두 권의 가이드를 작성했습니다.

A2A Quick-Start — 무료, 6페이지. 15분 만에 배우는 Agent2Agent 프로토콜: 정의, 5가지 구성 요소, 작업 생명주기(task lifecycle), 그리고 MCP가 어디에 위치하는지 알아봅니다.

A2A: The Complete Guide — 42페이지. 15개의 장과 5개의 부록으로 구성되어 있습니다. 발견(Discovery), 보안(security), SDK를 이용한 첫 에이전트 구축, 오케스트레이션 패턴(orchestration patterns), 확장(extensions) 및 AP2, 프로덕션 및 스케일링(scaling)을 다루며, 두 에이전트가 대화하는 전체 실습 예제와 30일 도입 경로를 제공합니다.