아래는 google/A2A GitHub 저장소의 실행 방법과 실행 결과를 분석한 내용입니다. A2A는 에이전트 간 통신 및 상호운용성을 위한 프로토콜 명세와 참고 구현을 제공하는 프로젝트로, 단일 실행 파일이 아니라 여러 샘플(예제)과 데모를 통해 전체 시스템의 동작 방식을 보여주고 있습니다.
1. 실행 방법
1.1. 리포지토리 클론 및 샘플 준비
- 리포지토리 클론: 먼저, 해당 저장소를 로컬로 클론합니다.
git clone https://github.com/google/A2A.git
cd A2A- 샘플 디렉터리 확인: 저장소 내의 samples 폴더에는 Python, JavaScript, CLI 등 다양한 예제 구현이 포함되어 있습니다. 문서에서는 특히 Python 기반의 클라이언트/서버 샘플을 추천하고 있습니다.
1.2. 샘플 실행
- Python 샘플 실행 예시:
- 서버 실행: 예제 서버는 A2A 프로토콜 스펙에 정의된 HTTP 엔드포인트를 구현합니다. 예를 들어, 서버 스크립트가 있다면 다음과 같이 실행합니다.
cd samples/python
python server.py- 클라이언트 실행: 다른 터미널에서 클라이언트를 실행하여 서버로 작업(task)을 전송합니다.
python client.py- 동작 방식: 클라이언트는 우선 서버의 Agent Card(보통 /.well-known/agent.json 경로에 위치)를 조회한 후, tasks/send 또는 tasks/sendSubscribe 요청을 보냅니다.
1.3. 실행 환경 설정
- 필수 조건: Python 환경이 준비되어 있어야 하며(예: Python 3.8 이상), 샘플에 필요한 패키지들은 requirements.txt 파일을 확인 후 pip install -r requirements.txt로 설치할 수 있습니다.
- 설정 파일: 일부 샘플은 서버의 포트, 엔드포인트 URL, 인증 방식 등을 JSON이나 YAML 파일로 별도 정의하는 경우가 있으니, 각 샘플의 README나 주석을 참고하세요.
2. 실행 결과 분석
A2A 프로토콜은 작업(Task) 단위의 통신을 중심으로 진행됩니다. 실행 결과는 다음과 같은 단계로 이루어집니다.
2.1. 에이전트 디스커버리 (Discovery)
- Agent Card 조회: 클라이언트가 서버의 /.well-known/agent.json 파일을 호출하여 에이전트의 기능, 엔드포인트, 인증정보 등을 확인합니다.
- 결과 예시:
{
"agentName": "SampleAgent",
"capabilities": ["text-processing", "data-fetching"],
"endpoint": "http://localhost:8000/tasks/send",
"authentication": null
}- 이 정보는 클라이언트가 어떤 기능을 요청할 수 있는지 결정하게 해줍니다.
2.2. 작업(Task) 요청 및 처리
- 요청 단계: 클라이언트는 JSON 형식의 작업 요청을 서버에 보냅니다. 요청에는 고유 Task ID와 함께 요청 내용(예: 사용자 메시지)이 포함됩니다.
- 작업 요청 예시:
{
"task_id": "1234-5678",
"input": {
"message": "Hello, please process this data."
}
}- 서버 처리: 서버는 요청을 받은 후 내부에서 작업 상태를 업데이트합니다. 초기 상태는 "submitted"가 되며, 이후 "working", 그리고 모든 작업이 완료되면 "completed" 상태로 변경됩니다.
- 실시간 스트리밍: 만약 tasks/sendSubscribe 방식을 사용한다면 서버는 **Server-Sent Events (SSE)**를 통해 실시간 상태 업데이트(예: 진행률, 중간 결과 등)를 클라이언트로 전송합니다.
2.3. 최종 출력 (결과 메시지)
- 결과 형식: 작업이 완료되면 서버는 다음과 같은 JSON 객체를 응답으로 보냅니다.
{
"task_id": "1234-5678",
"status": "completed",
"messages": [
{ "role": "user", "content": "Hello, please process this data." },
{ "role": "agent", "content": "Processed data result here." }
],
"artifacts": {
"result": "Additional structured data or files can be attached here."
}
}- 이와 같이, 최종 결과물에는 작업 ID, 최종 상태, 역할별 메시지 목록, 생성된 아티팩트(예: 결과 파일, 데이터 등)가 포함됩니다.
3. 실행 결과 예시와 활용
3.1. 실행 시나리오
- 예시: Python 샘플을 실행한 경우,
- 클라이언트가 서버의 Agent Card를 읽고, 사용할 기능을 확인합니다.
- 클라이언트가 작업 요청을 보내면, 서버는 “submitted” → “working” → “completed” 단계로 진행하면서 작업의 진행 상황을 스트리밍 또는 단일 응답으로 전달합니다.
- 클라이언트는 응답으로 받은 JSON을 파싱하여, 최종 출력(예: 처리된 텍스트, 데이터 분석 결과 등)을 화면에 표시하거나 다음 작업에 이용합니다.
3.2. 복잡성 해소
- 프로토콜 자체의 복잡성: A2A는 에이전트 간 상호작용의 모든 세부 사항(메시지 포맷, 작업 상태 변화, 스트리밍, 푸시 알림 등)을 표준화하고 있습니다. 따라서 단일 실행 파일로 보여지지는 않지만, 핵심은 HTTP 요청/응답과 JSON 형태의 명세를 통해 구현된다는 점입니다.
- 실행 결과 분석 관점: 결과는 매우 모듈화되어 있으며, 각 단계별(디스커버리, 작업 제출, 진행 상태 업데이트, 완료 결과)로 나뉘어 이해할 수 있습니다. 이 모듈화 덕분에 실제 서비스에 통합할 때 개별 에이전트를 독립적으로 개발하고 연동할 수 있도록 설계되었습니다.
참고 자료 및 추가 링크
- Demo Video: A2A 데모 영상(Watch this demo video) – 실제 에이전트 간 통신 과정을 시각적으로 확인할 수 있습니다.
- JSON 스펙: 프로토콜의 상세 JSON 구조 및 스펙은 여기에서 확인 가능합니다.
- 샘플 코드: Python 및 JavaScript 샘플 구현체는 저장소 내 samples 폴더에서 찾을 수 있습니다.
반응형
