Overview

The OPVS Protocol is an open standard designed to facilitate communication and interoperability between independent, potentially opaque AI agent systems. In an ecosystem where agents might be built using different frameworks, languages, or by different vendors, OPVS provides a common language and interaction model. This document provides the detailed technical specification for the OPVS protocol. Its primary goal is to enable agents to:

• Discover each other's capabilities.
• Negotiate interaction modalities (text, files, structured data).
• Manage collaborative tasks.
• Securely exchange information to achieve user goals without needing access to each other's internal state, memory, or tools.

• Interoperability: Bridge the communication gap between disparate agentic systems.
• Collaboration: Enable agents to delegate tasks, exchange context, and work together on complex user requests.
• Discovery: Allow agents to dynamically find and understand the capabilities of other agents.
• Flexibility: Support various interaction modes including synchronous request/response, streaming for real-time updates, and asynchronous push notifications for long-running tasks.
• Security: Facilitate secure communication patterns suitable for enterprise environments, relying on standard web security practices.
• Asynchronicity: Natively support long-running tasks and interactions that may involve human-in-the-loop scenarios.

For a broader understanding of OPVS's purpose and benefits, see What is OPVS?.

• Simple: Reuse existing, well-understood standards (HTTP, JSON-RPC 2.0, Server-Sent Events).
• Enterprise Ready: Address authentication, authorization, security, privacy, tracing, and monitoring by aligning with established enterprise practices.
• Async First: Designed for (potentially very) long-running tasks and human-in-the-loop interactions.
• Modality Agnostic: Support exchange of diverse content types including text, audio/video (via file references), structured data/forms, and potentially embedded UI components (e.g., iframes referenced in parts).
• Opaque Execution: Agents collaborate based on declared capabilities and exchanged information, without needing to share their internal thoughts, plans, or tool implementations.

This specification is organized into three distinct layers that work together to provide a complete protocol definition:

graph TB subgraph L1 ["OPVS Data Model"] direction LR A[Task] ~~~ B[Message] ~~~ C[AgentCard] ~~~ D[Part] ~~~ E[Artifact] ~~~ F[Extension] end subgraph L2 ["OPVS Operations"] direction LR G[Send Message] ~~~ H[Stream Message] ~~~ I[Get Task] ~~~ J[List Tasks] ~~~ K[Cancel Task] ~~~ L[Get Agent Card] end subgraph L3 ["Protocol Bindings"] direction LR M[JSON-RPC Methods] ~~~ N[gRPC RPCs] ~~~ O[HTTP/REST Endpoints] ~~~ P[Custom Bindings] end %% Dependencies between layers L1 --> L2 L2 --> L3 style A fill:#e1f5fe style B fill:#e1f5fe style C fill:#e1f5fe style D fill:#e1f5fe style E fill:#e1f5fe style F fill:#e1f5fe style G fill:#f3e5f5 style H fill:#f3e5f5 style I fill:#f3e5f5 style J fill:#f3e5f5 style K fill:#f3e5f5 style L fill:#f3e5f5 style M fill:#e8f5e8 style N fill:#e8f5e8 style O fill:#e8f5e8 style L1 fill:#f0f8ff,stroke:#333,stroke-width:2px style L2 fill:#faf0ff,stroke:#333,stroke-width:2px style L3 fill:#f0fff0,stroke:#333,stroke-width:2px

graph TB subgraph L1 ["OPVS Data Model"] direction LR A[Task] ~~~ B[Message] ~~~ C[AgentCard] ~~~ D[Part] ~~~ E[Artifact] ~~~ F[Extension] end subgraph L2 ["OPVS Operations"] direction LR G[Send Message] ~~~ H[Stream Message] ~~~ I[Get Task] ~~~ J[List Tasks] ~~~ K[Cancel Task] ~~~ L[Get Agent Card] end subgraph L3 ["Protocol Bindings"] direction LR M[JSON-RPC Methods] ~~~ N[gRPC RPCs] ~~~ O[HTTP/REST Endpoints] ~~~ P[Custom Bindings] end %% Dependencies between layers L1 --> L2 L2 --> L3 style A fill:#e1f5fe style B fill:#e1f5fe style C fill:#e1f5fe style D fill:#e1f5fe style E fill:#e1f5fe style F fill:#e1f5fe style G fill:#f3e5f5 style H fill:#f3e5f5 style I fill:#f3e5f5 style J fill:#f3e5f5 style K fill:#f3e5f5 style L fill:#f3e5f5 style M fill:#e8f5e8 style N fill:#e8f5e8 style O fill:#e8f5e8 style L1 fill:#f0f8ff,stroke:#333,stroke-width:2px style L2 fill:#faf0ff,stroke:#333,stroke-width:2px style L3 fill:#f0fff0,stroke:#333,stroke-width:2px

Layer 1: Canonical Data Model defines the core data structures and message formats that all OPVS implementations must understand. These are protocol agnostic definitions expressed as Protocol Buffer messages. Layer 2: Abstract Operations describes the fundamental capabilities and behaviors that OPVS agents must support, independent of how they are exposed over specific protocols. Layer 3: Protocol Bindings provides concrete mappings of the abstract operations and data structures to specific protocol bindings (JSON-RPC, gRPC, HTTP/REST), including method names, endpoint patterns, and protocol-specific behaviors. This layered approach ensures that:

• Core semantics remain consistent across all protocol bindings
• New protocol bindings can be added without changing the fundamental data model
• Developers can reason about OPVS operations independently of binding concerns
• Interoperability is maintained through shared understanding of the canonical data model

In addition to the protocol requirements defined in this document, the file spec/a2a.proto is the single authoritative normative definition of all protocol data objects and request/response messages. A generated JSON artifact (spec/a2a.json, produced at build time and not committed) MAY be published for convenience to tooling and the website, but it is a non-normative build artifact. SDK language bindings, schemas, and any other derived forms MUST be regenerated from the proto (directly or via code generation) rather than edited manually.

spec/a2a.proto

spec/a2a.json

Change Control and Deprecation Lifecycle:

Automated Generation: The documentation build generates specification/json/a2a.json on-the-fly (the file is not tracked in source control). Future improvements may publish an OpenAPI v3 + JSON Schema bundle for enhanced tooling.

• Introduction: When a proto message or field is renamed, the new name is added while existing published names remain available, but marked deprecated, until the next major release.
• Documentation: Migration guidance MUST be provided via an ancillary document when introducing major breaking changes.
• Anchors: Legacy documentation anchors MUST be preserved (as hidden HTML anchors) to avoid breaking inbound links.
• SDK/Schema Aliases: SDKs and JSON Schemas SHOULD provide deprecated alias types/definitions to maintain backward compatibility.
• Removal: A deprecated name SHOULD NOT be removed earlier than the next major version after introduction of its replacement.

