개요

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 프로토콜은 지능형 에이전트 간의 통신과 협력을 위한 포괄적인 프레임워크를 제공합니다. 표준화된 메시지 형식, 작업 관리, 보안 인증, 오류 처리를 통해 이 프로토콜은 서로 다른 에이전트 구현 간의 상호 운용성을 보장합니다.

프로토콜의 설계는 확장성과 하위 호환성을 고려하여 미래의 요구사항 변화에 적응할 수 있습니다. 여러 콘텐츠 타입, 전송 프로토콜, 인증 스킴을 지원함으로써 A2A 프로토콜은 복잡한 에이전트 생태계를 구축하기 위한 견고한 기반을 제공합니다.

A2A Specification