A2A Protocol

A2A Python 샘플: GitHub 에이전트

English中文русскийportuguês한국어日本語हिंदीfrançaisdeutsch
MILO•
Share
A2A Python 샘플: GitHub 에이전트

자연어를 사용하여 GitHub 저장소, 최신 업데이트, 커밋 및 프로젝트 활동을 쿼리할 수 있는 A2A (Agent2Agent) SDK로 구축된 지능형 GitHub 에이전트입니다.

🏗️ 아키텍처

이 프로젝트는 GitHub API 통합과 함께 OpenAI 기반 에이전트를 사용하는 A2A 서버를 구현합니다. 아키텍처는 다음과 같은 주요 구성 요소로 이루어져 있습니다:

구성 요소 개요

  • A2A 서버 (__main__.py): HTTP 요청을 처리하고 에이전트 생명주기를 관리하는 메인 서버 애플리케이션
  • OpenAI 에이전트 실행기 (openai_agent_executor.py): OpenRouter API 통합으로 에이전트 작업을 실행
  • GitHub 도구 세트 (github_toolset.py): 저장소 작업을 위한 GitHub API 도구 제공
  • 에이전트 정의 (openai_agent.py): 에이전트의 기능과 시스템 프롬프트 정의

아키텍처 플로우

sequenceDiagram
    participant Client as A2A 클라이언트
    participant Server as A2A 서버
    participant Agent as OpenAI 에이전트
    participant GitHub as GitHub API
    participant OpenRouter as OpenRouter API

    Note over Client,OpenRouter: A2A GitHub 에이전트 아키텍처

    Client->>Server: HTTP 요청<br/>(GitHub에 대한 쿼리)
    Server->>Agent: 요청 처리<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: 채팅 완성 전송<br/>(정의된 도구와 함께)
    OpenRouter-->>Agent: 도구 호출이 포함된 응답

    loop 도구 실행
        Agent->>GitHub: API 호출<br/>(GitHubToolset)
        GitHub-->>Agent: 저장소/커밋 데이터
        Agent->>OpenRouter: 도구 결과 전송
        OpenRouter-->>Agent: 최종 응답
    end

    Agent->>Server: 스트리밍 응답<br/>(TaskUpdater)
    Server->>Client: HTTP 응답<br/>(포맷된 결과)

    Note over Client: 사용자가 AI에 의해<br/>포맷된 GitHub 데이터 확인

🔧 주요 모듈 로직

1. 메인 서버 (__main__.py)

  • Starlette 프레임워크로 A2A 서버 초기화
  • 에이전트의 기능과 스킬을 정의하는 AgentCard 생성
  • GitHub 도구와 함께 OpenAI 에이전트 실행기 설정
  • 지정된 호스트와 포트에서 HTTP 서버 시작

2. GitHub 도구 세트 (github_toolset.py)

세 가지 주요 GitHub API 기능 제공:

  • get_user_repositories(): 사용자의 최신 저장소 검색
  • get_recent_commits(): 특정 저장소의 최신 커밋 가져오기
  • search_repositories(): 최근 활동이 있는 저장소 검색

모든 기능은 오류 처리를 포함하고 필터링을 위한 선택적 매개변수를 지원합니다.

3. OpenAI 에이전트 실행기 (openai_agent_executor.py)

  • OpenRouter API와의 대화 플로우 관리
  • GitHub 도구를 OpenAI 함수 호출 형식으로 변환
  • 도구 실행 및 응답 스트리밍 처리
  • 도구 호출과 함께 반복적 대화 구현

4. 에이전트 정의 (openai_agent.py)

  • 시스템 프롬프트와 사용 가능한 도구로 에이전트 생성
  • GitHub 관련 쿼리에 대한 에이전트의 동작 정의
  • 유용한 저장소 정보를 제공하도록 에이전트 구성

📋 전제 조건

  • Python 3.10 이상
  • UV - Python 패키지 관리자
  • OpenRouter API 키 - AI 기능용
  • GitHub 개인 액세스 토큰 (선택사항이지만 더 높은 속도 제한을 위해 권장)

