A2A Protocol

A2A JS Пример: Агент фильмов

English中文русскийportuguês한국어日本語हिंदीfrançaisdeutsch
MILO•
Share
A2A JS Пример: Агент фильмов

Исходный код

A2A JS Пример: Агент фильмов

Обзор проекта

Этот проект демонстрирует комплексного агента информации о фильмах, построенного с использованием фреймворка A2A (Agent2Agent). Агент использует API TMDB (The Movie Database) для предоставления подробной информации о фильмах, функций поиска и разговорных возможностей на основе ИИ через интеграцию с OpenRouter.

Ключевые особенности

  • Улучшенная интеграция TMDB API: Современная реализация с использованием аутентификации Bearer token
  • Комплексный поиск фильмов: Поиск фильмов с фильтрами по году, контенту для взрослых и т.д.
  • Возможности мульти-поиска: Поиск по фильмам, телешоу и людям одновременно
  • Разговоры на основе ИИ: Использует API OpenRouter для интеллектуальных запросов о фильмах
  • Поддержка прокси: Встроенная поддержка SOCKS5/HTTP прокси для сетевых запросов
  • Фреймворк A2A: Реализует протокол связи Agent2Agent
  • 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 token)
TMDB_API_TOKEN=your_tmdb_api_token_here

# Ключ 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 Tools: Пять специализированных инструментов для получения данных о фильмах
  3. Интеграция OpenAI: Обрабатывает разговоры на основе ИИ через OpenRouter
  4. Фреймворк A2A: Управляет протоколом связи агентов

Доступные инструменты

Агент предоставляет пять основных инструментов для информации о фильмах:

  1. searchMovies: Базовый поиск фильмов с опциональными фильтрами (год, контент для взрослых)
  2. searchPeople: Поиск актеров, режиссеров и других личностей киноиндустрии
  3. getMovieDetails: Получение подробной информации о конкретном фильме
  4. searchMoviesWithDetails: Комбинированный поиск и детали в одном вызове (рекомендуется)
  5. multiSearch: Поиск по всем типам контента (фильмы, телешоу, люди) одновременно

Процесс рабочего потока

Агент следует этому общему рабочему потоку:

  1. Обработка запросов: Получает пользовательские запросы через фреймворк A2A
  2. Управление контекстом: Поддерживает историю разговоров и контекст
  3. Анализ ИИ: Использует 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

Технические особенности

Интеллект на основе ИИ

Агент использует OpenRouter для предоставления интеллектуальных ответов, автоматически определяя, какие инструменты использовать на основе пользовательских запросов. Он может обрабатывать сложные запросы, такие как "Найти боевики 2023 года с участием Тома Круза", комбинируя несколько вызовов инструментов.

Улучшенная интеграция TMDB

В отличие от базовых реализаций TMDB, этот агент:

  • Использует современную аутентификацию Bearer token
  • Реализует "append to response" для эффективного использования API
  • Автоматически генерирует полные URL изображений
  • Обеспечивает комплексную обработку ошибок

Соответствие протоколу A2A

Агент полностью реализует протокол A2A (Agent2Agent), обеспечивая:

  • Стандартизированное обнаружение агентов через карточки агентов
  • Обновления статуса в реальном времени во время обработки
  • Правильное управление жизненным циклом задач
  • Потоковые ответы для лучшего пользовательского опыта

Поддержка прокси

Встроенная поддержка прокси обеспечивает работу агента в ограниченных сетевых средах, поддерживая:

  • SOCKS5 прокси
  • HTTP/HTTPS прокси
  • Настраиваемые параметры прокси

Примеры использования

Базовый поиск фильмов

Пользователь: "Расскажи мне о фильме Начало"
Агент: [Ищет Начало, получает детали, актерский состав и сюжет]

Сложные запросы

Пользователь: "Найди научно-фантастические фильмы 2020 года режиссера Кристофера Нолана"
Агент: [Использует несколько инструментов для поиска и фильтрации результатов]

Информация об актерах

Пользователь: "В каких фильмах недавно снимался Леонардо ДиКаприо?"
Агент: [Ищет актера и перечисляет недавнюю фильмографию]

Разработка и развертывание

Проект включает комплексные инструменты разработки:

  • TypeScript: Полная типобезопасность во всей кодовой базе
  • ESLint & Prettier: Качество кода и форматирование
  • Bun: Быстрое управление пакетами и выполнение
  • Модульная архитектура: Легко расширяется и поддерживается

Заключение

Этот A2A JS агент фильмов демонстрирует сложную реализацию фреймворка Agent2Agent, объединяя современные веб-технологии с возможностями ИИ для создания мощной системы информации о фильмах. Проект служит отличным примером того, как создавать интеллектуальных разговорных агентов, которые могут взаимодействовать с внешними API и предоставлять богатые, контекстуальные ответы на пользовательские запросы.

Модульный дизайн, комплексная обработка ошибок и соблюдение протокола A2A делают этот проект подходящим как для целей обучения, так и для сценариев развертывания в продакшене.