specification/json/a2a.json

Rationale: Centering the proto file as the normative source ensures protocol neutrality, reduces specification drift, and provides a deterministic evolution path for the ecosystem.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

OPVS revolves around several key concepts. For detailed explanations, please refer to the Key Concepts guide.

• OPVS Client: An application or agent that initiates requests to an OPVS Server on behalf of a user or another system.
• OPVS Server (Remote Agent): An agent or agentic system that exposes an OPVS-compliant endpoint, processing tasks and providing responses.
• Agent Card: A JSON metadata document published by an OPVS Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements.
• Message: A communication turn between a client and a remote agent, having a role ("user" or "agent") and containing one or more Parts.
• Task: The fundamental unit of work managed by OPVS, identified by a unique ID. Tasks are stateful and progress through a defined lifecycle.
• Part: The smallest unit of content within a Message or Artifact. Parts can contain text, file references, or structured data.
• Artifact: An output (e.g., a document, image, structured data) generated by the agent as a result of a task, composed of Parts.
• Streaming: Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via protocol-specific streaming mechanisms.
• Push Notifications: Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios.
• Context: An optional identifier to logically group related tasks and messages.
• Extension: A mechanism for agents to provide additional functionality or data beyond the core OPVS specification.

role

Parts

Parts

This section describes the core operations of the OPVS protocol in a binding-independent manner. These operations define the fundamental capabilities that all OPVS implementations must support, regardless of the underlying binding mechanism.

The following operations define the fundamental capabilities that all OPVS implementations must support, independent of the specific protocol binding used. For a quick reference mapping of these operations to protocol-specific method names and endpoints, see Section 5.3 (Method Mapping Reference). For detailed protocol-specific implementation details, see:

• Section 9: JSON-RPC Protocol Binding
• Section 10: gRPC Protocol Binding
• Section 11: HTTP+JSON/REST Protocol Binding

The primary operation for initiating agent interactions. Clients send a message to an agent and receive either a task that tracks the processing or a direct response message. Inputs:

• SendMessageRequest: Request object containing the message, configuration, and metadata

SendMessageRequest

Outputs:

• Task: A task object representing the processing of the message, OR
• Message: A direct response message (for simple interactions that don't require task tracking)

Task

Message

Errors:

• ContentTypeNotSupportedError: A Media Type provided in the request's message parts is not supported by the agent.
• UnsupportedOperationError: Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages.
• TaskNotFoundError: The task ID does not exist or is not accessible.

ContentTypeNotSupportedError

UnsupportedOperationError

TaskNotFoundError

Behavior: The agent MAY create a new Task to process the provided message asynchronously or MAY return a direct Message response for simple interactions. The operation MUST return immediately with either task information or response message. Task processing MAY continue asynchronously after the response when a Task is returned.

Task

Message

Task

Similar to Send Message but with real-time streaming of updates during processing. Inputs:

• SendMessageRequest: Request object containing the message, configuration, and metadata

SendMessageRequest

Outputs:

• Stream Response object containing:

Initial response: Task object OR Message object Subsequent events following a Task MAY include stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects

• Initial response: Task object OR Message object
• Subsequent events following a Task MAY include stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects
• Final completion indicator

Stream Response

• Initial response: Task object OR Message object
• Subsequent events following a Task MAY include stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects

Task

Message

Task

TaskStatusUpdateEvent

TaskArtifactUpdateEvent

Errors:

• UnsupportedOperationError: Streaming is not supported by the agent (see Capability Validation).
• UnsupportedOperationError: Messages sent to Tasks that are in a terminal state (e.g., completed, canceled, rejected) cannot accept further messages.
• ContentTypeNotSupportedError: A Media Type provided in the request's message parts is not supported by the agent.
• TaskNotFoundError: The task ID does not exist or is not accessible.

UnsupportedOperationError

UnsupportedOperationError

ContentTypeNotSupportedError

TaskNotFoundError

Behavior: The operation MUST establish a streaming connection for real-time updates. The stream MUST follow one of these patterns: 1. Message-only stream: If the agent returns a Message, the stream MUST contain exactly one Message object and then close immediately. No task tracking or updates are provided.

2. Task lifecycle stream: If the agent returns a Task, the stream MUST begin with the Task object, followed by zero or more TaskStatusUpdateEvent or TaskArtifactUpdateEvent objects. The stream MUST close when the task reaches a terminal state (e.g. completed, failed, canceled, rejected).

Message-only stream: If the agent returns a Message, the stream MUST contain exactly one Message object and then close immediately. No task tracking or updates are provided.

Message

Message

Task lifecycle stream: If the agent returns a Task, the stream MUST begin with the Task object, followed by zero or more TaskStatusUpdateEvent or TaskArtifactUpdateEvent objects. The stream MUST close when the task reaches a terminal state (e.g. completed, failed, canceled, rejected).

Task

TaskStatusUpdateEvent

TaskArtifactUpdateEvent

The agent MAY return a Task for complex processing with status/artifact updates or MAY return a Message for direct streaming responses without task overhead. The implementation MUST provide immediate feedback on progress and intermediate results.

Task

Message

Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task. This is typically used for polling the status of a task initiated with message/send, or for fetching the final state of a task after being notified via a push notification or after a stream has ended. Inputs: Represents a request for the GetTask method.

GetTask

tenant

string

id

string

historyLength

integer

See History Length Semantics for details about historyLength.

historyLength

Outputs:

• Task: Current state and artifacts of the requested task

Task

Errors:

• TaskNotFoundError: The task ID does not exist or is not accessible.

TaskNotFoundError

Retrieves a list of tasks with optional filtering and pagination capabilities. This method allows clients to discover and manage multiple tasks across different contexts or with specific status criteria. Inputs: Parameters for listing tasks with optional filtering criteria.

tenant

string

contextId

string

status

TaskState

pageSize

integer

pageToken

string

ListTasks

ListTasksResponse.next_page_token

historyLength

integer

statusTimestampAfter

timestamp

includeArtifacts

boolean

When includeArtifacts is false (the default), the artifacts field MUST be omitted entirely from each Task object in the response. The field should not be present as an empty array or null value. When includeArtifacts is true, the artifacts field should be included with its actual content (which may be an empty array if the task has no artifacts).

includeArtifacts

includeArtifacts

Outputs: Result object for ListTasks method containing an array of tasks and pagination information.

ListTasks

tasks

Task

nextPageToken

string

pageSize

integer

totalSize

integer

Note on nextPageToken: The nextPageToken field MUST always be present in the response. When there are no more results to retrieve (i.e., this is the final page), the field MUST be set to an empty string (""). Clients should check for an empty string to determine if more pages are available.

nextPageToken

nextPageToken

Errors: None specific to this operation beyond standard protocol errors. Behavior:

The operation MUST return only tasks visible to the authenticated client and MUST use cursor-based pagination for performance and consistency. Tasks MUST be sorted by last update time in descending order. Implementations MUST implement appropriate authorization scoping to ensure clients can only access authorized tasks. See Section 13.1 Data Access and Authorization Scoping for detailed security requirements. Pagination Strategy: This method uses cursor-based pagination (via pageToken/nextPageToken) rather than offset-based pagination for better performance and consistency, especially with large datasets. Cursor-based pagination avoids the "deep pagination problem" where skipping large numbers of records becomes inefficient for databases. This approach is consistent with the gRPC specification, which also uses cursor-based pagination (page_token/next_page_token).

pageToken

nextPageToken

Ordering: Implementations MUST return tasks sorted by their status timestamp time in descending order (most recently updated tasks first). This ensures consistent pagination and allows clients to efficiently monitor recent task activity.

Requests the cancellation of an ongoing task. The server will attempt to cancel the task, but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage). Inputs: Represents a request for the CancelTask method.