🚀 단계별 설정 및 실행

1단계: 클론 및 환경 설정

# 저장소 클론
git clone https://github.com/sing1ee/a2a-py-github-agent.git
cd a2a-py-github-agent

# 가상 환경 생성
uv venv
source .venv/bin/activate  # Windows에서: .venv\Scripts\activate

2단계: 종속성 설치

# UV를 사용하여 종속성 설치
uv sync

3단계: 환경 변수 구성

프로젝트 루트에 .env 파일 생성:

# OpenRouter API 키 (필수)
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# GitHub 개인 액세스 토큰 (선택사항이지만 권장)
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

참고: GitHub 토큰은 선택사항입니다. 토큰 없이는 에이전트가 제한된 속도 제한(시간당 60회 요청 vs 토큰 사용 시 5000회)으로 인증되지 않은 액세스를 사용합니다.

4단계: A2A 서버 실행

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

# 서버 실행
uv run .

서버는 기본적으로 http://localhost:10007에서 시작됩니다.

🧪 클라이언트 테스트

옵션 1: A2A Movie Agent 클라이언트 사용

A2A Movie Agent 클라이언트를 사용하여 GitHub 에이전트를 테스트할 수 있습니다:

# A2A Movie Agent 클라이언트 클론
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# 종속성 설치
bun install

# GitHub 에이전트에 연결
bun cli http://localhost:10007

이것은 GitHub 에이전트 서버에 연결하는 대화형 CLI를 시작합니다.

옵션 2: 직접 HTTP 요청 사용

curl 또는 다른 HTTP 클라이언트를 사용하여 테스트할 수도 있습니다:

# 예제: 간단한 쿼리로 테스트
curl -X POST http://localhost:10007/ \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "저장소 'facebook/react'의 최근 커밋을 보여주세요"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 예제 쿼리

GitHub 에이전트는 다음과 같은 쿼리를 처리할 수 있습니다:

  • 최근 커밋: "저장소 'facebook/react'의 최근 커밋을 보여주세요"
  • 저장소 검색: "최근 활동이 있는 인기 Python 저장소를 검색하세요"
  • 프로젝트 활동: "머신러닝 저장소의 최신 업데이트는 무엇인가요?"

🔑 GitHub 토큰 설정

더 나은 속도 제한을 위해 GitHub 개인 액세스 토큰을 생성하려면:

  1. GitHub 설정 > 토큰으로 이동
  2. "새 토큰 생성 (클래식)" 클릭
  3. 다음 범위 선택:
    • repo - 저장소 액세스
    • user - 사용자 정보 액세스
  4. 토큰을 복사하여 .env 파일에 추가

🛠️ 구성 옵션

서버 구성

명령줄 옵션을 사용하여 서버를 사용자 정의할 수 있습니다:

# 사용자 정의 호스트 및 포트
uv run . --host=0.0.0.0 --port=10007

환경 변수

  • OPENROUTER_API_KEY: OpenRouter API 키 (필수)
  • GITHUB_TOKEN: GitHub 개인 액세스 토큰 (선택사항)

📖 API 문서

사용 가능한 도구

  1. get_user_repositories

    • 최근 업데이트가 있는 사용자의 저장소 가져오기
    • 매개변수: username (선택사항), days (기본값: 30), limit (기본값: 10)

  2. get_recent_commits

    • 저장소의 최근 커밋 가져오기
    • 매개변수: repo_name (필수), days (기본값: 7), limit (기본값: 10)

  3. search_repositories

    • 최근 활동이 있는 저장소 검색
    • 매개변수: query (필수), sort (기본값: 'updated'), limit (기본값: 10)

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

🔗 관련 프로젝트

  • A2A SDK - 기본 A2A 프로토콜 구현
  • A2A Movie Agent - A2A 프로토콜로 구축된 영화 정보 에이전트