A2A Protocol

A2A Protocol Specification (Python)

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

Aperçu

Le protocole A2A (Agent2Agent) est un protocole de communication basé sur JSON-RPC 2.0 conçu pour l'interaction entre agents intelligents. Ce protocole définit les fonctionnalités principales incluant la déclaration de capacités d'agent, le passage de messages, la gestion des tâches, l'authentification de sécurité.

Ce document est basé sur le fichier a2a-python/src/a2a/types.py et fournit une introduction détaillée à toutes les structures de données et relations d'objets du protocole A2A.

Version du Protocole

Version actuelle du protocole : 0.2.5

Concepts Principaux

1. Agent

L'agent est l'entité principale du protocole A2A, possédant des compétences et capacités spécifiques pour traiter les demandes des utilisateurs et exécuter des tâches.

2. Tâche

La tâche est l'unité de travail exécutée par l'agent, caractérisée par la gestion du statut du cycle de vie et l'enregistrement de l'historique.

3. Message

Le message est l'unité de base pour l'échange d'informations entre l'utilisateur et l'agent, supportant plusieurs types de contenu.

4. JSON-RPC 2.0

Le protocole A2A est basé sur la norme JSON-RPC 2.0, fournissant un modèle de communication standardisé demande-réponse.

Détails des Structures de Données

Types de Base

A2A

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

Type racine du protocole, peut contenir toute donnée.

Role (énumération)

class Role(str, Enum):
    """Rôle de l'expéditeur du message"""
    agent = 'agent'  # Agent
    user = 'user'    # Utilisateur

TaskState (énumération)

class TaskState(str, Enum):
    """États possibles de la tâche"""
    submitted = 'submitted'           # Soumise
    working = 'working'               # En cours
    input_required = 'input-required' # Entrée requise
    completed = 'completed'           # Terminée
    canceled = 'canceled'             # Annulée
    failed = 'failed'                 # Échouée
    rejected = 'rejected'             # Rejetée
    auth_required = 'auth-required'   # Authentification requise
    unknown = 'unknown'               # État inconnu

Types Liés aux Agents

AgentCard

class AgentCard(A2ABaseModel):
    """Carte d'agent - contient les informations importantes de l'agent"""
    name: str                                    # Nom de l'agent
    description: str                             # Description de l'agent
    version: str                                 # Version de l'agent
    url: str                                     # URL de l'agent
    protocolVersion: str | None = '0.2.5'       # Version du protocole
    skills: list[AgentSkill]                     # Liste des compétences
    capabilities: AgentCapabilities              # Déclaration des capacités
    defaultInputModes: list[str]                 # Modes d'entrée par défaut
    defaultOutputModes: list[str]                # Modes de sortie par défaut
    provider: AgentProvider | None = None        # Fournisseur de service
    security: list[dict[str, list[str]]] | None = None  # Exigences de sécurité
    securitySchemes: dict[str, SecurityScheme] | None = None  # Schémas de sécurité
    # ... autres champs

AgentSkill

class AgentSkill(A2ABaseModel):
    """Compétence d'agent - unité de capacité exécutable par l'agent"""
    id: str                          # Identifiant unique de la compétence
    name: str                        # Nom de la compétence
    description: str                 # Description de la compétence
    tags: list[str]                  # Tags de la compétence
    examples: list[str] | None = None # Exemples d'utilisation
    inputModes: list[str] | None = None   # Modes d'entrée
    outputModes: list[str] | None = None  # Modes de sortie

AgentCapabilities

class AgentCapabilities(A2ABaseModel):
    """Définition des capacités de l'agent"""
    extensions: list[AgentExtension] | None = None      # Extensions supportées
    pushNotifications: bool | None = None               # Support des notifications push
    stateTransitionHistory: bool | None = None          # Historique des transitions d'état
    streaming: bool | None = None                       # Support du streaming

AgentExtension

class AgentExtension(A2ABaseModel):
    """Déclaration d'extension d'agent"""
    uri: str                                # URI de l'extension
    description: str | None = None          # Description de l'extension
    params: dict[str, Any] | None = None    # Paramètres de l'extension
    required: bool | None = None            # Requis ou non

AgentProvider

class AgentProvider(A2ABaseModel):
    """Fournisseur de service d'agent"""
    organization: str  # Nom de l'organisation
    url: str          # URL de l'organisation