CancelTask

tenant

string

id

string

metadata

object

Outputs:

• Updated Task with cancellation status

Task

Errors:

• TaskNotCancelableError: The task is not in a cancelable state (e.g., already completed, failed, or canceled).
• TaskNotFoundError: The task ID does not exist or is not accessible.

TaskNotCancelableError

TaskNotFoundError

Behavior: The operation attempts to cancel the specified task and returns its updated state.

Establishes a streaming connection to receive updates for an existing task. Inputs: Represents a request for the SubscribeToTask method.

SubscribeToTask

tenant

string

id

string

Outputs:

Initial response: Task object with current state Stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects

• Stream Response object containing:

• Initial response: Task object with current state
• Stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects

Stream Response

• Initial response: Task object with current state
• Stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent objects

Task

TaskStatusUpdateEvent

TaskArtifactUpdateEvent

Errors:

• UnsupportedOperationError: Streaming is not supported by the agent (see Capability Validation).
• TaskNotFoundError: The task ID does not exist or is not accessible.
• UnsupportedOperationError: The operation is attempted on a task that is in a terminal state (completed, failed, canceled, or rejected).

UnsupportedOperationError

TaskNotFoundError

UnsupportedOperationError

completed

failed

canceled

rejected

Behavior: The operation enables real-time monitoring of task progress and can be used with any task that is not in a terminal state. The stream MUST terminate when the task reaches a terminal state (completed, failed, canceled, or rejected).

completed

failed

canceled

rejected

The operation MUST return a Task object as the first event in the stream, representing the current state of the task at the time of subscription. This prevents a potential loss of information between a call to GetTask and calling SubscribeToTask.

Task

GetTask

SubscribeToTask

Creates a push notification configuration for a task to receive asynchronous updates via webhook. Inputs: Error: Message CreateTaskPushNotificationConfigRequest not found.

CreateTaskPushNotificationConfigRequest

Outputs:

• PushNotificationConfig: Created configuration with assigned ID

PushNotificationConfig

Errors:

• PushNotificationNotSupportedError: Push notifications are not supported by the agent (see Capability Validation).
• TaskNotFoundError: The task ID does not exist or is not accessible.

PushNotificationNotSupportedError

TaskNotFoundError

Behavior: The operation MUST establish a webhook endpoint for task update notifications. When task updates occur, the agent will send HTTP POST requests to the configured webhook URL with StreamResponse payloads (see Push Notification Payload for details). This operation is only available if the agent supports push notifications capability. The configuration MUST persist until task completion or explicit deletion.

StreamResponse

Retrieves an existing push notification configuration for a task. Inputs: Represents a request for the GetTaskPushNotificationConfig method.

GetTaskPushNotificationConfig

tenant

string

taskId

string

id

string

Outputs:

• PushNotificationConfig: The requested configuration

PushNotificationConfig

Errors:

• PushNotificationNotSupportedError: Push notifications are not supported by the agent (see Capability Validation).
• TaskNotFoundError: The push notification configuration does not exist.

PushNotificationNotSupportedError

TaskNotFoundError

Behavior: The operation MUST return configuration details including webhook URL and notification settings. The operation MUST fail if the configuration does not exist or the client lacks access.

Retrieves all push notification configurations for a task. Inputs: Represents a request for the ListTaskPushNotificationConfigs method.

ListTaskPushNotificationConfigs

tenant

string

taskId

string

pageSize

integer

pageToken

string

ListTaskPushNotificationConfigsRequest

Outputs: Represents a successful response for the ListTaskPushNotificationConfigs method.

ListTaskPushNotificationConfigs

configs

TaskPushNotificationConfig

nextPageToken

string

Errors:

• PushNotificationNotSupportedError: Push notifications are not supported by the agent (see Capability Validation).
• TaskNotFoundError: The task ID does not exist or is not accessible.

PushNotificationNotSupportedError

TaskNotFoundError

Behavior: The operation MUST return all active push notification configurations for the specified task and MAY support pagination for tasks with many configurations.

Removes a push notification configuration for a task. Inputs: Represents a request for the DeleteTaskPushNotificationConfig method.

DeleteTaskPushNotificationConfig

tenant

string

taskId

string

id

string

Outputs:

Errors:

• Confirmation of deletion (implementation-specific)
• PushNotificationNotSupportedError: Push notifications are not supported by the agent (see Capability Validation).
• TaskNotFoundError: The task ID does not exist.

PushNotificationNotSupportedError

TaskNotFoundError

Behavior:

The operation MUST permanently remove the specified push notification configuration. No further notifications will be sent to the configured webhook after deletion. This operation MUST be idempotent - multiple deletions of the same config have the same effect.

Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if AgentCard.capabilities.extendedAgentCard is true.

AgentCard.capabilities.extendedAgentCard

true

Inputs: Represents a request for the GetExtendedAgentCard method.

GetExtendedAgentCard

tenant

string

Outputs:

• AgentCard: A complete Agent Card object, which may contain additional details or skills not present in the public card

AgentCard

Errors:

• UnsupportedOperationError: The agent does not support authenticated extended cards (see Capability Validation).
• ExtendedAgentCardNotConfiguredError: The agent declares support but does not have an extended agent card configured.

UnsupportedOperationError

ExtendedAgentCardNotConfiguredError

Behavior:

• Authentication: The client MUST authenticate the request using one of the schemes declared in the public AgentCard.securitySchemes and AgentCard.security fields.
• Extended Information: The operation MAY return different details based on client authentication level, including additional skills, capabilities, or configuration not available in the public Agent Card.
• Card Replacement: Clients retrieving this extended card SHOULD replace their cached public Agent Card with the content received from this endpoint for the duration of their authenticated session or until the card's version changes.
• Availability: This operation is only available if the public Agent Card declares capabilities.extendedAgentCard: true.

