A2A Python 示例：GitHub 智能代理

一个基于 A2A（Agent2Agent）SDK 构建的智能 GitHub 代理，可以使用自然语言查询 GitHub 仓库、最新更新、提交记录和项目活动。

🏗️ 架构

本项目实现了一个使用基于 OpenAI 的代理与 GitHub API 集成的 A2A 服务器。架构包含以下关键组件：

组件概览

A2A 服务器 (__main__.py)：处理 HTTP 请求并管理代理生命周期的主服务器应用程序
OpenAI 代理执行器 (openai_agent_executor.py)：通过 OpenRouter API 集成执行代理任务
GitHub 工具集 (github_toolset.py)：为仓库操作提供 GitHub API 工具
代理定义 (openai_agent.py)：定义代理的能力和系统提示

架构流程

sequenceDiagram
    participant Client as A2A 客户端
    participant Server as A2A 服务器
    participant Agent as OpenAI 代理
    participant GitHub as GitHub API
    participant OpenRouter as OpenRouter API

    Note over Client,OpenRouter: A2A GitHub 代理架构

    Client->>Server: HTTP 请求<br/>(关于 GitHub 的查询)
    Server->>Agent: 处理请求<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: 发送聊天完成<br/>(定义工具)
    OpenRouter-->>Agent: 带工具调用的响应

    loop 工具执行
        Agent->>GitHub: API 调用<br/>(GitHubToolset)
        GitHub-->>Agent: 仓库/提交数据
        Agent->>OpenRouter: 发送工具结果
        OpenRouter-->>Agent: 最终响应
    end

    Agent->>Server: 流式响应<br/>(TaskUpdater)
    Server->>Client: HTTP 响应<br/>(格式化结果)

    Note over Client: 用户看到由 AI<br/>格式化的 GitHub 数据

🔧 关键模块逻辑

1. 主服务器 (`main.py`)

使用 Starlette 框架初始化 A2A 服务器
创建定义代理能力和技能的 AgentCard
设置带有 GitHub 工具的 OpenAI 代理执行器
在指定主机和端口上启动 HTTP 服务器

2. GitHub 工具集 (`github_toolset.py`)

提供三个主要的 GitHub API 功能：

get_user_repositories()：检索用户的最新仓库
get_recent_commits()：获取特定仓库的最新提交
search_repositories()：搜索具有最新活动的仓库

所有功能都包含错误处理并支持用于过滤的可选参数。

3. OpenAI 代理执行器 (`openai_agent_executor.py`)

管理与 OpenRouter API 的对话流程
将 GitHub 工具转换为 OpenAI 函数调用格式
处理工具执行和响应流
实现带工具调用的迭代对话

4. 代理定义 (`openai_agent.py`)

使用系统提示和可用工具创建代理
定义代理对 GitHub 相关查询的行为
配置代理提供有用的仓库信息

📋 先决条件

Python 3.10 或更高版本
UV - Python 包管理器
OpenRouter API 密钥 - 用于 AI 功能
GitHub 个人访问令牌（可选，但建议用于更高的速率限制）

🚀 逐步设置和运行

步骤 1：克隆和设置环境

# 克隆仓库
git clone https://github.com/sing1ee/a2a-py-github-agent.git
cd a2a-py-github-agent

# 创建虚拟环境
uv venv
source .venv/bin/activate  # Windows 上：.venv\Scripts\activate

步骤 2：安装依赖项

# 使用 UV 安装依赖项
uv sync

步骤 3：配置环境变量

在项目根目录创建 .env 文件：

# OpenRouter API 密钥（必需）
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# GitHub 个人访问令牌（可选但建议）
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

注意：GitHub 令牌是可选的。没有它，代理将使用未认证访问，速率限制较低（每小时 60 次请求 vs 有令牌时的 5000 次）。

步骤 4：运行 A2A 服务器

# 激活虚拟环境
source .venv/bin/activate

# 运行服务器
uv run .

服务器默认将在 http://localhost:10007 上启动。

🧪 客户端测试

选项 1：使用 A2A 电影代理客户端

您可以使用 A2A 电影代理客户端测试 GitHub 代理：

# 克隆 A2A 电影代理客户端
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# 安装依赖项
bun install

# 连接到您的 GitHub 代理
bun cli http://localhost:10007

这将启动一个连接到您的 GitHub 代理服务器的交互式 CLI。

选项 2：使用直接 HTTP 请求

您也可以使用 curl 或任何 HTTP 客户端进行测试：

# 示例：使用简单查询进行测试
curl -X POST http://localhost:10007/ \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "显示仓库 'facebook/react' 的最新提交"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 示例查询

GitHub 代理可以处理以下类型的查询：

最新提交："显示仓库 'facebook/react' 的最新提交"
仓库搜索："搜索具有最新活动的热门 Python 仓库"
项目活动："机器学习仓库的最新更新是什么？"

🔑 GitHub 令牌设置

要创建 GitHub 个人访问令牌以获得更好的速率限制：

转到 GitHub 设置 > 令牌
点击"生成新令牌（经典）"
选择以下范围：
- repo - 访问仓库
- user - 访问用户信息
复制令牌并将其添加到您的 .env 文件中

🛠️ 配置选项

服务器配置

您可以使用命令行选项自定义服务器：

# 自定义主机和端口
uv run . --host=0.0.0.0 --port=10007

环境变量

OPENROUTER_API_KEY：您的 OpenRouter API 密钥（必需）
GITHUB_TOKEN：GitHub 个人访问令牌（可选）

📖 API 文档

可用工具

get_user_repositories
- 获取用户的最新更新仓库
- 参数：username（可选）、days（默认：30）、limit（默认：10）
get_recent_commits
- 获取仓库的最新提交
- 参数：repo_name（必需）、days（默认：7）、limit（默认：10）
search_repositories
- 搜索具有最新活动的仓库
- 参数：query（必需）、sort（默认：'updated'）、limit（默认：10）

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🔗 相关项目

A2A SDK - 底层 A2A 协议实现
A2A 电影代理 - 使用 A2A 协议构建的电影信息代理