A2A Protocol

A2A Protocol Specification (Python)

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

Overzicht

Het A2A (Agent2Agent) protocol is een communicatieprotocol gebaseerd op JSON-RPC 2.0, ontworpen voor interactie tussen intelligente agenten. Dit protocol definieert kernfunctionaliteiten inclusief agent capability declaratie, berichtoverdracht, taakbeheer en beveiligingsauthenticatie.

Dit document is gebaseerd op het bestand a2a-python/src/a2a/types.py en biedt een gedetailleerde introductie van alle datastructuren en objectrelaties van het A2A protocol.

Protocolversie

Huidige protocolversie: 0.2.5

Kernconcepten

1. Agent

De Agent is de hoofdentiteit van het A2A protocol, met specifieke vaardigheden en mogelijkheden om gebruikersverzoeken te verwerken en taken uit te voeren.

2. Taak

De Taak is de werkeenheid uitgevoerd door de agent, gekenmerkt door levenscyclus statusbeheer en geschiedenisregistratie.

3. Bericht

Het Bericht is de basiseenheid voor informatie-uitwisseling tussen gebruiker en agent, ondersteunt meerdere inhoudstypen.

4. JSON-RPC 2.0

Het A2A protocol is gebaseerd op de JSON-RPC 2.0 standaard en biedt een gestandaardiseerd verzoek-antwoord communicatiepatroon.

Datastructuur Details

Basistypen

A2A

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

Worteltype van het protocol, kan willekeurige data bevatten.

Role (Enumeratie)

class Role(str, Enum):
    """Rol van de berichtzender"""
    agent = 'agent'  # Agent
    user = 'user'    # Gebruiker

TaskState (Enumeratie)

class TaskState(str, Enum):
    """Mogelijke toestanden van de taak"""
    submitted = 'submitted'           # Ingediend
    working = 'working'               # In uitvoering
    input_required = 'input-required' # Invoer vereist
    completed = 'completed'           # Voltooid
    canceled = 'canceled'             # Geannuleerd
    failed = 'failed'                 # Mislukt
    rejected = 'rejected'             # Afgewezen
    auth_required = 'auth-required'   # Authenticatie vereist
    unknown = 'unknown'               # Onbekende status

Agent-gerelateerde Typen

AgentCard

class AgentCard(A2ABaseModel):
    """Agentkaart - bevat belangrijke informatie van de agent"""
    name: str                                    # Agentnaam
    description: str                             # Agentbeschrijving
    version: str                                 # Agentversie
    url: str                                     # Agent URL
    protocolVersion: str | None = '0.2.5'       # Protocolversie
    skills: list[AgentSkill]                     # Vaardighedenlijst
    capabilities: AgentCapabilities              # Mogelijkhedendeclaratie
    defaultInputModes: list[str]                 # Standaard invoermodi
    defaultOutputModes: list[str]                # Standaard uitvoermodi
    provider: AgentProvider | None = None        # Serviceprovider
    security: list[dict[str, list[str]]] | None = None  # Beveiligingsvereisten
    securitySchemes: dict[str, SecurityScheme] | None = None  # Beveiligingsschema's
    # ... andere velden

AgentSkill

class AgentSkill(A2ABaseModel):
    """Agentvaardigheid - uitvoerbare vaardigheidseenheid door de agent"""
    id: str                          # Unieke vaardigheidsidentificatie
    name: str                        # Vaardigheidsnaam
    description: str                 # Vaardigheidsbeschrijving
    tags: list[str]                  # Vaardigheids-tags
    examples: list[str] | None = None # Gebruiksvoorbeelden
    inputModes: list[str] | None = None   # Invoermodi
    outputModes: list[str] | None = None  # Uitvoermodi

AgentCapabilities