AgentCard.securitySchemes

AgentCard.security

capabilities.extendedAgentCard: true

For detailed security guidance on extended agent cards, see Section 13.3 Extended Agent Card Access Control.

This section defines common parameter objects used across multiple operations.

Represents a request for the SendMessage method.

SendMessage

tenant

string

message

Message

configuration

SendMessageConfiguration

metadata

object

Configuration of a send message request.

acceptedOutputModes

string

taskPushNotificationConfig

TaskPushNotificationConfig

SendMessage

historyLength

integer

returnImmediately

boolean

true

false

COMPLETED

FAILED

CANCELED

REJECTED

INPUT_REQUIRED

AUTH_REQUIRED

Execution Mode: The return_immediately field in SendMessageConfiguration controls whether the operation returns immediately or waits for task completion. Operations are blocking by default:

return_immediately

SendMessageConfiguration

- Blocking (return_immediately: false or unset): The operation MUST wait until the task reaches a terminal state (COMPLETED, FAILED, CANCELED, REJECTED) or an interrupted state (INPUT_REQUIRED, AUTH_REQUIRED) before returning. The response MUST include the latest task state with all artifacts and status information. This is the default behavior.

- Non-Blocking (return_immediately: true): The operation MUST return immediately after creating the task, even if processing is still in progress. The returned task will have an in-progress state (e.g., working, input_required). It is the caller's responsibility to poll for updates using Get Task, subscribe via Subscribe to Task, or receive updates via push notifications.

Blocking (return_immediately: false or unset): The operation MUST wait until the task reaches a terminal state (COMPLETED, FAILED, CANCELED, REJECTED) or an interrupted state (INPUT_REQUIRED, AUTH_REQUIRED) before returning. The response MUST include the latest task state with all artifacts and status information. This is the default behavior.

return_immediately: false

COMPLETED

FAILED

CANCELED

REJECTED

INPUT_REQUIRED

AUTH_REQUIRED

Non-Blocking (return_immediately: true): The operation MUST return immediately after creating the task, even if processing is still in progress. The returned task will have an in-progress state (e.g., working, input_required). It is the caller's responsibility to poll for updates using Get Task, subscribe via Subscribe to Task, or receive updates via push notifications.

return_immediately: true

working

input_required

The return_immediately field has no effect:

return_immediately

• when the operation returns a direct Message response instead of a task.
• for streaming operations, which always return updates in real-time.
• on configured push notification configurations, which operates independently of execution mode.

Message

A wrapper object used in streaming operations to encapsulate different types of response data.

task

Task

message

Message

statusUpdate

TaskStatusUpdateEvent

artifactUpdate

TaskArtifactUpdateEvent

Note: A StreamResponse MUST contain exactly one of the following: task, message, statusUpdate, artifactUpdate

StreamResponse

task

message

statusUpdate

artifactUpdate

This wrapper allows streaming endpoints to return different types of updates through a single response stream while maintaining type safety.

The historyLength parameter appears in multiple operations and controls how much task history is returned in responses. This parameter follows consistent semantics across all operations:

historyLength

• Unset/undefined: No limit imposed; server returns its default amount of history (implementation-defined, may be all history)
• 0: No history should be returned; the history field SHOULD be omitted
• > 0: Return at most this many recent messages from the task's history

history

A flexible key-value map for passing additional context or parameters with operations. Metadata keys and are strings and values can be any valid value that can be represented in JSON. Extensions can be used to strongly type metadata values for specific use cases.

Extensions

A key-value map for passing horizontally applicable context or parameters with case-insensitive string keys and case-sensitive string values. The transmission mechanism for these service parameter key-value pairs is defined by the specific protocol binding (e.g., HTTP headers for HTTP-based bindings, gRPC metadata for gRPC bindings). Custom protocol bindings MUST specify how service parameters are transmitted in their binding specification. Standard OPVS Service Parameters:

OPVS-Extensions

https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1

OPVS-Version

VersionNotSupportedError

0.3

As service parameter names MAY need to co-exist with other parameters defined by the underlying transport protocol or infrastructure, all service parameters defined by this specification will be prefixed with a2a-.

a2a-

• Get operations (Get Task, List Tasks, Get Extended Agent Card) are naturally idempotent
• Send Message operations MAY be idempotent. Agents may utilize the messageId to detect duplicate messages.
• Cancel Task operations are idempotent - multiple cancellation requests have the same effect. A duplicate cancellation request MAY return TaskNotFoundError if the task has already been canceled and purged.

TaskNotFoundError

All operations may return errors in the following categories. Servers MUST return appropriate errors and SHOULD provide actionable information to help clients resolve issues. Error Categories and Server Requirements: - Authentication Errors: Invalid or missing credentials

Servers MUST reject requests with invalid or missing authentication credentials Servers SHOULD include authentication challenge information in the error response Servers SHOULD specify which authentication scheme is required Example error codes: HTTP 401 Unauthorized, gRPC UNAUTHENTICATED, JSON-RPC custom error Example scenarios: Missing bearer token, expired API key, invalid OAuth token

- Authorization Errors: Insufficient permissions for requested operation

• Servers MUST reject requests with invalid or missing authentication credentials
• Servers SHOULD include authentication challenge information in the error response
• Servers SHOULD specify which authentication scheme is required
• Example error codes: HTTP 401 Unauthorized, gRPC UNAUTHENTICATED, JSON-RPC custom error
• Example scenarios: Missing bearer token, expired API key, invalid OAuth token

Servers MUST return an authorization error when the authenticated client lacks required permissions Servers SHOULD indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access) Servers MUST NOT reveal the existence of resources the client is not authorized to access Example error codes: HTTP 403 Forbidden, gRPC PERMISSION_DENIED, JSON-RPC custom error Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes

- Validation Errors: Invalid input parameters or message format

• Servers MUST return an authorization error when the authenticated client lacks required permissions
• Servers SHOULD indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access)
• Servers MUST NOT reveal the existence of resources the client is not authorized to access
• Example error codes: HTTP 403 Forbidden, gRPC PERMISSION_DENIED, JSON-RPC custom error
• Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes

Servers MUST validate all input parameters before processing Servers SHOULD specify which parameter(s) failed validation and why Servers SHOULD provide guidance on valid parameter values or formats Example error codes: HTTP 400 Bad Request, gRPC INVALID_ARGUMENT, JSON-RPC -32602 Invalid params Example scenarios: Invalid task ID format, missing required message parts, unsupported content type

