A2A Protocol

A2A Protocol Specification (Python)

deutschEnglishfrançaisहिंदी日本語한국어nederlands中文
MILO•
Share
SpecificationPython
A2A Protocol Specification (Python)

अवलोकन

A2A (Agent2Agent) प्रोटोकॉल एक JSON-RPC 2.0 आधारित संचार प्रोटोकॉल है जो बुद्धिमान एजेंटों के बीच बातचीत के लिए डिज़ाइन किया गया है। यह प्रोटोकॉल एजेंट क्षमता घोषणा, संदेश पासिंग, कार्य प्रबंधन, सुरक्षा प्रमाणीकरण सहित मुख्य कार्यक्षमताओं को परिभाषित करता है।

यह दस्तावेज़ a2a-python/src/a2a/types.py फ़ाइल पर आधारित है और A2A प्रोटोकॉल की सभी डेटा संरचनाओं और ऑब्जेक्ट संबंधों का विस्तृत परिचय प्रदान करता है।

प्रोटोकॉल संस्करण

वर्तमान प्रोटोकॉल संस्करण: 0.2.5

मुख्य अवधारणाएं

1. एजेंट

एजेंट A2A प्रोटोकॉल की मुख्य इकाई है, जिसके पास उपयोगकर्ता अनुरोधों को संभालने और कार्यों को निष्पादित करने के लिए विशिष्ट कौशल और क्षमताएं हैं।

2. कार्य

कार्य एजेंट द्वारा निष्पादित कार्य इकाई है, जो जीवनचक्र स्थिति प्रबंधन और इतिहास रिकॉर्डिंग सुविधाओं की विशेषता है।

3. संदेश

संदेश उपयोगकर्ता और एजेंट के बीच जानकारी का आदान-प्रदान करने की मूल इकाई है, जो कई सामग्री प्रकारों का समर्थन करता है।

4. JSON-RPC 2.0

A2A प्रोटोकॉल JSON-RPC 2.0 मानक पर आधारित है, जो मानकीकृत अनुरोध-प्रतिक्रिया संचार पैटर्न प्रदान करता है।

डेटा संरचना विवरण

मूल प्रकार

A2A

class A2A(RootModel[Any]):
    root: Any

प्रोटोकॉल का रूट प्रकार, जो किसी भी डेटा को शामिल कर सकता है।

Role (गणना)

class Role(str, Enum):
    """संदेश भेजने वाले की भूमिका"""
    agent = 'agent'  # एजेंट
    user = 'user'    # उपयोगकर्ता

TaskState (गणना)

class TaskState(str, Enum):
    """कार्य की संभावित स्थितियां"""
    submitted = 'submitted'           # प्रस्तुत
    working = 'working'               # कार्य में
    input_required = 'input-required' # इनपुट आवश्यक
    completed = 'completed'           # पूर्ण
    canceled = 'canceled'             # रद्द
    failed = 'failed'                 # असफल
    rejected = 'rejected'             # अस्वीकृत
    auth_required = 'auth-required'   # प्रमाणीकरण आवश्यक
    unknown = 'unknown'               # अज्ञात स्थिति

एजेंट संबंधित प्रकार

AgentCard

class AgentCard(A2ABaseModel):
    """एजेंट कार्ड - एजेंट की महत्वपूर्ण जानकारी शामिल करता है"""
    name: str                                    # एजेंट नाम
    description: str                             # एजेंट विवरण
    version: str                                 # एजेंट संस्करण
    url: str                                     # एजेंट URL
    protocolVersion: str | None = '0.2.5'       # प्रोटोकॉल संस्करण
    skills: list[AgentSkill]                     # कौशल सूची
    capabilities: AgentCapabilities              # क्षमता घोषणा
    defaultInputModes: list[str]                 # डिफ़ॉल्ट इनपुट मोड
    defaultOutputModes: list[str]                # डिफ़ॉल्ट आउटपुट मोड
    provider: AgentProvider | None = None        # सेवा प्रदाता
    security: list[dict[str, list[str]]] | None = None  # सुरक्षा आवश्यकताएं
    securitySchemes: dict[str, SecurityScheme] | None = None  # सुरक्षा स्कीम
    # ... अन्य फ़ील्ड

AgentSkill

class AgentSkill(A2ABaseModel):
    """एजेंट कौशल - एजेंट द्वारा निष्पादित की जा सकने वाली क्षमता इकाई"""
    id: str                          # कौशल अद्वितीय पहचानकर्ता
    name: str                        # कौशल नाम
    description: str                 # कौशल विवरण
    tags: list[str]                  # कौशल टैग
    examples: list[str] | None = None # उपयोग उदाहरण
    inputModes: list[str] | None = None   # इनपुट मोड
    outputModes: list[str] | None = None  # आउटपुट मोड

AgentCapabilities

class AgentCapabilities(A2ABaseModel):
    """एजेंट क्षमता परिभाषा"""
    extensions: list[AgentExtension] | None = None      # समर्थित एक्सटेंशन
    pushNotifications: bool | None = None               # पुश नोटिफिकेशन समर्थन
    stateTransitionHistory: bool | None = None          # स्थिति संक्रमण इतिहास
    streaming: bool | None = None                       # स्ट्रीमिंग समर्थन

AgentExtension

