a2aproject/a2a-js
Official JavaScript SDK for the Agent2Agent (A2A) Protocol
A2A JavaScript SDK – 무엇인가요
@a2a-js/sdk 는 에이전트-투-에이전트(A2A) 프로토콜 의 공식 TypeScript/JavaScript 클라이언트 라이브러리 입니다. 이 프로토콜은 자율적인 "에이전트" 가 네트워크를 통해 기능(예: 영화 검색 봇, 장시간 실행되는 데이터 처리 작업)을 노출하고, 다른 소프트웨어에 의해 검색 및 제어될 수 있도록 합니다. SDK 는 A2A 서버(에이전트)와 A2A 클라이언트(에이전트를 호출하는 애플리케이션)를 하나의 패키지로 작성할 수 있게 해줍니다.
핵심 기능
| 기능 | 제공하는 기능 |
|---|---|
| 세 가지 전송 방식 | JSON-RPC, HTTP + JSON/REST, gRPC(Node 전용) – 모두 동일한 DefaultRequestHandler 를 공유하므로, 동일한 에이전트를 여러 프로토콜로 동시에 노출할 수 있습니다. |
| v1.0 프로토콜 구현 | A2A 사양 v1.0(메시지 형식, 태스크 라이프사이클, 푸시 알림, 인증, 확장)을 완전히 구현합니다. |
| 역방향 호환성 레이어 | 옵션으로 구형 v0.3 피어를 지원하여, v1.0 서버가 오래된 클라이언트와 통신할 수 있고(반대도 가능) 마이그레이션 기간 동안 사용할 수 있습니다. |
| 서버 측 헬퍼 | AgentExecutor(비즈니스 로직), ExecutionEventBus(태스크, 상태, 아티팩트 이벤트 발행), Express 및 gRPC용 전송 어댑터, 푸시 알림 구현, JWT/Bearer 인증 미들웨어. |
| 클라이언트 측 헬퍼 | ClientFactory (에이전트 카드 또는 URL에서 전송 방식에 관계없이 클라이언트 생성), 각 호출용 RequestOptions(헤더, 취소 신호, 컨텍스트), CallInterceptor API(로그, 트레이싱, 사용자 정의 확장). |
| 에이전트 카드 서명 | JWS 서명된 에이전트 카드 생성 및 검증 유틸리티, 신뢰 검증을 위한 JWKS 처리. |
| 확장 가능 | 에이전트 카드에서 확장 기능을 선언하고 A2A-Extensions 헤더로 활성화할 수 있음. SDK 는 출력 이벤트를 수정할 수 있는 데코레이터 훅 제공. |
일반적인 워크플로우
- 에이전트 정의 –
RequestContext를 수신하고ExecutionEventBus에Message,Task, 상태, 아티팩트 이벤트를 발행하는AgentExecutor를 구현. - 서버 생성 –
DefaultRequestHandler를 인스턴스화하고 하나 이상의 전송 어댑터(jsonRpcHandler,restHandler,grpcService)를 마운트. 인증 미들웨어, 푸시 알림 저장소, 서명 훅을 선택적으로 추가. - 에이전트 카드 노출 – 에이전트의 기능, 지원하는 전송 방식, (선택적으로) JWS 서명을 설명하는 JSON 문서.
- 에이전트 사용 – 클라이언트 측에서
ClientFactory.createFromUrl(또는createFromAgentCard) 를 사용해Client를 얻고,sendMessage,sendMessageStream,createTask,cancelTask등의 메서드를 호출. - 스트리밍 및 취소 처리 – 장시간 실행 태스크는 이벤트 스트림을 발행. 클라이언트는
AsyncGenerator를 반복.cancelTask를 에그제큐터에서 구현해 사용자 시작 취소를 존중. - 옵션 푸시 알림 – 지속적인 스트림을 유지할 수 없는 태스크의 경우,
taskPushNotificationConfig를 통해 웹훅 URL을 구성. 서버는 업데이트를 POST로 전송.
SDK와 함께 제공되는 샘플 프로젝트
| 샘플 | 설명 |
|---|---|
sample-agent |
최소한의 스트리밍 에이전트 (JSON-RPC). |
movie-agent |
Genkit + TMDB API 를 사용하는 실제 세계 에이전트. |
multi-transport-agent |
동일한 에이전트를 JSON-RPC, REST, gRPC 에 동시에 노출. |
cancellable-agent |
cancelTask 의 구현. |
push-notification-agent |
웹훅 기반 푸시 알림. |
authentication |
Express 미들웨어 + Passport JWT 인증, User 를 에그제큐터로 전달. |
extensions |
확장 메커니즘을 통해 사용자 정의 메타데이터를 추가하는 데코레이터. |
verify-signing |
클라이언트 측에서 서명된 에이전트 카드 검증. |
cli.ts |
어떤 전송 방식에도 대응하는 인터랙티브 명령줄 클라이언트. 인증 헤더 삽입 가능. |
compat-v1-server / compat-v1-client |
옵션 v0.3 호환성 레이어를 사용한 v1.0 서버/클라이언트의 엔드투엔드 데모. |
설치 및 빠른 시작
# 핵심 SDK
npm install @a2a-js/sdk
# Express 서버 통합이 필요한 경우
npm install express
# gRPC 전송 방식 사용 예정인 경우 (Node 전용)
npm install @grpc/grpc-js @bufbuild/protobuf
그 후 src/samples 의 README 파일을 따라 실행 가능한 예제를 따라해보세요.
성숙도 및 생태계
- 버전:
v1.0.0– 안정적 릴리스로 표시. - 라이선스: Apache 2.0 (허용성 높고 상용 사용에 적합).
- 거버넌스:
google-a2aGitHub 조직에서 호스팅. 명확한 기여 가이드 및 마이그레이션 문서 제공. - 상호 운용성: A2A 사양을 구현한 모든 언어와 작동 가능 (예: Python SDK
a2a-python). 호환성 레이어로 구형 v0.3 사양에서 점진적 업그레이드 가능.
누구에게 적합한가요?
- 자율 에이전트를 개발하는 개발자 (LLM 기반 봇, 데이터 파이프라인, 도구 호출 서비스)로, 탐색 및 실행에 표준화된 버전화된 프로토콜이 필요한 경우.
- 플랫폼 팀 – 내부 AI 서비스를 네트워크 주소 가능한 에이전트로 공개하고, 일관된 인증, 스트리밍, 취소 세미antics를 제공하고자 하는 경우.
- 통합자 – HTTP, JSON-RPC, gRPC를 통해 에이전트와 통신할 수 있는 다중 전송 방식 클라이언트가 필요한 경우.
- 연구자 – 프로토콜 확장 또는 사용자 정의 푸시 알림 흐름을 실험하고자 하는 경우.
더 알아보기
- 사양: https://a2a-protocol.org/v1.0.0/specification/
- 문서 폴더: 리포지토리 내
docs/(마이그레이션 가이드, 호환성 가이드). - 샘플:
src/samples/– 각각 독자적인 README 및 npm 스크립트 포함. - 기여 가이드: https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md
TL;DR
A2A JavaScript SDK 는 오픈 소스 에이전트-투-에이전트 프로토콜 을 따르는 에이전트를 구축하고 사용하기 위한 프로덕션 준비 완료, 타입 안정성 있는 라이브러리입니다. JSON-RPC, REST, gRPC 전송 방식을 지원하며, 내장된 스트리밍, 취소, 푸시 알림, 인증, 그리고 이전 프로토콜 버전과의 호환성 레이어를 제공하여, 현대적인 AI 중심 마이크로서비스 아키텍처의 견고한 기반을 제공합니다.
관련
- 프로젝트
- 프로젝트
- Dispatch