A2A ADK 경비 상환 에이전트

이것은 Google Agent Development Kit (ADK)를 기반으로 개발된 지능형 경비 상환 에이전트로, Agent2Agent (A2A) 서버로 실행됩니다. 이 에이전트의 핵심 기능은 지능형 양식 생성입니다: 사용자의 상환 요청에 필요한 정보가 부족할 때, 에이전트가 자동으로 사용자가 작성할 양식을 생성하여 처리 전에 완전한 상환 정보를 수집합니다.

소스 코드

A2A ADK Sample

🎯 프로젝트 특징

• 지능형 양식 상호작용: 누락된 정보를 자동으로 감지하고 동적 양식을 생성
• A2A 프로토콜 지원: 표준화된 에이전트 간 통신 프로토콜
• 스트리밍 처리: 실시간 응답 및 상태 업데이트 지원
• Google ADK 통합: Google의 최신 에이전트 개발 키트 기반

📋 시스템 요구사항

• Python 3.12 이상
• UV 패키지 관리 도구
• Google API Key (Gemini 모델 액세스)

🚀 빠른 시작

1. Google API Key 획득

1. Google AI Studio 방문
2. Google 계정으로 로그인
3. "Get API key" 클릭
4. 새 API 키 생성 또는 기존 키 사용
5. 나중에 사용할 API 키 복사

2. 환경 설정

# 프로젝트를 로컬로 클론 (필요한 경우)
git clone https://github.com/sing1ee/a2a-adk-expense-reimbursement.git
cd a2a-adk-expense-reimbursement

# 환경 변수 파일 생성
echo "GOOGLE_API_KEY=your_api_key_here" > .env

# your_api_key_here를 실제 API 키로 교체

3. 종속성 설치 및 실행

# 가상 환경 활성화
source .venv/bin/activate

# uv를 사용하여 프로젝트 실행
uv run .

서버는 http://localhost:10002에서 시작됩니다.

4. CLI 클라이언트로 테스트

새 터미널 창을 엽니다:

git clone https://github.com/a2aproject/a2a-samples.git
# CLI 클라이언트 디렉토리로 이동 (samples/python/hosts/cli에 있다고 가정)
cd a2a-samples/samples/python/hosts/cli

# 상환 에이전트에 연결
uv run . --agent http://localhost:10002

5. 테스트 상호작용 예제

CLI 클라이언트에서 다음 테스트 명령을 입력하세요:

# 예제 1: 정보가 누락된 요청 (양식이 트리거됨)
점심 식사비 $20를 상환해야 합니다

# 예제 2: 완전한 정보가 있는 요청
2024년 1월 15일 고객 점심 식사비 $50를 상환해야 합니다

# 예제 3: 부분적인 정보가 있는 요청
어제 교통비 $25를 상환해 주세요

🏗️ 프로젝트 아키텍처

핵심 파일 구조

a2a-adk-expense-reimbursement/
├── __main__.py          # 서버 시작 진입점
├── agent.py             # 핵심 에이전트 로직
├── agent_executor.py    # A2A 요청 실행기
├── pyproject.toml       # 프로젝트 설정 및 종속성
└── README.md           # 프로젝트 문서

주요 구성 요소 설명

1. __main__.py - 서버 진입점

• A2A 서버 및 에이전트 정보 구성
• 에이전트 기술 및 능력 설명 설정
• 요청을 수신하기 위한 HTTP 서버 시작

2. agent.py - 핵심 에이전트 로직

세 가지 주요 도구 함수를 포함:

• create_request_form(): 상환 양식 템플릿 생성
• return_form(): 양식을 A2A 프로토콜 형식으로 래핑하여 반환
• reimburse(): 실제 상환 승인 작업 실행

3. agent_executor.py - 요청 실행기

• A2A 프로토콜 요청 및 응답 처리
• 작업 상태 관리 (작업 중, 입력 필요, 완료 등)
• 에이전트와 A2A 서버 간의 통신 조정