class AgentCapabilities(A2ABaseModel):
    """Agent mogelijkheidsdefinitie"""
    extensions: list[AgentExtension] | None = None      # Ondersteunde uitbreidingen
    pushNotifications: bool | None = None               # Push notificatie ondersteuning
    stateTransitionHistory: bool | None = None          # Status overgangsgeschiedenis
    streaming: bool | None = None                       # Streaming ondersteuning

AgentExtension

class AgentExtension(A2ABaseModel):
    """Agent uitbreidingsdeclaratie"""
    uri: str                                # Uitbreidings-URI
    description: str | None = None          # Uitbreidingsbeschrijving
    params: dict[str, Any] | None = None    # Uitbreidingsparameters
    required: bool | None = None            # Vereist of niet

AgentProvider

class AgentProvider(A2ABaseModel):
    """Agent serviceprovider"""
    organization: str  # Organisatienaam
    url: str          # Organisatie URL

AgentInterface

class AgentInterface(A2ABaseModel):
    """Agent interfacedeclaratie"""
    transport: str  # Transportprotocol (JSONRPC, GRPC, HTTP+JSON)
    url: str       # Interface URL

Bericht-gerelateerde Typen

Message

class Message(A2ABaseModel):
    """Berichten uitgewisseld tussen gebruiker en agent"""
    messageId: str                           # Bericht-ID
    role: Role                               # Rol van de zender
    parts: list[Part]                        # Berichtinhoud delen
    kind: Literal['message'] = 'message'     # Gebeurtenistype
    taskId: str | None = None                # Gerelateerde taak-ID
    contextId: str | None = None             # Context-ID
    referenceTaskIds: list[str] | None = None # Gerefereerde taak-ID lijst
    extensions: list[str] | None = None       # Uitbreidings-URI lijst
    metadata: dict[str, Any] | None = None    # Metadata

Part (Union Type)

class Part(RootModel[TextPart | FilePart | DataPart]):
    """Berichtdeel - tekst, bestand of gestructureerde data"""
    root: TextPart | FilePart | DataPart

TextPart

class TextPart(A2ABaseModel):
    """Tekst berichtdeel"""
    kind: Literal['text'] = 'text'           # Deeltype
    text: str                                # Tekstinhoud
    metadata: dict[str, Any] | None = None   # Metadata

FilePart

class FilePart(A2ABaseModel):
    """Bestand berichtdeel"""
    kind: Literal['file'] = 'file'           # Deeltype
    file: FileWithBytes | FileWithUri        # Bestandsinhoud
    metadata: dict[str, Any] | None = None   # Metadata

DataPart

class DataPart(A2ABaseModel):
    """Gestructureerde data berichtdeel"""
    kind: Literal['data'] = 'data'           # Deeltype
    data: dict[str, Any]                     # Gestructureerde data
    metadata: dict[str, Any] | None = None   # Metadata

Bestandstypen

FileWithBytes
class FileWithBytes(A2ABaseModel):
    """Bestand met byte-inhoud"""
    bytes: str                        # base64-gecodeerde bestandsinhoud
    name: str | None = None           # Bestandsnaam
    mimeType: str | None = None       # MIME-type
FileWithUri
class FileWithUri(A2ABaseModel):
    """Bestand met URI"""
    uri: str                          # Bestand URL
    name: str | None = None           # Bestandsnaam
    mimeType: str | None = None       # MIME-type

Taak-gerelateerde Typen

Task

class Task(A2ABaseModel):
    """Taakentiteit"""
    id: str                                  # Unieke taakidentificatie
    contextId: str                           # Context-ID
    status: TaskStatus                       # Taakstatus
    kind: Literal['task'] = 'task'           # Gebeurtenistype
    history: list[Message] | None = None     # Berichtgeschiedenis
    artifacts: list[Artifact] | None = None  # Gegenereerde artefacten
    metadata: dict[str, Any] | None = None   # Metadata

TaskStatus

class TaskStatus(A2ABaseModel):
    """Taakstatus en gerelateerd bericht"""
    state: TaskState                         # Taaktoestand
    message: Message | None = None           # Status update bericht
    timestamp: str | None = None             # Tijdstempel (ISO 8601)

