A2A मल्टी-एजेंट उदाहरण: संख्या अनुमान गेम

परियोजना अवलोकन

यह Agent2Agent (A2A) protocol आधारित संख्या अनुमान गेम का उदाहरण है, जो दिखाता है कि तीन हल्के A2A एजेंट कैसे मिलकर एक क्लासिक संख्या अनुमान गेम पूरा करते हैं। यह परियोजना A2A protocol और Python SDK के लिए एक व्यावहारिक परिचयात्मक उदाहरण के रूप में कार्य करती है, जिसमें निम्नलिखित विशेषताएं हैं:

• LLM निर्भरता नहीं: API keys या बड़े भाषा मॉडल की आवश्यकता नहीं
• स्थानीय निष्पादन: तीनों एजेंट दूरस्थ सर्वर के बिना स्थानीय रूप से चलते हैं
• आसान स्थापना: न्यूनतम बाहरी निर्भरताएं
• मुख्य अवधारणा प्रदर्शन: A2A protocol की मुख्य कार्यक्षमता प्रदर्शित करता है

एजेंट भूमिका विवरण

विस्तृत कोड फ़ाइल विश्लेषण

1. कॉन्फ़िगरेशन फ़ाइल (config.py)

AGENT_ALICE_PORT = 8001
AGENT_BOB_PORT = 8002
AGENT_CAROL_PORT = 8003

कार्य: पोर्ट संघर्ष से बचने के लिए पोर्ट कॉन्फ़िगरेशन को केंद्रीय रूप से प्रबंधित करता है। सभी एजेंट इस मॉड्यूल से कॉन्फ़िगरेशन आयात करते हैं, पोर्ट आवंटन में स्थिरता सुनिश्चित करते हैं।

2. AgentAlice (agent_Alice.py)

मुख्य कार्य:

• स्टार्टअप पर 1-100 से यादृच्छिक रूप से गुप्त संख्या चुनता है
• अनुमान मूल्यांकन को संभालने के लिए NumberGuessExecutor क्लास लागू करता है
• A2A SDK के AgentExecutor इंटरफेस के माध्यम से संदेशों को प्रोसेस करता है

मुख्य विधियां:

• execute(): नए प्राप्त संदेशों को प्रोसेस करता है, अनुमानों का मूल्यांकन करने के लिए process_guess() को कॉल करता है
• cancel(): निर्दिष्ट कार्यों को अस्वीकार करता है

प्रतिक्रिया प्रकार:

• "Go higher" - अनुमान गुप्त संख्या से कम है
• "Go lower" - अनुमान गुप्त संख्या से अधिक है
• "correct! attempts: <n>" - अनुमान सही है, प्रयास संख्या दिखाता है

3. AgentBob (agent_Bob.py)

मुख्य कार्य:

• CLI फ्रंटएंड के रूप में कार्य करता है, खिलाड़ियों को अन्य एजेंटों से जोड़ता है
• गेम स्थिति और इतिहास रिकॉर्ड प्रबंधित करता है
• इतिहास रिकॉर्ड को सॉर्ट करने के लिए Carol के साथ बातचीत करता है

मुख्य विधियां:

• _handle_guess(): अनुमानों को Alice को फॉरवर्ड करता है और फीडबैक वापस करता है
• _negotiate_sorted_history(): इतिहास सॉर्ट होने तक Carol के साथ बातचीत करता है
• _visualise_history(): फॉर्मेटेड इतिहास विज़ुअलाइज़ेशन का अनुरोध करता है और प्रिंट करता है
• play_game(): इंटरैक्टिव CLI लूप चलाता है

बातचीत तर्क:

• Carol को प्रारंभिक शफल अनुरोध भेजता है
• जांचता है कि वापस की गई सूची सॉर्ट है या नहीं
• यदि सॉर्ट नहीं है, तो बातचीत जारी रखने के लिए "Try again" भेजता है
• यदि सॉर्ट है, तो बातचीत पूरी करने के लिए "Well done!" भेजता है

4. AgentCarol (agent_Carol.py)

मुख्य कार्य:

• अनुमान इतिहास रिकॉर्ड को विज़ुअलाइज़ करता है
• इतिहास रिकॉर्ड सूचियों को यादृच्छिक रूप से फेरबदल करता है
• मल्टी-टर्न संवाद और कार्य संदर्भ का समर्थन करता है

मुख्य विधियां:

• _handle_initial(): नई बातचीत में प्रारंभिक संदेशों को संभालता है
• _handle_followup(): मौजूदा कार्यों का संदर्भ देने वाले फॉलो-अप संदेशों को संभालता है
• execute(): संदेश प्रकार के आधार पर उपयुक्त हैंडलर को डिस्पैच करता है

कौशल परिभाषाएं:

