A2A JS 샘플: 영화 에이전트

소스 코드

A2A JS 샘플: 영화 에이전트

프로젝트 개요

이 프로젝트는 A2A (Agent-to-Agent) 프레임워크로 구축된 포괄적인 영화 정보 에이전트를 보여줍니다. 이 에이전트는 TMDB (The Movie Database) API를 활용하여 상세한 영화 정보, 검색 기능 및 OpenRouter 통합을 통한 AI 기반 대화 기능을 제공합니다.

주요 기능

• 향상된 TMDB API 통합: Bearer 토큰 인증을 사용한 현대적 구현
• 포괄적인 영화 검색: 연도, 성인 콘텐츠 등의 필터로 영화 검색
• 멀티 검색 기능: 영화, TV 쇼, 인물을 동시에 검색
• AI 기반 대화: 지능적인 영화 쿼리를 위해 OpenRouter API 활용
• 프록시 지원: 네트워크 요청을 위한 내장 SOCKS5/HTTP 프록시 지원
• A2A 프레임워크: Agent-to-Agent 통신 프로토콜 구현
• CLI 인터페이스: 테스트를 위한 대화형 명령줄 인터페이스
• Express 서버: 에이전트 통신을 위한 RESTful API 엔드포인트

프로젝트 아키텍처

프로젝트는 명확한 관심사 분리를 가진 모듈식 아키텍처를 따릅니다:

src/
├── index.ts                    # 메인 서버 진입점
├── cli.ts                      # 명령줄 인터페이스
├── config/
│   └── env.ts                  # 환경 설정
└── movie-agent/
    ├── index.ts                # 핵심 에이전트 실행기
    ├── tools.ts                # TMDB API 도구
    ├── tmdb.ts                 # TMDB API 클라이언트
    └── openai.ts              # OpenRouter 통합

단계별 설정 및 실행

1. 전제 조건

• Node.js (v18 이상)
• Bun 패키지 매니저
• TMDB API 계정
• OpenRouter API 계정

2. 종속성 설치

# 저장소 복제
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Bun을 사용하여 종속성 설치
bun install

3. 환경 설정

프로젝트 루트에 .env 파일을 생성하세요:

# TMDB API 키 (Bearer 토큰)
TMDB_API_TOKEN=your_tmdb_api_token_here

# AI 기능을 위한 OpenRouter API 키
OPENROUTER_API_KEY=your_openrouter_api_key_here

# 프록시 설정 (선택사항)
USE_PROXY=true
PROXY_URL=socks5://127.0.0.1:7890

# 서버 설정
NODE_ENV=development
PORT=3000

4. 에이전트 서버 실행

# 개발 서버 시작
bun dev

# 또는 프로덕션에서 빌드 및 실행
bun run build
bun start

서버는 http://localhost:3000 (또는 .env 파일에 지정된 포트)에서 시작됩니다.

5. CLI 인터페이스로 테스트

# 대화형 CLI 실행
bun cli

# 또는 사용자 정의 서버 URL 지정
bun cli http://localhost:3000

6. 에이전트 정보 접근

서버가 실행되면 다음에 접근할 수 있습니다:

• 에이전트 카드: http://localhost:3000/.well-known/agent.json
• API 문서: A2A 프레임워크 엔드포인트를 통해 사용 가능

프로젝트 로직 설명

핵심 구성 요소

1. MovieAgentExecutor: 사용자 쿼리를 처리하는 메인 에이전트 로직
2. TMDB 도구: 영화 데이터 검색을 위한 5개의 전문 도구
3. OpenAI 통합: OpenRouter를 통한 AI 기반 대화 처리
4. A2A 프레임워크: 에이전트 통신 프로토콜 관리

사용 가능한 도구

에이전트는 영화 정보를 위한 5가지 주요 도구를 제공합니다:

1. searchMovies: 선택적 필터(연도, 성인 콘텐츠)가 있는 기본 영화 검색
2. searchPeople: 배우, 감독 및 기타 영화 산업 인물 검색
3. getMovieDetails: 특정 영화에 대한 상세 정보 검색
4. searchMoviesWithDetails: 한 번의 호출로 검색과 세부 정보 결합 (권장)
5. multiSearch: 모든 콘텐츠 유형(영화, TV 쇼, 인물)을 동시에 검색

워크플로우 프로세스

에이전트는 다음과 같은 일반적인 워크플로우를 따릅니다:

1. 요청 처리: A2A 프레임워크를 통해 사용자 쿼리 수신
2. 컨텍스트 관리: 대화 기록과 컨텍스트 유지
3. AI 분석: OpenRouter를 사용하여 사용자 의도 이해
4. 도구 실행: 쿼리를 기반으로 적절한 TMDB 도구 호출
5. 응답 생성: 포괄적인 영화 정보 형식화 및 반환
6. 상태 관리: 작업 상태 추적 및 실시간 업데이트 제공

Mermaid 시퀀스 다이어그램

sequenceDiagram
    participant U as User
    participant CLI as CLI Client
    participant A as A2A Server
    participant MA as Movie Agent
    participant AI as OpenRouter API
    participant TMDB as TMDB API

    U->>CLI: Enter movie query
    CLI->>A: Send message via A2A protocol
    A->>MA: Execute task
    MA->>A: Publish "working" status
    A->>CLI: Stream status update
    CLI->>U: Show "Processing..." message

    MA->>AI: Send query with available tools
    AI->>MA: Respond with tool calls
    MA->>TMDB: Execute tool calls (searchMovies, getMovieDetails, etc.)
    TMDB->>MA: Return movie data
    MA->>AI: Send tool results
    AI->>MA: Generate final response
    MA->>A: Publish "completed" status with response
    A->>CLI: Stream final response
    CLI->>U: Display movie information

    Note over MA,TMDB: Tools available:<br/>- searchMovies<br/>- searchPeople<br/>- getMovieDetails<br/>- searchMoviesWithDetails<br/>- multiSearch

기술적 하이라이트

AI 기반 지능

에이전트는 OpenRouter를 사용하여 지능적인 응답을 제공하며, 사용자 쿼리를 기반으로 어떤 도구를 사용할지 자동으로 결정합니다. "톰 크루즈가 출연한 2023년 액션 영화 찾기"와 같은 복잡한 요청을 여러 도구 호출을 결합하여 처리할 수 있습니다.

향상된 TMDB 통합

기본 TMDB 구현과 달리 이 에이전트는:

• 현대적인 Bearer 토큰 인증 사용
• 효율적인 API 사용을 위한 "append to response" 구현
• 전체 이미지 URL 자동 생성
• 포괄적인 오류 처리 제공

A2A 프로토콜 준수

에이전트는 A2A (Agent-to-Agent) 프로토콜을 완전히 구현하여 다음을 가능하게 합니다:

• 에이전트 카드를 통한 표준화된 에이전트 발견
• 처리 중 실시간 상태 업데이트
• 적절한 작업 생명주기 관리
• 더 나은 사용자 경험을 위한 스트리밍 응답

프록시 지원

내장 프록시 지원으로 제한된 네트워크 환경에서도 에이전트가 작동할 수 있도록 보장하며, 다음을 지원합니다:

• SOCKS5 프록시
• HTTP/HTTPS 프록시
• 구성 가능한 프록시 설정

사용 예시

기본 영화 검색

사용자: "인셉션 영화에 대해 알려줘"
에이전트: [인셉션을 검색하고, 세부 정보, 출연진, 줄거리를 검색]

복잡한 쿼리

사용자: "크리스토퍼 놀란이 감독한 2020년 SF 영화를 찾아줘"
에이전트: [여러 도구를 사용하여 결과를 검색하고 필터링]

배우 정보

사용자: "레오나르도 디카프리오가 최근에 출연한 영화는?"
에이전트: [배우를 검색하고 최근 필모그래피 나열]

개발 및 배포

프로젝트에는 포괄적인 개발 도구가 포함되어 있습니다:

• TypeScript: 전체 코드베이스에 걸친 완전한 타입 안전성
• ESLint & Prettier: 코드 품질 및 포맷팅
• Bun: 빠른 패키지 관리 및 실행
• 모듈식 아키텍처: 확장 및 유지보수 용이

결론

이 A2A JS 영화 에이전트는 Agent-to-Agent 프레임워크의 정교한 구현을 보여주며, 현대적인 웹 기술과 AI 기능을 결합하여 강력한 영화 정보 시스템을 만듭니다. 이 프로젝트는 외부 API와 상호작용하고 사용자 쿼리에 대해 풍부하고 맥락적인 응답을 제공할 수 있는 지능적이고 대화형 에이전트를 구축하는 방법의 훌륭한 예시입니다.

모듈식 설계, 포괄적인 오류 처리 및 A2A 프로토콜 준수로 인해 이 프로젝트는 학습 목적과 프로덕션 배포 시나리오 모두에 적합합니다.