A2A Python नमूना: GitHub एजेंट

A2A (Agent2Agent) SDK के साथ बनाया गया एक बुद्धिमान GitHub एजेंट जो प्राकृतिक भाषा का उपयोग करके GitHub रिपॉजिटरी, हाल के अपडेट, कमिट्स और प्रोजेक्ट गतिविधि को क्वेरी कर सकता है।

🏗️ आर्किटेक्चर

यह प्रोजेक्ट एक A2A सर्वर को लागू करता है जो GitHub API एकीकरण के साथ OpenAI-आधारित एजेंट का उपयोग करता है। आर्किटेक्चर निम्नलिखित मुख्य घटकों से मिलकर बना है:

घटक अवलोकन

• 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 टोकन वैकल्पिक है। इसके बिना, एजेंट सीमित दर सीमा (टोकन के साथ 5000 बनाम प्रति घंटे 60 अनुरोध) के साथ अप्रमाणित पहुंच का उपयोग करेगा।

चरण 4: A2A सर्वर चलाएं

# वर्चुअल वातावरण सक्रिय करें
source .venv/bin/activate

# सर्वर चलाएं
uv run .

सर्वर डिफ़ॉल्ट रूप से http://localhost:10007 पर शुरू होगा।

🧪 क्लाइंट परीक्षण

विकल्प 1: A2A Movie Agent क्लाइंट का उपयोग

आप A2A Movie Agent क्लाइंट का उपयोग करके GitHub एजेंट का परीक्षण कर सकते हैं:

# A2A Movie Agent क्लाइंट क्लोन करें
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# निर्भरताएं स्थापित करें
bun install

# अपने GitHub एजेंट से कनेक्ट करें
bun cli http://localhost:10007

यह एक इंटरैक्टिव CLI शुरू करेगा जो आपके GitHub एजेंट सर्वर से कनेक्ट होता है।

विकल्प 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 व्यक्तिगत एक्सेस टोकन बनाने के लिए:

1. GitHub सेटिंग्स > टोकन पर जाएं
2. "नया टोकन जेनरेट करें (क्लासिक)" पर क्लिक करें
3. निम्नलिखित स्कोप का चयन करें:
   • repo - रिपॉजिटरी तक पहुंच
   • user - उपयोगकर्ता जानकारी तक पहुंच
4. टोकन कॉपी करें और इसे अपनी .env फ़ाइल में जोड़ें

🛠️ कॉन्फ़िगरेशन विकल्प

सर्वर कॉन्फ़िगरेशन

आप कमांड-लाइन विकल्पों का उपयोग करके सर्वर को अनुकूलित कर सकते हैं:

# कस्टम होस्ट और पोर्ट
uv run . --host=0.0.0.0 --port=10007

पर्यावरण चर

• OPENROUTER_API_KEY: आपकी OpenRouter API की (आवश्यक)
• GITHUB_TOKEN: GitHub व्यक्तिगत एक्सेस टोकन (वैकल्पिक)

📖 API दस्तावेज़ीकरण

उपलब्ध टूल

1. get_user_repositories

   • हाल के अपडेट के साथ उपयोगकर्ता की रिपॉजिटरी प्राप्त करें
   • पैरामीटर: username (वैकल्पिक), days (डिफ़ॉल्ट: 30), limit (डिफ़ॉल्ट: 10)

2. get_recent_commits

   • रिपॉजिटरी के लिए हाल के कमिट्स प्राप्त करें
   • पैरामीटर: repo_name (आवश्यक), days (डिफ़ॉल्ट: 7), limit (डिफ़ॉल्ट: 10)

3. search_repositories

   • हाल की गतिविधि के साथ रिपॉजिटरी खोजें
   • पैरामीटर: query (आवश्यक), sort (डिफ़ॉल्ट: 'updated'), limit (डिफ़ॉल्ट: 10)

📄 लाइसेंस

यह प्रोजेक्ट MIT लाइसेंस के तहत लाइसेंस प्राप्त है - विवरण के लिए LICENSE फ़ाइल देखें।

🔗 संबंधित प्रोजेक्ट

• A2A SDK - अंतर्निहित A2A प्रोटोकॉल कार्यान्वयन
• A2A Movie Agent - A2A प्रोटोकॉल के साथ निर्मित एक फिल्म जानकारी एजेंट