• history_visualiser: फॉर्मेटेड अनुमान इतिहास सारांश उत्पन्न करता है
• history_shuffler: इतिहास रिकॉर्ड प्रविष्टि क्रम को यादृच्छिक रूप से फेरबदल करता है

5. उपयोगिता मॉड्यूल (utils/)

game_logic.py

मुख्य कार्य:

• process_guess(): व्यक्तिगत अनुमानों का मूल्यांकन करता है और फीडबैक वापस करता है
• build_visualisation(): मानव-पठनीय इतिहास रिकॉर्ड रेंडरिंग बनाता है
• is_sorted_history(): जांचता है कि इतिहास अनुमान मानों द्वारा सॉर्ट है या नहीं
• process_history_payload(): इतिहास-संबंधित अनुरोधों को प्रोसेस करता है

protocol_wrappers.py

मुख्य कार्य:

• send_text(): लक्ष्य एजेंटों को टेक्स्ट संदेश समकालिक रूप से भेजता है
• send_followup(): फॉलो-अप संदेश भेजता है, बातचीत संदर्भ बनाए रखता है
• cancel_task(): दूरस्थ एजेंटों पर कार्य रद्द करता है
• extract_text(): Task या Message ऑब्जेक्ट से सादा टेक्स्ट निकालता है

server.py

मुख्य कार्य:

• run_agent_blocking(): ब्लॉकिंग एजेंट सर्वर शुरू करता है
• HTTP सर्वर के रूप में Starlette + Uvicorn का उपयोग करता है

सिस्टम आर्किटेक्चर फ्लोचार्ट

graph TD
    A[Player] --> B[AgentBob CLI]
    B --> C[AgentAlice Evaluator]
    B --> D[AgentCarol Visualizer]
    
    C --> E[Secret Number 1-100]
    C --> F[Evaluate Guess]
    F --> G{Guess Result}
    G -->|Too Low| H[Return Go higher]
    G -->|Too High| I[Return Go lower]
    G -->|Correct| J[Return correct! attempts: N]
    
    B --> K[Game History]
    K --> L[Send to Carol for Visualization]
    L --> M[Generate Formatted Table]
    M --> N[Display to Player]
    
    B --> O[Negotiate Sorting]
    O --> P[Send Shuffle Request]
    P --> Q[Carol Random Shuffle]
    Q --> R{Check if Sorted}
    R -->|Not Sorted| S[Send Try again]
    R -->|Sorted| T[Send Well done!]
    S --> Q
    T --> U[Update History]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#ffebee
    style F fill:#e8f5e8
    style K fill:#f3e5f5
    style O fill:#f3e5f5

संदेश प्रवाह आरेख

sequenceDiagram
    participant Player as Player
    participant Bob as AgentBob
    participant Alice as AgentAlice
    participant Carol as AgentCarol
    
    Note over Player,Carol: Game Start
    Player->>Bob: Input guess number
    Bob->>Alice: Send guess
    Alice->>Bob: Return evaluation result
    Bob->>Player: Display hint
    
    Note over Player,Carol: Record History
    Bob->>Bob: Add to game history
    
    Note over Player,Carol: Visualize History
    Bob->>Carol: Send history records
    Carol->>Bob: Return formatted table
    Bob->>Player: Display history visualization
    
    Note over Player,Carol: Negotiate Sorting
    Bob->>Carol: Send shuffle request
    Carol->>Bob: Return shuffled list
    Bob->>Bob: Check if sorted
    
    alt Not Sorted
        Bob->>Carol: Send "Try again"
        Carol->>Bob: Shuffle list again
        Bob->>Bob: Recheck sorting
    else Sorted
        Bob->>Carol: Send "Well done!"
        Carol->>Bob: Complete task
        Bob->>Bob: Update history
    end
    
    Note over Player,Carol: Continue Game or End
    alt Guess Correct
        Bob->>Player: Display victory message
    else Guess Incorrect
        Player->>Bob: Continue inputting guesses
    end

uv के साथ परियोजना चलाना

1. पर्यावरण सेटअप

सुनिश्चित करें कि uv स्थापित है:

# uv स्थापित करें (यदि पहले से स्थापित नहीं है)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. परियोजना सेटअप

# परियोजना क्लोन करें
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/number_guessing_game

# uv का उपयोग करके वर्चुअल वातावरण बनाएं और निर्भरताएं स्थापित करें
uv venv
source .venv/bin/activate  # Linux/macOS
# या .venv\Scripts\activate  # Windows

# निर्भरताएं स्थापित करें
uv pip install -r requirements.txt

3. गेम चलाना

तीन टर्मिनल विंडो खोलें और प्रत्येक में वर्चुअल वातावरण सक्रिय करें:

# टर्मिनल 1 - Alice (मूल्यांकनकर्ता) शुरू करें
uv run python agent_Alice.py

