AI 에이전트 통신에 A2A 프로토콜 사용

작성자

AI Advocate & Technology Writer

A2A 또는 Agent2Agent 프로토콜은 AI 에이전트, 클라이언트 및 도구 간의 구조화된 커뮤니케이션을 가능하게 하는 개방형 표준입니다. 이 튜토리얼에서는 채팅 클라이언트가 사용자 쿼리를 처리하여 A2A 호환 서버에서 실행되는 AI 에이전트로 전송하는 에이전트 시스템을 구축할 수 있습니다.

대부분의 에이전틱 AI 애플리케이션은 구성 요소 간의 사용자 지정 커뮤니케이션(예: ChatDev의 ChatChain)을 구현하므로 여러 애플리케이션에서 동일한 에이전트를 재사용하거나 외부 도구를 통합하는 것이 어렵습니다. 이러한 표준화가 부족하면 상호 운용성이 저해되고 더 광범위한 에이전트 에코시스템의 개발이 제한됩니다.

A2A는 HTTP, JSON-RPC 2.0 및 서버 전송 이벤트(SSE)를 기반으로 구축된 표준화된 프로토콜을 통해 에이전트 논리에서 통신 계층을 분리함으로써 이러한 한계를 해결합니다. 이러한 분리를 통해 에이전트는 사용자 지정 통합 코드 없이 다른 에이전트와 협업하고, 클라이언트 요청을 처리하고, 외부 도구에 액세스할 수 있습니다.

A2A는 팀이 클라이언트 코드를 손상시키지 않고 AI 시스템을 점진적으로 발전시킬 수 있도록 하는 분산형 아키텍처를 지원합니다. 팀은 복잡한 워크플로에서 일관된 인터페이스를 유지하면서 도구를 업데이트하고, 모델을 교체하고, 에이전트 행동을 수정할 수 있습니다.

에이전트는 명확성과 일관성으로 에이전트 상호 작용을 강화하는 메타데이터를 포함하는 JSON-RPC 형식으로 구성된 메시지로 정보를 교환합니다. 각 A2A 서버는 에이전트의 능력을 구조화된 JSON 데이터로 설명하는 잘 알려진 엔드포인트(.well-known/agent-card.json)에 AgentCard를 노출합니다. 따라서 클라이언트는 API 문서에서 사용 가능한 엔드포인트를 설명하는 방식과 유사하게 에이전트가 수행할 수 있는 작업을 동적으로 발견할 수 있습니다.

다음을 활용하여 A2A 에이전트 시스템을 구축 및 실행하고 실무 경험을 쌓으세요.

BeeAI: AI 에이전트를 구축하기 위한 오픈소스 에이전트 프레임워크.
A2A 프로토콜: 에이전트 상호 운용성을 위한 표준화된 커뮤니케이션 프로토콜.
Ollama: 대규모 언어 모델(LLM)을 로컬에서 실행하기 위한 도구.
에이전트 도구: 웹 검색(DuckDuckGo), 날씨 데이터(OpenMeteo), Wikipedia 액세스(WikipediaTool) 및 추론(ThinkTool) 등의 전문 기능

참고: ACP(에이전트 통신 프로토콜)로 작업한 적이 있다면 유사점을 인식할 수 있습니다. 원래 IBM의 BeAIAI가 개발한 ACP는 Linux Foundation에서 Google A2A와 협력하게 되었습니다. BeeAI는 이제 A2A 어댑터(A2AServer 및 A2AAgent)를 사용하여 A2A 호환 커뮤니케이션을 제공합니다. 또한 A2A는 MCP(모델 컨텍스트 프로토콜)와 함께 작동하여 에이전트가 데이터 소스 및 도구와 상호 작용할 수 있도록 지원하여 상호 운용 가능한 에이전트 에코시스템을 구축합니다.

A2A 채팅 시스템 작동 방식

이 프로젝트는 A2A를 통해 클라이언트 인터페이스와 에이전트 논리를 깔끔하게 분리할 수 있는 방법을 보여줍니다.

워크플로는 다음과 같은 순서를 따릅니다.

사용자 입력: 클라이언트는 터미널 인터페이스를 통해 사용자 입력을 캡처합니다.
A2A 요청: 클라이언트는 입력을 JSON-RPC 메시지 페이로드로 형식화하고 에이전트 서버로 보냅니다.
에이전트 처리: 서버는 요청을RequirementAgent 에 전달합니다. 이는 작업을 분석하고 필요에 따라 적절한 도구를 실행합니다.
A2A 응답: 서버는 에이전트의 응답을 JSON-RPC 형식의 구조화된 데이터로 반환하며, 스트리밍 결과는 생성되는 즉시 실시간으로 전달됩니다.
표시: 클라이언트가 응답 텍스트를 추출하여 터미널에 표시합니다.