Artifact

class Artifact(A2ABaseModel):
    """Door de taak gegenereerd artefact"""
    artifactId: str                          # Artefact-ID
    parts: list[Part]                        # Artefactinhoud delen
    name: str | None = None                  # Artefactnaam
    description: str | None = None           # Artefactbeschrijving
    extensions: list[str] | None = None      # Uitbreidings-URI lijst
    metadata: dict[str, Any] | None = None   # Metadata

JSON-RPC-gerelateerde Typen

JSONRPCMessage (Basisklasse)

class JSONRPCMessage(A2ABaseModel):
    """JSON-RPC 2.0 bericht basisklasse"""
    jsonrpc: Literal['2.0'] = '2.0'          # Protocolversie
    id: str | int | None = None              # Verzoek/antwoord ID

JSONRPCRequest

class JSONRPCRequest(A2ABaseModel):
    """JSON-RPC 2.0 verzoekobject"""
    jsonrpc: Literal['2.0'] = '2.0'          # Protocolversie
    method: str                              # Methodenaam
    params: dict[str, Any] | None = None     # Parameters
    id: str | int | None = None              # Verzoek-ID

JSONRPCSuccessResponse

class JSONRPCSuccessResponse(A2ABaseModel):
    """JSON-RPC 2.0 succes antwoordobject"""
    jsonrpc: Literal['2.0'] = '2.0'          # Protocolversie
    result: Any                              # Resultaatdata
    id: str | int | None = None              # Antwoord-ID

JSONRPCErrorResponse

class JSONRPCErrorResponse(A2ABaseModel):
    """JSON-RPC 2.0 fout antwoordobject"""
    jsonrpc: Literal['2.0'] = '2.0'          # Protocolversie
    error: JSONRPCError | [specific error type]      # Foutinformatie
    id: str | int | None = None              # Antwoord-ID

Fouttypen

Het A2A protocol definieert verschillende fouttypen, allemaal afgeleid van standaard JSON-RPC fouten:

Standaard JSON-RPC Fouten

JSONParseError
class JSONParseError(A2ABaseModel):
    """JSON parsing fout"""
    code: Literal[-32700] = -32700
    message: str | None = 'Invalid JSON payload'
    data: Any | None = None
InvalidRequestError
class InvalidRequestError(A2ABaseModel):
    """Ongeldig verzoek fout"""
    code: Literal[-32600] = -32600
    message: str | None = 'Request payload validation error'
    data: Any | None = None
MethodNotFoundError
class MethodNotFoundError(A2ABaseModel):
    """Methode niet gevonden fout"""
    code: Literal[-32601] = -32601
    message: str | None = 'Method not found'
    data: Any | None = None
InvalidParamsError
class InvalidParamsError(A2ABaseModel):
    """Ongeldige parameters fout"""
    code: Literal[-32602] = -32602
    message: str | None = 'Invalid parameters'
    data: Any | None = None
InternalError
class InternalError(A2ABaseModel):
    """Interne fout"""
    code: Literal[-32603] = -32603
    message: str | None = 'Internal error'
    data: Any | None = None

A2A-specifieke Fouten

TaskNotFoundError
class TaskNotFoundError(A2ABaseModel):
    """Taak niet gevonden fout"""
    code: Literal[-32001] = -32001
    message: str | None = 'Task not found'
    data: Any | None = None
TaskNotCancelableError
class TaskNotCancelableError(A2ABaseModel):
    """Taak niet annuleerbaar fout"""
    code: Literal[-32002] = -32002
    message: str | None = 'Task cannot be canceled'
    data: Any | None = None
PushNotificationNotSupportedError
class PushNotificationNotSupportedError(A2ABaseModel):
    """Push notificatie niet ondersteund fout"""
    code: Literal[-32003] = -32003
    message: str | None = 'Push Notification is not supported'
    data: Any | None = None
