TL;DR

  • 공식 명령줄 클라이언트인 A2A CLI(a2a)가 A2A Protocol v1.0 기반 에이전트의 검색, 메시징, 실시간 업데이트 수신을 지원함.
  • A2A 에이전트 계층이 없는 도구에서도 원격 에이전트의 기능을 확인하고 작업을 전달할 수 있음.
  • 코딩 에이전트 위임, 터미널에서의 직접 상호작용, 비 A2A 에이전트를 포함하는 자동화 워크플로라는 세 가지 활용 방식을 제공함.
  • Homebrew, WinGet, Go 소스 설치, 사전 빌드 바이너리로 설치할 수 있으며, 카드 조회·메시지 전송·스트리밍 명령을 제공함.
  • JSON-RPC, REST, gRPC를 기본 지원하고, PATH에 플러그인 바이너리를 추가해 사용자 지정 전송 프로토콜을 사용할 수 있음.

A2A CLI

  • A2A CLI(a2a)는 A2A(Agent2Agent) 에이전트를 위한 공식 명령줄 클라이언트이며, A2A Project Team이 관리함.
  • 터미널에서 A2A 에이전트를 검색하고, 메시지를 보내고, 관리할 수 있음.

A2A CLI가 필요한 이유

  • A2A는 양방향 프로토콜로, 모든 A2A 에이전트가 다른 에이전트의 클라이언트로 동작하며 작업을 넘길 수 있음.
  • A2A 계층이 없는 에이전트는 메시지를 보내거나 업데이트를 받기 어려우며, A2A CLI가 이 간극을 메움.
  • 도구를 호출할 수 있는 사용자, 모델, 에이전트, 코딩 하네스가 A2A 에이전트의 기능을 검색하고 작업을 전달할 수 있음.
  • 주요 활용 방식은 다음 세 가지임.
  • AI 코딩 보조 도구 강화: 코딩 에이전트에 a2a 도구를 제공해 원격 A2A 에이전트에 작업을 위임함.
  • 즉시 상호작용: 터미널에서 에이전트 카드를 가져오고, 메시지를 보내고, 실시간 업데이트를 스트리밍함.
  • 워크플로 자동화: 프로토콜에 맞춘 JSON 출력과 예측 가능한 종료 코드를 활용해 A2A 에이전트를 비 A2A 에이전트와 통합하고 파이프라인을 구성함.

설치

  • macOS와 Linux에서는 brew tap a2aproject/a2a-cli https://github.com/a2aproject/a2a-cli로 탭을 추가하고 brew install a2a로 설치함.
  • Windows에서는 winget install a2aproject.a2acli로 설치함.
  • Linux, Windows, macOS에서 go install github.com/a2aproject/a2a-cli@latest로 소스에서 설치할 수 있음.
  • Go 설치 명령은 바이너리 이름을 a2a-cli로 지정하므로, a2a로 이름을 바꾸고 PATH에 둠.
  • 최신 릴리스의 아카이브를 내려받아 압축을 푼 뒤, a2a 바이너리를 PATH에 추가하는 사전 빌드 바이너리 설치 방식도 제공함.

사용법

  • a2a card get https://agent.example.com 명령으로 에이전트 카드를 조회함.
  • a2a send -a https://agent.example.com "Hello, what can you do?" 명령으로 메시지를 보내고 결과를 기다림.
  • a2a send -a https://agent.example.com --stream "Summarize this document" 명령으로 이벤트를 도착하는 대로 스트리밍함.
  • 전체 명령, 플래그, 설정, 서버 모드는 전체 명령 참조 문서에서 확인할 수 있음.

쿡북

  • 쿡북은 각 레슨을 독립적으로 실행할 수 있는 실습형 CLI 과정이며, 첫 A2A 서버 구성부터 스트리밍, 설정, 메시지와 작업의 전체 수명 주기까지 다룸.
  • 레슨은 다음 네 가지임.
  • 빠른 A2A 서버 구축: --exec로 일반 스크립트를 A2A 서버로 바꾸고 메시지를 보냄.
  • 에이전트 검색 및 대화: 에이전트 카드를 읽고 저장한 뒤 텍스트 메시지를 보냄.
  • CLI 설정: 플래그, 환경 변수, .env 파일과 설정 간 우선순위 확인 방법을 다룸.
  • 메시지와 작업: 여러 부분으로 구성된 메시지를 만들고, 답변을 스트리밍하며, 작업의 수명 주기를 추적함.

에이전트 스킬

  • A2A CLI Agent Skill은 Claude Code, Cursor, Codex 같은 하네스가 명령줄에서 A2A 에이전트에 작업을 위임하도록 지원함.
  • npx skills add https://github.com/a2aproject/a2a-cli --skill a2a-cli 명령으로 에이전트에 스킬을 설치함.
  • 스킬은 a2a 바이너리를 사용하므로 CLI를 먼저 설치해야 하며, 설명 파일은 skills/a2a-cli/SKILL.md에 있음.

에이전트 플러그인

  • 플러그인 인식 클라이언트를 선호하는 경우, Agent Plugin을 설치 가능한 단일 단위로 사용할 수 있으며 Agent Plugins 1.0.0 형식의 스킬 전용 구성임.
  • npx skills add https://github.com/a2aproject/a2a-cli/tree/main/agent-plugin/skills/a2a-cli -g 명령으로 설치함.
  • 스킬과 마찬가지로 a2a 바이너리를 사용하므로 CLI를 먼저 설치해야 함.

프로젝트 소개

  • 여러 커뮤니티 및 SDK 제공 A2A CLI가 언어별로 존재했지만 명령 이름, 플래그, 출력 형식, 전송 처리 방식이 서로 달랐음.
  • 이 프로젝트는 이를 하나의 표준 CLI로 통합해 장기적인 안정성과 전송 방식 간 일관성을 지향하며, A2A Go SDK의 CLI를 기반으로 구축됨.
  • SPEC.md에는 통합 내용을 담았으며 명령 분류, 출력 계약, 폴링·스트리밍 규칙, 종료 코드를 정의하고 로드맵 역할을 함.

사용자 지정 전송 플러그인

  • CLI는 JSON-RPC, REST, gRPC를 기본 지원함.
  • a2a-transport-<name> 바이너리를 PATH에 추가하면 재컴파일 없이 추가 전송 바인딩을 사용할 수 있음.
  • CLI는 플러그인을 로컬 프록시로 실행하며, 프록시는 표준 A2A 바인딩으로 통신하고 사용자 지정 프로토콜로 요청을 전달함.
  • 따라서 기본 제공 전송과 플러그인 모두 --transport <name> 형식으로 사용할 수 있음. a2a transport list로 전송 목록을 확인하고, a2a send --transport slimrpc --endpoint slim://agents.example/agent "hello"처럼 메시지를 보냄.
  • Go 플러그인은 devkit/clitransport 패키지에 a2aclient.Transport를 제공해 CLI 호환 플러그인을 생성하는 방식으로 구현함.
  • 전송 플러그인 가이드와 실행 가능한 에코 플러그인 예제를 참고할 수 있음.

기여 및 피드백

  • 검토와 의견을 환영하며, 먼저 SPEC.md에서 배경을 확인한 뒤 이슈나 풀 리퀘스트로 제안, 질문, 예외 사례를 공유할 수 있음.
  • 도구 사용 방식을 공유하거나 기여 가이드를 참고할 수 있으며, 적합성 관련 세부 사항은 COMPLIANCE.md에 있음.

라이선스

  • A2A CLI와 사양은 오픈 소스이며 Apache License 2.0에 따라 배포됨.