이 워크플로는 챗봇, 작업 자동화, 고객 지원 에이전트, 툴 오케스트레이션을 갖춘 연구 어시스턴트 등 구조화된 클라이언트-에이전트 통신이 필요한 사용 사례에 적용할 수 있는 재사용 가능한 워크플로 패턴을 보여줍니다.

A2A 에이전트

이 프로젝트는 여러 기능을 갖춘 단일 AI 에이전트를 사용합니다. 더 복잡한 시스템에서는 각각 특정 도메인이나 작업에 초점을 맞춘 여러 특수 에이전트를 배포할 수 있습니다.

RequirementAgent(BeeAI): 사용자의 요청에 따라 여러 도구를 동적으로 선택하고 조정하는 선언적 에이전트입니다. 다음을 사용합니다.

ThinkTool 추론 및 논리적 연산용
DuckDuckGoSearchTool 웹 검색용
OpenMeteoTool 날씨 데이터용
WikipediaTool 정보 검색용

A2A 서버

A2A 서버(beeai-a2a-server/beeai_chat_server.py )는 HTTP API를 통해 에이전트 기능을 노출합니다. 다음과 같은 3가지 주요 책임을 담당합니다.

LLM 초기화: Ollama를 통해 로컬 언어 모델을 로드합니다.

llm = ChatModel.from_name(os.environ.get(“BEEAI_MODEL”, “ollama:granite3.3:8b”))