UnsupportedOperationError
class UnsupportedOperationError(A2ABaseModel):
    """Niet ondersteunde operatie fout"""
    code: Literal[-32004] = -32004
    message: str | None = 'This operation is not supported'
    data: Any | None = None
ContentTypeNotSupportedError
class ContentTypeNotSupportedError(A2ABaseModel):
    """Inhoudstype niet ondersteund fout"""
    code: Literal[-32005] = -32005
    message: str | None = 'Incompatible content types'
    data: Any | None = None
InvalidAgentResponseError
class InvalidAgentResponseError(A2ABaseModel):
    """Ongeldig agent antwoord fout"""
    code: Literal[-32006] = -32006
    message: str | None = 'Invalid agent response'
    data: Any | None = None

Beveiligingsauthenticatie-gerelateerde Typen

SecurityScheme (Union Type)

class SecurityScheme(RootModel[
    APIKeySecurityScheme |
    HTTPAuthSecurityScheme |
    OAuth2SecurityScheme |
    OpenIdConnectSecurityScheme
]):
    """Beveiligingsschema - ondersteunt meerdere authenticatiemethoden"""

APIKeySecurityScheme

class APIKeySecurityScheme(A2ABaseModel):
    """API sleutel beveiligingsschema"""
    type: Literal['apiKey'] = 'apiKey'
    name: str                              # Parameternaam
    in_: In                                # Locatie (header/query/cookie)
    description: str | None = None         # Beschrijving

HTTPAuthSecurityScheme

class HTTPAuthSecurityScheme(A2ABaseModel):
    """HTTP authenticatie beveiligingsschema"""
    type: Literal['http'] = 'http'
    scheme: str                            # Authenticatieschema (Basic, Bearer etc.)
    bearerFormat: str | None = None        # Bearer token formaat
    description: str | None = None         # Beschrijving

OAuth2SecurityScheme

class OAuth2SecurityScheme(A2ABaseModel):
    """OAuth2.0 beveiligingsschema"""
    type: Literal['oauth2'] = 'oauth2'
    flows: OAuthFlows                      # OAuth flow instellingen
    description: str | None = None         # Beschrijving

OpenIdConnectSecurityScheme

class OpenIdConnectSecurityScheme(A2ABaseModel):
    """OpenID Connect beveiligingsschema"""
    type: Literal['openIdConnect'] = 'openIdConnect'
    openIdConnectUrl: str                  # OpenID Connect discovery URL
    description: str | None = None         # Beschrijving

OAuth Flow Typen

OAuthFlows
class OAuthFlows(A2ABaseModel):
    """OAuth flow instellingen"""
    implicit: ImplicitOAuthFlow | None = None                    # Impliciete flow
    password: PasswordOAuthFlow | None = None                    # Wachtwoord flow
    clientCredentials: ClientCredentialsOAuthFlow | None = None  # Client credentials flow
    authorizationCode: AuthorizationCodeOAuthFlow | None = None  # Authorization code flow

Push Notificatie-gerelateerde Typen

PushNotificationConfig

class PushNotificationConfig(A2ABaseModel):
    """Push notificatie configuratie"""
    url: str                                                    # Push URL
    id: str | None = None                                       # Push notificatie ID
    token: str | None = None                                    # Sessietoken
    authentication: PushNotificationAuthenticationInfo | None = None  # Authenticatie informatie

PushNotificationAuthenticationInfo

class PushNotificationAuthenticationInfo(A2ABaseModel):
    """Push notificatie authenticatie informatie"""
    schemes: list[str]                     # Ondersteunde authenticatieschema's
    credentials: str | None = None         # Authenticatie informatie

Verzoek en Antwoord Typen

Bericht Verzending