class AgentExtension(A2ABaseModel):
    """एजेंट एक्सटेंशन घोषणा"""
    uri: str                                # एक्सटेंशन URI
    description: str | None = None          # एक्सटेंशन विवरण
    params: dict[str, Any] | None = None    # एक्सटेंशन पैरामीटर
    required: bool | None = None            # आवश्यक है या नहीं

AgentProvider

class AgentProvider(A2ABaseModel):
    """एजेंट सेवा प्रदाता"""
    organization: str  # संगठन नाम
    url: str          # संगठन URL

AgentInterface

class AgentInterface(A2ABaseModel):
    """एजेंट इंटरफ़ेस घोषणा"""
    transport: str  # परिवहन प्रोटोकॉल (JSONRPC, GRPC, HTTP+JSON)
    url: str       # इंटरफ़ेस URL

संदेश संबंधित प्रकार

Message

class Message(A2ABaseModel):
    """उपयोगकर्ता और एजेंट के बीच आदान-प्रदान किए जाने वाले संदेश"""
    messageId: str                           # संदेश ID
    role: Role                               # भेजने वाले की भूमिका
    parts: list[Part]                        # संदेश सामग्री भाग
    kind: Literal['message'] = 'message'     # इवेंट प्रकार
    taskId: str | None = None                # संबंधित कार्य ID
    contextId: str | None = None             # संदर्भ ID
    referenceTaskIds: list[str] | None = None # संदर्भित कार्य ID सूची
    extensions: list[str] | None = None       # एक्सटेंशन URI सूची
    metadata: dict[str, Any] | None = None    # मेटाडेटा

Part (यूनियन प्रकार)

class Part(RootModel[TextPart | FilePart | DataPart]):
    """संदेश भाग - टेक्स्ट, फ़ाइल या संरचित डेटा"""
    root: TextPart | FilePart | DataPart

TextPart

class TextPart(A2ABaseModel):
    """टेक्स्ट संदेश भाग"""
    kind: Literal['text'] = 'text'           # भाग प्रकार
    text: str                                # टेक्स्ट सामग्री
    metadata: dict[str, Any] | None = None   # मेटाडेटा

FilePart

class FilePart(A2ABaseModel):
    """फ़ाइल संदेश भाग"""
    kind: Literal['file'] = 'file'           # भाग प्रकार
    file: FileWithBytes | FileWithUri        # फ़ाइल सामग्री
    metadata: dict[str, Any] | None = None   # मेटाडेटा

DataPart

class DataPart(A2ABaseModel):
    """संरचित डेटा संदेश भाग"""
    kind: Literal['data'] = 'data'           # भाग प्रकार
    data: dict[str, Any]                     # संरचित डेटा
    metadata: dict[str, Any] | None = None   # मेटाडेटा

फ़ाइल प्रकार

FileWithBytes
class FileWithBytes(A2ABaseModel):
    """बाइट सामग्री वाली फ़ाइल"""
    bytes: str                        # base64 एन्कोडेड फ़ाइल सामग्री
    name: str | None = None           # फ़ाइल नाम
    mimeType: str | None = None       # MIME प्रकार
FileWithUri
class FileWithUri(A2ABaseModel):
    """URI वाली फ़ाइल"""
    uri: str                          # फ़ाइल URL
    name: str | None = None           # फ़ाइल नाम
    mimeType: str | None = None       # MIME प्रकार

कार्य संबंधित प्रकार

Task

class Task(A2ABaseModel):
    """कार्य इकाई"""
    id: str                                  # कार्य अद्वितीय पहचानकर्ता
    contextId: str                           # संदर्भ ID
    status: TaskStatus                       # कार्य स्थिति
    kind: Literal['task'] = 'task'           # इवेंट प्रकार
    history: list[Message] | None = None     # संदेश इतिहास
    artifacts: list[Artifact] | None = None  # उत्पन्न कलाकृतियां
    metadata: dict[str, Any] | None = None   # मेटाडेटा

TaskStatus

class TaskStatus(A2ABaseModel):
    """कार्य स्थिति और संबंधित संदेश"""
    state: TaskState                         # कार्य स्थिति
    message: Message | None = None           # स्थिति अपडेट संदेश
    timestamp: str | None = None             # टाइमस्टैम्प (ISO 8601)

Artifact

class Artifact(A2ABaseModel):
    """कार्य द्वारा उत्पन्न कलाकृति"""
    artifactId: str                          # कलाकृति ID
    parts: list[Part]                        # कलाकृति सामग्री भाग
    name: str | None = None                  # कलाकृति नाम
    description: str | None = None           # कलाकृति विवरण
    extensions: list[str] | None = None      # एक्सटेंशन URI सूची
    metadata: dict[str, Any] | None = None   # मेटाडेटा

JSON-RPC संबंधित प्रकार

JSONRPCMessage (आधार वर्ग)

class JSONRPCMessage(A2ABaseModel):
    """JSON-RPC 2.0 संदेश आधार वर्ग"""
    jsonrpc: Literal['2.0'] = '2.0'          # प्रोटोकॉल संस्करण
    id: str | int | None = None              # अनुरोध/प्रतिक्रिया ID

JSONRPCRequest

