A2A 클라이언트와 오케스트레이터 만들기

클라이언트가 협업의 중심이다

8장에서는 하나의 A2A 호환 에이전트를 만들었다. 이제 관점을 바꿔 보자. 실제 업무에서는 한 에이전트만 호출해서 끝나는 경우보다 여러 전문 에이전트를 골라 쓰는 경우가 많다. 시장 조사는 리서치 에이전트에게, 코드 검토는 개발 에이전트에게, 법무 검토는 컴플라이언스 에이전트에게 맡길 수 있다.

이때 필요한 주체가 클라이언트 에이전트다. 클라이언트 에이전트는 단순히 HTTP 요청을 보내는 프로그램이 아니다. 사용자의 목표를 이해하고, 일을 나누고, 적절한 원격 에이전트를 선택하고, 결과를 모아 최종 답을 만드는 조율자다. 회사로 비유하면 프로젝트 매니저에 가깝다.

오케스트레이터는 이런 조율 기능을 구현한 구성 요소다. 오케스트라는 여러 악기가 따로 연주하지만 지휘자가 박자와 순서를 맞춘다. A2A 오케스트레이터도 마찬가지다. 여러 원격 에이전트가 각자의 방식으로 일하더라도, 클라이언트 쪽에서 요청 순서, 상태 추적, 결과 병합, 오류 복구를 관리한다.

A2A가 공개 표준으로 강조하는 가치는 바로 이 지점에서 드러난다. 서로 다른 프레임워크와 벤더로 만든 에이전트도 공통 언어로 발견하고 호출할 수 있어야 한다는 문제의식이 A2A의 출발점이다.¹ Google이 제안한 이 문제의식은 Linux Foundation 기반의 공개 표준 맥락으로 확장되면서, 특정 플랫폼 안의 통합이 아니라 플랫폼 밖의 협업까지 고려하는 방향으로 발전했다.

AI 생성 이미지

Agent Card로 기능 카탈로그 만들기

오케스트레이터가 가장 먼저 해야 할 일은 "누가 무엇을 할 수 있는가"를 아는 것이다. 이를 위해 각 원격 에이전트의 Agent Card를 수집해 기능 카탈로그를 만든다. 기능 카탈로그는 여러 에이전트의 명함과 메뉴판을 한곳에 모은 목록이다.

카탈로그에는 보통 다음 정보가 들어간다.

• 에이전트 이름과 설명

• 서비스 엔드포인트

• 제공자와 버전

• 지원하는 스킬 목록

• 스킬별 태그, 설명, 예시

• 입력·출력 형식

• 인증 요구사항

• 스트리밍, 푸시 알림, 파일 처리 같은 지원 기능

• 운영 정책: 타임아웃, 우선순위, 비용, 신뢰 등급 등

A2A 생태계의 SDK들은 Agent Card 발견, 메시지 전송, 스트리밍, 장기 실행 태스크 처리를 클라이언트 쪽에서 구현할 수 있도록 돕는다.² 예를 들어 Python SDK를 사용하든 JavaScript SDK를 사용하든, 핵심 흐름은 같다. Agent Card를 읽고, 그 내용을 바탕으로 클라이언트를 만들고, 적절한 메서드로 메시지나 태스크를 보낸다.

카탈로그는 정적으로 설정할 수도 있고 동적으로 갱신할 수도 있다. 작은 실험에서는 다음처럼 몇 개의 URL을 설정 파일에 적어 두고 시작해도 된다.

• research-agent: 시장 조사, 웹 리서치, 요약

• code-agent: 코드 리뷰, 테스트 제안, 리팩터링

• data-agent: CSV 분석, 통계 요약, 차트 생성

하지만 운영 환경에서는 더 신중해야 한다. Agent Card의 버전이 바뀌었는지 확인하고, 인증 정책이 달라졌는지 감지하고, 더 이상 신뢰할 수 없는 에이전트를 카탈로그에서 제외해야 한다. 캐시를 쓰더라도 만료 시간을 두어야 한다. 에이전트가 사라졌는데 오래된 Agent Card만 믿고 요청을 보내면 장애가 된다.