AgentInterface

class AgentInterface(A2ABaseModel):
    """Déclaration d'interface d'agent"""
    transport: str  # Protocole de transport (JSONRPC, GRPC, HTTP+JSON)
    url: str       # URL de l'interface

Types Liés aux Messages

Message

class Message(A2ABaseModel):
    """Messages échangés entre l'utilisateur et l'agent"""
    messageId: str                           # ID du message
    role: Role                               # Rôle de l'expéditeur
    parts: list[Part]                        # Parties du contenu du message
    kind: Literal['message'] = 'message'     # Type d'événement
    taskId: str | None = None                # ID de tâche associé
    contextId: str | None = None             # ID de contexte
    referenceTaskIds: list[str] | None = None # Liste des ID de tâches référencées
    extensions: list[str] | None = None       # Liste des URI d'extension
    metadata: dict[str, Any] | None = None    # Métadonnées

Part (type union)

class Part(RootModel[TextPart | FilePart | DataPart]):
    """Partie de message - texte, fichier ou données structurées"""
    root: TextPart | FilePart | DataPart

TextPart

class TextPart(A2ABaseModel):
    """Partie de message texte"""
    kind: Literal['text'] = 'text'           # Type de partie
    text: str                                # Contenu texte
    metadata: dict[str, Any] | None = None   # Métadonnées

FilePart

class FilePart(A2ABaseModel):
    """Partie de message fichier"""
    kind: Literal['file'] = 'file'           # Type de partie
    file: FileWithBytes | FileWithUri        # Contenu du fichier
    metadata: dict[str, Any] | None = None   # Métadonnées

DataPart

class DataPart(A2ABaseModel):
    """Partie de message données structurées"""
    kind: Literal['data'] = 'data'           # Type de partie
    data: dict[str, Any]                     # Données structurées
    metadata: dict[str, Any] | None = None   # Métadonnées

Types de Fichiers

FileWithBytes
class FileWithBytes(A2ABaseModel):
    """Fichier avec contenu en bytes"""
    bytes: str                        # Contenu du fichier encodé en base64
    name: str | None = None           # Nom du fichier
    mimeType: str | None = None       # Type MIME
FileWithUri
class FileWithUri(A2ABaseModel):
    """Fichier avec URI"""
    uri: str                          # URL du fichier
    name: str | None = None           # Nom du fichier
    mimeType: str | None = None       # Type MIME

Types Liés aux Tâches

Task

class Task(A2ABaseModel):
    """Entité de tâche"""
    id: str                                  # Identifiant unique de la tâche
    contextId: str                           # ID de contexte
    status: TaskStatus                       # Statut de la tâche
    kind: Literal['task'] = 'task'           # Type d'événement
    history: list[Message] | None = None     # Historique des messages
    artifacts: list[Artifact] | None = None  # Artefacts générés
    metadata: dict[str, Any] | None = None   # Métadonnées

TaskStatus

class TaskStatus(A2ABaseModel):
    """Statut de la tâche et message associé"""
    state: TaskState                         # État de la tâche
    message: Message | None = None           # Message de mise à jour du statut
    timestamp: str | None = None             # Horodatage (ISO 8601)

Artifact

class Artifact(A2ABaseModel):
    """Artefact généré par la tâche"""
    artifactId: str                          # ID de l'artefact
    parts: list[Part]                        # Parties du contenu de l'artefact
    name: str | None = None                  # Nom de l'artefact
    description: str | None = None           # Description de l'artefact
    extensions: list[str] | None = None      # Liste des URI d'extension
    metadata: dict[str, Any] | None = None   # Métadonnées

Types Liés à JSON-RPC

JSONRPCMessage (classe de base)

class JSONRPCMessage(A2ABaseModel):
    """Classe de base des messages JSON-RPC 2.0"""
    jsonrpc: Literal['2.0'] = '2.0'          # Version du protocole
    id: str | int | None = None              # ID de demande/réponse

JSONRPCRequest

class JSONRPCRequest(A2ABaseModel):
    """Objet de demande JSON-RPC 2.0"""
    jsonrpc: Literal['2.0'] = '2.0'          # Version du protocole
    method: str                              # Nom de la méthode
    params: dict[str, Any] | None = None     # Paramètres
    id: str | int | None = None              # ID de demande

JSONRPCSuccessResponse