class JSONRPCRequest(A2ABaseModel):
    """JSON-RPC 2.0 अनुरोध ऑब्जेक्ट"""
    jsonrpc: Literal['2.0'] = '2.0'          # प्रोटोकॉल संस्करण
    method: str                              # मेथड नाम
    params: dict[str, Any] | None = None     # पैरामीटर
    id: str | int | None = None              # अनुरोध ID

JSONRPCSuccessResponse

class JSONRPCSuccessResponse(A2ABaseModel):
    """JSON-RPC 2.0 सफल प्रतिक्रिया ऑब्जेक्ट"""
    jsonrpc: Literal['2.0'] = '2.0'          # प्रोटोकॉल संस्करण
    result: Any                              # परिणाम डेटा
    id: str | int | None = None              # प्रतिक्रिया ID

JSONRPCErrorResponse

class JSONRPCErrorResponse(A2ABaseModel):
    """JSON-RPC 2.0 त्रुटि प्रतिक्रिया ऑब्जेक्ट"""
    jsonrpc: Literal['2.0'] = '2.0'          # प्रोटोकॉल संस्करण
    error: JSONRPCError | [specific error type]      # त्रुटि जानकारी
    id: str | int | None = None              # प्रतिक्रिया ID

त्रुटि प्रकार

A2A प्रोटोकॉल कई त्रुटि प्रकारों को परिभाषित करता है, सभी मानक JSON-RPC त्रुटियों से विरासत में मिले हैं:

मानक JSON-RPC त्रुटियां

JSONParseError
class JSONParseError(A2ABaseModel):
    """JSON पार्सिंग त्रुटि"""
    code: Literal[-32700] = -32700
    message: str | None = 'Invalid JSON payload'
    data: Any | None = None
InvalidRequestError
class InvalidRequestError(A2ABaseModel):
    """अमान्य अनुरोध त्रुटि"""
    code: Literal[-32600] = -32600
    message: str | None = 'Request payload validation error'
    data: Any | None = None
MethodNotFoundError
class MethodNotFoundError(A2ABaseModel):
    """मेथड नहीं मिला त्रुटि"""
    code: Literal[-32601] = -32601
    message: str | None = 'Method not found'
    data: Any | None = None
InvalidParamsError
class InvalidParamsError(A2ABaseModel):
    """अमान्य पैरामीटर त्रुटि"""
    code: Literal[-32602] = -32602
    message: str | None = 'Invalid parameters'
    data: Any | None = None
InternalError
class InternalError(A2ABaseModel):
    """आंतरिक त्रुटि"""
    code: Literal[-32603] = -32603
    message: str | None = 'Internal error'
    data: Any | None = None

A2A विशिष्ट त्रुटियां

TaskNotFoundError
class TaskNotFoundError(A2ABaseModel):
    """कार्य नहीं मिला त्रुटि"""
    code: Literal[-32001] = -32001
    message: str | None = 'Task not found'
    data: Any | None = None
TaskNotCancelableError
class TaskNotCancelableError(A2ABaseModel):
    """कार्य रद्द नहीं किया जा सकता त्रुटि"""
    code: Literal[-32002] = -32002
    message: str | None = 'Task cannot be canceled'
    data: Any | None = None
PushNotificationNotSupportedError
class PushNotificationNotSupportedError(A2ABaseModel):
    """पुश नोटिफिकेशन समर्थित नहीं त्रुटि"""
    code: Literal[-32003] = -32003
    message: str | None = 'Push Notification is not supported'
    data: Any | None = None
UnsupportedOperationError
class UnsupportedOperationError(A2ABaseModel):
    """असमर्थित ऑपरेशन त्रुटि"""
    code: Literal[-32004] = -32004
    message: str | None = 'This operation is not supported'
    data: Any | None = None
ContentTypeNotSupportedError
class ContentTypeNotSupportedError(A2ABaseModel):
    """सामग्री प्रकार समर्थित नहीं त्रुटि"""
    code: Literal[-32005] = -32005
    message: str | None = 'Incompatible content types'
    data: Any | None = None
InvalidAgentResponseError
class InvalidAgentResponseError(A2ABaseModel):
    """अमान्य एजेंट प्रतिक्रिया त्रुटि"""
    code: Literal[-32006] = -32006
    message: str | None = 'Invalid agent response'
    data: Any | None = None

सुरक्षा प्रमाणीकरण संबंधित प्रकार

SecurityScheme (यूनियन प्रकार)

class SecurityScheme(RootModel[
    APIKeySecurityScheme |
    HTTPAuthSecurityScheme |
    OAuth2SecurityScheme |
    OpenIdConnectSecurityScheme
]):
    """सुरक्षा स्कीम - कई प्रमाणीकरण विधियों का समर्थन करता है"""

APIKeySecurityScheme

class APIKeySecurityScheme(A2ABaseModel):
    """API कुंजी सुरक्षा स्कीम"""
    type: Literal['apiKey'] = 'apiKey'
    name: str                              # पैरामीटर नाम
    in_: In                                # स्थान (header/query/cookie)
    description: str | None = None         # विवरण

HTTPAuthSecurityScheme

class HTTPAuthSecurityScheme(A2ABaseModel):
    """HTTP प्रमाणीकरण सुरक्षा स्कीम"""
    type: Literal['http'] = 'http'
    scheme: str                            # प्रमाणीकरण स्कीम (Basic, Bearer आदि)
    bearerFormat: str | None = None        # Bearer टोकन प्रारूप
    description: str | None = None         # विवरण

