A2A Protocol

A2A JS Beispiel: Film-Agent

English中文русскийportuguês한국어日本語हिंदीfrançaisdeutsch
MILO•
Share
A2A JS Beispiel: Film-Agent

Quellcode

A2A JS Beispiel: Film-Agent

Projektübersicht

Dieses Projekt demonstriert einen umfassenden Film-Informations-Agent, der mit dem A2A (Agent2Agent) Framework erstellt wurde. Der Agent nutzt die TMDB (The Movie Database) API, um detaillierte Filminformationen, Suchfunktionen und KI-gestützte Gesprächsfähigkeiten durch OpenRouter-Integration bereitzustellen.

Hauptmerkmale

  • Erweiterte TMDB-API-Integration: Moderne Implementierung mit Bearer-Token-Authentifizierung
  • Umfassende Filmsuche: Filme mit Filtern wie Jahr, Erwachseneninhalte usw. suchen
  • Multi-Such-Fähigkeiten: Gleichzeitige Suche in Filmen, TV-Sendungen und Personen
  • KI-gestützte Gespräche: Nutzt OpenRouter API für intelligente Filmanfragen
  • Proxy-Unterstützung: Integrierte SOCKS5/HTTP-Proxy-Unterstützung für Netzwerkanfragen
  • A2A-Framework: Implementiert das Agent2Agent-Kommunikationsprotokoll
  • CLI-Interface: Interaktive Befehlszeilenschnittstelle zum Testen
  • Express-Server: RESTful API-Endpunkte für Agent-Kommunikation

Projektarchitektur

Das Projekt folgt einer modularen Architektur mit klarer Trennung der Belange:

src/
├── index.ts                    # Haupt-Server-Einstiegspunkt
├── cli.ts                      # Befehlszeilenschnittstelle
├── config/
│   └── env.ts                  # Umgebungskonfiguration
└── movie-agent/
    ├── index.ts                # Haupt-Agent-Executor
    ├── tools.ts                # TMDB-API-Tools
    ├── tmdb.ts                 # TMDB-API-Client
    └── openai.ts              # OpenRouter-Integration

Schritt-für-Schritt-Setup und -Ausführung

1. Voraussetzungen

  • Node.js (v18 oder höher)
  • Bun-Paketmanager
  • TMDB-API-Konto
  • OpenRouter-API-Konto

2. Abhängigkeiten installieren

# Repository klonen
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Abhängigkeiten mit Bun installieren
bun install

3. Umgebungskonfiguration

Erstellen Sie eine .env-Datei im Projektstamm:

# TMDB-API-Schlüssel (Bearer-Token)
TMDB_API_TOKEN=your_tmdb_api_token_here

# OpenRouter-API-Schlüssel für KI-Funktionen
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Proxy-Konfiguration (Optional)
USE_PROXY=true
PROXY_URL=socks5://127.0.0.1:7890

# Server-Konfiguration
NODE_ENV=development
PORT=3000

4. Agent-Server ausführen

# Entwicklungsserver starten
bun dev

# Oder für Produktion bauen und ausführen
bun run build
bun start

Der Server startet auf http://localhost:3000 (oder dem in Ihrer .env-Datei angegebenen Port).

5. Mit CLI-Interface testen

# Interaktive CLI ausführen
bun cli

# Oder benutzerdefinierte Server-URL angeben
bun cli http://localhost:3000

6. Agent-Informationen abrufen

Sobald der Server läuft, können Sie zugreifen auf:

  • Agent-Karte: http://localhost:3000/.well-known/agent.json
  • API-Dokumentation: Verfügbar über A2A-Framework-Endpunkte

Projektlogik-Erklärung

Hauptkomponenten

  1. MovieAgentExecutor: Die Haupt-Agent-Logik, die Benutzeranfragen verarbeitet
  2. TMDB-Tools: Fünf spezialisierte Tools für Film-Datenabruf
  3. OpenAI-Integration: Verwaltet KI-gestützte Gespräche über OpenRouter
  4. A2A-Framework: Verwaltet das Agent-Kommunikationsprotokoll

Verfügbare Tools