class JSONRPCSuccessResponse(A2ABaseModel):
    """Objet de réponse de succès JSON-RPC 2.0"""
    jsonrpc: Literal['2.0'] = '2.0'          # Version du protocole
    result: Any                              # Données de résultat
    id: str | int | None = None              # ID de réponse

JSONRPCErrorResponse

class JSONRPCErrorResponse(A2ABaseModel):
    """Objet de réponse d'erreur JSON-RPC 2.0"""
    jsonrpc: Literal['2.0'] = '2.0'          # Version du protocole
    error: JSONRPCError | [specific error type]      # Informations d'erreur
    id: str | int | None = None              # ID de réponse

Types d'Erreurs

Le protocole A2A définit plusieurs types d'erreurs, tous hérités des erreurs JSON-RPC standard :

Erreurs JSON-RPC Standard

JSONParseError
class JSONParseError(A2ABaseModel):
    """Erreur d'analyse JSON"""
    code: Literal[-32700] = -32700
    message: str | None = 'Invalid JSON payload'
    data: Any | None = None
InvalidRequestError
class InvalidRequestError(A2ABaseModel):
    """Erreur de demande invalide"""
    code: Literal[-32600] = -32600
    message: str | None = 'Request payload validation error'
    data: Any | None = None
MethodNotFoundError
class MethodNotFoundError(A2ABaseModel):
    """Erreur méthode non trouvée"""
    code: Literal[-32601] = -32601
    message: str | None = 'Method not found'
    data: Any | None = None
InvalidParamsError
class InvalidParamsError(A2ABaseModel):
    """Erreur de paramètres invalides"""
    code: Literal[-32602] = -32602
    message: str | None = 'Invalid parameters'
    data: Any | None = None
InternalError
class InternalError(A2ABaseModel):
    """Erreur interne"""
    code: Literal[-32603] = -32603
    message: str | None = 'Internal error'
    data: Any | None = None

Erreurs Spécifiques A2A

TaskNotFoundError
class TaskNotFoundError(A2ABaseModel):
    """Erreur tâche non trouvée"""
    code: Literal[-32001] = -32001
    message: str | None = 'Task not found'
    data: Any | None = None
TaskNotCancelableError
class TaskNotCancelableError(A2ABaseModel):
    """Erreur tâche non annulable"""
    code: Literal[-32002] = -32002
    message: str | None = 'Task cannot be canceled'
    data: Any | None = None
PushNotificationNotSupportedError
class PushNotificationNotSupportedError(A2ABaseModel):
    """Erreur notification push non supportée"""
    code: Literal[-32003] = -32003
    message: str | None = 'Push Notification is not supported'
    data: Any | None = None
UnsupportedOperationError
class UnsupportedOperationError(A2ABaseModel):
    """Erreur opération non supportée"""
    code: Literal[-32004] = -32004
    message: str | None = 'This operation is not supported'
    data: Any | None = None
ContentTypeNotSupportedError
class ContentTypeNotSupportedError(A2ABaseModel):
    """Erreur type de contenu non supporté"""
    code: Literal[-32005] = -32005
    message: str | None = 'Incompatible content types'
    data: Any | None = None
InvalidAgentResponseError
class InvalidAgentResponseError(A2ABaseModel):
    """Erreur réponse d'agent invalide"""
    code: Literal[-32006] = -32006
    message: str | None = 'Invalid agent response'
    data: Any | None = None

Types Liés à l'Authentification de Sécurité

SecurityScheme (type union)

class SecurityScheme(RootModel[
    APIKeySecurityScheme |
    HTTPAuthSecurityScheme |
    OAuth2SecurityScheme |
    OpenIdConnectSecurityScheme
]):
    """Schéma de sécurité - supporte plusieurs méthodes d'authentification"""

APIKeySecurityScheme

class APIKeySecurityScheme(A2ABaseModel):
    """Schéma de sécurité par clé API"""
    type: Literal['apiKey'] = 'apiKey'
    name: str                              # Nom du paramètre
    in_: In                                # Emplacement (header/query/cookie)
    description: str | None = None         # Description

HTTPAuthSecurityScheme

class HTTPAuthSecurityScheme(A2ABaseModel):
    """Schéma de sécurité d'authentification HTTP"""
    type: Literal['http'] = 'http'
    scheme: str                            # Schéma d'authentification (Basic, Bearer, etc.)
    bearerFormat: str | None = None        # Format du token Bearer
    description: str | None = None         # Description