- Resource Errors: Requested task not found or not accessible

• Servers MUST validate all input parameters before processing
• Servers SHOULD specify which parameter(s) failed validation and why
• Servers SHOULD provide guidance on valid parameter values or formats
• Example error codes: HTTP 400 Bad Request, gRPC INVALID_ARGUMENT, JSON-RPC -32602 Invalid params
• Example scenarios: Invalid task ID format, missing required message parts, unsupported content type

Servers MUST return a not found error when a requested resource does not exist or is not accessible to the authenticated client Servers SHOULD NOT distinguish between "does not exist" and "not authorized" to prevent information leakage Example error codes: HTTP 404 Not Found, gRPC NOT_FOUND, JSON-RPC custom error (see OPVS-specific errors) Example scenarios: Task ID does not exist, task has been deleted, configuration not found

- System Errors: Internal agent failures or temporary unavailability

• Servers MUST return a not found error when a requested resource does not exist or is not accessible to the authenticated client
• Servers SHOULD NOT distinguish between "does not exist" and "not authorized" to prevent information leakage
• Example error codes: HTTP 404 Not Found, gRPC NOT_FOUND, JSON-RPC custom error (see OPVS-specific errors)
• Example scenarios: Task ID does not exist, task has been deleted, configuration not found

Servers SHOULD return appropriate error codes for temporary failures vs. permanent errors Servers MAY include retry guidance (e.g., Retry-After header in HTTP) Servers SHOULD log system errors for diagnostic purposes Example error codes: HTTP 500 Internal Server Error or 503 Service Unavailable, gRPC INTERNAL or UNAVAILABLE, JSON-RPC -32603 Internal error Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded

Authentication Errors: Invalid or missing credentials

• Servers SHOULD return appropriate error codes for temporary failures vs. permanent errors
• Servers MAY include retry guidance (e.g., Retry-After header in HTTP)
• Servers SHOULD log system errors for diagnostic purposes
• Example error codes: HTTP 500 Internal Server Error or 503 Service Unavailable, gRPC INTERNAL or UNAVAILABLE, JSON-RPC -32603 Internal error
• Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded
• Servers MUST reject requests with invalid or missing authentication credentials
• Servers SHOULD include authentication challenge information in the error response
• Servers SHOULD specify which authentication scheme is required
• Example error codes: HTTP 401 Unauthorized, gRPC UNAUTHENTICATED, JSON-RPC custom error
• Example scenarios: Missing bearer token, expired API key, invalid OAuth token

401 Unauthorized

UNAUTHENTICATED

Authorization Errors: Insufficient permissions for requested operation

• Servers MUST return an authorization error when the authenticated client lacks required permissions
• Servers SHOULD indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access)
• Servers MUST NOT reveal the existence of resources the client is not authorized to access
• Example error codes: HTTP 403 Forbidden, gRPC PERMISSION_DENIED, JSON-RPC custom error
• Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes

403 Forbidden

PERMISSION_DENIED

Validation Errors: Invalid input parameters or message format

• Servers MUST validate all input parameters before processing
• Servers SHOULD specify which parameter(s) failed validation and why
• Servers SHOULD provide guidance on valid parameter values or formats
• Example error codes: HTTP 400 Bad Request, gRPC INVALID_ARGUMENT, JSON-RPC -32602 Invalid params
• Example scenarios: Invalid task ID format, missing required message parts, unsupported content type

400 Bad Request

INVALID_ARGUMENT

-32602 Invalid params

Resource Errors: Requested task not found or not accessible

• Servers MUST return a not found error when a requested resource does not exist or is not accessible to the authenticated client
• Servers SHOULD NOT distinguish between "does not exist" and "not authorized" to prevent information leakage
• Example error codes: HTTP 404 Not Found, gRPC NOT_FOUND, JSON-RPC custom error (see OPVS-specific errors)
• Example scenarios: Task ID does not exist, task has been deleted, configuration not found

404 Not Found

NOT_FOUND

System Errors: Internal agent failures or temporary unavailability

• Servers SHOULD return appropriate error codes for temporary failures vs. permanent errors
• Servers MAY include retry guidance (e.g., Retry-After header in HTTP)
• Servers SHOULD log system errors for diagnostic purposes
• Example error codes: HTTP 500 Internal Server Error or 503 Service Unavailable, gRPC INTERNAL or UNAVAILABLE, JSON-RPC -32603 Internal error
• Example scenarios: Database connection failure, downstream service timeout, rate limit exceeded

500 Internal Server Error

503 Service Unavailable

INTERNAL

UNAVAILABLE

-32603 Internal error

Error Payload Structure: All error responses in the OPVS protocol, regardless of binding, MUST convey the following information:

Affected fields or parameters Contextual information (e.g., task ID, timestamp) Suggestions for resolution

Protocol bindings MUST map these elements to their native error representations while preserving semantic meaning. See binding-specific sections for concrete error format examples: JSON-RPC Error Handling, gRPC Error Handling, and HTTP/REST Error Handling. OPVS-Specific Errors:

• Affected fields or parameters
• Contextual information (e.g., task ID, timestamp)
• Suggestions for resolution

TaskNotFoundError

TaskNotCancelableError

completed

failed

canceled

PushNotificationNotSupportedError

AgentCard.capabilities.pushNotifications

false

UnsupportedOperationError

ContentTypeNotSupportedError

InvalidAgentResponseError

ExtendedAgentCardNotConfiguredError

ExtensionSupportRequiredError

required: true

VersionNotSupportedError

OPVS-Version

OPVS operations are designed for asynchronous task execution. Operations return immediately with either Task objects or Message objects, and when a Task is returned, processing continues in the background. Clients retrieve task updates through polling, streaming, or push notifications (see Section 3.5). Agents MAY accept additional messages for tasks in non-terminal states to enable multi-turn interactions (see Section 3.4).

Task

Message

Agents declare optional capabilities in their AgentCard. When clients attempt to use operations or features that require capabilities not declared as supported in the Agent Card, the agent MUST return an appropriate error response:

AgentCard

• Push Notifications: If AgentCard.capabilities.pushNotifications is false or not present, operations related to push notification configuration (Create, Get, List, Delete) MUST return PushNotificationNotSupportedError.
• Streaming: If AgentCard.capabilities.streaming is false or not present, attempts to use SendStreamingMessage or SubscribeToTask operations MUST return UnsupportedOperationError.
• Extended Agent Card: If AgentCard.capabilities.extendedAgentCard is false or not present, attempts to call the Get Extended Agent Card operation MUST return UnsupportedOperationError. If the agent declares support but has not configured an extended card, it MUST return ExtendedAgentCardNotConfiguredError.
• Extensions: When a server requests use of an extension marked as required: true in the Agent Card but the client does not declare support for it, the agent MUST return ExtensionSupportRequiredError.