# टर्मिनल 2 - Carol (विज़ुअलाइज़र) शुरू करें
uv run python agent_Carol.py

# टर्मिनल 3 - Bob (CLI फ्रंटएंड) शुरू करें
uv run python agent_Bob.py

4. गेमप्ले

Bob के टर्मिनल में, गेम आपको 1-100 के बीच संख्याएं दर्ज करने के लिए प्रेरित करेगा। सही अनुमान लगाने तक Alice के फीडबैक के आधार पर अनुमान लगाते रहें।

गेम फ्लो उदाहरण:

Guess the number AgentAlice chose (1-100)!
Your guess: 50
Alice says: Go higher

=== Carol's visualisation (sorted) ===
Guesses so far:
  1.  50 -> Go higher
============================

Your guess: 75
Alice says: Go lower

=== Carol's visualisation (sorted) ===
Guesses so far:
  1.  50 -> Go higher
  2.  75 -> Go lower
============================

Your guess: 62
Alice says: correct! attempts: 3
You won! Exiting…

परियोजना सारांश

तकनीकी विशेषताएं

1. A2A Protocol अभ्यास:

   • अंतर-एजेंट संचार की मुख्य अवधारणाओं का प्रदर्शन
   • संदेश भेजना, कार्य प्रबंधन, और स्थिति ट्रैकिंग लागू करता है
   • मल्टी-टर्न संवाद और कार्य संदर्भ तंत्र दिखाता है

2. मॉड्यूलर डिज़ाइन:

   • जिम्मेदारियों का स्पष्ट विभाजन: Alice मूल्यांकन संभालता है, Bob इंटरैक्शन, Carol विज़ुअलाइज़ेशन
   • आसान विस्तार और रखरखाव के लिए पुन: उपयोग योग्य उपयोगिता मॉड्यूल

3. त्रुटि हैंडलिंग:

   • इनपुट सत्यापन और त्रुटि प्रॉम्प्ट
   • नेटवर्क संचार अपवाद हैंडलिंग
   • कार्य रद्दीकरण और टाइमआउट तंत्र

शिक्षण मूल्य

1. A2A परिचय: A2A protocol को समझने के लिए सरल, समझने योग्य उदाहरण प्रदान करता है
2. एजेंट सहयोग: दिखाता है कि कैसे कई एजेंट जटिल कार्यों को पूरा करने के लिए सहयोग करते हैं
3. असिंक्रोनस प्रोग्रामिंग: असिंक्रोनस संदेश प्रसंस्करण और स्थिति प्रबंधन का प्रदर्शन
4. Protocol डिज़ाइन: स्पष्ट एजेंट इंटरफेस और कौशल परिभाषाओं को डिज़ाइन करने का तरीका दिखाता है

विस्तार संभावनाएं

1. अधिक एजेंट जोड़ें: सांख्यिकीय विश्लेषक, रणनीति सलाहकार आदि जैसी नई एजेंट भूमिकाएं पेश करें
2. गेम लॉजिक बढ़ाएं: समय सीमा, स्कोरिंग सिस्टम आदि जैसे अधिक जटिल गेम नियम जोड़ें
3. नेटवर्क तैनाती: एजेंटों को विभिन्न मशीनों पर तैनात करें, वितरित एजेंट सिस्टम का प्रदर्शन
4. LLM एकीकरण: बुद्धिमान संकेत और रणनीति सुझाव प्रदान करने वाले AI एजेंट जोड़ें

सुरक्षा विचार

जैसा कि परियोजना दस्तावेज़ीकरण में उल्लेख किया गया है, उत्पादन वातावरण में:

• बाहरी एजेंटों को अविश्वसनीय संस्थाओं के रूप में माना जाना चाहिए
• सभी प्राप्त डेटा को सत्यापन और सैनिटाइज़ेशन की आवश्यकता है
• इनपुट सत्यापन और क्रेडेंशियल सुरक्षा जैसे उपयुक्त सुरक्षा उपाय लागू करें

यह उदाहरण डेवलपर्स को A2A protocol सीखने और प्रयोग करने के लिए एक सुरक्षित, नियंत्रित वातावरण प्रदान करता है जबकि वितरित एजेंट सिस्टम निर्माण के लिए बुनियादी पैटर्न का प्रदर्शन करता है।

संबंधित केस स्टडी

🚀 शुरुआती उदाहरण

• A2A Samples: Hello World Agent

  • A2A Python SDK का उपयोग करके Hello World एजेंट बनाने की पूर्ण गाइड
  • विस्तृत वातावरण सेटअप और परीक्षण निर्देश शामिल

• A2A SDK Currency Agent Tutorial

  • मुद्रा रूपांतरण एजेंट निर्माण की चरणबद्ध गाइड
  • OpenRouter AI सेवाओं को एकीकृत करता है

