A2A Protocol

A2A Python Exemplo: Agente GitHub

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

Um agente GitHub inteligente construído com A2A (Agent2Agent) SDK que pode consultar repositórios GitHub, atualizações recentes, commits e atividade de projetos usando linguagem natural.

🏗️ Arquitetura

Este projeto implementa um servidor A2A que usa um agente baseado em OpenAI com integração da API do GitHub. A arquitetura consiste nos seguintes componentes principais:

Visão Geral dos Componentes

  • Servidor A2A (__main__.py): A aplicação principal do servidor que lida com requisições HTTP e gerencia o ciclo de vida do agente
  • Executor do Agente OpenAI (openai_agent_executor.py): Executa tarefas do agente com integração da API OpenRouter
  • Conjunto de Ferramentas GitHub (github_toolset.py): Fornece ferramentas da API GitHub para operações de repositório
  • Definição do Agente (openai_agent.py): Define as capacidades do agente e prompt do sistema

Fluxo da Arquitetura

sequenceDiagram
    participant Client as Cliente A2A
    participant Server as Servidor A2A
    participant Agent as Agente OpenAI
    participant GitHub as API GitHub
    participant OpenRouter as API OpenRouter

    Note over Client,OpenRouter: Arquitetura do Agente GitHub A2A

    Client->>Server: Requisição HTTP<br/>(consulta sobre GitHub)
    Server->>Agent: Processar Requisição<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: Enviar Conclusão de Chat<br/>(com ferramentas definidas)
    OpenRouter-->>Agent: Resposta com chamadas de ferramentas

    loop Execução de Ferramentas
        Agent->>GitHub: Chamada da API<br/>(GitHubToolset)
        GitHub-->>Agent: Dados de Repositório/Commit
        Agent->>OpenRouter: Enviar resultados das ferramentas
        OpenRouter-->>Agent: Resposta final
    end

    Agent->>Server: Resposta em Streaming<br/>(TaskUpdater)
    Server->>Client: Resposta HTTP<br/>(resultados formatados)

    Note over Client: Usuário vê dados do GitHub<br/>formatados por IA

🔧 Lógica dos Módulos Principais

1. Servidor Principal (__main__.py)

  • Inicializa o servidor A2A com framework Starlette
  • Cria um AgentCard que define as capacidades e habilidades do agente
  • Configura o executor do agente OpenAI com ferramentas GitHub
  • Inicia o servidor HTTP no host e porta especificados

2. Conjunto de Ferramentas GitHub (github_toolset.py)

Fornece três funções principais da API GitHub:

  • get_user_repositories(): Recupera repositórios recentes para um usuário
  • get_recent_commits(): Busca commits recentes para um repositório específico
  • search_repositories(): Pesquisa repositórios com atividade recente

Todas as funções incluem tratamento de erros e suportam parâmetros opcionais para filtragem.

3. Executor do Agente OpenAI (openai_agent_executor.py)

  • Gerencia o fluxo de conversa com a API OpenRouter
  • Converte ferramentas GitHub para formato de chamada de função OpenAI
  • Lida com execução de ferramentas e streaming de resposta
  • Implementa conversa iterativa com chamadas de ferramentas

4. Definição do Agente (openai_agent.py)

  • Cria o agente com prompt do sistema e ferramentas disponíveis
  • Define o comportamento do agente para consultas relacionadas ao GitHub
  • Configura o agente para fornecer informações úteis sobre repositórios

📋 Pré-requisitos

  • Python 3.10 ou superior
  • UV - Gerenciador de pacotes Python
  • Chave da API OpenRouter - Para capacidades de IA
  • Token de Acesso Pessoal do GitHub (opcional, mas recomendado para limites de taxa mais altos)

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

Passo 1: Clonar e Configurar Ambiente

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

# Criar ambiente virtual
uv venv
source .venv/bin/activate  # No Windows: .venv\Scripts\activate

Passo 2: Instalar Dependências

# Instalar dependências usando UV
uv sync

Passo 3: Configurar Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Chave da API OpenRouter (obrigatório)
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# Token de Acesso Pessoal do GitHub (opcional mas recomendado)
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

Nota: O token do GitHub é opcional. Sem ele, o agente usará acesso não autenticado com limites de taxa limitados (60 requisições por hora vs 5000 com token).

Passo 4: Executar o Servidor A2A

# Ativar ambiente virtual
source .venv/bin/activate

# Executar o servidor
uv run .

O servidor iniciará em http://localhost:10007 por padrão.

🧪 Teste do Cliente

Opção 1: Usando Cliente A2A Movie Agent

Você pode testar o agente GitHub usando o cliente A2A Movie Agent:

# Clonar o cliente A2A Movie Agent
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Instalar dependências
bun install

# Conectar ao seu agente GitHub
bun cli http://localhost:10007

Isso iniciará um CLI interativo que se conecta ao seu servidor de agente GitHub.

Opção 2: Usando Requisições HTTP Diretas

Você também pode testar usando curl ou qualquer cliente HTTP:

# Exemplo: Teste com uma consulta simples
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": "Mostrar commits recentes para o repositório 'facebook/react'"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 Exemplos de Consultas

O Agente GitHub pode lidar com consultas como:

  • Commits Recentes: "Mostrar commits recentes para o repositório 'facebook/react'"
  • Pesquisa de Repositórios: "Pesquisar repositórios Python populares com atividade recente"
  • Atividade do Projeto: "Quais são as últimas atualizações em repositórios de aprendizado de máquina?"

🔑 Configuração do Token GitHub

Para criar um Token de Acesso Pessoal do GitHub para melhores limites de taxa:

  1. Vá para Configurações do GitHub > Tokens
  2. Clique em "Gerar novo token (clássico)"
  3. Selecione os seguintes escopos:
    • repo - Acesso a repositórios
    • user - Acesso a informações do usuário
  4. Copie o token e adicione-o ao seu arquivo .env

🛠️ Opções de Configuração

Configuração do Servidor

Você pode personalizar o servidor usando opções de linha de comando:

# Host e porta personalizados
uv run . --host=0.0.0.0 --port=10007

Variáveis de Ambiente

  • OPENROUTER_API_KEY: Sua chave da API OpenRouter (obrigatório)
  • GITHUB_TOKEN: Token de Acesso Pessoal do GitHub (opcional)

📖 Documentação da API

Ferramentas Disponíveis

  1. get_user_repositories

    • Obter repositórios do usuário com atualizações recentes
    • Parâmetros: username (opcional), days (padrão: 30), limit (padrão: 10)

  2. get_recent_commits

    • Obter commits recentes para um repositório
    • Parâmetros: repo_name (obrigatório), days (padrão: 7), limit (padrão: 10)

  3. search_repositories

    • Pesquisar repositórios com atividade recente
    • Parâmetros: query (obrigatório), sort (padrão: 'updated'), limit (padrão: 10)

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🔗 Projetos Relacionados

  • A2A SDK - A implementação subjacente do protocolo A2A
  • A2A Movie Agent - Um agente de informações de filmes construído com protocolo A2A