A2A Protocol

A2A .NET SDK Comprehensive Documentation

deutschEnglishfrançaisहिंदी日本語한국어中文
MILO•
Share
A2A .NET SDK Comprehensive Documentation

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

A2A (Agent2Agent) .NET SDK एक .NET लाइब्रेरी है जो Google के A2A Protocol v0.2.1 को लागू करती है, जिससे .NET अनुप्रयोगों में एजेंट-से-एजेंट संचार संभव होता है। यह SDK ASP.NET Core अनुप्रयोगों के साथ काम करने के लिए डिज़ाइन किया गया है, जिससे आपके एजेंटों में A2A समर्थन जोड़ने का एक सरल तरीका प्रदान होता है।

मुख्य विशेषताएँ

  • प्रोटोकॉल संगतता: A2A Protocol v0.2.1 की अधिकांश विशेषताओं को लागू करता है
  • मल्टी-फ्रेमवर्क समर्थन: .NET 9.0, .NET 8.0, और .NET Standard 2.0 का समर्थन करता है
  • ASP.NET Core एकीकरण: सरल एकीकरण विधियाँ प्रदान करता है
  • कार्य प्रबंधन: मानकीकृत कार्य प्रबंधन और निष्पादन समर्थन
  • स्ट्रीमिंग: रीयल-टाइम स्ट्रीमिंग प्रतिक्रियाओं का समर्थन करता है
  • OpenTelemetry: अंतर्निहित टेलीमेट्री और अवलोकनीयता समर्थन

परियोजना स्थिति

लाइब्रेरी ने प्रोटोकॉल की अधिकांश विशेषताओं को लागू किया है, लेकिन कुछ परिदृश्य अभी भी अपूर्ण हो सकते हैं। सबसे बड़ी अनुपस्थित विशेषता पुश नोटिफिकेशन का उपयोग करके क्लाइंट कॉलबैक है।

2. A2A .NET Core आर्किटेक्चर

2.1 परियोजना संरचना

src/
├── A2A/                    # मुख्य A2A प्रोटोकॉल कार्यान्वयन
│   ├── Client/            # क्लाइंट घटक
│   ├── JsonRpc/           # JSON-RPC कार्यान्वयन
│   ├── Models/            # डेटा मॉडल
│   ├── Server/            # सर्वर-साइड घटक
│   └── openapi.yaml       # API विनिर्देश
└── A2A.AspNetCore/        # ASP.NET Core एकीकरण

2.2 मुख्य घटक

  1. A2A Core Library: मुख्य प्रोटोकॉल कार्यान्वयन शामिल है
  2. A2A.AspNetCore: ASP.NET Core एकीकरण प्रदान करता है
  3. Sample Projects: विभिन्न उपयोग परिदृश्यों को प्रदर्शित करने वाले उदाहरण कोड

3. A2A .NET क्लाइंट कार्यान्वयन

3.1 A2AClient क्लास

A2AClient क्लास एजेंटों के साथ संवाद करने के लिए मुख्य क्लाइंट इंटरफेस है, जो IA2AClient इंटरफेस को लागू करता है।

मुख्य फंक्शन:

public class A2AClient : IA2AClient
{
    // संदेश भेजें
    public Task<A2AResponse> SendMessageAsync(MessageSendParams taskSendParams)
    
    // कार्य प्राप्त करें
    public Task<AgentTask> GetTaskAsync(string taskId)
    
    // कार्य रद्द करें
    public Task<AgentTask> CancelTaskAsync(TaskIdParams taskIdParams)
    
    // स्ट्रीम संदेश भेजना
    public async IAsyncEnumerable<SseItem<A2AEvent>> SendMessageStreamAsync(MessageSendParams taskSendParams)
    
    // कार्य को पुनः सदस्यता दें
    public async IAsyncEnumerable<SseItem<A2AEvent>> ResubscribeToTaskAsync(string taskId)
}

मुख्य विशेषताएँ:

  1. JSON-RPC संचार: सभी संचार JSON-RPC प्रोटोकॉल के माध्यम से किए जाते हैं
  2. स्ट्रीमिंग प्रतिक्रिया: रीयल-टाइम स्ट्रीमिंग के लिए Server-Sent Events (SSE) का समर्थन करता है
  3. सीरियलाइजेशन अनुकूलन: उच्च-प्रदर्शन सीरियलाइजेशन के लिए System.Text.Json स्रोत जनरेटर का उपयोग करता है
  4. त्रुटि प्रबंधन: पूर्ण त्रुटि प्रबंधन और स्थिति प्रबंधन