OAuth2SecurityScheme

class OAuth2SecurityScheme(A2ABaseModel):
    """OAuth2.0 सुरक्षा स्कीम"""
    type: Literal['oauth2'] = 'oauth2'
    flows: OAuthFlows                      # OAuth फ्लो सेटिंग
    description: str | None = None         # विवरण

OpenIdConnectSecurityScheme

class OpenIdConnectSecurityScheme(A2ABaseModel):
    """OpenID Connect सुरक्षा स्कीम"""
    type: Literal['openIdConnect'] = 'openIdConnect'
    openIdConnectUrl: str                  # OpenID Connect खोज URL
    description: str | None = None         # विवरण

OAuth फ्लो प्रकार

OAuthFlows
class OAuthFlows(A2ABaseModel):
    """OAuth फ्लो सेटिंग"""
    implicit: ImplicitOAuthFlow | None = None                    # निहित फ्लो
    password: PasswordOAuthFlow | None = None                    # पासवर्ड फ्लो
    clientCredentials: ClientCredentialsOAuthFlow | None = None  # क्लाइंट क्रेडेंशियल फ्लो
    authorizationCode: AuthorizationCodeOAuthFlow | None = None  # प्राधिकरण कोड फ्लो

पुश नोटिफिकेशन संबंधित प्रकार

PushNotificationConfig

class PushNotificationConfig(A2ABaseModel):
    """पुश नोटिफिकेशन कॉन्फ़िगरेशन"""
    url: str                                                    # पुश URL
    id: str | None = None                                       # पुश नोटिफिकेशन ID
    token: str | None = None                                    # सत्र टोकन
    authentication: PushNotificationAuthenticationInfo | None = None  # प्रमाणीकरण जानकारी

PushNotificationAuthenticationInfo

class PushNotificationAuthenticationInfo(A2ABaseModel):
    """पुश नोटिफिकेशन प्रमाणीकरण जानकारी"""
    schemes: list[str]                     # समर्थित प्रमाणीकरण स्कीम
    credentials: str | None = None         # प्रमाणीकरण जानकारी

अनुरोध और प्रतिक्रिया प्रकार

संदेश भेजना

SendMessageRequest
class SendMessageRequest(A2ABaseModel):
    """संदेश भेजने का अनुरोध"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['message/send'] = 'message/send'
    params: MessageSendParams
    id: str | int
MessageSendParams
class MessageSendParams(A2ABaseModel):
    """संदेश भेजने के पैरामीटर"""
    message: Message                                    # भेजा जाने वाला संदेश
    configuration: MessageSendConfiguration | None = None  # भेजने की सेटिंग
    metadata: dict[str, Any] | None = None             # मेटाडेटा
MessageSendConfiguration
class MessageSendConfiguration(A2ABaseModel):
    """संदेश भेजने की कॉन्फ़िगरेशन"""
    acceptedOutputModes: list[str]                          # स्वीकृत आउटपुट मोड
    blocking: bool | None = None                            # अनुरोध को ब्लॉक करना है या नहीं
    historyLength: int | None = None                        # इतिहास संदेश लंबाई
    pushNotificationConfig: PushNotificationConfig | None = None  # पुश नोटिफिकेशन सेटिंग

कार्य संचालन

GetTaskRequest
class GetTaskRequest(A2ABaseModel):
    """कार्य प्राप्त करने का अनुरोध"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['tasks/get'] = 'tasks/get'
    params: TaskQueryParams
    id: str | int
TaskQueryParams
class TaskQueryParams(A2ABaseModel):
    """कार्य क्वेरी पैरामीटर"""
    id: str                              # कार्य ID
    historyLength: int | None = None     # इतिहास लंबाई
    metadata: dict[str, Any] | None = None  # मेटाडेटा