2. 에이전트 설정: 에이전트 수명 주기를 처리하기 위한 도구와 메모리가 포함된 RequirementAgent를 생성합니다.

    agent = RequirementAgent(
        llm=llm,
        tools=[ThinkTool(), DuckDuckGoSearchTool(), OpenMeteoTool(), WikipediaTool()],
        memory=UnconstrainedMemory(),
        description=”An agent that can search the web, check the weather, and think through problems step-by-step.”,

3. 서버 구성: A2A 호환 HTTP 엔드포인트를 통해 에이전트를 노출합니다.

A2AServer(
config=A2AServerConfig(port=int(os.environ.get(“A2A_PORT”, 9999))),
memory_manager=LRUMemoryManager(maxsize=100)
).register(agent).serve()

서버는 에이전트의 능력을 설명하고 에이전트 구성을 검증하는 데 도움이 되는 /.well-known/agent-card.json에 자동으로 AgentCard를 노출합니다.

A2A 클라이언트

A2A 클라이언트(beeai-a2a-client/beeai_chat_client.py )는 사용자 인터페이스를 제공하고 비동기 메시지 처리를 위해 A2A SDK 및 Python의 asyncio 라이브러리를 사용하여 서버와의 커뮤니케이션을 처리합니다.

연결 설정: A2A 클라이언트 어댑터 생성

agent = A2AAgent(
url=os.environ.get(“BEEAI_AGENT_URL”, “http://127.0.0.1:9999”),
memory=UnconstrainedMemory()
)

이러한url 매개변수는 A2A 호환 서버의 엔드포인트를 지정합니다(기본값:http://127.0.0.1:9999 ). memory 매개변수는 대화 기록을 로컬에 저장하여 클라이언트가 상호 작용 중에 컨텍스트를 유지하고 장기 실행 작업을 지원할 수 있도록 합니다.

메시지 교환: 비동기 프롬프트를 보내고 응답을 처리합니다.

for prompt in reader:
response = await agent.run(prompt)
# Extract and display response text

이러한A2AAgent 은(는) JSON-RPC 커뮤니케이션 세부 정보를 추상화하는 클라이언트 측 어댑터입니다. 자율 에이전트가 아니라 단순히 사용자 입력을 A2A 호환 메시지로 변환하고 서버 응답을 처리하여 원활한 데이터 교환 및 관측을 가능하게 합니다.

이 프로젝트를 실행하기 위한 전제 조건

시스템 요구사항

이 프로젝트를 실행하기 위한 시스템 요구 사항은 다음과 같습니다.

운영 체제: macOS, Linux 또는 Windows
메모리(RAM): >= 8GB(권장: 로컬 LLM 실행의 경우 16GB 이상)
디스크 공간: >= 5GB의 여유 공간(권장: Python 환경 및 로컬 모델을 수용하려면 10GB 이상)
Python 버전: >= 3.11

도구 및 공급자 요구 사항

시작하기 전에 이 프로젝트에 필요한 도구에 대한 개요는 다음과 같습니다.

BeeAI: AI 에이전트를 구축하기 위한 오픈 소스 에이전트 개발 키트입니다. BeeAI는 Ollama(이 튜토리얼에서 사용됨), OpenAI 및 Anthropic을 포함한 여러 LLM 공급자를 지원합니다.
Ollama: 로컬 LLM을 실행하여 AI 에이전트를 지원합니다.
A2A 프로토콜: BeeAI 프레임워크에 통합되어 클라이언트와 서버 간의 구조화된 커뮤니케이션을 가능하게 합니다.
터미널 또는 IDE: Visual Studio Code와 같은 터미널이나 IDE(여러 터미널을 관리하고 로그를 보는 데 권장).
Python 가상 환경: 클라이언트와 서버의 종속성을 분리합니다.

LLM 공급자 요구 사항

이 프로젝트에서는 AI 에이전트의 모델 공급자로 Ollama를 사용합니다. Ollama를 설정하려면 다음 단계를 따르세요.

Ollama 다운로드 및 설치:
- Ollama를 방문하여 운영 체제용 애플리케이션을 설치합니다.
Ollama 서버 시작
- 터미널을 열고 다음을 실행합니다.
ollama serve
기본 모델을 가져옵니다(약 5GB의 디스크 공간이 필요함).

ollama pull granite3.3:8b

참고: 환경 변수를 설정해 Ollama와 호환되는 모든 모델을BEEAI_MODEL 사용할 수 있습니다. 사용 가능한 모델과 해당 크기는 Ollama 모델 라이브러리를 확인하세요.

단계

1단계. GitHub 리포지토리 복제

이 프로젝트를 실행하려면 https://github.com/IBM/ibmdotcom-tutorials.git을 HTTPS URL로 사용하여 GitHub 리포지토리를 복제합니다. 리포지토리 복제 방법은 GitHub 문서를 참고하세요.

이 튜토리얼은 리포지토리의 프로젝트 디렉터리 내에서 찾을 수 있습니다.

터미널 내부에서 이 튜토리얼의 디렉토리로 이동합니다.

cd docs/tutorials/projects/a2a_tutorial

2단계. 개발 환경 설정

이 프로젝트에는 서버용과 클라이언트용의 두 개의 별도 Python 스크립트를 동시에 실행해야 합니다. 두 개의 터미널 창 또는 탭을 열어야 합니다.

현재 터미널을 열어둔 상태에서 두 번째 터미널을 열고 둘 다 올바른 프로젝트 디렉터리(a2a_tutorial 루트 디렉토리)로 이동하는지 확인합니다.

IDE를 사용하시나요?

Visual Studio Code와 같은 IDE를 사용하는 경우 분할 터미널 기능을 사용하여 여러 터미널을 나란히 관리할 수 있습니다.

그렇지 않으면 두 개의 독립 실행형 터미널 창을 열고 각각 프로젝트 디렉터리로 이동합니다.

3단계. 가상 환경 생성 및 활성화

가상 환경은 종속성을 분리하고 유지 관리하는 데 도움이 됩니다. 서버 및 클라이언트 종속성을 분리하려면 각 구성 요소에 대한 가상 환경을 만듭니다.

서버의 경우:

디렉토리beeai-a2a-server 로 이동합니다.

cd beeai-a2a-server

Python 3.11로 가상 환경을 만듭니다.

python3.11 -m venv venv

가상 환경을 활성화합니다.

source venv/bin/activate

Windows 사용자를 위한 참고 사항: venv\Scripts\activate를 사용하여 가상 환경을 활성화합니다.

클라이언트의 경우:

디렉토리beeai-a2a-client 로 이동합니다.

cd beeai-a2a-client

가상 환경을 생성하고 활성화합니다.

python3.11 -m venv venv
source venv/bin/activate

4단계. 종속성 설치

각 터미널에서 다음 코드를 실행하여 각 구성 요소에 필요한 종속성을 설치합니다.

pip install -r requirements.txt

터미널에서pip freeze 을(를) 실행하여 종속성이 있는 환경이 최신 상태인지 확인할 수 있습니다.

5단계. A2A 에이전트 서버 시작

첫 번째 터미널에서 A2A 에이전트 서버를 시작합니다.

python beeai_chat_server.py

다음 사항이 표시됩니다.

INFO:     Started server process [88159]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)

이제 서버가 클라이언트 애플리케이션으로부터 들어오는 요청을 수신 대기 중이며 에이전트 간 커뮤니케이션을 지원할 준비가 되었습니다.

6단계. A2A 클라이언트 시작

다른 터미널에서 A2A 클라이언트를 시작합니다.

python beeai_chat_client.py

입력하라는 메시지가 표시됩니다.

Type your message (Ctrl+C to exit):
You:

7단계. 에이전트와 상호 작용

클라이언트 터미널에 메시지를 입력하고Enter 을(를) 누릅니다. 에이전트는 쿼리를 처리하고 다음과 같이 응답합니다.

You: What is the capital of France?
Agent 🤖 : The capital of France is Paris.

서버 터미널에서 푸시 알림과의 통신을 보여주는 A2A 프로토콜 로그를 볼 수 있습니다.

INFO: 127.0.0.1:49292 - “GET /.well-known/agent-card.json HTTP/1.1” 200 OK
INFO: 127.0.0.1:49294 - “POST / HTTP/1.1” 200 OK

첫 번째 요청은 에이전트의 능력을 설명하는 AgentCard를 검색합니다. 두 번째 요청은TextPart (A2A 메시지 내의 텍스트 콘텐츠 단위)(으)로 메시지를 전송하고 응답을 수신합니다.

참고: LLM의 아웃풋은 확률적이며 동일한 입력을 사용하더라도 워크플로를 실행할 때마다 달라질 수 있습니다.

다양한 쿼리 시도

다양한 유형의 쿼리를 실험하여 에이전트의 다양한 도구를 테스트합니다.

웹 검색: "인공지능 관련 최신 뉴스를 검색해"
날씨 데이터: "도쿄의 날씨는 어때요?"
Wikipedia: "양자 컴퓨팅에 대해 알려줘"
추론: "하늘이 파랗게 보이는 세 가지 이유는 뭐야?"

AgentCard 보기

브라우저에서 https://0.0.0.0:9999/.well-known/agent-card.json로 이동하여RequirementAgent 의 AgentCard를 확인합니다.

{
    “capabilities”: {
        “streaming”: true
    },
    “defaultInputModes”: [
        “text”
    ],
    “defaultOutputModes”: [
        “text”
    ],
    “description”: “An agent that can search the web, check the weather, and think through problems step-by-step.”,
    “name”: “RequirementAgent”,
    “preferredTransport”: “JSONRPC”,
    “protocolVersion”: “0.3.0”,
    “skills”: [
        {
            “description”: “An agent that can search the web, check the weather, and think through problems step-by-step.”,
            “id”: “RequirementAgent”,
            “name”: “RequirementAgent”,
            “tags”: []
        }
    ],
    “url”: “http://localhost:9999”,
    “version”: “1.0.0”
}

이 JSON 문서에서는 다음을 설명합니다.

에이전트의 이름(RequirementAgent) 및 해당 능력에 대한 간략한 설명입니다.
지원되는 커뮤니케이션 프로토콜 및 메시지 형식
모든 요구 사항 또는 제약 조건

이 AgentCard를 사용하면 A2A를 준수하는 모든 클라이언트는 구현 세부 사항에 대한 사전 지식 없이도 에이전트를 검색하고 에이전트와 상호 작용할 수 있습니다.

결론

이 튜토리얼에서 클라이언트-에이전트 통신을 위한 구조화된 인터페이스를 노출하는 A2A-complaint 서버를 사용하여 채팅 시스템을 구축했습니다. 메시징 계층을 내부 논리에서 분리함으로써 Agent2Agent 프로토콜을 통해 팀은 클라이언트 코드를 변경하지 않고도 에이전트 능력을 업데이트하고, 모델을 교체하거나, 도구 구성을 수정할 수 있습니다. 이러한 유연성은 입력이 필요한 작업을 조정하거나, 작업 상태를 추적하거나, 각 작업을 개별 작업 단위로 취급할 때 특히 유용합니다.

A2A는 규정을 준수하는 모든 구성 요소가 이해할 수 있는 공통 메시지 형식을 정의하여 자율 에이전트가 다른 에이전트와 협업할 수 있도록 합니다. 프로토콜 사양은 상호 작용 전반에서 일관성과 명확성을 보장하기 위해 메시지가 JSON-RPC 형식으로 구조화되고 메타데이터로 보강되는 방식을 정의합니다.

이 튜토리얼은 A2A 샘플 리포지토리에서 제공하는 기본 예시를 기반으로 합니다. 원래 구현에 대한 자세한 내용은 A2A 호환 시스템 구축에 대한 자세한 컨텍스트와 예시를 제공하는 리포지토리의 readme 파일을 참조하세요.

실제 배포의 경우 A2A 서버는 인증 메커니즘을 구현하여 에이전트 엔드포인트를 보호하고, 스트리밍 응답에 서버 전송 이벤트를 사용하며, 프로덕션 워크플로를 처리할 수 있도록 확장할 수 있습니다. 이 워크플로를 통해 명령줄 클라이언트가 표준화된 프로토콜을 통해 AI 에이전트와 상호 작용하여 에이전트가 여러 도구를 조정하고 상황에 맞는 응답을 제공할 수 있는 방법을 살펴보았습니다. 이 접근 방식은 유지 관리 가능하고 확장 가능하며 유연한 AI 시스템을 가능하게 하는 A2A의 힘을 보여줍니다.