3.2 JsonRpcContent क्लास

JSON-RPC अनुरोधों के लिए विशेष रूप से HTTP सामग्री क्लास:

public class JsonRpcContent : HttpContent
{
    public JsonRpcContent(JsonRpcRequest request)
    {
        _request = request;
        Headers.ContentType = new MediaTypeHeaderValue("application/json");
    }
}

3.3 A2ACardResolver क्लास

एजेंट कार्ड जानकारी को पार्स करने और प्राप्त करने के लिए उपयोग किया जाता है:

public class A2ACardResolver
{
    public async Task<AgentCard> GetAgentCardAsync(Uri agentUri)
    public async Task<AgentCard> GetAgentCardAsync(string agentUrl)
}

4. A2A .NET सर्वर कार्यान्वयन

4.1 TaskManager क्लास

TaskManager कार्य जीवनचक्र प्रबंधन के लिए जिम्मेदार मुख्य सर्वर-साइड घटक है।

मुख्य जिम्मेदारियाँ:

  1. कार्य जीवनचक्र प्रबंधन: कार्य बनाना, अपडेट करना, रद्द करना
  2. संदेश प्रसंस्करण: आने वाले संदेशों और कार्य अपडेट को संभालना
  3. इवेंट वितरण: कार्य स्थिति परिवर्तन इवेंट प्रबंधन
  4. स्टोरेज अमूर्तीकरण: ITaskStore इंटरफेस के माध्यम से कार्य स्थायित्व

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

public class TaskManager : ITaskManager
{
    // इवेंट हैंडलर
    public Func<MessageSendParams, Task<Message>>? OnMessageReceived { get; set; }
    public Func<AgentTask, Task> OnTaskCreated { get; set; }
    public Func<AgentTask, Task> OnTaskCancelled { get; set; }
    public Func<AgentTask, Task> OnTaskUpdated { get; set; }
    public Func<string, AgentCard> OnAgentCardQuery { get; set; }
    
    // मुख्य संचालन
    public async Task<AgentTask> CreateTaskAsync(string? contextId = null)
    public async Task<AgentTask?> CancelTaskAsync(TaskIdParams? taskIdParams)
    public async Task<A2AResponse?> SendMessageAsync(MessageSendParams messageSendParams)
    public async Task<IAsyncEnumerable<A2AEvent>> SendMessageStreamAsync(MessageSendParams messageSendParams)
    public async Task UpdateStatusAsync(string taskId, TaskState status, Message? message = null, bool final = false)
    public async Task ReturnArtifactAsync(string taskId, Artifact artifact)
}

4.2 ITaskStore इंटरफेस

कार्य भंडारण के लिए अमूर्त इंटरफेस:

public interface ITaskStore
{
    Task<AgentTask?> GetTaskAsync(string taskId);
    Task SetTaskAsync(AgentTask task);
    Task UpdateStatusAsync(string taskId, TaskState status);
}

4.3 ASP.NET Core एकीकरण

A2A.AspNetCore लाइब्रेरी द्वारा प्रदान की गई एक्सटेंशन मेथड्स के माध्यम से:

// JSON-RPC A2A समर्थन जोड़ें
app.MapA2A(taskManager, "/echo");

// HTTP A2A समर्थन जोड़ें
app.MapHttpA2A(taskManager, "/echo");

5. A2A .NET डेटा मॉडल

5.1 मुख्य मॉडल क्लासेस

AgentCard - एजेंट कार्ड

public class AgentCard
{
    public string Name { get; set; }                    // एजेंट नाम
    public string Description { get; set; }            // एजेंट विवरण
    public string Url { get; set; }                     // एजेंट URL
    public AgentProvider? Provider { get; set; }        // प्रदाता जानकारी
    public string Version { get; set; }                 // संस्करण जानकारी
    public AgentCapabilities Capabilities { get; set; } // एजेंट क्षमताएँ
    public List<AgentSkill> Skills { get; set; }        // एजेंट कौशल
    public List<string> DefaultInputModes { get; set; } // डिफ़ॉल्ट इनपुट मोड
    public List<string> DefaultOutputModes { get; set; }// डिफ़ॉल्ट आउटपुट मोड
}

AgentTask - एजेंट कार्य