실제 오케스트레이터 예제에서는 여러 에이전트의 Agent Card를 읽은 뒤, 각 카드의 스킬과 태그를 인덱싱해 요청 라우팅에 사용한다. 단순한 버전은 사용자 요청의 단어와 스킬 태그의 겹침을 비교해 가장 알맞은 에이전트를 고를 수 있다.³ 이 방식은 이해하기 쉽지만 한계도 분명하다. "계약서 위험을 요약해 줘"라는 요청이 법무 검토인지 요약 작업인지 문맥에 따라 달라질 수 있기 때문이다.

사용자 요청을 라우팅하는 흐름

라우팅은 "이 일을 누구에게 맡길 것인가"를 결정하는 과정이다. 좋은 라우터는 단순히 키워드를 맞추지 않는다. 사용자의 의도, 필요한 전문성, 데이터 민감도, 출력 형식, 작업 시간, 실패 시 대안까지 함께 고려한다.

기본 흐름은 다음과 같다.

1. 요청 이해: 사용자의 목표와 제약을 파악한다. 필요한 경우 추가 질문을 한다.

2. 작업 분해: 하나의 요청을 여러 하위 작업으로 나눈다.

3. 후보 선택: 기능 카탈로그에서 관련 스킬을 가진 에이전트를 찾는다.

4. 정책 검사: 인증, 권한, 데이터 반출 가능 여부, 비용, 신뢰 등급을 확인한다.

5. 호출 방식 결정: 짧은 작업은 message/send, 긴 작업은 message/stream이나 푸시 알림 기반 흐름을 선택한다.

6. 결과 수집: Message와 Artifact를 모아 최종 응답을 만든다.

라우팅 로직은 단계적으로 발전시키는 편이 좋다. 처음에는 규칙 기반으로 시작할 수 있다. 예를 들어 "코드", "버그", "테스트"라는 단어가 있으면 코드 에이전트로 보내고, "매출", "CSV", "상관관계"가 있으면 데이터 에이전트로 보낸다.

그다음에는 스코어링을 추가할 수 있다. 스킬 태그 일치도, 입력 형식 일치 여부, 과거 성공률, 평균 응답 시간, 비용을 점수화해 가장 높은 후보를 선택한다. 더 복잡한 환경에서는 LLM이 작업을 분해하고 후보 에이전트를 추천하도록 할 수 있다. 다만 최종 호출 전에 정책 검사는 코드로 명확히 수행하는 것이 좋다. 모델의 판단만으로 민감한 데이터를 외부 에이전트에 보내서는 안 된다.

라우팅에서 중요한 원칙은 "모르면 묻기"다. 오케스트레이터가 확신하지 못하면 임의로 에이전트를 선택하기보다 사용자에게 질문해야 한다. 예를 들어 "이 계약서를 법무 위험 관점에서 검토할까요, 아니면 핵심 조항만 요약할까요?"라고 묻는 편이 안전하다.

순차 워크플로와 병렬 워크플로

여러 에이전트를 호출하는 방식은 크게 순차와 병렬로 나눌 수 있다.

순차 워크플로는 앞 단계의 결과가 다음 단계의 입력이 되는 구조다. 예를 들어 "신제품 출시 전략 보고서"를 만든다고 하자. 먼저 리서치 에이전트가 시장 자료를 모은다. 다음으로 데이터 에이전트가 수치를 분석한다. 마지막으로 작성 에이전트가 보고서를 만든다. 각 단계는 이전 단계의 Artifact를 입력으로 받는다.

순차 흐름에서는 상태 관리가 중요하다. 첫 번째 태스크가 실패하면 다음 태스크를 시작할 수 없다. 중간 결과가 부족하면 input-required 상태로 멈추고 사용자에게 추가 정보를 요청해야 한다. 또한 각 단계의 Artifact가 다음 단계에 그대로 전달되어도 되는지 확인해야 한다. 필요 없는 개인정보나 내부 메모까지 넘기면 안 된다.