CancelTaskRequest
class CancelTaskRequest(A2ABaseModel):
    """कार्य रद्द करने का अनुरोध"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['tasks/cancel'] = 'tasks/cancel'
    params: TaskIdParams
    id: str | int

इवेंट प्रकार

TaskStatusUpdateEvent

class TaskStatusUpdateEvent(A2ABaseModel):
    """कार्य स्थिति अपडेट इवेंट"""
    kind: Literal['status-update'] = 'status-update'
    taskId: str                              # कार्य ID
    contextId: str                           # संदर्भ ID
    status: TaskStatus                       # कार्य स्थिति
    final: bool                              # अंतिम इवेंट है या नहीं
    metadata: dict[str, Any] | None = None   # मेटाडेटा

TaskArtifactUpdateEvent

class TaskArtifactUpdateEvent(A2ABaseModel):
    """कार्य कलाकृति अपडेट इवेंट"""
    kind: Literal['artifact-update'] = 'artifact-update'
    taskId: str                              # कार्य ID
    contextId: str                           # संदर्भ ID
    artifact: Artifact                       # कलाकृति
    append: bool | None = None               # जोड़ना है या नहीं
    lastChunk: bool | None = None            # अंतिम चंक है या नहीं
    metadata: dict[str, Any] | None = None   # मेटाडेटा

ऑब्जेक्ट संबंध आरेख

graph TB
    %% मुख्य इकाइयां
    AgentCard[AgentCard<br/>एजेंट कार्ड]
    Task[Task<br/>कार्य]
    Message[Message<br/>संदेश]
    
    %% एजेंट संबंधित
    AgentSkill[AgentSkill<br/>एजेंट कौशल]
    AgentCapabilities[AgentCapabilities<br/>एजेंट क्षमताएं]
    AgentProvider[AgentProvider<br/>सेवा प्रदाता]
    AgentExtension[AgentExtension<br/>एजेंट एक्सटेंशन]
    AgentInterface[AgentInterface<br/>एजेंट इंटरफ़ेस]
    
    %% संदेश सामग्री
    Part[Part<br/>संदेश भाग]
    TextPart[TextPart<br/>टेक्स्ट भाग]
    FilePart[FilePart<br/>फ़ाइल भाग]
    DataPart[DataPart<br/>डेटा भाग]
    
    %% फ़ाइल प्रकार
    FileWithBytes[FileWithBytes<br/>बाइट फ़ाइल]
    FileWithUri[FileWithUri<br/>URI फ़ाइल]
    
    %% कार्य संबंधित
    TaskStatus[TaskStatus<br/>कार्य स्थिति]
    Artifact[Artifact<br/>कलाकृति]
    
    %% JSON-RPC
    JSONRPCRequest[JSONRPCRequest<br/>JSON-RPC अनुरोध]
    JSONRPCResponse[JSONRPCResponse<br/>JSON-RPC प्रतिक्रिया]
    
    %% सुरक्षा प्रमाणीकरण
    SecurityScheme[SecurityScheme<br/>सुरक्षा स्कीम]
    APIKeySecurityScheme[APIKeySecurityScheme<br/>API कुंजी स्कीम]
    HTTPAuthSecurityScheme[HTTPAuthSecurityScheme<br/>HTTP प्रमाणीकरण स्कीम]
    OAuth2SecurityScheme[OAuth2SecurityScheme<br/>OAuth2 स्कीम]
    OpenIdConnectSecurityScheme[OpenIdConnectSecurityScheme<br/>OpenID Connect स्कीम]
    
    %% पुश नोटिफिकेशन
    PushNotificationConfig[PushNotificationConfig<br/>पुश नोटिफिकेशन कॉन्फ़िगरेशन]
    PushNotificationAuthenticationInfo[PushNotificationAuthenticationInfo<br/>पुश प्रमाणीकरण जानकारी]
    
    %% त्रुटि प्रकार
    A2AError[A2AError<br/>A2A त्रुटि]
    JSONRPCError[JSONRPCError<br/>JSON-RPC त्रुटि]
    
    %% इवेंट
    TaskStatusUpdateEvent[TaskStatusUpdateEvent<br/>स्थिति अपडेट इवेंट]
    TaskArtifactUpdateEvent[TaskArtifactUpdateEvent<br/>कलाकृति अपडेट इवेंट]
    
    %% संबंध कनेक्शन
    AgentCard --> AgentSkill
    AgentCard --> AgentCapabilities
    AgentCard --> AgentProvider
    AgentCard --> AgentInterface
    AgentCard --> SecurityScheme
    
    AgentCapabilities --> AgentExtension
    
    Task --> TaskStatus
    Task --> Message
    Task --> Artifact
    
    Message --> Part
    Part --> TextPart
    Part --> FilePart
    Part --> DataPart
    
    FilePart --> FileWithBytes
    FilePart --> FileWithUri
    
    Artifact --> Part
    
    SecurityScheme --> APIKeySecurityScheme
    SecurityScheme --> HTTPAuthSecurityScheme
    SecurityScheme --> OAuth2SecurityScheme
    SecurityScheme --> OpenIdConnectSecurityScheme
    
    PushNotificationConfig --> PushNotificationAuthenticationInfo
    
    TaskStatusUpdateEvent --> TaskStatus
    TaskArtifactUpdateEvent --> Artifact
    
    JSONRPCResponse --> A2AError
    A2AError --> JSONRPCError
    
    %% शैली
    classDef coreEntity fill:#e1f5fe
    classDef agentRelated fill:#f3e5f5
    classDef messageRelated fill:#e8f5e8
    classDef taskRelated fill:#fff3e0
    classDef securityRelated fill:#fce4ec
    classDef errorRelated fill:#ffebee
    classDef eventRelated fill:#f1f8e9
    
    class AgentCard,Task,Message coreEntity
    class AgentSkill,AgentCapabilities,AgentProvider,AgentExtension,AgentInterface agentRelated
    class Part,TextPart,FilePart,DataPart,FileWithBytes,FileWithUri messageRelated
    class TaskStatus,Artifact taskRelated
    class SecurityScheme,APIKeySecurityScheme,HTTPAuthSecurityScheme,OAuth2SecurityScheme,OpenIdConnectSecurityScheme,PushNotificationConfig,PushNotificationAuthenticationInfo securityRelated
    class A2AError,JSONRPCError errorRelated
    class TaskStatusUpdateEvent,TaskArtifactUpdateEvent eventRelated

प्रोटोकॉल फ्लो आरेख

sequenceDiagram
    participant Client as क्लाइंट
    participant Agent as एजेंट
    
    Note over Client,Agent: 1. एजेंट खोज और क्षमता क्वेरी
    Client->>Agent: GET /agent-card
    Agent->>Client: AgentCard (कौशल, क्षमताएं, सुरक्षा आवश्यकताएं)
    
    Note over Client,Agent: 2. प्रमाणीकरण (यदि आवश्यक हो)
    Client->>Agent: प्रमाणीकरण अनुरोध (SecurityScheme के अनुसार)
    Agent->>Client: प्रमाणीकरण प्रतिक्रिया
    
    Note over Client,Agent: 3. संदेश भेजना और कार्य निर्माण
    Client->>Agent: SendMessageRequest
    Note right of Agent: कार्य निर्माण<br/>स्थिति: submitted
    Agent->>Client: SendMessageResponse (Task)
    
    Note over Client,Agent: 4. कार्य प्रसंस्करण (वैकल्पिक पुश नोटिफिकेशन)
    loop कार्य प्रसंस्करण
        Note right of Agent: कार्य स्थिति अपडेट<br/>working -> completed
        alt पुश नोटिफिकेशन समर्थन
            Agent->>Client: TaskStatusUpdateEvent
        else पोलिंग मोड
            Client->>Agent: GetTaskRequest
            Agent->>Client: GetTaskResponse (अपडेटेड Task)
        end
    end
    
    Note over Client,Agent: 5. अंतिम परिणाम प्राप्त करना
    Client->>Agent: GetTaskRequest
    Agent->>Client: Task (Artifacts और पूर्ण इतिहास के साथ)

कार्य स्थिति संक्रमण आरेख

stateDiagram-v2
    [*] --> submitted: कार्य निर्माण
    
    submitted --> working: प्रसंस्करण शुरू
    submitted --> rejected: कार्य अस्वीकार
    submitted --> auth_required: प्रमाणीकरण आवश्यक
    
    working --> completed: प्रसंस्करण पूर्ण
    working --> failed: प्रसंस्करण असफल
    working --> input_required: उपयोगकर्ता इनपुट आवश्यक
    working --> canceled: उपयोगकर्ता रद्द
    
    input_required --> working: उपयोगकर्ता इनपुट प्राप्त
    input_required --> canceled: उपयोगकर्ता रद्द
    
    auth_required --> working: प्रमाणीकरण सफल
    auth_required --> rejected: प्रमाणीकरण असफल
    
    completed --> [*]
    failed --> [*]
    canceled --> [*]
    rejected --> [*]
    
    unknown --> working: स्थिति पुनर्प्राप्ति
    unknown --> failed: पुनर्प्राप्ति असंभव

संदेश भाग प्रकार पदानुक्रम आरेख

flowchart TD
    Part["Part<br/>संदेश भाग आधार वर्ग"]
    
    Part --> TextPart["TextPart<br/>टेक्स्ट भाग<br/>kind: text"]
    Part --> FilePart["FilePart<br/>फ़ाइल भाग<br/>kind: file"]
    Part --> DataPart["DataPart<br/>डेटा भाग<br/>kind: data"]
    
    FilePart --> FileContent{"फ़ाइल सामग्री"}
    FileContent --> FileWithBytes["FileWithBytes<br/>base64 बाइट डेटा शामिल"]
    FileContent --> FileWithUri["FileWithUri<br/>फ़ाइल URI शामिल"]
    
    TextPart --> TextContent["text: str<br/>टेक्स्ट सामग्री"]
    DataPart --> DataContent["data: dict[str, Any]<br/>संरचित डेटा"]
    
    FileWithBytes --> BytesContent["bytes: str<br/>base64 एन्कोडेड सामग्री"]
    FileWithUri --> UriContent["uri: str<br/>फ़ाइल URL"]
    
    %% सामान्य गुण
    Part --> Metadata["metadata: dict[str, Any]<br/>वैकल्पिक मेटाडेटा"]
    FileWithBytes --> FileMetadata["name: str<br/>mimeType: str<br/>फ़ाइल मेटाडेटा"]
    FileWithUri --> FileMetadata
    
    classDef baseClass fill:#e3f2fd
    classDef textClass fill:#e8f5e8
    classDef fileClass fill:#fff3e0
    classDef dataClass fill:#f3e5f5
    classDef metaClass fill:#f5f5f5
    
    class Part baseClass
    class TextPart,TextContent textClass
    class FilePart,FileWithBytes,FileWithUri,BytesContent,UriContent fileClass
    class DataPart,DataContent dataClass
    class Metadata,FileMetadata metaClass

सुरक्षा स्कीम प्रकार आरेख

flowchart TD
    SecurityScheme["SecurityScheme<br/>सुरक्षा स्कीम यूनियन प्रकार"]
    
    SecurityScheme --> APIKeySecurityScheme["APIKeySecurityScheme<br/>API कुंजी प्रमाणीकरण<br/>type: apiKey"]
    SecurityScheme --> HTTPAuthSecurityScheme["HTTPAuthSecurityScheme<br/>HTTP प्रमाणीकरण<br/>type: http"]
    SecurityScheme --> OAuth2SecurityScheme["OAuth2SecurityScheme<br/>OAuth2 प्रमाणीकरण<br/>type: oauth2"]
    SecurityScheme --> OpenIdConnectSecurityScheme["OpenIdConnectSecurityScheme<br/>OpenID Connect<br/>type: openIdConnect"]
    
    APIKeySecurityScheme --> APIKeyDetails["name: str<br/>in: header|query|cookie"]
    HTTPAuthSecurityScheme --> HTTPDetails["scheme: str<br/>bearerFormat: str"]
    OAuth2SecurityScheme --> OAuthFlows["flows: OAuthFlows"]
    OpenIdConnectSecurityScheme --> OIDCDetails["openIdConnectUrl: str"]
    
    OAuthFlows --> ImplicitFlow["implicit: ImplicitOAuthFlow"]
    OAuthFlows --> PasswordFlow["password: PasswordOAuthFlow"]
    OAuthFlows --> ClientCredentialsFlow["clientCredentials: ClientCredentialsOAuthFlow"]
    OAuthFlows --> AuthorizationCodeFlow["authorizationCode: AuthorizationCodeOAuthFlow"]
    
    ImplicitFlow --> ImplicitDetails["authorizationUrl: str<br/>scopes: dict[str, str]"]
    PasswordFlow --> PasswordDetails["tokenUrl: str<br/>scopes: dict[str, str]"]
    ClientCredentialsFlow --> ClientDetails["tokenUrl: str<br/>scopes: dict[str, str]"]
    AuthorizationCodeFlow --> AuthCodeDetails["authorizationUrl: str<br/>tokenUrl: str<br/>scopes: dict[str, str]"]
    
    classDef baseClass fill:#e3f2fd
    classDef apiKeyClass fill:#e8f5e8
    classDef httpClass fill:#fff3e0
    classDef oauthClass fill:#f3e5f5
    classDef oidcClass fill:#fce4ec
    
    class SecurityScheme baseClass
    class APIKeySecurityScheme,APIKeyDetails apiKeyClass
    class HTTPAuthSecurityScheme,HTTPDetails httpClass
    class OAuth2SecurityScheme,OAuthFlows,ImplicitFlow,PasswordFlow,ClientCredentialsFlow,AuthorizationCodeFlow,ImplicitDetails,PasswordDetails,ClientDetails,AuthCodeDetails oauthClass
    class OpenIdConnectSecurityScheme,OIDCDetails oidcClass

त्रुटि कोड मैपिंग तालिका

त्रुटि कोड त्रुटि प्रकार विवरण उपयोग मामला
-32700 JSONParseError JSON पार्सिंग त्रुटि अमान्य JSON प्रारूप
-32600 InvalidRequestError अमान्य अनुरोध अनुरोध प्रारूप विनिर्देश के अनुरूप नहीं
-32601 MethodNotFoundError मेथड नहीं मिला अस्तित्वहीन मेथड कॉल
-32602 InvalidParamsError अमान्य पैरामीटर मेथड पैरामीटर सही नहीं
-32603 InternalError आंतरिक त्रुटि सर्वर आंतरिक प्रसंस्करण त्रुटि
-32001 TaskNotFoundError कार्य नहीं मिला अनुरोधित कार्य ID मौजूद नहीं
-32002 TaskNotCancelableError कार्य रद्द नहीं किया जा सकता कार्य स्थिति रद्दीकरण की अनुमति नहीं देती
-32003 PushNotificationNotSupportedError पुश नोटिफिकेशन समर्थित नहीं एजेंट पुश नोटिफिकेशन का समर्थन नहीं करता
-32004 UnsupportedOperationError ऑपरेशन समर्थित नहीं एजेंट अनुरोधित ऑपरेशन का समर्थन नहीं करता
-32005 ContentTypeNotSupportedError सामग्री प्रकार समर्थित नहीं अनुरोधित सामग्री प्रकार एजेंट क्षमताओं से मेल नहीं खाता
-32006 InvalidAgentResponseError अमान्य एजेंट प्रतिक्रिया एजेंट ने गलत प्रारूप की प्रतिक्रिया लौटाई

समर्थित मेथड सूची

A2A प्रोटोकॉल निम्नलिखित मानक मेथड परिभाषित करता है:

संदेश संबंधित मेथड

  • message/send - एजेंट को संदेश भेजना
  • message/stream - एजेंट को स्ट्रीमिंग संदेश भेजना

कार्य संबंधित मेथड

  • tasks/get - कार्य विवरण प्राप्त करना
  • tasks/cancel - कार्य रद्द करना
  • tasks/resubscribe - कार्य अपडेट पुनः सब्स्क्राइब करना

पुश नोटिफिकेशन कॉन्फ़िगरेशन मेथड

  • tasks/pushNotificationConfig/set - पुश नोटिफिकेशन कॉन्फ़िगरेशन सेट करना
  • tasks/pushNotificationConfig/get - पुश नोटिफिकेशन कॉन्फ़िगरेशन प्राप्त करना
  • tasks/pushNotificationConfig/list - पुश नोटिफिकेशन कॉन्फ़िगरेशन सूची
  • tasks/pushNotificationConfig/delete - पुश नोटिफिकेशन कॉन्फ़िगरेशन हटाना

उपयोग उदाहरण

1. सरल टेक्स्ट संदेश भेजना

from a2a.types import SendMessageRequest, MessageSendParams, Message, TextPart, Part

# टेक्स्ट संदेश भाग बनाना
text_part = TextPart(text="नमस्ते, मैं आपकी कैसे सहायता कर सकता हूं?")
part = Part(root=text_part)

# संदेश बनाना
message = Message(
    messageId="msg-001",
    role="user",
    parts=[part]
)

# भेजने के पैरामीटर बनाना
params = MessageSendParams(message=message)

# अनुरोध बनाना
request = SendMessageRequest(
    id="req-001",
    params=params
)

2. फ़ाइल के साथ संदेश भेजना

from a2a.types import FilePart, FileWithBytes
import base64

# फ़ाइल पढ़ना और एन्कोड करना
with open("document.pdf", "rb") as f:
    file_bytes = base64.b64encode(f.read()).decode()

# फ़ाइल भाग बनाना
file_with_bytes = FileWithBytes(
    bytes=file_bytes,
    name="document.pdf",
    mimeType="application/pdf"
)

file_part = FilePart(file=file_with_bytes)
part = Part(root=file_part)

# फ़ाइल के साथ संदेश बनाना
message = Message(
    messageId="msg-002",
    role="user",
    parts=[part]
)

3. कार्य स्थिति क्वेरी

from a2a.types import GetTaskRequest, TaskQueryParams

# कार्य क्वेरी अनुरोध बनाना
request = GetTaskRequest(
    id="req-002",
    params=TaskQueryParams(
        id="task-001",
        historyLength=10  # नवीनतम 10 संदेश इतिहास प्राप्त करना
    )
)

4. पुश नोटिफिकेशन कॉन्फ़िगरेशन

from a2a.types import (
    SetTaskPushNotificationConfigRequest,
    TaskPushNotificationConfig,
    PushNotificationConfig,
    PushNotificationAuthenticationInfo
)

# पुश नोटिफिकेशन कॉन्फ़िगरेशन बनाना
push_config = PushNotificationConfig(
    url="https://my-app.com/webhook/task-updates",
    authentication=PushNotificationAuthenticationInfo(
        schemes=["Bearer"],
        credentials="my-auth-token"
    )
)

# कार्य पुश कॉन्फ़िगरेशन बनाना
task_push_config = TaskPushNotificationConfig(
    taskId="task-001",
    pushNotificationConfig=push_config
)

# कॉन्फ़िगरेशन अनुरोध बनाना
request = SetTaskPushNotificationConfigRequest(
    id="req-003",
    params=task_push_config
)

सर्वोत्तम प्रथाएं

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

  • प्रतिक्रिया के त्रुटि फ़ील्ड की हमेशा जांच करें
  • त्रुटि कोड के आधार पर उपयुक्त पुनः प्रयास रणनीति लागू करें
  • उपयोगकर्ता को अर्थपूर्ण त्रुटि संदेश प्रदान करें

2. कार्य प्रबंधन

  • कार्य अपडेट के लिए पोलिंग के बजाय पुश नोटिफिकेशन का उपयोग करें
  • कार्य टाइमआउट तंत्र लागू करें
  • बाद की क्वेरी के लिए कार्य ID सहेजें

3. सुरक्षा

  • HTTPS परिवहन का उपयोग करें
  • प्रमाणीकरण स्कीम को उचित रूप से लागू करें
  • API कुंजी और टोकन को नियमित रूप से रोटेट करें

4. प्रदर्शन अनुकूलन

  • बड़ी प्रतिक्रिया प्रसंस्करण के लिए स्ट्रीमिंग का उपयोग करें
  • इतिहास संदेश लंबाई सीमित करें
  • क्लाइंट-साइड कैशिंग लागू करें

विस्तारशीलता

A2A प्रोटोकॉल निम्नलिखित तंत्रों के माध्यम से विस्तार का समर्थन करता है:

  1. एजेंट एक्सटेंशन - AgentExtension के माध्यम से कस्टम क्षमताओं की घोषणा
  2. मेटाडेटा फ़ील्ड - अधिकांश ऑब्जेक्ट में वैकल्पिक metadata फ़ील्ड शामिल
  3. कस्टम परिवहन प्रोटोकॉल - AgentInterface के माध्यम से नए परिवहन विधियों का समर्थन
  4. एक्सटेंशन URI - संदेश और कलाकृतियों में एक्सटेंशन विनिर्देशों का संदर्भ

सारांश

A2A प्रोटोकॉल बुद्धिमान एजेंटों के बीच संचार और सहयोग के लिए एक व्यापक ढांचा प्रदान करता है। JSON-RPC 2.0 पर आधारित, यह मानकीकृत संदेश पासिंग, कार्य प्रबंधन, सुरक्षा प्रमाणीकरण और विस्तारशीलता तंत्र प्रदान करता है।

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

  • मानकीकृत संचार: JSON-RPC 2.0 आधारित अनुरोध-प्रतिक्रिया पैटर्न
  • समृद्ध सामग्री समर्थन: टेक्स्ट, फ़ाइल और संरचित डेटा का समर्थन
  • लचीली सुरक्षा: कई प्रमाणीकरण विधियों का समर्थन
  • रीयल-टाइम अपडेट: पुश नोटिफिकेशन तंत्र
  • मजबूत त्रुटि हैंडलिंग: व्यापक त्रुटि कोड और संदेश
  • अच्छी विस्तारशीलता: एक्सटेंशन तंत्र और मेटाडेटा समर्थन

यह प्रोटोकॉल डेवलपर्स को शक्तिशाली एजेंट-आधारित एप्लिकेशन बनाने के लिए एक ठोस आधार प्रदान करता है।