🐍 Python कार्यान्वयन केस

• A2A Python Example: GitHub Agent

  • a2a-python का उपयोग करके GitHub एजेंट बनाना और कनेक्ट करना
  • कोड रिपॉजिटरी जानकारी क्वेरी कार्यक्षमता लागू करता है

• A2A Example: Travel Planning Assistant

  • OpenRouter को एकीकृत करने वाला यात्रा योजना एजेंट कार्यान्वयन
  • Python a2a-sdk का उपयोग करके निर्मित

• A2A SDK Python व्यावहारिक गाइड

  • गहन A2A SDK Python विकास ट्यूटोरियल
  • वर्कफ़्लो आरेख और व्यावहारिक कोड उदाहरण शामिल

🟨 JavaScript/TypeScript केस

• A2A JS Example: Movie Agent

  • TMDB API और OpenRouter AI के साथ एकीकरण
  • Express.js सर्वर कार्यान्वयन

• A2A JavaScript SDK पूर्ण ट्यूटोरियल

  • TypeScript टाइप-सेफ कार्यान्वयन
  • Express.js सर्वर SDK और स्ट्रीमिंग प्रसंस्करण

☕ Java कार्यान्वयन केस

• A2A Java Example
  • Maven मल्टी-मॉड्यूल आर्किटेक्चर
  • Spring Boot सर्वर SDK कार्यान्वयन
  • AI अनुवाद सेवा उदाहरण

🔧 फ्रेमवर्क एकीकरण केस

• ADK के साथ A2A एजेंट लागू करना: पूर्ण विकास गाइड

  • Google ADK फ्रेमवर्क का उपयोग करके A2A बुद्धिमान एजेंट सिस्टम लागू करना
  • पूर्ण विकास वर्कफ़्लो को कवर करता है

• A2A ADK व्यय प्रतिपूर्ति एजेंट

  • Google ADK और A2A protocol आधारित बुद्धिमान व्यय प्रतिपूर्ति एजेंट
  • स्वचालित रूप से फॉर्म पूरक जानकारी उत्पन्न करता है

• A2A CrewAI विश्लेषण चार्ट एजेंट

  • CrewAI फ्रेमवर्क का उपयोग करके डेटा विश्लेषण एजेंट निर्माण
  • चार्ट जेनरेशन और डेटा विज़ुअलाइज़ेशन कार्यक्षमता को एकीकृत करता है

🛠️ विकास उपकरण

• A2A Inspector: Agent2Agent संचार डिबगिंग व्याख्या

  • शक्तिशाली वेब-आधारित डिबगिंग उपकरण
  • एजेंट कार्ड और JSON-RPC संचार का रीयल-टाइम निरीक्षण

• A2A .NET SDK व्यापक दस्तावेज़ीकरण

  • Google A2A Protocol v0.2.1 लागू करने वाली .NET लाइब्रेरी
  • ASP.NET Core अनुप्रयोगों के लिए उपयुक्त

📚 Protocol समझ और सर्वोत्तम प्रथाएं

• A2A Protocol समझना: व्यापक गाइड

  • A2A protocol को समझने के लिए व्यापक गाइड
  • मुख्य अवधारणाएं और AI एजेंट अंतरसंचालनीयता लाभ

• A2A Protocol विनिर्देश (Python)

  • Python कार्यान्वयन विनिर्देशों की व्यापक गाइड
  • एजेंट कार्ड, मैसेजिंग, कार्य प्रबंधन सहित मुख्य कार्यक्षमता को कवर करता है

• 2025 A2A Protocol पूर्ण गाइड

  • A2A protocol का व्यापक परिचय और व्यावहारिक गाइड
  • बुनियादी अवधारणाओं से उन्नत अनुप्रयोगों तक पूर्ण कवरेज

🌟 पारिस्थितिकी तंत्र संसाधन

• Awesome A2A निर्देशिका

  • Google A2A protocol के पूर्ण पारिस्थितिकी तंत्र का अन्वेषण
  • आधिकारिक दस्तावेज़ीकरण, समुदायिक कार्यान्वयन, नमूना परियोजनाएं, और एकीकरण गाइड शामिल

• A2A कार्यान्वयन संग्रह

  • A2A protocol के विभिन्न ओपन-सोर्स कार्यान्वयनों का अन्वेषण
  • Java, TypeScript, Go, Rust, Python, और अधिक शामिल

इन केस स्टडी के माध्यम से, आप सरल Hello World उदाहरणों से जटिल मल्टी-एजेंट सिस्टम तक विभिन्न परिदृश्यों में A2A protocol अनुप्रयोगों के बारे में गहरी अंतर्दृष्टि प्राप्त कर सकते हैं, जो आपकी A2A विकास यात्रा के लिए समृद्ध संदर्भ संसाधन प्रदान करते हैं।