A2A Java Sample

कोड क्लोन करें

git clone https://github.com/google-a2a/a2a-samples
cd a2a-samples/samples/java

यह प्रोजेक्ट Agent2Agent (A2A) प्रोटोकॉल का एक Java कार्यान्वयन उदाहरण है, जो पूर्ण क्लाइंट और सर्वर SDK के साथ-साथ एक AI-संचालित अनुवाद सेवा प्रदर्शन एप्लिकेशन प्रदान करता है।

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

यह प्रोजेक्ट Maven मल्टी-मॉड्यूल आर्किटेक्चर का उपयोग करता है, जिसमें निम्नलिखित तीन मुख्य मॉड्यूल हैं:

samples/java/
├── model/          # A2A प्रोटोकॉल डेटा मॉडल
├── server/         # A2A सर्वर SDK और अनुवाद सेवा
├── client/         # A2A क्लाइंट SDK और उदाहरण कोड
└── pom.xml         # पैरेंट Maven कॉन्फ़िगरेशन फ़ाइल

मॉड्यूल विवरण

🎯 मॉडल मॉड्यूल (model/)

A2A प्रोटोकॉल के लिए मुख्य डेटा मॉडल, JSON-RPC 2.0 और A2A प्रोटोकॉल के लिए पूर्ण डेटा संरचनाएं प्रदान करते हैं:

• संदेश मॉडल: Message, Part, TextPart, Artifact
• कार्य मॉडल: Task, TaskStatus, TaskState
• एजेंट मॉडल: AgentCard, AgentCapabilities, AgentSkill
• JSON-RPC मॉडल: JSONRPCRequest, JSONRPCResponse, JSONRPCError
• इवेंट मॉडल: TaskStatusUpdateEvent, TaskArtifactUpdateEvent

🚀 सर्वर मॉड्यूल (server/)

Spring Boot-आधारित A2A सर्वर SDK, Spring AI फ्रेमवर्क के साथ एकीकृत:

• मुख्य घटक:

  • A2AServer: एजेंट व्यवहार का प्रबंधन करने वाला मुख्य सर्वर क्लास
  • A2AController: A2A प्रोटोकॉल एंडपॉइंट्स को लागू करने वाला REST कंट्रोलर
  • TaskHandler: कार्य प्रसंस्करण इंटरफेस
  • A2AServerConfiguration: AI अनुवाद बॉट कॉन्फ़िगरेशन

• मुख्य सुविधाएं:

  • पूर्ण JSON-RPC 2.0 समर्थन
  • एजेंट कार्ड प्रकाशन (/.well-known/agent-card)
  • कार्य प्रबंधन (भेजना, क्वेरी, रद्द करना)
  • स्ट्रीमिंग प्रतिक्रिया समर्थन (Server-Sent Events)
  • OpenAI और अन्य मॉडल का समर्थन करने वाला Spring AI एकीकरण

📱 क्लाइंट मॉड्यूल (client/)

अनुवाद क्लाइंट उदाहरणों के साथ शुद्ध Java A2A क्लाइंट SDK:

• मुख्य घटक:

  • A2AClient: सभी A2A ऑपरेशन को संभालने वाला मुख्य क्लाइंट क्लास
  • StreamingEventListener: स्ट्रीमिंग इवेंट लिस्नर इंटरफेस
  • A2AClientException: A2A-विशिष्ट अपवाद हैंडलिंग
  • A2AClientExample: पूर्ण अनुवाद क्लाइंट उदाहरण

• मुख्य सुविधाएं:

  • JSON-RPC 2.0 क्लाइंट कार्यान्वयन
  • एजेंट खोज और क्षमता क्वेरी
  • सिंक्रोनस/असिंक्रोनस कार्य ऑपरेशन
  • स्ट्रीमिंग प्रतिक्रिया हैंडलिंग
  • कनेक्शन पूलिंग और त्रुटि रिकवरी

मुख्य कार्यक्षमता कार्यान्वयन

🤖 AI अनुवाद सेवा

प्रोजेक्ट बहु-भाषा अनुवाद का समर्थन करने वाला एक बुद्धिमान अनुवाद एजेंट लागू करता है:

अनुवाद तर्क:

• चीनी → अंग्रेजी
• अंग्रेजी → चीनी
• अन्य भाषाएं → अंग्रेजी

