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

यह Google Agent Development Kit (ADK) पर आधारित एक बुद्धिमान व्यय प्रतिपूर्ति एजेंट है, जो Agent2Agent (A2A) सर्वर के रूप में चलता है। इस एजेंट की मुख्य विशेषता बुद्धिमान फॉर्म जेनरेशन है: जब उपयोगकर्ता के प्रतिपूर्ति अनुरोध में आवश्यक जानकारी की कमी होती है, तो एजेंट स्वचालित रूप से उपयोगकर्ता के भरने के लिए एक फॉर्म जेनरेट करता है, जिससे प्रसंस्करण से पहले पूर्ण प्रतिपूर्ति जानकारी एकत्र करना सुनिश्चित होता है।

स्रोत कोड

A2A ADK Sample

🎯 प्रोजेक्ट विशेषताएं

• बुद्धिमान फॉर्म इंटरैक्शन: गुम जानकारी को स्वचालित रूप से पहचानता है और डायनामिक फॉर्म जेनरेट करता है
• A2A प्रोटोकॉल समर्थन: मानकीकृत इंटर-एजेंट संचार प्रोटोकॉल
• स्ट्रीमिंग प्रसंस्करण: रियल-टाइम प्रतिक्रियाओं और स्थिति अपडेट का समर्थन करता है
• Google ADK एकीकरण: Google के नवीनतम एजेंट डेवलपमेंट किट पर आधारित

📋 सिस्टम आवश्यकताएं

• Python 3.12 या उच्चतर
• UV पैकेज प्रबंधन उपकरण
• Google API Key (Gemini मॉडल एक्सेस)

🚀 त्वरित शुरुआत

1. Google API Key प्राप्त करें

1. Google AI Studio पर जाएं
2. अपने Google खाते से लॉग इन करें
3. "Get API key" पर क्लिक करें
4. नई API key बनाएं या मौजूदा का उपयोग करें
5. बाद में उपयोग के लिए API key कॉपी करें

2. पर्यावरण कॉन्फ़िगरेशन

# प्रोजेक्ट को स्थानीय रूप से क्लोन करें (यदि आवश्यक हो)
git clone https://github.com/sing1ee/a2a-adk-expense-reimbursement.git
cd a2a-adk-expense-reimbursement

# पर्यावरण चर फ़ाइल बनाएं
echo "GOOGLE_API_KEY=your_api_key_here" > .env

# your_api_key_here को अपनी वास्तविक API key से बदलें

3. निर्भरताएं स्थापित करें और चलाएं

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

# uv का उपयोग करके प्रोजेक्ट चलाएं
uv run .

सर्वर http://localhost:10002 पर शुरू होगा।

4. CLI क्लाइंट के साथ परीक्षण

एक नई टर्मिनल विंडो खोलें:

git clone https://github.com/a2aproject/a2a-samples.git
# CLI क्लाइंट डायरेक्टरी में नेविगेट करें (samples/python/hosts/cli में मान लेते हैं)
cd a2a-samples/samples/python/hosts/cli

# प्रतिपूर्ति एजेंट से कनेक्ट करें
uv run . --agent http://localhost:10002

5. परीक्षण इंटरैक्शन उदाहरण

CLI क्लाइंट में निम्नलिखित परीक्षण कमांड दर्ज करें:

# उदाहरण 1: गुम जानकारी के साथ अनुरोध (फॉर्म ट्रिगर होगा)
मुझे दोपहर के भोजन के लिए $20 की प्रतिपूर्ति की आवश्यकता है

# उदाहरण 2: पूर्ण जानकारी के साथ अनुरोध
मुझे 15 जनवरी, 2024 को क्लाइंट दोपहर के भोजन के लिए $50 की प्रतिपूर्ति की आवश्यकता है

# उदाहरण 3: आंशिक जानकारी के साथ अनुरोध
कृपया कल के परिवहन खर्च $25 की प्रतिपूर्ति में मेरी सहायता करें

🏗️ प्रोजेक्ट आर्किटेक्चर

मुख्य फ़ाइल संरचना

a2a-adk-expense-reimbursement/
├── __main__.py          # सर्वर स्टार्टअप एंट्री पॉइंट
├── agent.py             # मुख्य एजेंट लॉजिक
├── agent_executor.py    # A2A अनुरोध निष्पादक
├── pyproject.toml       # प्रोजेक्ट कॉन्फ़िगरेशन और निर्भरताएं
└── README.md           # प्रोजेक्ट दस्तावेज़

मुख्य घटक विवरण

1. __main__.py - सर्वर एंट्री

• A2A सर्वर और एजेंट जानकारी कॉन्फ़िगर करें
• एजेंट कौशल और क्षमता विवरण सेट करें
• अनुरोधों को सुनने के लिए HTTP सर्वर शुरू करें

2. agent.py - मुख्य एजेंट लॉजिक

तीन मुख्य टूल फ़ंक्शन शामिल हैं:

• create_request_form(): प्रतिपूर्ति फॉर्म टेम्प्लेट बनाएं
• return_form(): फॉर्म को A2A प्रोटोकॉल प्रारूप में लपेटें और वापस करें
• reimburse(): वास्तविक प्रतिपूर्ति अनुमोदन ऑपरेशन निष्पादित करें

3. agent_executor.py - अनुरोध निष्पादक