병렬 워크플로는 서로 독립적인 작업을 동시에 실행하는 구조다. 예를 들어 한 문서를 법무, 보안, 브랜드 관점에서 동시에 검토할 수 있다. 세 에이전트가 같은 입력을 받아 각자 결과를 만든 뒤, 오케스트레이터가 결과를 비교하고 종합한다.

병렬 흐름에서는 결과 수집과 충돌 조정이 중요하다. 한 에이전트는 "문제 없음"이라고 하고 다른 에이전트는 "위험 높음"이라고 할 수 있다. 오케스트레이터는 이를 단순 평균으로 처리하지 말고, 어떤 관점에서 충돌이 생겼는지 설명해야 한다. 장기 실행 작업에서는 일부 태스크만 실패할 수도 있다. 이 경우 전체를 실패로 볼지, 부분 결과를 사용자에게 보여 줄지, 대체 에이전트를 호출할지 정책을 정해 두어야 한다.

멀티 에이전트 설계에서는 순차, 병렬, 핸드오프, 사람 승인 같은 패턴을 상황에 맞게 조합해야 한다. 특히 외부 에이전트나 서로 다른 플랫폼의 에이전트를 호출할 때는 A2A의 태스크와 Artifact 모델을 사용해 장기 실행 작업을 추적하는 것이 적합하다.⁴

직접 처리할 일과 위임할 일

오케스트레이터가 모든 일을 직접 하면 원격 에이전트를 쓰는 의미가 줄어든다. 반대로 모든 일을 위임하면 전체 품질과 보안을 통제하기 어렵다. 따라서 클라이언트 에이전트가 직접 처리할 일과 원격 에이전트에 맡길 일을 나누어야 한다.

클라이언트가 직접 처리해야 할 일은 다음과 같다.

• 사용자 의도 확인과 추가 질문

• 작업 분해와 실행 계획 수립

• Agent Card 기반 후보 선정

• 인증, 권한, 데이터 민감도 검사

• 태스크 ID와 컨텍스트 관리

• 중간 결과의 검증과 필터링

• 최종 결과의 종합과 사용자 설명

• 실패 시 재시도, 취소, 대체 경로 선택

원격 에이전트에 위임하기 좋은 일은 다음과 같다.

• 특정 도메인 전문성이 필요한 작업

• 외부 조직이나 다른 팀이 소유한 기능

• 이미 검증된 전문 에이전트가 더 잘 처리하는 작업

• 장시간 실행되는 분석, 생성, 검토 작업

• 특정 도구나 데이터에 접근해야 하는 작업

• 결과가 명확한 Artifact로 반환될 수 있는 작업

기준은 단순하다. 전체 흐름과 책임은 클라이언트가 잡고, 전문 실행은 원격 에이전트에 맡긴다. 오케스트레이터는 원격 에이전트의 내부 프롬프트, 메모리, 도구 호출 과정을 알 필요가 없다. 대신 Agent Card, Task 상태, Message, Artifact라는 외부 계약을 신뢰하고 관리한다.

태스크 추적과 오류 복구

오케스트레이터에는 태스크 관리자(Task Manager)가 필요하다. 태스크 관리자는 어떤 사용자 요청에서 어떤 원격 태스크가 만들어졌는지 기록한다. 최소한 다음 정보를 저장해야 한다.

• 사용자 요청 ID

• 컨텍스트 ID

• 원격 에이전트 ID

• 원격 태스크 ID

• 현재 상태

• 마지막 업데이트 시각

• 수신한 Artifact 목록

• 재시도 횟수와 오류 기록