SendMessageRequest
class SendMessageRequest(A2ABaseModel):
    """Bericht verzending verzoek"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['message/send'] = 'message/send'
    params: MessageSendParams
    id: str | int
MessageSendParams
class MessageSendParams(A2ABaseModel):
    """Bericht verzending parameters"""
    message: Message                                    # Te verzenden bericht
    configuration: MessageSendConfiguration | None = None  # Verzending instellingen
    metadata: dict[str, Any] | None = None             # Metadata
MessageSendConfiguration
class MessageSendConfiguration(A2ABaseModel):
    """Bericht verzending configuratie"""
    acceptedOutputModes: list[str]                          # Geaccepteerde uitvoermodi
    blocking: bool | None = None                            # Verzoek blokkeren of niet
    historyLength: int | None = None                        # Berichtgeschiedenis lengte
    pushNotificationConfig: PushNotificationConfig | None = None  # Push notificatie instellingen

Taak Operaties

GetTaskRequest
class GetTaskRequest(A2ABaseModel):
    """Taak ophaal verzoek"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['tasks/get'] = 'tasks/get'
    params: TaskQueryParams
    id: str | int
TaskQueryParams
class TaskQueryParams(A2ABaseModel):
    """Taak query parameters"""
    id: str                              # Taak-ID
    historyLength: int | None = None     # Geschiedenis lengte
    metadata: dict[str, Any] | None = None  # Metadata
