Data Structures

A field reference for the A2A data model, listed by their JSON-serialized camelCase names (snake_case in a2a.proto). Fields marked “required” correspond to REQUIRED in the proto. The authoritative definition is a2a.proto .

Task and TaskStatus

Task is the core unit of work in A2A: it has a current status, stores results as artifacts when they are produced, and keeps multi-turn interactions in its history.

Field	Description
`id`	Required. Unique identifier of the task, generated by the server for a new task
`contextId`	Identifier that groups the task and messages into one context
`status`	Required. A `TaskStatus` with `state` (required), an optional `message`, and an ISO 8601 `timestamp`
`artifacts`	The output artifacts of the task
`history`	The interaction history of the task (a list of messages)
`metadata`	Custom key-value metadata about the task

TaskState

Value	Kind	Meaning
`TASK_STATE_SUBMITTED`	In progress	The task has been submitted and acknowledged
`TASK_STATE_WORKING`	In progress	The agent is actively processing the task
`TASK_STATE_INPUT_REQUIRED`	Interrupted	The agent needs additional user input to proceed
`TASK_STATE_AUTH_REQUIRED`	Interrupted	Authentication is required to proceed. Entering this state is not, by itself, authorization for any particular operation; the scope and semantics of the authorization are defined by the implementation
`TASK_STATE_COMPLETED`	Terminal	Finished successfully
`TASK_STATE_FAILED`	Terminal	Finished with an error
`TASK_STATE_CANCELED`	Terminal	Canceled before completion
`TASK_STATE_REJECTED`	Terminal	The agent decided not to perform the task (at creation or later)

There is also TASK_STATE_UNSPECIFIED for an unknown or indeterminate state. For how states flow, see Life of a Task .

Message, Role, and Part

Message is one unit of communication between client and server.

Field	Description
`messageId`	Required. Identifier of the message, created by the message creator
`contextId` / `taskId`	Optional; associate the message with a context or a task. Server messages must carry `contextId` and carry `taskId` only if a task was created. Both are optional on client messages and must match if both are provided
`role`	Required. `ROLE_USER` (client to server) or `ROLE_AGENT` (server to client)
`parts`	Required. The message content, at least one `Part`
`metadata`	Optional metadata
`extensions`	URIs of extensions present in or contributed to this message
`referenceTaskIds`	IDs of tasks referenced for additional context

Part is the smallest unit of content in a message or artifact. In v1.0 it is a single unified structure: exactly one of the four content fields below, plus the shared fields.

Field	Description
`text`	Text content
`raw`	The raw bytes of a file, a base64 string in JSON
`url`	A URL pointing to the file’s content
`data`	Arbitrary structured JSON value (object, array, string, number, boolean, or null)
`mediaType`	The media type (MIME type) of the content, available for all part types
`filename`	An optional file name
`metadata`	Optional metadata of the part

Artifact and streaming events

Artifact represents a task output.

Field	Description
`artifactId`	Required. Unique within the task
`name` / `description`	A human-readable name and description
`parts`	Required. The content, at least one `Part`
`metadata` / `extensions`	Metadata and extension URIs

Streaming operations and subscriptions return StreamResponse, whose payload is one of: task, message, statusUpdate, or artifactUpdate.

Event	Key fields
`TaskStatusUpdateEvent`	`taskId`, `contextId`, `status` (all required), `metadata`. v1.0 has no `kind` and no `final`; completion is detected from a terminal state and stream closure
`TaskArtifactUpdateEvent`	`taskId`, `contextId`, `artifact` (all required), `append` (when `true`, the content is appended to an already sent artifact with the same ID), `lastChunk` (when `true`, this is the final chunk of the artifact), `metadata`

Request configuration and push notifications

SendMessageRequest contains the required message plus optional tenant, configuration, and metadata. The fields of SendMessageConfiguration:

Field	Description
`acceptedOutputModes`	Media types the client is prepared to accept for responses; agents SHOULD tailor their output to them
`taskPushNotificationConfig`	Configuration for the agent to send push notifications for task updates; the task ID should be empty in a `SendMessage` request
`historyLength`	Maximum number of recent messages in the response; semantics in the Core Protocol Specification
`returnImmediately`	When `true`, return right after creating the task; defaults to `false`, which waits for a terminal or interrupted state