public class AgentTask : A2AResponse
{
    public string Id { get; set; }                      // कार्य ID
    public string? ContextId { get; set; }              // संदर्भ ID
    public AgentTaskStatus Status { get; set; }         // कार्य स्थिति
    public List<Artifact>? Artifacts { get; set; }      // कार्य आर्टिफैक्ट
    public List<Message>? History { get; set; }         // संदेश इतिहास
    public Dictionary<string, JsonElement>? Metadata { get; set; } // मेटाडेटा
}

Message - संदेश

public class Message : A2AResponse
{
    public MessageRole Role { get; set; }               // संदेश भूमिका (User/Agent)
    public List<Part> Parts { get; set; }               // संदेश भाग
    public string? MessageId { get; set; }              // संदेश ID
    public string? TaskId { get; set; }                 // संबंधित कार्य ID
    public string? ContextId { get; set; }              // संदर्भ ID
    public Dictionary<string, JsonElement>? Metadata { get; set; } // मेटाडेटा
}

5.2 कार्य स्थितियाँ

public enum TaskState
{
    Submitted,      // प्रस्तुत
    Working,        // कार्यरत
    InputRequired,  // इनपुट आवश्यक
    Completed,      // पूर्ण
    Canceled,       // रद्द
    Failed,         // विफल
    Rejected        // अस्वीकृत
}

5.3 संदेश भाग प्रकार

कई संदेश भाग प्रकारों का समर्थन करता है:

  • TextPart: पाठ सामग्री
  • FilePart: फ़ाइल सामग्री
  • DataPart: डेटा सामग्री

6. A2A .NET AgentServer उदाहरण विस्तृत विश्लेषण

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

AgentServer उदाहरण दिखाता है कि कैसे विभिन्न प्रकार के एजेंटों को बनाया और तैनात किया जाए, जिसमें शामिल हैं:

  1. EchoAgent: सरल इको एजेंट
  2. EchoAgentWithTasks: कार्य समर्थन के साथ इको एजेंट
  3. HostedClientAgent: होस्टेड क्लाइंट एजेंट
  4. ResearcherAgent: शोधकर्ता एजेंट (स्टेट मशीन कार्यान्वयन)

6.2 EchoAgent कार्यान्वयन

public class EchoAgent
{
    private ITaskManager? _taskManager;

    public void Attach(TaskManager taskManager)
    {
        _taskManager = taskManager;
        taskManager.OnMessageReceived = ProcessMessage;
        taskManager.OnAgentCardQuery = GetAgentCard;
    }

    public Task<Message> ProcessMessage(MessageSendParams messageSendParams)
    {
        var messageText = messageSendParams.Message.Parts.OfType<TextPart>().First().Text;
        var message = new Message()
        {
            Role = MessageRole.Agent,
            MessageId = Guid.NewGuid().ToString(),
            ContextId = messageSendParams.Message.ContextId,
            Parts = [new TextPart() { Text = $"Echo: {messageText}" }]
        };
        return Task.FromResult(message);
    }
}

6.3 ResearcherAgent कार्यान्वयन

ResearcherAgent एक अधिक जटिल स्टेट मशीन कार्यान्वयन दिखाता है:

public class ResearcherAgent
{
    private enum AgentState
    {
        Planning,                    // योजना चरण
        WaitingForFeedbackOnPlan,   // योजना पर प्रतिक्रिया की प्रतीक्षा
        Researching                 // शोध चरण
    }

    public async Task Invoke(string taskId, string message)
    {
        switch (_agentStates[taskId])
        {
            case AgentState.Planning:
                await DoPlanning(taskId, message);
                break;
            case AgentState.WaitingForFeedbackOnPlan:
                if (message == "go ahead")
                    await DoResearch(taskId, message);
                else
                    await DoPlanning(taskId, message);
                break;
            case AgentState.Researching:
                await DoResearch(taskId, message);
                break;
        }
    }
}

7. AgentServer उदाहरण चलाने का तरीका

7.1 पर्यावरण आवश्यकताएँ

  • .NET 9.0 SDK या उच्चतर
  • वैकल्पिक: OpenTelemetry Collector (टेलीमेट्री डेटा के लिए)

7.2 चलाने के चरण

  1. परियोजना क्लोन करें:

    git clone https://github.com/a2aproject/a2a-dotnet
cd a2a-dotnet

  2. उदाहरण निर्देशिका में नेविगेट करें:

    cd samples/AgentServer

  3. परियोजना चलाएँ:

    dotnet run

  4. सेवा चल रही है यह सत्यापित करें: सेवा निम्नलिखित पोर्ट पर शुरू होगी:

7.3 उपलब्ध एंडपॉइंट

  • /echo - सरल इको एजेंट
  • /echotasks - कार्य समर्थन के साथ इको एजेंट
  • /hostedclient - होस्टेड क्लाइंट एजेंट
  • /researcher - शोधकर्ता एजेंट

7.4 API कॉल का परीक्षण

एजेंट कार्ड प्राप्त करें

curl -X GET http://localhost:5048/echo/.well-known/agent.json

इको एजेंट को संदेश भेजें

curl -X POST http://localhost:5048/echo \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "12345",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello, world!"
          }
        ]
      }
    }
  }'

शोधकर्ता एजेंट कार्य बनाएँ

curl -X POST http://localhost:5048/researcher \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "research-1",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Research the current price of butter"
          }
        ]
      }
    }
  }'

8. अनुक्रम आरेख

8.1 सरल संदेश प्रसंस्करण अनुक्रम आरेख

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant Agent as Agent Implementation
    participant TaskMgr as TaskManager

    Client->>Server: POST /echo (JSON-RPC message/send)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>Agent: OnMessageReceived()
    Agent->>Agent: ProcessMessage()
    Agent-->>TaskMgr: Return Message
    TaskMgr-->>Server: Return A2AResponse
    Server-->>Client: JSON-RPC Response

8.2 कार्य प्रसंस्करण अनुक्रम आरेख

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant TaskMgr as TaskManager
    participant Agent as Agent Implementation
    participant Store as TaskStore

    Client->>Server: POST /researcher (message/send)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>TaskMgr: CreateTaskAsync()
    TaskMgr->>Store: SetTaskAsync()
    TaskMgr->>Agent: OnTaskCreated()
    Agent->>Agent: State Change (Planning)
    Agent->>TaskMgr: UpdateStatusAsync(Working)
    TaskMgr->>Store: UpdateStatusAsync()
    Agent->>TaskMgr: ReturnArtifactAsync()
    Agent->>TaskMgr: UpdateStatusAsync(InputRequired)
    TaskMgr-->>Server: Return AgentTask
    Server-->>Client: JSON-RPC Response

    Note over Client,Store: Client sends follow-up message

    Client->>Server: POST /researcher (message/send, taskId)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>Store: GetTaskAsync()
    TaskMgr->>Agent: OnTaskUpdated()
    Agent->>Agent: State processing logic
    Agent->>TaskMgr: UpdateStatusAsync(Completed)
    TaskMgr-->>Server: Return AgentTask
    Server-->>Client: JSON-RPC Response

8.3 स्ट्रीमिंग प्रसंस्करण अनुक्रम आरेख

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant TaskMgr as TaskManager
    participant Agent as Agent Implementation

    Client->>Server: POST /echo (JSON-RPC message/stream)
    Server->>TaskMgr: SendMessageStreamAsync()
    TaskMgr->>Agent: OnMessageReceived()
    
    loop Streaming Response
        Agent->>TaskMgr: Generate Event
        TaskMgr->>Server: A2AEvent
        Server->>Client: Server-Sent Event
    end
    
    Agent->>TaskMgr: Complete Processing
    TaskMgr->>Server: End Stream
    Server->>Client: Close Connection

9. A2A .NET प्रमुख डिज़ाइन पैटर्न

9.1 इवेंट-ड्रिवन आर्किटेक्चर

TaskManager इवेंट-ड्रिवन पैटर्न का उपयोग करता है:

  • OnMessageReceived: आने वाले संदेशों को संभालना
  • OnTaskCreated: कार्य निर्माण इवेंट
  • OnTaskUpdated: कार्य अपडेट इवेंट
  • OnTaskCancelled: कार्य रद्दीकरण इवेंट

9.2 रणनीति पैटर्न

विभिन्न एजेंट कार्यान्वयन में विभिन्न प्रसंस्करण रणनीतियाँ हो सकती हैं:

  • स्टेटलेस प्रसंस्करण (EchoAgent)
  • स्टेटफुल प्रसंस्करण (ResearcherAgent)
  • कार्य-उन्मुख प्रसंस्करण (EchoAgentWithTasks)

9.3 स्टोरेज अमूर्तीकरण

ITaskStore इंटरफेस के माध्यम से कार्य स्टोरेज अमूर्तीकरण:

  • InMemoryTaskStore: इन-मेमोरी स्टोरेज कार्यान्वयन
  • डेटाबेस स्टोरेज कार्यान्वयन के लिए विस्तारणीय

