이것은 Google Agent Development Kit (ADK)를 기반으로 개발된 지능형 경비 상환 에이전트로, Agent2Agent (A2A) 서버로 실행됩니다. 이 에이전트의 핵심 기능은 지능형 양식 생성입니다: 사용자의 상환 요청에 필요한 정보가 부족할 때, 에이전트가 자동으로 사용자가 작성할 양식을 생성하여 처리 전에 완전한 상환 정보를 수집합니다.
소스 코드
🎯 프로젝트 특징
- 지능형 양식 상호작용: 누락된 정보를 자동으로 감지하고 동적 양식을 생성
- A2A 프로토콜 지원: 표준화된 에이전트 간 통신 프로토콜
- 스트리밍 처리: 실시간 응답 및 상태 업데이트 지원
- Google ADK 통합: Google의 최신 에이전트 개발 키트 기반
📋 시스템 요구사항
- Python 3.12 이상
- UV 패키지 관리 도구
- Google API Key (Gemini 모델 액세스)
🚀 빠른 시작
1. Google API Key 획득
- Google AI Studio 방문
- Google 계정으로 로그인
- "Get API key" 클릭
- 새 API 키 생성 또는 기존 키 사용
- 나중에 사용할 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 - 요청 실행기
🔄 핵심 워크플로우
다음 시퀀스 다이어그램은 상환 에이전트의 완전한 상호작용 흐름을 보여줍니다:
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/>"상환이 승인되었습니다"
워크플로우 세부사항
- 요청 수신: 사용자가 CLI 클라이언트를 통해 상환 요청 전송
- 지능형 분석: Gemini 모델이 요청을 분석하고 누락된 필수 정보 식별
- 양식 생성: 정보가 불완전한 경우, 필요한 필드가 포함된 양식을 자동 생성
- 사용자 상호작용: 사용자가 양식을 작성하여 누락된 정보 보완
- 정보 검증: 양식 데이터의 완성도와 유효성 검증
- 상환 처리: 상환 승인을 실행하고 결과 반환
🛠️ 고급 설정
환경 변수
# 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) 프로토콜의 작동 방식을 보여주기 위한 데모 목적으로만 사용됩니다. 프로덕션 애플리케이션을 구축할 때는 모든 외부 에이전트를 잠재적으로 신뢰할 수 없는 엔티티로 취급해야 합니다.
보안 조치
- 입력 검증: 모든 외부 입력을 엄격하게 검증하고 정화
- 데이터 처리: 에이전트 카드, 메시지, 아티팩트 및 기타 데이터를 주의깊게 처리
- 자격 증명 관리: 적절한 자격 증명 보호 조치 구현
- 권한 제어: 에이전트의 액세스 권한 및 작업 범위 제한