The fields of TaskPushNotificationConfig (a webhook configuration):

Field	Description
`tenant`	Optional routing identifier; when set, it must match the `tenant` of the selected `AgentInterface`
`id`	Unique identifier of this configuration
`taskId`	The task the configuration belongs to
`url`	Required. The URL to which notifications are sent
`token`	A token unique to the task or session
`authentication`	Authentication required to send the notification: `scheme` (required, an HTTP authentication scheme from the IANA registry such as `Bearer`) and `credentials`

AgentCard and related objects

AgentCard is the agent’s self-describing manifest. For discovery and verification rules, see Agent Discovery and the Agent Card .

Field	Description
`name`, `description`, `version`	Required. Basic identity information
`supportedInterfaces`	Required. An ordered list of interfaces; the first entry is preferred
`provider`	The service provider: `organization` and `url` (both required)
`documentationUrl`, `iconUrl`	Optional documentation and icon URLs
`capabilities`	Required. `AgentCapabilities`
`securitySchemes`	A map of authentication schemes (name to `SecurityScheme`)
`securityRequirements`	Security requirements for contacting the agent
`defaultInputModes`, `defaultOutputModes`	Required. Default input and output media types, overridable per skill
`skills`	Required. A list of `AgentSkill`
`signatures`	JSON Web Signatures computed for this card

AgentInterface: url (a valid absolute HTTPS URL in production for HTTP-based transports, or a hostname:port address for gRPC), protocolBinding (the core bindings are JSONRPC, GRPC, and HTTP+JSON; custom bindings are an open string), and protocolVersion (for example 1.0) are required. The optional tenant is an opaque routing string; when set, the client MUST include it in all requests sent to that interface.
AgentCapabilities: three optional booleans, streaming, pushNotifications, and extendedAgentCard, plus extensions (a list of AgentExtension).
AgentExtension: uri, description, required (when true, the client must understand and comply with the extension), and params.
AgentSkill: id, name, description, and tags are required; examples, inputModes, outputModes (overriding the defaults), and securityRequirements are optional.
AgentCardSignature: protected (the base64url-encoded JWS protected header, required), signature (the base64url signature, required), and header (the unprotected header, optional).

Security schemes

SecurityScheme is based on the OpenAPI 3.2 Security Scheme Object and is one of five types:

Scheme	Key fields
`apiKeySecurityScheme`	`location` (`query`, `header`, or `cookie`) and `name`
`httpAuthSecurityScheme`	`scheme` (such as `Bearer`, which should be registered in the IANA authentication scheme registry) and `bearerFormat` (such as `JWT`, a hint only)
`oauth2SecurityScheme`	`flows` (required) and `oauth2MetadataUrl` (RFC 8414 authorization server metadata, TLS required)
`openIdConnectSecurityScheme`	`openIdConnectUrl` (the OIDC Discovery URL, required)
`mtlsSecurityScheme`	Mutual TLS, with no additional required fields

OAuthFlows supports:

Authorization Code: authorizationUrl, tokenUrl, and scopes are required, refreshUrl is optional, and pkceRequired indicates whether PKCE (RFC 7636) is mandatory. PKCE should always be used for public clients and is recommended for all clients.
Client Credentials: tokenUrl and scopes are required, refreshUrl is optional.
Device Code (RFC 8628, for input-constrained devices such as IoT devices and CLI tools): deviceAuthorizationUrl, tokenUrl, and scopes are required, refreshUrl is optional.
Implicit and Password flows: marked deprecated in the proto; use Authorization Code + PKCE, or Device Code instead.

In securityRequirements, the schemes of each entry map a scheme name to the list of required scopes.

Core Protocol Specification : how these objects are used by each operation.
Common Workflows and Examples : these objects in real requests and responses.
Key Concepts : an approachable explanation of these objects.
What Changed in v1.0 and How to Migrate : the field differences from v0.3.
AgentSkill and SecurityScheme : one page each, with examples and the v0.3 differences.
Agent Card Proto Field Numbers : the protobuf field numbers of the Agent Card objects in v0.3.0 and v1.0.1.

Source: A2A official specification · Protocol Data Model and a2a.proto