OAuth2SecurityScheme

class OAuth2SecurityScheme(A2ABaseModel):
    """Schéma de sécurité OAuth2.0"""
    type: Literal['oauth2'] = 'oauth2'
    flows: OAuthFlows                      # Configuration des flux OAuth
    description: str | None = None         # Description

OpenIdConnectSecurityScheme

class OpenIdConnectSecurityScheme(A2ABaseModel):
    """Schéma de sécurité OpenID Connect"""
    type: Literal['openIdConnect'] = 'openIdConnect'
    openIdConnectUrl: str                  # URL de découverte OpenID Connect
    description: str | None = None         # Description

Types de Flux OAuth

OAuthFlows
class OAuthFlows(A2ABaseModel):
    """Configuration des flux OAuth"""
    implicit: ImplicitOAuthFlow | None = None                    # Flux implicite
    password: PasswordOAuthFlow | None = None                    # Flux par mot de passe
    clientCredentials: ClientCredentialsOAuthFlow | None = None  # Flux par identifiants client
    authorizationCode: AuthorizationCodeOAuthFlow | None = None  # Flux par code d'autorisation

Types Liés aux Notifications Push

PushNotificationConfig

class PushNotificationConfig(A2ABaseModel):
    """Configuration des notifications push"""
    url: str                                                    # URL push
    id: str | None = None                                       # ID de notification push
    token: str | None = None                                    # Token de session
    authentication: PushNotificationAuthenticationInfo | None = None  # Informations d'authentification

PushNotificationAuthenticationInfo

class PushNotificationAuthenticationInfo(A2ABaseModel):
    """Informations d'authentification des notifications push"""
    schemes: list[str]                     # Schémas d'authentification supportés
    credentials: str | None = None         # Informations d'authentification

Types de Demandes et Réponses

Envoi de Messages

SendMessageRequest
class SendMessageRequest(A2ABaseModel):
    """Demande d'envoi de message"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['message/send'] = 'message/send'
    params: MessageSendParams
    id: str | int
MessageSendParams
class MessageSendParams(A2ABaseModel):
    """Paramètres d'envoi de message"""
    message: Message                                    # Message à envoyer
    configuration: MessageSendConfiguration | None = None  # Configuration d'envoi
    metadata: dict[str, Any] | None = None             # Métadonnées
MessageSendConfiguration
class MessageSendConfiguration(A2ABaseModel):
    """Configuration d'envoi de message"""
    acceptedOutputModes: list[str]                          # Modes de sortie acceptés
    blocking: bool | None = None                            # Bloquer la demande ou non
    historyLength: int | None = None                        # Longueur de l'historique des messages
    pushNotificationConfig: PushNotificationConfig | None = None  # Configuration des notifications push

Opérations sur les Tâches

GetTaskRequest
class GetTaskRequest(A2ABaseModel):
    """Demande d'obtention de tâche"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['tasks/get'] = 'tasks/get'
    params: TaskQueryParams
    id: str | int
TaskQueryParams
class TaskQueryParams(A2ABaseModel):
    """Paramètres de requête de tâche"""
    id: str                              # ID de tâche
    historyLength: int | None = None     # Longueur de l'historique
    metadata: dict[str, Any] | None = None  # Métadonnées
CancelTaskRequest
class CancelTaskRequest(A2ABaseModel):
    """Demande d'annulation de tâche"""
    jsonrpc: Literal['2.0'] = '2.0'
    method: Literal['tasks/cancel'] = 'tasks/cancel'
    params: TaskIdParams
    id: str | int

Types d'Événements

TaskStatusUpdateEvent

class TaskStatusUpdateEvent(A2ABaseModel):
    """Événement de mise à jour du statut de tâche"""
    kind: Literal['status-update'] = 'status-update'
    taskId: str                              # ID de tâche
    contextId: str                           # ID de contexte
    status: TaskStatus                       # Statut de la tâche
    final: bool                              # Événement final ou non
    metadata: dict[str, Any] | None = None   # Métadonnées

TaskArtifactUpdateEvent

