A2A Protocol

A2A JS Exemplo: Agente de Filmes

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

Código Fonte

A2A JS Exemplo: Agente de Filmes

Visão Geral do Projeto

Este projeto demonstra um agente abrangente de informações de filmes construído com o framework A2A (Agent2Agent). O agente aproveita a API TMDB (The Movie Database) para fornecer informações detalhadas sobre filmes, funcionalidade de pesquisa e capacidades conversacionais alimentadas por IA através da integração OpenRouter.

Características Principais

  • Integração Aprimorada da API TMDB: Implementação moderna usando autenticação Bearer token
  • Pesquisa Abrangente de Filmes: Pesquisar filmes com filtros como ano, conteúdo adulto, etc.
  • Capacidades Multi-Pesquisa: Pesquisar em filmes, programas de TV e pessoas simultaneamente
  • Conversas Alimentadas por IA: Utiliza a API OpenRouter para consultas inteligentes de filmes
  • Suporte a Proxy: Suporte integrado a proxy SOCKS5/HTTP para solicitações de rede
  • Framework A2A: Implementa o protocolo de comunicação Agent2Agent
  • Interface CLI: Interface de linha de comando interativa para testes
  • Servidor Express: Endpoints de API RESTful para comunicação de agentes

Arquitetura do Projeto

O projeto segue uma arquitetura modular com clara separação de responsabilidades:

src/
├── index.ts                    # Ponto de entrada principal do servidor
├── cli.ts                      # Interface de linha de comando
├── config/
│   └── env.ts                  # Configuração do ambiente
└── movie-agent/
    ├── index.ts                # Executor principal do agente
    ├── tools.ts                # Ferramentas da API TMDB
    ├── tmdb.ts                 # Cliente da API TMDB
    └── openai.ts              # Integração OpenRouter

Configuração e Execução Passo a Passo

1. Pré-requisitos

  • Node.js (v18 ou superior)
  • Gerenciador de pacotes Bun
  • Conta da API TMDB
  • Conta da API OpenRouter

2. Instalar Dependências

# Clonar o repositório
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Instalar dependências usando Bun
bun install

3. Configuração do Ambiente

Crie um arquivo .env na raiz do projeto:

# Chave da API TMDB (Bearer token)
TMDB_API_TOKEN=your_tmdb_api_token_here

# Chave da API OpenRouter para recursos de IA
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Configuração de Proxy (Opcional)
USE_PROXY=true
PROXY_URL=socks5://127.0.0.1:7890

# Configuração do Servidor
NODE_ENV=development
PORT=3000

4. Executando o Servidor do Agente

# Iniciar o servidor de desenvolvimento
bun dev

# Ou construir e executar em produção
bun run build
bun start

O servidor iniciará em http://localhost:3000 (ou a porta especificada no seu arquivo .env).

5. Testando com Interface CLI

# Executar o CLI interativo
bun cli

# Ou especificar uma URL de servidor personalizada
bun cli http://localhost:3000

6. Acessando Informações do Agente

Uma vez que o servidor esteja executando, você pode acessar:

  • Cartão do Agente: http://localhost:3000/.well-known/agent.json
  • Documentação da API: Disponível através dos endpoints do framework A2A

Explicação da Lógica do Projeto

Componentes Principais

  1. MovieAgentExecutor: A lógica principal do agente que processa consultas do usuário
  2. Ferramentas TMDB: Cinco ferramentas especializadas para recuperação de dados de filmes
  3. Integração OpenAI: Lida com conversas alimentadas por IA via OpenRouter
  4. Framework A2A: Gerencia o protocolo de comunicação de agentes

Ferramentas Disponíveis

O agente fornece cinco ferramentas principais para informações de filmes:

  1. searchMovies: Pesquisa básica de filmes com filtros opcionais (ano, conteúdo adulto)
  2. searchPeople: Pesquisar atores, diretores e outras personalidades da indústria cinematográfica
  3. getMovieDetails: Recuperar informações detalhadas sobre um filme específico
  4. searchMoviesWithDetails: Pesquisa combinada e detalhes em uma chamada (recomendado)
  5. multiSearch: Pesquisar em todos os tipos de conteúdo (filmes, programas de TV, pessoas) simultaneamente

Processo de Fluxo de Trabalho

O agente segue este fluxo de trabalho geral:

  1. Processamento de Solicitações: Recebe consultas do usuário através do framework A2A
  2. Gerenciamento de Contexto: Mantém histórico de conversas e contexto
  3. Análise de IA: Usa OpenRouter para entender a intenção do usuário
  4. Execução de Ferramentas: Chama ferramentas TMDB apropriadas baseadas na consulta
  5. Geração de Resposta: Formata e retorna informações abrangentes de filmes
  6. Gerenciamento de Estado: Rastreia status de tarefas e fornece atualizações em tempo real

Diagrama de Sequência 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

Destaques Técnicos

Inteligência Alimentada por IA

O agente usa OpenRouter para fornecer respostas inteligentes, determinando automaticamente quais ferramentas usar baseadas nas consultas do usuário. Ele pode lidar com solicitações complexas como "Encontrar filmes de ação de 2023 estrelando Tom Cruise" combinando múltiplas chamadas de ferramentas.

Integração TMDB Aprimorada

Ao contrário de implementações básicas do TMDB, este agente:

  • Usa autenticação moderna Bearer token
  • Implementa "append to response" para uso eficiente da API
  • Gera automaticamente URLs completas de imagens
  • Fornece tratamento abrangente de erros

Conformidade com Protocolo A2A

O agente implementa completamente o protocolo A2A (Agent2Agent), permitindo:

  • Descoberta padronizada de agentes através de cartões de agentes
  • Atualizações de status em tempo real durante o processamento
  • Gerenciamento adequado do ciclo de vida de tarefas
  • Respostas em streaming para melhor experiência do usuário

Suporte a Proxy

O suporte integrado a proxy garante que o agente possa funcionar em ambientes de rede restritos, suportando:

  • Proxies SOCKS5
  • Proxies HTTP/HTTPS
  • Configurações de proxy configuráveis

Exemplos de Uso

Pesquisa Básica de Filmes

Usuário: "Me conte sobre o filme A Origem"
Agente: [Pesquisa por A Origem, recupera detalhes, elenco e enredo]

Consultas Complexas

Usuário: "Encontre filmes de ficção científica de 2020 dirigidos por Christopher Nolan"
Agente: [Usa múltiplas ferramentas para pesquisar e filtrar resultados]

Informações de Atores

Usuário: "Em quais filmes Leonardo DiCaprio esteve recentemente?"
Agente: [Pesquisa pelo ator e lista filmografia recente]

Desenvolvimento e Implantação

O projeto inclui ferramentas abrangentes de desenvolvimento:

  • TypeScript: Segurança de tipos completa em toda a base de código
  • ESLint & Prettier: Qualidade de código e formatação
  • Bun: Gerenciamento rápido de pacotes e execução
  • Arquitetura Modular: Fácil de estender e manter

Conclusão

Este A2A JS Agente de Filmes demonstra uma implementação sofisticada do framework Agent2Agent, combinando tecnologias web modernas com capacidades de IA para criar um sistema poderoso de informações de filmes. O projeto serve como um excelente exemplo de como construir agentes conversacionais inteligentes que podem interagir com APIs externas e fornecer respostas ricas e contextuais às consultas dos usuários.

O design modular, tratamento abrangente de erros e aderência ao protocolo A2A tornam este projeto adequado tanto para fins de aprendizado quanto para cenários de implantação em produção.