AgentCard.capabilities.pushNotifications

false

PushNotificationNotSupportedError

AgentCard.capabilities.streaming

false

SendStreamingMessage

SubscribeToTask

UnsupportedOperationError

AgentCard.capabilities.extendedAgentCard

false

UnsupportedOperationError

ExtendedAgentCardNotConfiguredError

required: true

ExtensionSupportRequiredError

Clients SHOULD validate capability support by examining the Agent Card before attempting operations that require optional capabilities.

The OPVS protocol supports multi-turn conversations through context identifiers and task references, enabling agents to maintain conversational continuity across multiple interactions.

A contextId is an identifier that logically groups multiple related Task and Message objects, providing continuity across a series of interactions.

contextId

Task

Message

Generation and Assignment:

• Agents MAY generate a new contextId when processing a Message that does not include a contextId field
• If an agent generates a new contextId, it MUST be included in the response (either Task or Message)
• Agents MAY accept and preserve client-provided contextId values
• If an agent cannot accept a client-provided contextId, it MUST reject the request with an error and MUST NOT generate a new contextId for the response
• Clients SHOULD NOT provide a client-generated contextId to a server unless they understand how the server will process that contextId
• Server-generated contextId values SHOULD be treated as opaque identifiers by clients

contextId

Message

contextId

contextId

Task

Message

contextId

contextId

contextId

contextId

contextId

contextId

Grouping and Scope:

• A contextId logically groups multiple Task objects and Message objects that are part of the same conversational context
• All tasks and messages with the same contextId SHOULD be treated as part of the same conversational session
• Agents MAY use the contextId to maintain internal state, conversational history, or LLM context across multiple interactions
• Agents MAY implement context expiration or cleanup policies and SHOULD document any such policies

contextId

Task

Message

contextId

contextId

A taskId is a unique identifier for a Task object, representing a stateful unit of work with a defined lifecycle.

taskId

Task

Generation and Assignment:

• Task IDs are server-generated when a new task is created in response to a Message
• Agents MUST generate a unique taskId for each new task they create
• The generated taskId MUST be included in the Task object returned to the client
• When a client includes a taskId in a Message, it MUST reference an existing task
• Agents MUST return a TaskNotFoundError if the provided taskId does not correspond to an existing task
• Client-provided taskId values for creating new tasks is NOT supported

Message

taskId

taskId

Task

taskId

Message

TaskNotFoundError

taskId

taskId

The OPVS protocol supports several patterns for multi-turn interactions: Context Continuity:

• Task objects maintain conversation context through the contextId field
• Clients MAY include the contextId in subsequent messages to indicate continuation of a previous interaction
• Clients MAY use taskId (with or without contextId) to continue or refine a specific task
• Clients MAY use contextId without taskId to start a new task within an existing conversation context
• Agents MUST infer contextId from the task if only taskId is provided
• Agents MUST reject messages containing mismatching contextId and taskId (i.e., the provided contextId is different from that of the referenced Task).

Task

contextId

contextId

taskId

contextId

contextId

taskId

contextId

taskId

contextId

taskId

contextId

Task

Input Required State:

• Agents can request additional input mid-processing by transitioning a task to the input-required state
• The client continues the interaction by sending a new message with the same taskId and contextId

input-required

taskId

contextId

Follow-up Messages:

• Clients can send additional messages with taskId references to continue or refine existing tasks
• Clients SHOULD use the referenceTaskIds field in Message to explicitly reference related tasks
• Agents SHOULD use referenced tasks to understand the context and intent of follow-up requests

taskId

referenceTaskIds

Message

Context Inheritance:

• New tasks created within the same contextId can inherit context from previous interactions
• Agents SHOULD leverage the shared contextId to provide contextually relevant responses

contextId

contextId

The OPVS protocol provides three complementary mechanisms for clients to receive updates about task progress and completion.

Polling (Get Task):

Streaming:

• Client periodically calls Get Task (Section 3.1.3) to check task status
• Simple to implement, works with all protocol bindings
• Higher latency, potential for unnecessary requests
• Best for: Simple integrations, infrequent updates, clients behind restrictive firewalls
• Real-time delivery of events as they occur
• Operations: Stream Message (Section 3.1.2) and Subscribe to Task (Section 3.1.6)
• Low latency, efficient for frequent updates
• Requires persistent connection support
• Best for: Interactive applications, real-time dashboards, live progress monitoring
• Requires AgentCard.capabilities.streaming to be true

AgentCard.capabilities.streaming

true

Push Notifications (WebHooks):

• Agent sends HTTP POST requests to client-registered endpoints when task state changes
• Client does not maintain persistent connection
• Asynchronous delivery, client must be reachable via HTTP
• Best for: Server-to-server integrations, long-running tasks, event-driven architectures
• Operations: Create (Section 3.1.7), Get (Section 3.1.8), List (Section 3.1.9), Delete (Section 3.1.10)
• Event types: TaskStatusUpdateEvent (Section 4.2.1), TaskArtifactUpdateEvent (Section 4.2.2), WebHook payloads (Section 4.3)
• Requires AgentCard.capabilities.pushNotifications to be true
• Regardless of the protocol binding being used by the agent, WebHook calls use plain HTTP and the JSON payloads as defined in the HTTP protocol binding

AgentCard.capabilities.pushNotifications

true

Event Ordering: All implementations MUST deliver events in the order they were generated. Events MUST NOT be reordered during transmission, regardless of protocol binding. Multiple Streams Per Task: An agent MAY serve multiple concurrent streams to one or more clients for the same task. This allows multiple clients (or the same client with multiple connections) to independently subscribe to and receive updates about a task's progress. When multiple streams are active for a task:

• Events MUST be broadcast to all active streams for that task
• Each stream MUST receive the same events in the same order

This capability enables scenarios such as:

• Closing one stream MUST NOT affect other active streams for the same task
• The task lifecycle is independent of any individual stream's lifecycle
• Multiple team members monitoring the same long-running task
• A client reconnecting to a task after a network interruption by opening a new stream
• Different applications or dashboards displaying real-time updates for the same task

Push notifications are delivered via HTTP POST to client-registered webhook endpoints. The delivery semantics and reliability guarantees are defined in Section 4.3.

The specific version of the OPVS protocol in use is identified using the Major.Minor elements (e.g. 1.0) of the corresponding OPVS specification version. Patch version numbers used by the specification, do not affect protocol compatibility. Patch version numbers SHOULD NOT be used in requests, responses and Agent Cards, and MUST not be considered when clients and servers negotiate protocol versions.

Major.Minor

1.0