• A2A प्रोटोकॉल अनुरोधों और प्रतिक्रियाओं को संभालें
• कार्य स्थितियों का प्रबंधन करें (काम कर रहा है, इनपुट की आवश्यकता है, पूर्ण, आदि)
• एजेंट और A2A सर्वर के बीच संचार का समन्वय करें

🔄 मुख्य वर्कफ़्लो

निम्नलिखित अनुक्रम आरेख प्रतिपूर्ति एजेंट के पूर्ण इंटरैक्शन प्रवाह को दिखाता है:

sequenceDiagram
    participant User as उपयोगकर्ता/CLI क्लाइंट
    participant Server as A2A सर्वर
    participant Agent as प्रतिपूर्ति एजेंट
    participant LLM as Gemini 2.0 Flash

    User->>Server: प्रतिपूर्ति अनुरोध भेजें<br/>"मुझे दोपहर के भोजन के लिए $20 की प्रतिपूर्ति की आवश्यकता है"
    Server->>Agent: उपयोगकर्ता अनुरोध अग्रेषित करें
    Agent->>LLM: अनुरोध सामग्री का विश्लेषण करें
    LLM->>Agent: गुम तारीख और अन्य जानकारी की पहचान करें
    Agent->>Agent: create_request_form() कॉल करें
    Agent->>Agent: return_form() कॉल करें
    Agent->>Server: फॉर्म संरचना वापस करें
    Server->>User: JSON फॉर्म वापस करें<br/>तारीख, राशि, उद्देश्य फ़ील्ड शामिल
    
    User->>User: उपयोगकर्ता फॉर्म भरता है<br/>तारीख, राशि, उद्देश्य
    User->>Server: पूर्ण फॉर्म सबमिट करें
    Server->>Agent: फॉर्म डेटा अग्रेषित करें
    Agent->>LLM: फॉर्म पूर्णता सत्यापित करें
    LLM->>Agent: जानकारी पूर्ण होने की पुष्टि करें
    Agent->>Agent: reimburse(request_id) कॉल करें
    Agent->>Server: अनुमोदन परिणाम वापस करें
    Server->>User: अंतिम परिणाम वापस करें<br/>"प्रतिपूर्ति अनुमोदित"

वर्कफ़्लो विवरण

1. अनुरोध स्वीकृति: उपयोगकर्ता CLI क्लाइंट के माध्यम से प्रतिपूर्ति अनुरोध भेजता है
2. बुद्धिमान विश्लेषण: Gemini मॉडल अनुरोध का विश्लेषण करता है और गुम आवश्यक जानकारी की पहचान करता है
3. फॉर्म जेनरेशन: यदि जानकारी अधूरी है, तो आवश्यक फ़ील्ड के साथ स्वचालित रूप से फॉर्म जेनरेट करें
4. उपयोगकर्ता इंटरैक्शन: उपयोगकर्ता गुम जानकारी को पूरा करने के लिए फॉर्म भरता है
5. जानकारी सत्यापन: फॉर्म डेटा की पूर्णता और वैधता सत्यापित करें
6. प्रतिपूर्ति प्रसंस्करण: प्रतिपूर्ति अनुमोदन निष्पादित करें और परिणाम वापस करें

🛠️ उन्नत कॉन्फ़िगरेशन

पर्यावरण चर

# Google API कॉन्फ़िगरेशन
GOOGLE_API_KEY=your_api_key_here

# Vertex AI का उपयोग करें (वैकल्पिक)
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# सर्वर कॉन्फ़िगरेशन
HOST=localhost
PORT=10002

कस्टम पोर्ट के साथ चलाएं

uv run . --host 0.0.0.0 --port 8080

🧪 विकास और डिबगिंग

विस्तृत लॉगिंग सक्षम करें

एजेंट डिफ़ॉल्ट रूप से INFO स्तर लॉगिंग सक्षम करता है। विस्तृत अनुरोध प्रसंस्करण देखें:

# सर्वर लॉग देखें
uv run . 2>&1 | tee agent.log

फॉर्म संरचना उदाहरण

एजेंट JSON Schema प्रारूप का पालन करने वाले फॉर्म जेनरेट करता है:

{
  "type": "form",
  "form": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date",
        "title": "Date",
        "description": "Date of expense"
      },
      "amount": {
        "type": "string",
        "format": "number", 
        "title": "Amount",
        "description": "Amount of expense"
      },
      "purpose": {
        "type": "string",
        "title": "Purpose",
        "description": "Purpose of expense"
      }
    },
    "required": ["date", "amount", "purpose"]
  }
}

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

महत्वपूर्ण सूचना: यह नमूना कोड केवल Agent2Agent (A2A) प्रोटोकॉल के काम करने के तरीके को दिखाने के लिए प्रदर्शन उद्देश्यों के लिए है। उत्पादन अनुप्रयोगों का निर्माण करते समय, किसी भी बाहरी एजेंट को संभावित रूप से अविश्वसनीय इकाई के रूप में माना जाना चाहिए।

सुरक्षा उपाय

• इनपुट सत्यापन: सभी बाहरी इनपुट को सख्ती से सत्यापित और साफ करें
• डेटा प्रसंस्करण: एजेंट कार्ड, संदेश, कलाकृतियों और अन्य डेटा को सावधानी से संभालें
• क्रेडेंशियल प्रबंधन: उचित क्रेडेंशियल सुरक्षा उपाय लागू करें
• अनुमति नियंत्रण: एजेंट की पहुंच अनुमतियों और ऑपरेशन स्कोप को सीमित करें