스트리밍을 사용하는 경우 이벤트가 중복으로 도착할 수 있다. 네트워크가 끊긴 뒤 재구독하면 이미 받은 상태 업데이트가 다시 올 수도 있다. 따라서 클라이언트는 이벤트를 받을 때마다 "새 정보인가, 이미 처리한 정보인가"를 확인해야 한다. 최종 응답을 만들기 전에는 tasks/get 같은 조회 흐름으로 확정 상태를 확인하는 편이 안전하다.

오류도 구분해서 다루어야 한다. 네트워크 오류는 재시도할 수 있다. 인증 오류는 토큰 갱신이나 사용자 승인이 필요하다. JSON-RPC 오류는 요청 형식이나 파라미터를 고쳐야 할 수 있다. A2A 태스크가 failed가 되었다면 원격 에이전트가 업무 수행에 실패한 것이다. 이때는 같은 요청을 다시 보낼지, 다른 에이전트를 선택할지, 사용자에게 실패 이유를 설명할지 결정해야 한다.

재시도에는 주의가 필요하다. 같은 태스크를 두 번 실행하면 비용이 두 번 발생하거나 외부 시스템에 중복 작업이 생길 수 있다. 따라서 요청 ID, 메시지 ID, 태스크 ID를 저장하고 멱등성을 고려해야 한다. 멱등성이란 같은 요청을 여러 번 보내도 결과가 한 번 처리된 것처럼 유지되는 성질이다.

작은 오케스트레이터의 예

예를 들어 사용자가 "다음 분기 일본 시장 진출 가능성을 검토하고, 핵심 리스크와 실행 제안을 보고서로 정리해 줘"라고 요청했다고 하자.

오케스트레이터는 먼저 요청을 세 부분으로 나눈다.

1. 시장 정보 조사

2. 리스크 분석

3. 보고서 작성

기능 카탈로그에서 리서치 에이전트, 리스크 분석 에이전트, 문서 작성 에이전트를 찾는다. 시장 정보 조사는 리서치 에이전트에게 보낸다. 결과 Artifact가 도착하면 그중 필요한 요약과 출처만 추려 리스크 분석 에이전트에 전달한다. 리스크 분석 결과가 나오면 문서 작성 에이전트가 최종 보고서 초안을 만든다. 마지막으로 클라이언트 에이전트가 전체 내용을 검토해 중복을 줄이고, 사용자에게 "가정", "근거", "불확실성"을 함께 설명한다.

이 예에서 클라이언트는 조사 자체를 직접 하지 않았다. 하지만 전체 품질은 클라이언트가 책임졌다. 어떤 에이전트를 선택할지, 어떤 결과를 다음 단계에 넘길지, 최종 답변을 어떻게 구성할지 결정했기 때문이다.

좋은 오케스트레이터의 조건

좋은 A2A 오케스트레이터는 많은 에이전트를 무작정 연결하지 않는다. 필요한 만큼만 호출하고, 각 호출의 목적을 분명히 하며, 결과를 검증한다. 사용자가 이해할 수 있는 방식으로 진행 상태를 설명하고, 실패했을 때 조용히 멈추지 않는다.

핵심은 네 가지다.

• 발견: Agent Card를 수집해 최신 기능 카탈로그를 유지한다.

• 판단: 사용자 요청을 분석해 적절한 원격 에이전트를 고른다.

• 조율: 순차와 병렬 흐름에서 태스크와 Artifact를 관리한다.

• 책임: 보안, 오류 복구, 최종 품질을 클라이언트 쪽에서 통제한다.

A2A의 진짜 가치는 원격 에이전트 하나를 호출하는 데서 끝나지 않는다. 여러 에이전트를 안전하게 선택하고 연결하며, 각자의 결과를 하나의 업무 성과로 묶을 때 드러난다. 클라이언트 에이전트와 오케스트레이터는 그 가치를 현실의 시스템으로 만드는 핵심 설계 지점이다.

참고

¹A2A Protocol

²GitHub - a2aproject/A2A

³How to Build a Multi-Agent Orchestrator with A2A Protocol

⁴Multi-agent patterns