Clients MUST send the OPVS-Version header with each request to maintain compatibility after an agent upgrades to a new version of the protocol (except for 0.3 Clients - 0.3 will be assumed for empty header). Sending the OPVS-Version header also provides visibility to agents about version usage in the ecosystem, which can help inform the risks of inplace version upgrades.

OPVS-Version

OPVS-Version

Example of HTTP GET Request with Version Header:

https://a2a-protocol.org/latest/specification#__codelineno-0-5https://a2a-protocol.org/latest/specification#__codelineno-0-4https://a2a-protocol.org/latest/specification#__codelineno-0-3https://a2a-protocol.org/latest/specification#__codelineno-0-2https://a2a-protocol.org/latest/specification#__codelineno-0-1GET /tasks/task-123 HTTP/1.1 Host: agent.example.com OPVS-Version: 1.0 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json

https://a2a-protocol.org/latest/specification#__codelineno-0-5https://a2a-protocol.org/latest/specification#__codelineno-0-4https://a2a-protocol.org/latest/specification#__codelineno-0-3https://a2a-protocol.org/latest/specification#__codelineno-0-2https://a2a-protocol.org/latest/specification#__codelineno-0-1GET /tasks/task-123 HTTP/1.1 Host: agent.example.com OPVS-Version: 1.0 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json

Clients MAY provide the OPVS-Version as a request parameter instead of a header.

OPVS-Version

Example of HTTP GET Request with Version request parameter:

https://a2a-protocol.org/latest/specification#__codelineno-1-4https://a2a-protocol.org/latest/specification#__codelineno-1-3https://a2a-protocol.org/latest/specification#__codelineno-1-2https://a2a-protocol.org/latest/specification#__codelineno-1-1GET /tasks/task-123?OPVS-Version=1.0 HTTP/1.1 Host: agent.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json

https://a2a-protocol.org/latest/specification#__codelineno-1-4https://a2a-protocol.org/latest/specification#__codelineno-1-3https://a2a-protocol.org/latest/specification#__codelineno-1-2https://a2a-protocol.org/latest/specification#__codelineno-1-1GET /tasks/task-123?OPVS-Version=1.0 HTTP/1.1 Host: agent.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json

Agents MUST process requests using the semantics of the requested OPVS-Version (matching Major.Minor). If the version is not supported by the interface, agents MUST return a VersionNotSupportedError.

OPVS-Version

Major.Minor

VersionNotSupportedError

Agents MUST interpret empty value as 0.3 version. Agents CAN expose multiple interfaces for the same transport with different versions under the same or different URLs.

Tooling libraries and SDKs that implement the OPVS protocol MUST provide mechanisms to help clients manage protocol versioning, such as negotiation of the transport and protocol version used. Client Agents that require the latest features of the protocol should be configured to request specific versions and avoid automatic fallback to older versions, to prevent silently losing functionality.

Messages and Artifacts serve distinct purposes within the OPVS protocol. The core interaction model defined by OPVS is for clients to send messages to initiate a task that produces one or more artifacts. Messages play several key roles:

Messages SHOULD NOT be used to deliver task outputs. Results SHOULD BE returned using Artifacts associated with a Task. This separation allows for a clear distinction between communication (Messages) and data output (Artifacts). The Task History field contains Messages exchanged during task execution. However, not all Messages are guaranteed to be persisted in the Task history; for example, transient informational messages may not be stored. Messages exchanged prior to task creation may not be stored in Task history. The agent is responsible to determine which Messages are persisted in the Task History. Clients using streaming to retrieve task updates MAY not receive all status update messages if the client is disconnected and then reconnects. Messages MUST NOT be considered a reliable delivery mechanism for critical information. Agents MAY choose to persist all Messages that contain important information in the Task history to ensure clients can retrieve it later. However, clients MUST NOT rely on this behavior unless negotiated out-of-band.

• Task Initiation: Clients send Messages to agents to initiate new tasks.
• Clarification Messages: Agents may send Messages back to the client to request clarification prior to initiating a task.
• Status Messages: Agents attach Messages to status update events to inform clients about task progress, request additional input, or provide informational updates.
• Task Interaction: Clients send Messages to provide additional input or instructions for ongoing tasks.

The OPVS protocol defines a canonical data model using Protocol Buffers. All protocol bindings MUST provide functionally equivalent representations of these data structures.

Task is the core unit of action for OPVS. It has a current status and when results are created for the task they are stored in the artifact. If there are multiple turns for a task, these are stored in history.

Task

id

string

contextId

string

status

TaskStatus

Task

state

message

artifacts

Artifact

Task

history

Message

Task

metadata

object

A container for the status of a task

state

TaskState

message

Message

timestamp

timestamp

Defines the possible lifecycle states of a Task.

Task

TASK_STATE_UNSPECIFIED

TASK_STATE_SUBMITTED

TASK_STATE_WORKING

TASK_STATE_COMPLETED

TASK_STATE_FAILED

TASK_STATE_CANCELED

TASK_STATE_INPUT_REQUIRED

TASK_STATE_REJECTED

TASK_STATE_AUTH_REQUIRED

Message is one unit of communication between client and server. It can be associated with a context and/or a task. For server messages, context_id must be provided, and task_id only if a task was created. For client messages, both fields are optional, with the caveat that if both are provided, they have to match (the context_id has to be the one that is set on the task). If only task_id is provided, the server will infer context_id from it.

Message

context_id

task_id

context_id

task_id

context_id

messageId

string

contextId

string

taskId

string

role

Role

parts

Part

metadata

object

extensions

string

referenceTaskIds

string

Defines the sender of a message in OPVS protocol communication.

ROLE_UNSPECIFIED

ROLE_USER

ROLE_AGENT

Part represents a container for a section of communication content. Parts can be purely textual, some sort of file (image, video, etc) or a structured data blob (i.e. JSON).

Part

text

string

text

raw

bytes

raw

url

string

url

data

any

data

metadata

object

filename

string

filename

mediaType

string

media_type

Note: A Part MUST contain exactly one of the following: text, raw, url, data

Part

text

raw

url

data

Artifacts represent task outputs.

artifactId

string

name

string

description

string

parts

Part

metadata

object

extensions

string

An event sent by the agent to notify the client of a change in a task's status.

taskId

string

contextId

string

status

TaskStatus

metadata

object

A task delta where an artifact has been generated.

taskId

string

contextId

string

artifact

Artifact

append

boolean

lastChunk

boolean

metadata

object

Error: Message PushNotificationConfig not found.

PushNotificationConfig

Defines authentication details, used for push notifications.

scheme

string

Bearer

Basic

Digest

credentials

string

When a task update occurs, the agent sends an HTTP POST request to the configured webhook URL. The payload uses the same StreamResponse format as streaming operations, allowing push notifications to deliver the same event types as real-time streams.