CancelTaskRequest
class CancelTaskRequest(A2ABaseModel):
    """Taak annulering verzoek"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['tasks/cancel'] = 'tasks/cancel'
    params: TaskIdParams
    id: str | int

Gebeurtenistypen

TaskStatusUpdateEvent

class TaskStatusUpdateEvent(A2ABaseModel):
    """Taak status update gebeurtenis"""
    kind: Literal['status-update'] = 'status-update'
    taskId: str                              # Taak-ID
    contextId: str                           # Context-ID
    status: TaskStatus                       # Taakstatus
    final: bool                              # Finale gebeurtenis of niet
    metadata: dict[str, Any] | None = None   # Metadata

TaskArtifactUpdateEvent

class TaskArtifactUpdateEvent(A2ABaseModel):
    """Taak artefact update gebeurtenis"""
    kind: Literal['artifact-update'] = 'artifact-update'
    taskId: str                              # Taak-ID
    contextId: str                           # Context-ID
    artifact: Artifact                       # Artefact
    append: bool | None = None               # Toevoegen of niet
    lastChunk: bool | None = None            # Laatste chunk of niet
    metadata: dict[str, Any] | None = None   # Metadata

Objectrelatie Diagram

graph TB
    %% Hoofdentiteiten
    AgentCard[AgentCard<br/>Agentkaart]
    Task[Task<br/>Taak]
    Message[Message<br/>Bericht]
    
    %% Agent-gerelateerd
    AgentSkill[AgentSkill<br/>Agentvaardigheid]
    AgentCapabilities[AgentCapabilities<br/>Agentmogelijkheden]
    AgentProvider[AgentProvider<br/>Serviceprovider]
    AgentExtension[AgentExtension<br/>Agentuitbreiding]
    AgentInterface[AgentInterface<br/>Agentinterface]
    
    %% Berichtinhoud
    Part[Part<br/>Berichtdeel]
    TextPart[TextPart<br/>Tekstdeel]
    FilePart[FilePart<br/>Bestandsdeel]
    DataPart[DataPart<br/>Datadeel]
    
    %% Bestandstypen
    FileWithBytes[FileWithBytes<br/>Byte-bestand]
    FileWithUri[FileWithUri<br/>URI-bestand]
    
    %% Taak-gerelateerd
    TaskStatus[TaskStatus<br/>Taakstatus]
    Artifact[Artifact<br/>Artefact]
    
    %% JSON-RPC
    JSONRPCRequest[JSONRPCRequest<br/>JSON-RPC Verzoek]
    JSONRPCResponse[JSONRPCResponse<br/>JSON-RPC Antwoord]
    
    %% Beveiligingsauthenticatie
    SecurityScheme[SecurityScheme<br/>Beveiligingsschema]
    APIKeySecurityScheme[APIKeySecurityScheme<br/>API Sleutel Schema]
    HTTPAuthSecurityScheme[HTTPAuthSecurityScheme<br/>HTTP Auth Schema]
    OAuth2SecurityScheme[OAuth2SecurityScheme<br/>OAuth2 Schema]
    OpenIdConnectSecurityScheme[OpenIdConnectSecurityScheme<br/>OpenID Connect Schema]
    
    %% Push notificaties
    PushNotificationConfig[PushNotificationConfig<br/>Push Notificatie Configuratie]
    PushNotificationAuthenticationInfo[PushNotificationAuthenticationInfo<br/>Push Auth Informatie]
    
    %% Fouttypen
    A2AError[A2AError<br/>A2A Fout]
    JSONRPCError[JSONRPCError<br/>JSON-RPC Fout]
    
    %% Gebeurtenissen
    TaskStatusUpdateEvent[TaskStatusUpdateEvent<br/>Status Update Gebeurtenis]
    TaskArtifactUpdateEvent[TaskArtifactUpdateEvent<br/>Artefact Update Gebeurtenis]
    
    %% Relatieverbindingen
    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
    
    %% Stijlen
    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

Protocol Flow Diagram

sequenceDiagram
    participant Client as Client
    participant Agent as Agent
    
    Note over Client,Agent: 1. Agent ontdekking en mogelijkheden query
    Client->>Agent: GET /agent-card
    Agent->>Client: AgentCard (vaardigheden, mogelijkheden, beveiligingsvereisten)
    
    Note over Client,Agent: 2. Authenticatie (indien vereist)
    Client->>Agent: Authenticatie verzoek (volgens SecurityScheme)
    Agent->>Client: Authenticatie antwoord
    
    Note over Client,Agent: 3. Bericht verzending en taak creatie
    Client->>Agent: SendMessageRequest
    Note right of Agent: Taak creatie<br/>Status: submitted
    Agent->>Client: SendMessageResponse (Task)
    
    Note over Client,Agent: 4. Taak verwerking (optionele push notificatie)
    loop Taak Verwerking
        Note right of Agent: Taak status update<br/>working -> completed
        alt Push Notificatie Ondersteuning
            Agent->>Client: TaskStatusUpdateEvent
        else Polling Modus
            Client->>Agent: GetTaskRequest
            Agent->>Client: GetTaskResponse (bijgewerkte Task)
        end
    end
    
    Note over Client,Agent: 5. Finaal resultaat ophalen
    Client->>Agent: GetTaskRequest
    Agent->>Client: Task (met Artifacts en volledige geschiedenis)

Taak Status Overgang Diagram

stateDiagram-v2
    [*] --> submitted: Taak creatie
    
    submitted --> working: Verwerking begint
    submitted --> rejected: Taak afgewezen
    submitted --> auth_required: Authenticatie vereist
    
    working --> completed: Verwerking voltooid
    working --> failed: Verwerking mislukt
    working --> input_required: Gebruikersinvoer vereist
    working --> canceled: Gebruiker annulering
    
    input_required --> working: Gebruikersinvoer ontvangen
    input_required --> canceled: Gebruiker annulering
    
    auth_required --> working: Authenticatie succesvol
    auth_required --> rejected: Authenticatie mislukt
    
    completed --> [*]
    failed --> [*]
    canceled --> [*]
    rejected --> [*]
    
    unknown --> working: Status herstel
    unknown --> failed: Herstel onmogelijk

Bericht Deel Type Hiërarchie Diagram

flowchart TD
    Part["Part<br/>Berichtdeel Basisklasse"]
    
    Part --> TextPart["TextPart<br/>Tekstdeel<br/>kind: text"]
    Part --> FilePart["FilePart<br/>Bestandsdeel<br/>kind: file"]
    Part --> DataPart["DataPart<br/>Datadeel<br/>kind: data"]
    
    FilePart --> FileContent{"Bestandsinhoud"}
    FileContent --> FileWithBytes["FileWithBytes<br/>Bevat base64 byte data"]
    FileContent --> FileWithUri["FileWithUri<br/>Bevat bestand URI"]
    
    TextPart --> TextContent["text: str<br/>Tekstinhoud"]
    DataPart --> DataContent["data: dict[str, Any]<br/>Gestructureerde data"]
    
    FileWithBytes --> BytesContent["bytes: str<br/>base64-gecodeerde inhoud"]
    FileWithUri --> UriContent["uri: str<br/>Bestand URL"]
    
    %% Gemeenschappelijke eigenschappen
    Part --> Metadata["metadata: dict[str, Any]<br/>Optionele metadata"]
    FileWithBytes --> FileMetadata["name: str<br/>mimeType: str<br/>Bestandsmetadata"]
    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

Beveiligingsschema Type Diagram

flowchart TD
    SecurityScheme["SecurityScheme<br/>Beveiligingsschema Union Type"]
    
    SecurityScheme --> APIKeySecurityScheme["APIKeySecurityScheme<br/>API Sleutel Authenticatie<br/>type: apiKey"]
    SecurityScheme --> HTTPAuthSecurityScheme["HTTPAuthSecurityScheme<br/>HTTP Authenticatie<br/>type: http"]
    SecurityScheme --> OAuth2SecurityScheme["OAuth2SecurityScheme<br/>OAuth2 Authenticatie<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

Foutcode Mapping Tabel

Foutcode Fouttype Beschrijving Gebruikscase
-32700 JSONParseError JSON parsing fout Ongeldig JSON formaat
-32600 InvalidRequestError Ongeldig verzoek Verzoekformaat voldoet niet aan specificatie
-32601 MethodNotFoundError Methode niet gevonden Aanroep van niet-bestaande methode
-32602 InvalidParamsError Ongeldige parameters Methodeparameters niet correct
-32603 InternalError Interne fout Server interne verwerkingsfout
-32001 TaskNotFoundError Taak niet gevonden Gevraagde taak-ID bestaat niet
-32002 TaskNotCancelableError Taak niet annuleerbaar Taakstatus staat annulering niet toe
-32003 PushNotificationNotSupportedError Push notificatie niet ondersteund Agent ondersteunt geen push notificaties
-32004 UnsupportedOperationError Operatie niet ondersteund Agent ondersteunt gevraagde operatie niet
-32005 ContentTypeNotSupportedError Inhoudstype niet ondersteund Gevraagd inhoudstype komt niet overeen met agentmogelijkheden
-32006 InvalidAgentResponseError Ongeldig agent antwoord Agent heeft antwoord met verkeerd formaat geretourneerd

Lijst van Ondersteunde Methoden

Het A2A protocol definieert de volgende standaardmethoden:

Bericht-gerelateerde Methoden

  • message/send - Bericht naar agent verzenden
  • message/stream - Streaming bericht naar agent verzenden

Taak-gerelateerde Methoden

  • tasks/get - Taakdetails ophalen
  • tasks/cancel - Taak annuleren
  • tasks/resubscribe - Taak updates opnieuw abonneren

Push Notificatie Configuratie Methoden

  • tasks/pushNotificationConfig/set - Push notificatie configuratie instellen
  • tasks/pushNotificationConfig/get - Push notificatie configuratie ophalen
  • tasks/pushNotificationConfig/list - Push notificatie configuraties opsommen
  • tasks/pushNotificationConfig/delete - Push notificatie configuratie verwijderen

Gebruiksvoorbeelden

1. Eenvoudig tekstbericht verzenden

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

# Tekstberichtdeel maken
text_part = TextPart(text="Hallo, hoe kan ik u helpen?")
part = Part(root=text_part)

# Bericht maken
message = Message(
    messageId="msg-001",
    role="user",
    parts=[part]
)

# Verzendparameters maken
params = MessageSendParams(message=message)

# Verzoek maken
request = SendMessageRequest(
    id="req-001",
    params=params
)

2. Bericht met bestand verzenden

from a2a.types import FilePart, FileWithBytes
import base64

# Bestand lezen en coderen
with open("document.pdf", "rb") as f:
    file_bytes = base64.b64encode(f.read()).decode()

# Bestandsdeel maken
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)

# Bericht met bestand maken
message = Message(
    messageId="msg-002",
    role="user",
    parts=[part]
)

3. Taakstatus Query

from a2a.types import GetTaskRequest, TaskQueryParams

# Taak query verzoek maken
request = GetTaskRequest(
    id="req-002",
    params=TaskQueryParams(
        id="task-001",
        historyLength=10  # Nieuwste 10 berichtgeschiedenis ophalen
    )
)

4. Push Notificatie Configuratie

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

# Push notificatie configuratie maken
push_config = PushNotificationConfig(
    url="https://my-app.com/webhook/task-updates",
    authentication=PushNotificationAuthenticationInfo(
        schemes=["Bearer"],
        credentials="my-auth-token"
    )
)

# Taak push configuratie maken
task_push_config = TaskPushNotificationConfig(
    taskId="task-001",
    pushNotificationConfig=push_config
)

# Configuratie verzoek maken
request = SetTaskPushNotificationConfigRequest(
    id="req-003",
    params=task_push_config
)

Beste Praktijken

1. Foutafhandeling

  • Altijd het foutveld van het antwoord controleren
  • Passende herhalingsstrategie implementeren gebaseerd op foutcode
  • Betekenisvolle foutberichten voor gebruikers verstrekken

2. Taakbeheer

  • Push notificaties gebruiken in plaats van polling voor taak updates
  • Taak timeout mechanisme implementeren
  • Taak-ID's opslaan voor latere queries

3. Beveiliging

  • HTTPS transport gebruiken
  • Authenticatieschema's correct implementeren
  • API sleutels en tokens regelmatig roteren

4. Prestatie Optimalisatie

  • Streaming gebruiken voor grote antwoordverwerking
  • Berichtgeschiedenis lengte beperken
  • Client-side caching implementeren

Uitbreidbaarheid

Het A2A protocol ondersteunt uitbreidingen door de volgende mechanismen:

  1. Agent Uitbreidingen - Aangepaste mogelijkheden declareren via AgentExtension
  2. Metadata Velden - De meeste objecten bevatten een optioneel metadata veld
  3. Aangepaste Transport Protocollen - Ondersteuning van nieuwe transportmethoden via AgentInterface
  4. Uitbreidings-URI's - Referentie naar uitbreidingsspecificaties in berichten en artefacten

Samenvatting

Het A2A protocol biedt een uitgebreid framework voor communicatie en samenwerking tussen intelligente agenten. Gebaseerd op JSON-RPC 2.0 biedt het gestandaardiseerde berichtoverdracht, taakbeheer, beveiligingsauthenticatie en uitbreidingsmechanismen.

Hoofdkenmerken:

  • Gestandaardiseerde Communicatie: JSON-RPC 2.0-gebaseerd verzoek-antwoord patroon
  • Rijke Inhoudsondersteuning: Ondersteuning voor tekst, bestanden en gestructureerde data
  • Flexibele Beveiliging: Ondersteuning van meerdere authenticatiemethoden
  • Real-time Updates: Push notificatie mechanisme
  • Robuuste Foutafhandeling: Uitgebreide foutcodes en berichten
  • Goede Uitbreidbaarheid: Uitbreidingsmechanismen en metadata ondersteuning

Dit protocol biedt ontwikkelaars een solide basis voor het bouwen van krachtige agent-gebaseerde applicaties.