10. A2A .NET प्रदर्शन और अवलोकनीयता

10.1 प्रदर्शन अनुकूलन

  1. स्रोत-जनित सीरियलाइजेशन: System.Text.Json स्रोत जनरेटर का उपयोग करता है
  2. AOT संगतता: Native AOT संकलन का समर्थन करता है
  3. अतुल्यकालिक प्रसंस्करण: async/await पैटर्न का व्यापक उपयोग
  4. स्ट्रीमिंग प्रसंस्करण: बड़े डेटा वॉल्यूम स्ट्रीमिंग का समर्थन करता है

10.2 अवलोकनीयता

एकीकृत OpenTelemetry समर्थन:

  • वितरित ट्रेसिंग: ActivitySource एकीकरण
  • मेट्रिक्स संग्रह: कार्य स्थिति और प्रदर्शन मेट्रिक्स
  • लॉगिंग: संरचित लॉगिंग समर्थन
// OpenTelemetry कॉन्फ़िगरेशन उदाहरण
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource(TaskManager.ActivitySource.Name)
        .AddSource(A2AJsonRpcProcessor.ActivitySource.Name)
        .AddConsoleExporter()
        .AddOtlpExporter());

11. A2A .NET सारांश

A2A .NET SDK .NET अनुप्रयोगों में एजेंट-से-एजेंट संचार को लागू करने के लिए एक पूर्ण, उत्पादन-तैयार समाधान प्रदान करता है।

11.1 मुख्य लाभ

  1. मानकीकृत प्रोटोकॉल: Google के A2A Protocol मानक पर आधारित
  2. आसान एकीकरण: सरल ASP.NET Core एकीकरण
  3. लचीला आर्किटेक्चर: कई एजेंट कार्यान्वयन पैटर्न का समर्थन करता है
  4. उच्च प्रदर्शन: अनुकूलित सीरियलाइजेशन और अतुल्यकालिक प्रसंस्करण
  5. अवलोकनीयता: अंतर्निहित टेलीमेट्री और निगरानी समर्थन
  6. विस्तारणीयता: अमूर्त इंटरफेस कस्टम कार्यान्वयन का समर्थन करते हैं

11.2 उपयोग के मामले

  1. AI एजेंट सिस्टम: बुद्धिमान एजेंट इंटरैक्शन सिस्टम बनाना
  2. माइक्रोसर्विस आर्किटेक्चर: सेवाओं के बीच बुद्धिमान संचार
  3. वर्कफ़्लो इंजन: जटिल व्यावसायिक प्रक्रियाओं का एजेंट-आधारित प्रसंस्करण
  4. चैटबॉट: मल्टी-एजेंट सहयोगी संवाद प्रणाली

11.3 भविष्य का विकास

  1. पुश नोटिफिकेशन: पूर्ण क्लाइंट कॉलबैक समर्थन
  2. अधिक स्टोरेज बैकएंड: डेटाबेस और वितरित स्टोरेज समर्थन
  3. सुरक्षा वृद्धि: अधिक व्यापक प्रमाणीकरण और प्राधिकरण तंत्र
  4. प्रोटोकॉल अपडेट: A2A Protocol के नवीनतम संस्करणों के साथ अद्यतन रहना

11.4 विकास अनुशंसाएँ

  1. सरल शुरुआत: मूल अवधारणाओं को समझने के लिए EchoAgent का उपयोग करें
  2. स्टेट प्रबंधन समझें: ResearcherAgent के स्टेट मशीन कार्यान्वयन का अध्ययन करें
  3. त्रुटि प्रबंधन पर जोर दें: व्यापक त्रुटि प्रबंधन और पुनर्प्राप्ति तंत्र लागू करें
  4. निगरानी और डिबगिंग: सिस्टम निगरानी के लिए OpenTelemetry का उपयोग करें
  5. परीक्षण-संचालित: व्यापक इकाई परीक्षण और एकीकरण परीक्षण लिखें

यह SDK .NET डेवलपर्स को अगली पीढ़ी के बुद्धिमान एजेंट सिस्टम बनाने के लिए एक शक्तिशाली और लचीला प्लेटफॉर्म प्रदान करता है। इसकी स्पष्ट आर्किटेक्चर और समृद्ध उदाहरणों के माध्यम से, डेवलपर्स जल्दी से शुरू कर सकते हैं और जटिल एजेंट-से-एजेंट संचार अनुप्रयोग बना सकते हैं।