Der Agent bietet fünf Haupttools für Filminformationen:

  1. searchMovies: Grundlegende Filmsuche mit optionalen Filtern (Jahr, Erwachseneninhalte)
  2. searchPeople: Suche nach Schauspielern, Regisseuren und anderen Filmindustrie-Persönlichkeiten
  3. getMovieDetails: Detaillierte Informationen zu einem bestimmten Film abrufen
  4. searchMoviesWithDetails: Kombinierte Suche und Details in einem Aufruf (empfohlen)
  5. multiSearch: Gleichzeitige Suche in allen Inhaltstypen (Filme, TV-Sendungen, Personen)

Workflow-Prozess

Der Agent folgt diesem allgemeinen Workflow:

  1. Anfrageverarbeitung: Empfängt Benutzeranfragen über das A2A-Framework
  2. Kontextverwaltung: Behält Gesprächshistorie und Kontext bei
  3. KI-Analyse: Nutzt OpenRouter, um Benutzerabsicht zu verstehen
  4. Tool-Ausführung: Ruft entsprechende TMDB-Tools basierend auf der Anfrage auf
  5. Antwortgenerierung: Formatiert und gibt umfassende Filminformationen zurück
  6. Zustandsverwaltung: Verfolgt Aufgabenstatus und bietet Echtzeit-Updates

Mermaid-Sequenzdiagramm

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

Technische Highlights

KI-gestützte Intelligenz

Der Agent nutzt OpenRouter, um intelligente Antworten zu liefern und automatisch zu bestimmen, welche Tools basierend auf Benutzeranfragen verwendet werden sollen. Er kann komplexe Anfragen wie "Finde Action-Filme von 2023 mit Tom Cruise" durch Kombination mehrerer Tool-Aufrufe bearbeiten.

Erweiterte TMDB-Integration

Im Gegensatz zu grundlegenden TMDB-Implementierungen bietet dieser Agent:

  • Moderne Bearer-Token-Authentifizierung
  • Implementiert "append to response" für effiziente API-Nutzung
  • Generiert automatisch vollständige Bild-URLs
  • Bietet umfassende Fehlerbehandlung

A2A-Protokoll-Konformität

Der Agent implementiert vollständig das A2A (Agent2Agent) Protokoll und ermöglicht:

  • Standardisierte Agent-Entdeckung über Agent-Karten
  • Echtzeit-Status-Updates während der Verarbeitung
  • Ordnungsgemäße Aufgaben-Lebenszyklus-Verwaltung
  • Streaming-Antworten für bessere Benutzererfahrung

Proxy-Unterstützung

Die integrierte Proxy-Unterstützung stellt sicher, dass der Agent in eingeschränkten Netzwerkumgebungen funktioniert und unterstützt:

  • SOCKS5-Proxies
  • HTTP/HTTPS-Proxies
  • Konfigurierbare Proxy-Einstellungen

Verwendungsbeispiele

Grundlegende Filmsuche

Benutzer: "Erzählen Sie mir über den Film Inception"
Agent: [Sucht Inception, ruft Details, Besetzung und Handlung ab]

Komplexe Anfragen

Benutzer: "Finden Sie Science-Fiction-Filme von 2020, die von Christopher Nolan gedreht wurden"
Agent: [Verwendet mehrere Tools zum Suchen und Filtern von Ergebnissen]

Schauspieler-Informationen

Benutzer: "In welchen Filmen hat Leonardo DiCaprio kürzlich gespielt?"
Agent: [Sucht den Schauspieler und listet die aktuelle Filmografie auf]

Entwicklung und Bereitstellung

Das Projekt umfasst umfassende Entwicklungstools:

  • TypeScript: Vollständige Typsicherheit in der gesamten Codebasis
  • ESLint & Prettier: Code-Qualität und Formatierung
  • Bun: Schnelle Paketverwaltung und -ausführung
  • Modulare Architektur: Einfach zu erweitern und zu warten

Fazit

Dieser A2A JS Film-Agent demonstriert eine ausgeklügelte Implementierung des Agent2Agent-Frameworks, die moderne Webtechnologien mit KI-Fähigkeiten kombiniert, um ein leistungsstarkes Film-Informationssystem zu schaffen. Das Projekt dient als ausgezeichnetes Beispiel dafür, wie intelligente Gesprächsagenten erstellt werden, die mit externen APIs interagieren und reiche, kontextuelle Antworten auf Benutzeranfragen liefern können.

Das modulare Design, die umfassende Fehlerbehandlung und die Einhaltung des A2A-Protokolls machen dieses Projekt sowohl für Lernzwecke als auch für Produktionsbereitstellungsszenarien geeignet.