class TaskArtifactUpdateEvent(A2ABaseModel):
    """Événement de mise à jour d'artefact de tâche"""
    kind: Literal['artifact-update'] = 'artifact-update'
    taskId: str                              # ID de tâche
    contextId: str                           # ID de contexte
    artifact: Artifact                       # Artefact
    append: bool | None = None               # Ajouter ou non
    lastChunk: bool | None = None            # Dernier chunk ou non
    metadata: dict[str, Any] | None = None   # Métadonnées

Diagramme de Relations d'Objets

graph TB
    %% Entités principales
    AgentCard[AgentCard<br/>Carte d'Agent]
    Task[Task<br/>Tâche]
    Message[Message<br/>Message]
    
    %% Liés aux agents
    AgentSkill[AgentSkill<br/>Compétence d'Agent]
    AgentCapabilities[AgentCapabilities<br/>Capacités d'Agent]
    AgentProvider[AgentProvider<br/>Fournisseur de Service]
    AgentExtension[AgentExtension<br/>Extension d'Agent]
    AgentInterface[AgentInterface<br/>Interface d'Agent]
    
    %% Contenu des messages
    Part[Part<br/>Partie de Message]
    TextPart[TextPart<br/>Partie Texte]
    FilePart[FilePart<br/>Partie Fichier]
    DataPart[DataPart<br/>Partie Données]
    
    %% Types de fichiers
    FileWithBytes[FileWithBytes<br/>Fichier Bytes]
    FileWithUri[FileWithUri<br/>Fichier URI]
    
    %% Liés aux tâches
    TaskStatus[TaskStatus<br/>Statut de Tâche]
    Artifact[Artifact<br/>Artefact]
    
    %% JSON-RPC
    JSONRPCRequest[JSONRPCRequest<br/>Demande JSON-RPC]
    JSONRPCResponse[JSONRPCResponse<br/>Réponse JSON-RPC]
    
    %% Authentification de sécurité
    SecurityScheme[SecurityScheme<br/>Schéma de Sécurité]
    APIKeySecurityScheme[APIKeySecurityScheme<br/>Schéma Clé API]
    HTTPAuthSecurityScheme[HTTPAuthSecurityScheme<br/>Schéma Auth HTTP]
    OAuth2SecurityScheme[OAuth2SecurityScheme<br/>Schéma OAuth2]
    OpenIdConnectSecurityScheme[OpenIdConnectSecurityScheme<br/>Schéma OpenID Connect]
    
    %% Notifications push
    PushNotificationConfig[PushNotificationConfig<br/>Config Notification Push]
    PushNotificationAuthenticationInfo[PushNotificationAuthenticationInfo<br/>Info Auth Push]
    
    %% Types d'erreurs
    A2AError[A2AError<br/>Erreur A2A]
    JSONRPCError[JSONRPCError<br/>Erreur JSON-RPC]
    
    %% Événements
    TaskStatusUpdateEvent[TaskStatusUpdateEvent<br/>Événement Mise à Jour Statut]
    TaskArtifactUpdateEvent[TaskArtifactUpdateEvent<br/>Événement Mise à Jour Artefact]
    
    %% Connexions de relations
    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
    
    %% Styles
    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

Diagramme de Flux du Protocole

sequenceDiagram
    participant Client as Client
    participant Agent as Agent
    
    Note over Client,Agent: 1. Découverte d'agent et requête de capacités
    Client->>Agent: GET /agent-card
    Agent->>Client: AgentCard (compétences, capacités, exigences de sécurité)
    
    Note over Client,Agent: 2. Authentification (si nécessaire)
    Client->>Agent: Demande d'authentification (selon SecurityScheme)
    Agent->>Client: Réponse d'authentification
    
    Note over Client,Agent: 3. Envoi de message et création de tâche
    Client->>Agent: SendMessageRequest
    Note right of Agent: Création de tâche<br/>Statut: submitted
    Agent->>Client: SendMessageResponse (Task)
    
    Note over Client,Agent: 4. Traitement de tâche (notification push optionnelle)
    loop Traitement de tâche
        Note right of Agent: Mise à jour statut tâche<br/>working -> completed
        alt Support notification push
            Agent->>Client: TaskStatusUpdateEvent
        else Mode polling
            Client->>Agent: GetTaskRequest
            Agent->>Client: GetTaskResponse (Task mise à jour)
        end
    end
    
    Note over Client,Agent: 5. Obtention du résultat final
    Client->>Agent: GetTaskRequest
    Agent->>Client: Task (avec Artifacts et historique complet)

Diagramme de Transition d'État des Tâches

stateDiagram-v2
    [*] --> submitted: Création de tâche
    
    submitted --> working: Début du traitement
    submitted --> rejected: Tâche rejetée
    submitted --> auth_required: Authentification requise
    
    working --> completed: Traitement terminé
    working --> failed: Traitement échoué
    working --> input_required: Entrée utilisateur requise
    working --> canceled: Annulation utilisateur
    
    input_required --> working: Entrée utilisateur reçue
    input_required --> canceled: Annulation utilisateur
    
    auth_required --> working: Authentification réussie
    auth_required --> rejected: Authentification échouée
    
    completed --> [*]
    failed --> [*]
    canceled --> [*]
    rejected --> [*]
    
    unknown --> working: Récupération d'état
    unknown --> failed: Récupération impossible

Diagramme de Hiérarchie des Types de Parties de Message

flowchart TD
    Part["Part<br/>Classe de base partie de message"]
    
    Part --> TextPart["TextPart<br/>Partie texte<br/>kind: text"]
    Part --> FilePart["FilePart<br/>Partie fichier<br/>kind: file"]
    Part --> DataPart["DataPart<br/>Partie données<br/>kind: data"]
    
    FilePart --> FileContent{"Contenu fichier"}
    FileContent --> FileWithBytes["FileWithBytes<br/>Contient données bytes base64"]
    FileContent --> FileWithUri["FileWithUri<br/>Contient URI fichier"]
    
    TextPart --> TextContent["text: str<br/>Contenu texte"]
    DataPart --> DataContent["data: dict[str, Any]<br/>Données structurées"]
    
    FileWithBytes --> BytesContent["bytes: str<br/>Contenu encodé base64"]
    FileWithUri --> UriContent["uri: str<br/>URL fichier"]
    
    %% Propriétés communes
    Part --> Metadata["metadata: dict[str, Any]<br/>Métadonnées optionnelles"]
    FileWithBytes --> FileMetadata["name: str<br/>mimeType: str<br/>Métadonnées fichier"]
    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

Diagramme des Types de Schémas de Sécurité

flowchart TD
    SecurityScheme["SecurityScheme<br/>Type union schéma de sécurité"]
    
    SecurityScheme --> APIKeySecurityScheme["APIKeySecurityScheme<br/>Authentification par clé API<br/>type: apiKey"]
    SecurityScheme --> HTTPAuthSecurityScheme["HTTPAuthSecurityScheme<br/>Authentification HTTP<br/>type: http"]
    SecurityScheme --> OAuth2SecurityScheme["OAuth2SecurityScheme<br/>Authentification 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

Tableau de Mappage des Codes d'Erreur

Code d'Erreur Type d'Erreur Description Cas d'Usage
-32700 JSONParseError Erreur d'analyse JSON Format JSON invalide
-32600 InvalidRequestError Demande invalide Format de demande non conforme aux spécifications
-32601 MethodNotFoundError Méthode non trouvée Appel de méthode inexistante
-32602 InvalidParamsError Paramètres invalides Paramètres de méthode incorrects
-32603 InternalError Erreur interne Erreur de traitement interne du serveur
-32001 TaskNotFoundError Tâche non trouvée ID de tâche demandé inexistant
-32002 TaskNotCancelableError Tâche non annulable État de tâche ne permettant pas l'annulation
-32003 PushNotificationNotSupportedError Notification push non supportée Agent ne supportant pas les notifications push
-32004 UnsupportedOperationError Opération non supportée Agent ne supportant pas l'opération demandée
-32005 ContentTypeNotSupportedError Type de contenu non supporté Type de contenu demandé ne correspondant pas aux capacités de l'agent
-32006 InvalidAgentResponseError Réponse d'agent invalide Agent ayant retourné une réponse de format incorrect

Liste des Méthodes Supportées

Le protocole A2A définit les méthodes standard suivantes :

Méthodes Liées aux Messages

  • message/send - Envoyer un message à l'agent
  • message/stream - Envoyer un message en streaming à l'agent

Méthodes Liées aux Tâches

  • tasks/get - Obtenir les détails d'une tâche
  • tasks/cancel - Annuler une tâche
  • tasks/resubscribe - Se réabonner aux mises à jour de tâche

Méthodes de Configuration des Notifications Push

  • tasks/pushNotificationConfig/set - Définir la configuration des notifications push
  • tasks/pushNotificationConfig/get - Obtenir la configuration des notifications push
  • tasks/pushNotificationConfig/list - Lister les configurations des notifications push
  • tasks/pushNotificationConfig/delete - Supprimer la configuration des notifications push

Exemples d'Usage

1. Envoyer un Message Texte Simple

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

# Créer une partie de message texte
text_part = TextPart(text="Bonjour, comment puis-je vous aider ?")
part = Part(root=text_part)

# Créer un message
message = Message(
    messageId="msg-001",
    role="user",
    parts=[part]
)

# Créer les paramètres d'envoi
params = MessageSendParams(message=message)

# Créer la demande
request = SendMessageRequest(
    id="req-001",
    params=params
)

2. Envoyer un Message avec Fichier

from a2a.types import FilePart, FileWithBytes
import base64

# Lire et encoder le fichier
with open("document.pdf", "rb") as f:
    file_bytes = base64.b64encode(f.read()).decode()

# Créer une partie fichier
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)

# Créer un message avec fichier
message = Message(
    messageId="msg-002",
    role="user",
    parts=[part]
)

3. Requête de Statut de Tâche

from a2a.types import GetTaskRequest, TaskQueryParams

# Créer une demande de requête de tâche
request = GetTaskRequest(
    id="req-002",
    params=TaskQueryParams(
        id="task-001",
        historyLength=10  # Obtenir les 10 derniers messages d'historique
    )
)

4. Configuration des Notifications Push

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

# Créer la configuration des notifications push
push_config = PushNotificationConfig(
    url="https://my-app.com/webhook/task-updates",
    authentication=PushNotificationAuthenticationInfo(
        schemes=["Bearer"],
        credentials="my-auth-token"
    )
)

# Créer la configuration push de tâche
task_push_config = TaskPushNotificationConfig(
    taskId="task-001",
    pushNotificationConfig=push_config
)

# Créer la demande de configuration
request = SetTaskPushNotificationConfigRequest(
    id="req-003",
    params=task_push_config
)

Meilleures Pratiques

1. Gestion des Erreurs

  • Toujours vérifier le champ d'erreur de la réponse
  • Implémenter une stratégie de nouvelle tentative appropriée basée sur le code d'erreur
  • Fournir des messages d'erreur significatifs à l'utilisateur

2. Gestion des Tâches

  • Utiliser les notifications push plutôt que le polling pour les mises à jour de tâche
  • Implémenter un mécanisme de timeout pour les tâches
  • Sauvegarder les ID de tâche pour les requêtes ultérieures

3. Sécurité

  • Utiliser le transport HTTPS
  • Implémenter correctement les schémas d'authentification
  • Faire tourner régulièrement les clés API et tokens

4. Optimisation des Performances

  • Utiliser le streaming pour le traitement de grandes réponses
  • Limiter la longueur de l'historique des messages
  • Implémenter la mise en cache côté client

Extensibilité

Le protocole A2A supporte l'extension à travers les mécanismes suivants :

  1. Extensions d'Agent - Déclarer des capacités personnalisées via AgentExtension
  2. Champs de Métadonnées - La plupart des objets incluent un champ metadata optionnel
  3. Protocoles de Transport Personnalisés - Support de nouvelles méthodes de transport via AgentInterface
  4. URI d'Extension - Référencer des spécifications d'extension dans les messages et artefacts

Résumé

Le protocole A2A fournit un cadre complet pour la communication et la collaboration entre agents intelligents. Basé sur JSON-RPC 2.0, il offre un passage de messages standardisé, une gestion des tâches, une authentification de sécurité et des mécanismes d'extensibilité.

Caractéristiques principales :

  • Communication Standardisée : Modèle demande-réponse basé sur JSON-RPC 2.0
  • Support de Contenu Riche : Support pour texte, fichiers et données structurées
  • Sécurité Flexible : Support de multiples méthodes d'authentification
  • Mises à Jour en Temps Réel : Mécanisme de notifications push
  • Gestion d'Erreurs Robuste : Codes d'erreur et messages complets
  • Bonne Extensibilité : Mécanismes d'extension et support de métadonnées

Ce protocole fournit aux développeurs une base solide pour construire des applications puissantes basées sur des agents.