A2A JS 示例：电影智能体

源代码

项目概述

本项目展示了一个使用 A2A（智能体到智能体）框架构建的综合性电影信息智能体。该智能体利用 TMDB（电影数据库）API 提供详细的电影信息、搜索功能，并通过 OpenRouter 集成实现 AI 驱动的对话能力。

主要特性

增强的 TMDB API 集成：使用 Bearer token 认证的现代化实现
全面的电影搜索：支持年份、成人内容等过滤器的电影搜索
多重搜索能力：同时搜索电影、电视剧和人物
AI 驱动的对话：利用 OpenRouter API 进行智能电影查询
代理支持：内置 SOCKS5/HTTP 代理支持网络请求
A2A 框架：实现智能体到智能体通信协议
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 密钥用于 AI 功能
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 框架端点提供

项目逻辑说明

核心组件

MovieAgentExecutor：处理用户查询的主要智能体逻辑
TMDB 工具：用于电影数据检索的五个专用工具
OpenAI 集成：通过 OpenRouter 处理 AI 驱动的对话
A2A 框架：管理智能体通信协议

可用工具

智能体提供五个主要的电影信息工具：

searchMovies：带有可选过滤器（年份、成人内容）的基本电影搜索
searchPeople：搜索演员、导演和其他电影行业人士
getMovieDetails：检索特定电影的详细信息
searchMoviesWithDetails：在一次调用中结合搜索和详情（推荐）
multiSearch：同时搜索所有内容类型（电影、电视剧、人物）

工作流程

智能体遵循以下一般工作流程：

请求处理：通过 A2A 框架接收用户查询
上下文管理：维护对话历史和上下文
AI 分析：使用 OpenRouter 理解用户意图
工具执行：根据查询调用适当的 TMDB 工具
响应生成：格式化并返回全面的电影信息
状态管理：跟踪任务状态并提供实时更新

Mermaid 序列图

sequenceDiagram
    participant U as 用户
    participant CLI as CLI 客户端
    participant A as A2A 服务器
    participant MA as 电影智能体
    participant AI as OpenRouter API
    participant TMDB as TMDB API

    U->>CLI: 输入电影查询
    CLI->>A: 通过 A2A 协议发送消息
    A->>MA: 执行任务
    MA->>A: 发布"工作中"状态
    A->>CLI: 流式状态更新
    CLI->>U: 显示"处理中..."消息

    MA->>AI: 发送带有可用工具的查询
    AI->>MA: 响应工具调用
    MA->>TMDB: 执行工具调用（searchMovies、getMovieDetails 等）
    TMDB->>MA: 返回电影数据
    MA->>AI: 发送工具结果
    AI->>MA: 生成最终响应
    MA->>A: 发布"已完成"状态和响应
    A->>CLI: 流式最终响应
    CLI->>U: 显示电影信息

    Note over MA,TMDB: 可用工具：<br/>- searchMovies<br/>- searchPeople<br/>- getMovieDetails<br/>- searchMoviesWithDetails<br/>- multiSearch

技术亮点

AI 驱动的智能

智能体使用 OpenRouter 提供智能响应，根据用户查询自动确定使用哪些工具。它可以通过组合多个工具调用来处理复杂请求，如"查找 2023 年汤姆·克鲁斯主演的动作电影"。

增强的 TMDB 集成

与基本的 TMDB 实现不同，此智能体：

使用现代 Bearer token 认证
实现"追加到响应"以提高 API 使用效率
自动生成完整的图像 URL
提供全面的错误处理

A2A 协议合规性

智能体完全实现 A2A（智能体到智能体）协议，支持：

通过智能体卡片进行标准化智能体发现
处理过程中的实时状态更新
适当的任务生命周期管理
更好用户体验的流式响应

代理支持

内置代理支持确保智能体可以在受限网络环境中工作，支持：

SOCKS5 代理
HTTP/HTTPS 代理
可配置的代理设置

使用示例

基本电影搜索

用户："告诉我关于电影《盗梦空间》的信息"
智能体：[搜索《盗梦空间》，检索详情、演员和剧情]

复杂查询

用户："找到 2020 年克里斯托弗·诺兰导演的科幻电影"
智能体：[使用多个工具搜索和过滤结果]

演员信息

用户："莱昂纳多·迪卡普里奥最近演了哪些电影？"
智能体：[搜索演员并列出最近的电影作品]

开发和部署

项目包含全面的开发工具：

TypeScript：整个代码库的完整类型安全
ESLint & Prettier：代码质量和格式化
Bun：快速包管理和执行
模块化架构：易于扩展和维护

结论

这个 A2A JS 电影智能体展示了智能体到智能体框架的复杂实现，结合现代 Web 技术和 AI 能力创建了一个强大的电影信息系统。该项目是如何构建能够与外部 API 交互并为用户查询提供丰富、上下文相关响应的智能对话智能体的优秀示例。

模块化设计、全面的错误处理和对 A2A 协议的遵循使该项目既适合学习目的，也适合生产部署场景。