🔄 핵심 워크플로우

다음 시퀀스 다이어그램은 상환 에이전트의 완전한 상호작용 흐름을 보여줍니다:

sequenceDiagram
    participant User as 사용자/CLI 클라이언트
    participant Server as A2A 서버
    participant Agent as 상환 에이전트
    participant LLM as Gemini 2.0 Flash

    User->>Server: 상환 요청 전송<br/>"점심 식사비 $20를 상환해야 합니다"
    Server->>Agent: 사용자 요청 전달
    Agent->>LLM: 요청 내용 분석
    LLM->>Agent: 날짜 및 기타 정보 누락 식별
    Agent->>Agent: create_request_form() 호출
    Agent->>Agent: return_form() 호출
    Agent->>Server: 양식 구조 반환
    Server->>User: JSON 양식 반환<br/>날짜, 금액, 목적 필드 포함
    
    User->>User: 사용자가 양식 작성<br/>날짜, 금액, 목적
    User->>Server: 완성된 양식 제출
    Server->>Agent: 양식 데이터 전달
    Agent->>LLM: 양식 완성도 검증
    LLM->>Agent: 정보가 완전함을 확인
    Agent->>Agent: reimburse(request_id) 호출
    Agent->>Server: 승인 결과 반환
    Server->>User: 최종 결과 반환<br/>"상환이 승인되었습니다"

워크플로우 세부사항

1. 요청 수신: 사용자가 CLI 클라이언트를 통해 상환 요청 전송
2. 지능형 분석: Gemini 모델이 요청을 분석하고 누락된 필수 정보 식별
3. 양식 생성: 정보가 불완전한 경우, 필요한 필드가 포함된 양식을 자동 생성
4. 사용자 상호작용: 사용자가 양식을 작성하여 누락된 정보 보완
5. 정보 검증: 양식 데이터의 완성도와 유효성 검증
6. 상환 처리: 상환 승인을 실행하고 결과 반환

🛠️ 고급 설정

환경 변수

# Google API 설정
GOOGLE_API_KEY=your_api_key_here

# Vertex AI 사용 (선택사항)
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# 서버 설정
HOST=localhost
PORT=10002

사용자 정의 포트로 실행

uv run . --host 0.0.0.0 --port 8080

🧪 개발 및 디버깅

상세 로깅 활성화

에이전트는 기본적으로 INFO 레벨 로깅을 활성화합니다. 상세한 요청 처리 과정을 확인하세요:

# 서버 로그 보기
uv run . 2>&1 | tee agent.log

양식 구조 예제

에이전트는 JSON Schema 형식을 따르는 양식을 생성합니다:

{
  "type": "form",
  "form": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date",
        "title": "Date",
        "description": "Date of expense"
      },
      "amount": {
        "type": "string",
        "format": "number", 
        "title": "Amount",
        "description": "Amount of expense"
      },
      "purpose": {
        "type": "string",
        "title": "Purpose",
        "description": "Purpose of expense"
      }
    },
    "required": ["date", "amount", "purpose"]
  }
}

⚠️ 보안 고려사항

중요 공지: 이 샘플 코드는 Agent2Agent (A2A) 프로토콜의 작동 방식을 보여주기 위한 데모 목적으로만 사용됩니다. 프로덕션 애플리케이션을 구축할 때는 모든 외부 에이전트를 잠재적으로 신뢰할 수 없는 엔티티로 취급해야 합니다.

보안 조치

• 입력 검증: 모든 외부 입력을 엄격하게 검증하고 정화
• 데이터 처리: 에이전트 카드, 메시지, 아티팩트 및 기타 데이터를 주의깊게 처리
• 자격 증명 관리: 적절한 자격 증명 보호 조치 구현
• 권한 제어: 에이전트의 액세스 권한 및 작업 범위 제한