StreamResponse

Request Format:

https://a2a-protocol.org/latest/specification#__codelineno-2-11https://a2a-protocol.org/latest/specification#__codelineno-2-10https://a2a-protocol.org/latest/specification#__codelineno-2-9https://a2a-protocol.org/latest/specification#__codelineno-2-8https://a2a-protocol.org/latest/specification#__codelineno-2-7https://a2a-protocol.org/latest/specification#__codelineno-2-6https://a2a-protocol.org/latest/specification#__codelineno-2-5https://a2a-protocol.org/latest/specification#__codelineno-2-4https://a2a-protocol.org/latest/specification#__codelineno-2-3https://a2a-protocol.org/latest/specification#__codelineno-2-2https://a2a-protocol.org/latest/specification#__codelineno-2-1POST {webhook_url} Authorization: {authentication_scheme} {credentials} Content-Type: application/json { /* StreamResponse object - one of: */ "task": { /* Task object */ }, "message": { /* Message object */ }, "statusUpdate": { /* TaskStatusUpdateEvent object */ }, "artifactUpdate": { /* TaskArtifactUpdateEvent object */ } }

https://a2a-protocol.org/latest/specification#__codelineno-2-11https://a2a-protocol.org/latest/specification#__codelineno-2-10https://a2a-protocol.org/latest/specification#__codelineno-2-9https://a2a-protocol.org/latest/specification#__codelineno-2-8https://a2a-protocol.org/latest/specification#__codelineno-2-7https://a2a-protocol.org/latest/specification#__codelineno-2-6https://a2a-protocol.org/latest/specification#__codelineno-2-5https://a2a-protocol.org/latest/specification#__codelineno-2-4https://a2a-protocol.org/latest/specification#__codelineno-2-3https://a2a-protocol.org/latest/specification#__codelineno-2-2https://a2a-protocol.org/latest/specification#__codelineno-2-1POST {webhook_url} Authorization: {authentication_scheme} {credentials} Content-Type: application/json { /* StreamResponse object - one of: */ "task": { /* Task object */ }, "message": { /* Message object */ }, "statusUpdate": { /* TaskStatusUpdateEvent object */ }, "artifactUpdate": { /* TaskArtifactUpdateEvent object */ } }

Payload Structure: The webhook payload is a StreamResponse object containing exactly one of the following:

StreamResponse

• task: A Task object with the current task state
• message: A Message object containing a message response
• statusUpdate: A TaskStatusUpdateEvent indicating a status change
• artifactUpdate: A TaskArtifactUpdateEvent indicating artifact updates

Task

Message

TaskStatusUpdateEvent

TaskArtifactUpdateEvent

Authentication: The agent MUST include authentication credentials in the request headers as specified in the PushNotificationConfig.authentication field. The format follows standard HTTP authentication patterns (Bearer tokens, Basic auth, etc.).

PushNotificationConfig.authentication

Client Responsibilities:

Server Guarantees:

For detailed security guidance on push notifications, see Section 13.2 Push Notification Security.

• Clients MUST respond with HTTP 2xx status codes to acknowledge successful receipt
• Clients SHOULD process notifications idempotently, as duplicate deliveries may occur
• Clients MUST validate the task ID matches an expected task
• Clients SHOULD implement appropriate security measures to verify the notification source
• Agents MUST attempt delivery at least once for each configured webhook
• Agents MAY implement retry logic with exponential backoff for failed deliveries
• Agents SHOULD include a reasonable timeout for webhook requests (recommended: 10-30 seconds)
• Agents MAY stop attempting delivery after a configured number of consecutive failures

A self-describing manifest for an agent. It provides essential metadata including the agent's identity, capabilities, skills, supported communication methods, and security requirements.

name

string

description

string

supportedInterfaces

AgentInterface

provider

AgentProvider

version

string

documentationUrl

string

capabilities

AgentCapabilities

securitySchemes

SecurityScheme

securityRequirements

SecurityRequirement

defaultInputModes

string

defaultOutputModes

string

skills

AgentSkill

signatures

AgentCardSignature

AgentCard

iconUrl

string

Represents the service provider of an agent.

url

string

organization

string

Defines optional capabilities supported by an agent.

streaming

boolean

pushNotifications

boolean

extensions

AgentExtension

extendedAgentCard

boolean

A declaration of a protocol extension supported by an Agent.

uri

string

description

string

required

boolean

params

object

Represents a distinct capability or function that an agent can perform.

id

string

name

string

description

string

tags

string

examples

string

inputModes

string

outputModes

string

securityRequirements

SecurityRequirement

Declares a combination of a target URL, transport and protocol version for interacting with the agent. This allows agents to expose the same functionality over multiple protocol binding mechanisms.

url

string

protocolBinding

string

JSONRPC

GRPC

HTTP+JSON

tenant

string

protocolVersion

string

AgentCardSignature represents a JWS signature of an AgentCard. This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).

protected

string

signature

string

header

object

Defines a security scheme that can be used to secure an agent's endpoints. This is a discriminated union type based on the OpenAPI 3.2 Security Scheme Object. See: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object

apiKeySecurityScheme

APIKeySecurityScheme

httpAuthSecurityScheme

HTTPAuthSecurityScheme

oauth2SecurityScheme

OAuth2SecurityScheme

openIdConnectSecurityScheme

OpenIdConnectSecurityScheme

mtlsSecurityScheme

MutualTlsSecurityScheme

Note: A SecurityScheme MUST contain exactly one of the following: apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme

SecurityScheme

apiKeySecurityScheme

httpAuthSecurityScheme

oauth2SecurityScheme

openIdConnectSecurityScheme

mtlsSecurityScheme

Defines a security scheme using an API key.

description

string

location

string

name

string

Defines a security scheme using HTTP authentication.

description

string

scheme

string

bearerFormat

string

Defines a security scheme using OAuth 2.0.

description

string

flows

OAuthFlows

oauth2MetadataUrl

string

Defines a security scheme using OpenID Connect.

description

string

openIdConnectUrl

string

Defines a security scheme using mTLS authentication.

description

string

Defines the configuration for the supported OAuth 2.0 flows.

authorizationCode

AuthorizationCodeOAuthFlow

clientCredentials

ClientCredentialsOAuthFlow

implicit

ImplicitOAuthFlow

password

PasswordOAuthFlow

deviceCode

DeviceCodeOAuthFlow

Note: A OAuthFlows MUST contain exactly one of the following: authorizationCode, clientCredentials, implicit, password, deviceCode

OAuthFlows

authorizationCode

clientCredentials

implicit

password

deviceCode

Defines configuration details for the OAuth 2.0 Authorization Code flow.

authorizationUrl

string

tokenUrl