तकनीकी सुविधाएं:

• Spring AI ChatClient पर आधारित
• OpenAI, Azure OpenAI, और अन्य मॉडल का समर्थन
• संदर्भ-जागरूक प्राकृतिक भाषा अनुवाद
• वास्तविक समय स्ट्रीमिंग प्रतिक्रियाएं

🔄 A2A प्रोटोकॉल कार्यान्वयन

A2A प्रोटोकॉल विनिर्देशों का पूर्ण कार्यान्वयन:

मुख्य ऑपरेशन:

• tasks/send: कार्य संदेश भेजना
• tasks/get: कार्य स्थिति क्वेरी
• tasks/cancel: कार्य निष्पादन रद्द करना

प्रोटोकॉल सुविधाएं:

• JSON-RPC 2.0 संचार
• एजेंट क्षमता खोज
• कार्य स्थिति ट्रैकिंग
• स्ट्रीमिंग इवेंट पुश
• मानकीकृत त्रुटि कोड

📡 संचार तंत्र

सिंक्रोनस संचार:

• HTTP POST /a2a - मानक JSON-RPC अनुरोध
• HTTP GET /.well-known/agent-card - एजेंट जानकारी पुनर्प्राप्ति

स्ट्रीमिंग संचार:

• HTTP POST /a2a/stream - Server-Sent Events
• वास्तविक समय कार्य स्थिति अपडेट
• स्वचालित पुनः कनेक्शन और त्रुटि रिकवरी

कैसे चलाएं

आवश्यकताएं

• Java: 17 या उच्चतर

चरण 1: प्रोजेक्ट संकलित करें

प्रोजेक्ट रूट डायरेक्टरी में संकलन निष्पादित करें:

cd samples/java
./mvnw clean install -DskipTests

चरण 2: पर्यावरण चर कॉन्फ़िगर करें

AI मॉडल-संबंधित पर्यावरण चर सेट करें (अनुवाद कार्यक्षमता के लिए आवश्यक):

# OpenAI कॉन्फ़िगरेशन
export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_BASE_URL="https://api.openai.com"
export OPENAI_CHAT_MODEL="gpt-4o"

# या GCP OpenAI कॉन्फ़िगरेशन
export OPENAI_API_KEY="your-gcp-api-key"
export OPENAI_BASE_URL="https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi"
export OPENAI_CHAT_MODEL="gemini-2.5-pro-preview-05-06"

OpenRouter कॉन्फ़िगरेशन

export OPENAI_API_KEY="sk-or-v1-"
export OPENAI_BASE_URL="https://openrouter.ai/api"
export OPENAI_CHAT_MODEL="openai/gpt-4o-2024-11-20"

OPENAI_BASE_URL पर ध्यान दें, URL में /v1 नहीं है।

चरण 3: अनुवाद सर्वर शुरू करें

A2A अनुवाद सर्वर शुरू करें:

cd server
../mvnw spring-boot:run

सर्वर http://localhost:8080 पर शुरू होगा, निम्नलिखित एंडपॉइंट्स प्रदान करेगा:

• http://localhost:8080/.well-known/agent-card - एजेंट जानकारी
• http://localhost:8080/a2a - A2A प्रोटोकॉल एंडपॉइंट
• http://localhost:8080/a2a/stream - स्ट्रीमिंग एंडपॉइंट

एजेंट कार्ड सत्यापित करें:

• A2A प्रोटोकॉल वैलिडेटर
• गाइड: अपने एजेंट कार्ड को कैसे सत्यापित करें

चरण 4: अनुवाद क्लाइंट चलाएं

एक नई टर्मिनल विंडो में, क्लाइंट उदाहरण चलाएं:

cd client
../mvnw exec:java -Dexec.mainClass="com.google.a2a.client.A2AClientExample"

अनुक्रम आरेख

निम्नलिखित अनुक्रम आरेख A2A Java नमूना एप्लिकेशन के पूर्ण इंटरैक्शन प्रवाह को दर्शाता है, A2AClientExample.java पर आधारित:

sequenceDiagram
    participant Example as A2AClientExample
    participant Client as A2AClient
    participant Server as A2A Server<br/>(localhost:8080)
    
    Note over Example,Server: A2A Java Sample Sequence Diagram
    
    %% 1. Initialize Client
    Example->>Client: new A2AClient("http://localhost:8080")
    activate Client
    
    %% 2. Get Agent Card
    Example->>Client: getAgentCard()
    Client->>Server: GET /.well-known/agent-card
    Server-->>Client: AgentCard (name, description, version, skills)
    Client-->>Example: AgentCard
    Note over Example: Print agent information
    
    %% 3. French to Chinese Translation
    Example->>Client: sendTask(frenchToChineseParams)
    Note right of Example: TextPart: "Bonjour le monde!<br/>Comment allez-vous?"
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status, history)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Print translation result
    
    %% 4. Chinese to English Translation
    Example->>Client: sendTask(chineseParams)
    Note right of Example: TextPart: "你好，世界！<br/>欢迎使用AI翻译机器人。"
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status, history)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Print translation result
    
    %% 5. Streaming Translation
    Example->>Client: sendTaskStreaming(frenchParams, StreamingEventListener)
    Note right of Example: TextPart: "Bonjour le monde!<br/>Comment allez-vous?"
    Client->>Server: POST /a2a/stream<br/>Server-Sent Events
    activate Server
    
    loop Streaming Response
        Server-->>Client: SSE Event (translation progress)
        Client-->>Example: onEvent(event)
        Note over Example: Print real-time translation events
    end
    
    Server-->>Client: SSE Complete
    deactivate Server
    Client-->>Example: onComplete()
    Note over Example: Streaming translation completed
    
    %% 6. Query Task Status
    Example->>Client: getTask(queryParams)
    Note right of Example: Query French translation task status
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/get
    Server-->>Client: Task (updated status)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Print task status
    
    %% 7. Send Task to be Canceled
    Example->>Client: sendTask(cancelParams)
    Note right of Example: TextPart: "Diese Übersetzung<br/>wird abgebrochen." (German)
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status)
    Client-->>Example: JSONRPCResponse<Task>
    
    %% 8. Cancel Task
    Example->>Client: cancelTask(cancelTaskParams)
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/cancel
    Server-->>Client: Task (canceled status)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Print cancellation result
    
    deactivate Client
    Note over Example,Server: Example program execution completed

मुख्य इंटरैक्शन पैटर्न

अनुक्रम आरेख निम्नलिखित मुख्य इंटरैक्शन पैटर्न प्रदर्शित करता है:

1. क्लाइंट प्रारंभीकरण: स्थानीय सर्वर से जुड़े A2AClient इंस्टेंस का निर्माण
2. एजेंट खोज: /.well-known/agent-card एंडपॉइंट के माध्यम से एजेंट जानकारी प्राप्त करना
3. बहु-भाषा अनुवाद उदाहरण:
   • फ्रेंच → चीनी अनुवाद
   • चीनी → अंग्रेजी अनुवाद
   • जर्मन → अंग्रेजी स्ट्रीमिंग अनुवाद
4. कार्य प्रबंधन:
   • कार्य स्थिति क्वेरी
   • कार्य निष्पादन रद्द करना

संचार तंत्र

• सिंक्रोनस अनुवाद: JSON-RPC अनुरोधों के साथ POST /a2a एंडपॉइंट का उपयोग
• स्ट्रीमिंग अनुवाद: Server-Sent Events (SSE) के साथ POST /a2a/stream एंडपॉइंट का उपयोग
• स्थिति क्वेरी: कार्य निष्पादन स्थिति जांचने के लिए tasks/get विधि का उपयोग
• कार्य रद्दीकरण: चल रहे कार्यों को रद्द करने के लिए tasks/cancel विधि का उपयोग

API उपयोग उदाहरण

एजेंट जानकारी प्राप्त करें

curl -X GET http://localhost:8080/.well-known/agent-card \
  -H "Accept: application/json"

अनुवाद कार्य भेजें

curl -X POST http://localhost:8080/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "tasks/send",
    "params": {
      "id": "translation-task-1",
      "message": {
        "messageId": "msg-1",
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello, world!"
          }
        ]
      }
    }
  }'

स्ट्रीमिंग अनुवाद

curl -X POST http://localhost:8080/a2a/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "stream-request-1",
    "method": "tasks/send",
    "params": {
      "id": "streaming-translation-task",
      "message": {
        "messageId": "stream-msg-1",
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello world!"
          }
        ]
      }
    }
  }'