Agent Card로 에이전트를 발견하기
발견은 협업의 첫 단계다
멀티 에이전트 시스템은 여러 전문가가 함께 일하는 조직과 비슷하다. 회계 담당자에게 법률 검토를 맡기면 좋은 결과를 기대하기 어렵고, 문서만 받을 수 있는 사람에게 동영상 분석을 부탁해도 일이 막힌다. 에이전트도 마찬가지다. 일을 맡기기 전에 먼저 물어야 한다.
이 에이전트는 누구인가. 무엇을 할 수 있는가. 어디로 요청을 보내야 하는가. 어떤 입력을 받을 수 있고, 어떤 결과를 돌려줄 수 있는가. 인증은 어떻게 해야 하는가.
A2A에서 이 질문에 답하는 문서가 Agent Card다. Agent Card는 원격 에이전트의 명함이자 서비스 메뉴판이다. 여기서 원격 에이전트란 네트워크 너머에 있거나, 적어도 내가 내부를 직접 제어하지 않는 협업 상대를 뜻한다. 클라이언트는 일을 요청하는 쪽이고, Agent Card를 읽어 적절한 원격 에이전트를 고른다.
A2A 공식 문서는 Agent Card를 A2A 서버가 게시하는 JSON 메타데이터 문서로 설명한다. 이 문서는 에이전트의 정체성, 능력, 스킬, 서비스 엔드포인트, 인증 요구사항을 알려준다.1 핵심은 간단하다. 에이전트끼리 협업하려면 먼저 서로를 발견해야 한다.
AI 생성 이미지
Agent Card는 명함이지만, 더 구체적이다
사람의 명함에는 이름, 소속, 연락처가 있다. Agent Card에는 여기에 더해 '무슨 일을 할 수 있는지'와 '어떤 방식으로 대화할 수 있는지'가 들어간다. 보통 다음 정보가 중요하다.
이름과 설명: 사람이 읽고 이해할 수 있는 에이전트의 이름과 역할이다.
제공자와 버전: 어느 조직이 제공하는지, 현재 버전은 무엇인지 알려준다.
서비스 엔드포인트: 실제 A2A 요청을 보낼 주소다.
지원 기능: 스트리밍, 푸시 알림, 상태 전이 이력 같은 프로토콜 기능 지원 여부다.
스킬: 계약서 검토, 이미지 분류, 회의록 요약처럼 에이전트가 수행할 수 있는 업무 단위다.
입출력 방식: 텍스트, JSON 같은 구조화 데이터, 파일, 이미지, 오디오·비디오 참조 등 어떤 형식을 받을 수 있고 내보낼 수 있는지다.
보안 요구사항: 어떤 인증 방식이 필요한지, 어떤 보안 스킴을 따라야 하는지다.
중요한 점은 Agent Card가 에이전트의 내부를 공개하는 문서가 아니라는 것이다. 내부 프롬프트, 모델 종류, 메모리 구조, 도구 호출 방식까지 보여줄 필요는 없다. A2A의 기본 원칙은 불투명한 에이전트도 협업할 수 있게 하는 것이다. 즉, 내부 사정을 몰라도 외부에서 안전하게 일을 맡길 수 있는 접점을 표준화한다.
A2A 최신 사양도 에이전트가 서로의 능력을 발견하고, 텍스트·파일·구조화 데이터 같은 상호작용 방식을 협상하며, 내부 상태나 도구를 공유하지 않고 협업하는 것을 목표로 둔다.2 Agent Card는 이 목표가 실제 시스템에서 시작되는 지점이다.
Agent Card는 어디에서 찾는가
가장 단순한 방식은 잘 알려진 위치에 Agent Card를 두는 것이다. A2A의 발견 가이드는 공개 에이전트나 도메인 단위 발견을 위해 다음 위치를 권장한다.1
https://{agent-server-domain}/.well-known/agent-card.json
클라이언트는 어떤 도메인에 에이전트가 있을 것으로 기대하면 이 주소로 HTTP GET 요청을 보내 Agent Card를 읽는다. 웹사이트의 robots.txt나 OpenID Connect의 well-known 설정처럼, 약속된 위치에 기계가 읽을 수 있는 설명서를 두는 방식이다.
하지만 모든 환경이 이렇게 단순하지는 않다. 기업 내부에는 수십 개, 많게는 수백 개의 에이전트가 있을 수 있다. 이때 클라이언트가 모든 도메인을 돌아다니며 카드를 가져오는 방식은 관리하기 어렵다. 그래서 실무에서는 보통 세 가지 발견 방식을 조합한다.
첫째, well-known URI 기반 발견이다. 공개 에이전트나 도메인 중심 구조에 적합하다. 간단하고 표준적이지만, 대규모 환경에서는 검색과 신뢰 검증이 약해질 수 있다.
둘째, 레지스트리 또는 카탈로그 기반 발견이다. 중앙 목록에 Agent Card를 등록해 두고, 클라이언트가 스킬, 태그, 제공자, 보안 등급 같은 조건으로 검색한다. 사내 앱스토어에서 업무 도구를 찾는 방식과 비슷하다. 대규모 조직에서는 이 방식이 운영과 거버넌스에 유리하다.
셋째, 직접 설정 기반 발견이다. 개발 환경이나 폐쇄적인 시스템에서 설정 파일, 환경 변수, 내부 API를 통해 특정 Agent Card 위치를 미리 알려준다. 동적 발견에는 약하지만, 통제된 환경에서는 단순하고 안전하다.
A2A가 공개 표준이라는 점은 여기서 중요하다. Agent Card를 특정 회사의 전용 카탈로그에만 묶어 두지 않아도 된다. well-known URI, 사내 레지스트리, 직접 설정 등 환경에 맞는 방식을 선택하되, 카드의 의미와 구조는 공통으로 유지할 수 있다.
capability discovery는 라우팅의 재료다
capability discovery는 말 그대로 '상대가 무엇을 할 수 있는지 알아내는 과정'이다. 이 과정은 단순 검색이 아니라 작업 라우팅의 출발점이다. 라우팅은 들어온 일을 적절한 담당자에게 배정하는 일이다.
예를 들어 사용자가 클라이언트 에이전트에게 이렇게 요청했다고 하자.
이 계약서 PDF를 검토해서 위험 조항을 표로 정리해 줘.
클라이언트 에이전트는 바로 아무 에이전트에게나 요청하지 않는다. 먼저 후보 에이전트들의 Agent Card를 확인한다.
PDF 파일 입력을 받을 수 있는가?
계약서 또는 법률 문서 검토 스킬이 있는가?
결과를 표나 JSON 같은 구조화된 형식으로 돌려줄 수 있는가?
민감한 문서를 처리할 보안 정책과 인증 방식이 있는가?
긴 작업이라면 진행 상태를 스트리밍하거나 완료 시 알림을 보낼 수 있는가?
이 조건을 만족하는 에이전트가 있다면 클라이언트는 그 에이전트를 선택한다. 없다면 다른 전략을 세운다. 예를 들어 PDF를 먼저 텍스트로 변환하는 에이전트에게 맡긴 뒤, 그 결과를 법률 검토 에이전트에게 넘길 수 있다. 또는 보안 등급이 맞지 않으면 사용자에게 추가 승인을 요청할 수 있다.
이처럼 Agent Card는 '선택'을 가능하게 한다. 단순히 주소록에서 URL을 찾는 것이 아니라, 업무 요구사항과 에이전트 능력을 비교하는 기준을 제공한다. 다만 Agent Card가 모든 판단을 대신하지는 않는다. 비용, 지연 시간, 신뢰도, 과거 성공률, 조직 정책 같은 정보는 별도 운영 데이터와 함께 판단해야 한다.
상호작용 방식도 협상해야 한다
사람 사이의 협업에서도 형식은 중요하다. 어떤 사람은 이메일로 요약을 받길 원하고, 어떤 사람은 스프레드시트를 원한다. 어떤 업무는 말로 설명하면 충분하지만, 어떤 업무는 원본 파일이 꼭 필요하다.
A2A에서 이런 형식을 interaction modality, 즉 상호작용 방식이라고 부른다. 쉽게 말해 에이전트가 주고받을 수 있는 내용의 종류다. 텍스트, 구조화 데이터, 양식, 파일, 이미지, 오디오, 비디오 등이 여기에 포함된다. 실제 구현에서는 MIME 타입이나 파일 참조, 구조화된 Part 같은 형태로 표현된다.
Agent Card는 기본 입력 방식과 출력 방식을 알려준다. 예를 들어 어떤 에이전트는 text/plain 입력만 받을 수 있고, 다른 에이전트는 application/pdf 파일과 application/json 데이터를 함께 처리할 수 있다. 출력도 마찬가지다. 어떤 에이전트는 자연어 설명만 돌려주고, 어떤 에이전트는 표 형태의 JSON이나 보고서 파일을 만들 수 있다.
스킬마다 가능한 방식이 다를 수도 있다. 한 에이전트가 '문서 요약' 스킬에서는 PDF를 받을 수 있지만, '질의응답' 스킬에서는 텍스트만 받을 수 있다. 그래서 Agent Card에는 에이전트 전체의 기본 입출력 방식과 함께, 스킬별 입출력 방식을 표현할 수 있다.
이 협상이 필요한 이유는 실패를 줄이기 위해서다. 클라이언트가 동영상 파일을 보냈는데 원격 에이전트가 텍스트만 처리할 수 있다면 요청은 실패한다. 반대로 Agent Card를 미리 읽으면 클라이언트는 동영상을 먼저 자막으로 변환하거나, 애초에 미디어 분석 에이전트를 선택할 수 있다.
협상은 거창한 절차가 아니다. 대개는 클라이언트가 카드의 정보를 보고 호환되는 입력과 출력을 고르는 과정이다. 중요한 것은 요청을 보내기 전에 양쪽이 이해할 수 있는 형식을 맞추는 것이다.
인증 정보는 공개하되, 비밀은 공개하지 않는다
Agent Card에는 보안 정보도 들어간다. 하지만 여기서 보안 정보란 비밀번호나 토큰 값을 공개한다는 뜻이 아니다. '어떤 인증 방식을 요구하는지'를 알려주는 것이다.
예를 들어 Agent Card는 Bearer 토큰, API 키, OAuth 2.0, OpenID Connect 같은 인증 방식을 요구한다고 표현할 수 있다. 최신 A2A 사양에서는 표준 웹 보안 관행에 맞춘 안전한 통신을 중요한 목표로 둔다.2 실무적으로는 다음 원칙을 지켜야 한다.
첫째, 인증 방식과 자격 증명을 구분한다. Agent Card에는 'OAuth 2.0이 필요하다'는 요구사항을 쓸 수 있지만, 실제 access token을 공개 카드에 넣어서는 안 된다. 공개 문서에 비밀을 넣는 순간 그 비밀은 더 이상 비밀이 아니다.
둘째, 공개 카드와 비공개 카드를 나눈다. 외부에 공개되는 Agent Card에는 최소 정보만 담고, 인증된 클라이언트에게 더 자세한 카드나 확장 정보를 제공할 수 있다. 민감한 스킬 이름, 내부 엔드포인트, 운영 정책을 모두 공개할 필요는 없다.
셋째, 권한 범위를 명확히 한다. 인증은 '누구인지 확인'하는 과정이고, 인가는 '무엇을 해도 되는지 결정'하는 과정이다. 계약서 검토 에이전트에 접근할 수 있다고 해서 모든 고객 문서를 볼 수 있어서는 안 된다. 스코프, 역할 기반 접근 제어, 테넌트 경계가 함께 설계되어야 한다.
넷째, 신뢰할 수 있는 발견 경로를 사용한다. 대규모 환경에서는 아무 Agent Card나 믿으면 안 된다. 신뢰된 레지스트리, 카드 검증, 도메인 확인, 버전 관리가 필요하다. 보안 관점의 실무 자료들도 단순한 직접 발견만으로는 대규모 배포에 한계가 있으며, 신뢰된 에이전트 레지스트리와 검증 메커니즘이 필요하다고 지적한다.3
다섯째, Agent Card는 보안 집행 장치가 아니다. 카드는 정책을 설명할 수 있지만, 실제 접근 통제는 서버에서 집행해야 한다. 잘못된 클라이언트가 허용되지 않은 태스크를 요청하면 서버가 거부해야 한다. 카드에 적혀 있다는 사실만으로 보안이 완성되지는 않는다.
좋은 Agent Card를 설계하는 기준
좋은 Agent Card는 자세하지만 과하지 않다. 클라이언트가 에이전트를 선택하고 요청을 구성하는 데 필요한 정보는 충분히 제공해야 한다. 그러나 내부 구현이나 민감한 운영 정보를 불필요하게 드러내서는 안 된다.
작성할 때는 다음 질문을 점검하면 좋다.
사람이 읽었을 때 이 에이전트의 역할이 분명한가?
기계가 읽었을 때 스킬과 입출력 방식이 명확한가?
어떤 엔드포인트로 어떤 인증을 사용해야 하는지 알 수 있는가?
스트리밍, 푸시 알림, 상태 이력 같은 기능 지원 여부가 드러나는가?
버전과 제공자 정보가 있어 변경 추적이 가능한가?
공개해도 되는 정보와 인증 후에만 보여줄 정보를 구분했는가?
Agent Card는 멀티 에이전트 시스템의 시작점이다. 태스크를 만들고 메시지를 주고받기 전에, 클라이언트는 먼저 협업할 상대를 찾아야 한다. 누구에게 일을 맡길지 모른다면 프로토콜의 나머지 기능도 사용할 수 없다.
다음 장에서 다룰 Task, Message, Artifact는 실제 업무를 표현하는 구조다. Agent Card가 '누구에게 맡길 수 있는가'를 알려준다면, Task와 Message와 Artifact는 '무엇을 맡겼고, 어떤 대화를 나눴으며, 무엇이 결과로 나왔는가'를 표현한다.
참고
1Agent Discovery - A2A Protocol
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.