Protocol Documentation¶

Table of Contents¶

• a2a/v1/a2a.proto

  • APIKeySecurityScheme
  • AgentCapabilities
  • AgentCard
  • AgentCard.SecuritySchemesEntry
  • AgentExtension
  • AgentInterface
  • AgentProvider
  • AgentSkill
  • Artifact
  • AuthenticationInfo
  • AuthorizationCodeOAuthFlow
  • AuthorizationCodeOAuthFlow.ScopesEntry
  • CancelTaskRequest
  • ClientCredentialsOAuthFlow
  • ClientCredentialsOAuthFlow.ScopesEntry
  • CreateTaskPushNotificationConfigRequest
  • DataPart
  • DeleteTaskPushNotificationConfigRequest
  • FilePart
  • GetAgentCardRequest
  • GetTaskPushNotificationConfigRequest
  • GetTaskRequest
  • HTTPAuthSecurityScheme
  • ImplicitOAuthFlow
  • ImplicitOAuthFlow.ScopesEntry
  • ListTaskPushNotificationConfigRequest
  • ListTaskPushNotificationConfigResponse
  • Message
  • OAuth2SecurityScheme
  • OAuthFlows
  • OpenIdConnectSecurityScheme
  • Part
  • PasswordOAuthFlow
  • PasswordOAuthFlow.ScopesEntry
  • PushNotificationConfig
  • Security
  • Security.SchemesEntry
  • SecurityScheme
  • SendMessageConfiguration
  • SendMessageRequest
  • SendMessageResponse
  • StreamResponse
  • StringList
  • Task
  • TaskArtifactUpdateEvent
  • TaskPushNotificationConfig
  • TaskStatus
  • TaskStatusUpdateEvent

  • TaskSubscriptionRequest

  • Role

  • TaskState

  • A2AService

• Scalar Value Types

Top

a2a/v1/a2a.proto¶

Older protoc compilers don't understand edition yet.

APIKeySecurityScheme¶

Field	Type	Label	Description
description	string		Description of this security scheme.
location	string		Location of the API key, valid values are "query", "header", or "cookie"
name	string		Name of the header, query or cookie parameter to be used.

AgentCapabilities¶

Defines the A2A feature set supported by the agent

Field	Type	Label	Description
streaming	bool		If the agent will support streaming responses
push_notifications	bool		If the agent can send push notifications to the clients webhook
extensions	AgentExtension	repeated	Extensions supported by this agent.

AgentCard¶

AgentCard conveys key information: - Overall details (version, name, description, uses) - Skills; a set of actions/solutions the agent can perform - Default modalities/content types supported by the agent. - Authentication requirements

Field	Type	Label	Description
protocol_version	string		The version of the A2A protocol this agent supports.
name	string		A human readable name for the agent. Example: "Recipe Agent"
description	string		A description of the agent's domain of action/solution space. Example: "Agent that helps users with recipes and cooking."
url	string		A URL to the address the agent is hosted at. This represents the preferred endpoint as declared by the agent.
preferred_transport	string		The transport of the preferred endpoint. If empty, defaults to JSONRPC.
additional_interfaces	AgentInterface	repeated	Announcement of additional supported transports. Client can use any of the supported transports.
provider	AgentProvider		The service provider of the agent.
version	string		The version of the agent. Example: "1.0.0"
documentation_url	string		A url to provide additional documentation about the agent.
capabilities	AgentCapabilities		A2A Capability set supported by the agent.
security_schemes	AgentCard.SecuritySchemesEntry	repeated	The security scheme details used for authenticating with this agent.
security	Security	repeated	protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Security requirements for contacting the agent.
default_input_modes	string	repeated	protolint:enable REPEATED_FIELD_NAMES_PLURALIZED The set of interaction modes that the agent supports across all skills. This can be overridden per skill. Defined as mime types.
default_output_modes	string	repeated	The mime types supported as outputs from this agent.
skills	AgentSkill	repeated	Skills represent a unit of ability an agent can perform. This may somewhat abstract but represents a more focused set of actions that the agent is highly likely to succeed at.
supports_authenticated_extended_card	bool		Whether the agent supports providing an extended agent card when the user is authenticated, i.e. is the card from .well-known different than the card from GetAgentCard.

AgentCard.SecuritySchemesEntry¶

Field	Type	Label	Description
key	string
value	SecurityScheme

AgentExtension¶

A declaration of an extension supported by an Agent.

Field	Type	Label	Description
uri	string		The URI of the extension. Example: "https://developers.google.com/identity/protocols/oauth2"
description	string		A description of how this agent uses this extension. Example: "Google OAuth 2.0 authentication"
required	bool		Whether the client must follow specific requirements of the extension. Example: false
params	google.protobuf.Struct		Optional configuration for the extension.

AgentInterface¶

Defines additional transport information for the agent.

Field	Type	Label	Description
url	string		The url this interface is found at.
transport	string		The transport supported this url. This is an open form string, to be easily extended for many transport protocols. The core ones officially supported are JSONRPC, GRPC and HTTP+JSON.

AgentProvider¶

Represents information about the service provider of an agent.

Field	Type	Label	Description
url	string		The providers reference url Example: "https://ai.google.dev"
organization	string		The providers organization name Example: "Google"

AgentSkill¶

AgentSkill represents a unit of action/solution that the agent can perform. One can think of this as a type of highly reliable solution that an agent can be tasked to provide. Agents have the autonomy to choose how and when to use specific skills, but clients should have confidence that if the skill is defined that unit of action can be reliably performed.

Field	Type	Label	Description
id	string		Unique id of the skill within this agent.
name	string		A human readable name for the skill.
description	string		A human (or llm) readable description of the skill details and behaviors.
tags	string	repeated	A set of tags for the skill to enhance categorization/utilization. Example: ["cooking", "customer support", "billing"]
examples	string	repeated	A set of example queries that this skill is designed to address. These examples should help the caller to understand how to craft requests to the agent to achieve specific goals. Example: ["I need a recipe for bread"]
input_modes	string	repeated	Possible input modalities supported.
output_modes	string	repeated	Possible output modalities produced

Artifact¶

Artifacts are the container for task completed results. These are similar to Messages but are intended to be the product of a task, as opposed to point-to-point communication.

Field	Type	Label	Description
artifact_id	string		Unique id for the artifact. It must be at least unique within a task.
name	string		A human readable name for the artifact.
description	string		A human readable description of the artifact, optional.
parts	Part	repeated	The content of the artifact.
metadata	google.protobuf.Struct		Optional metadata included with the artifact.
extensions	string	repeated	The URIs of extensions that are present or contributed to this Artifact.

AuthenticationInfo¶

Defines authentication details, used for push notifications.

Field	Type	Label	Description
schemes	string	repeated	Supported authentication schemes - e.g. Basic, Bearer, etc
credentials	string		Optional credentials

AuthorizationCodeOAuthFlow¶

Field	Type	Label	Description
authorization_url	string		The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS
token_url	string		The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
refresh_url	string		The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
scopes	AuthorizationCodeOAuthFlow.ScopesEntry	repeated	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.

AuthorizationCodeOAuthFlow.ScopesEntry¶

Field	Type	Label	Description
key	string
value	string

CancelTaskRequest¶

Field	Type	Label	Description
name	string		name=tasks/{id}

ClientCredentialsOAuthFlow¶

Field	Type	Label	Description
token_url	string		The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
refresh_url	string		The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
scopes	ClientCredentialsOAuthFlow.ScopesEntry	repeated	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.

ClientCredentialsOAuthFlow.ScopesEntry¶

Field	Type	Label	Description
key	string
value	string

CreateTaskPushNotificationConfigRequest¶

Field	Type	Label	Description
parent	string		The task resource for this config. Format: tasks/{id}
config_id	string
config	TaskPushNotificationConfig

DataPart¶

DataPart represents a structured blob. This is most commonly a JSON payload.

Field	Type	Label	Description
data	google.protobuf.Struct

DeleteTaskPushNotificationConfigRequest¶

Field	Type	Label	Description
name	string		name=tasks/{id}/pushNotificationConfigs/{push_id}

FilePart¶

FilePart represents the different ways files can be provided. If files are small, directly feeding the bytes is supported via file_with_bytes. If the file is large, the agent should read the content as appropriate directly from the file_with_uri source.

Field	Type	Label	Description
file_with_uri	string
file_with_bytes	bytes
mime_type	string

GetAgentCardRequest¶

Empty. Added to fix linter violation.

GetTaskPushNotificationConfigRequest¶

Field	Type	Label	Description
name	string		name=tasks/{id}/pushNotificationConfigs/{push_id}

GetTaskRequest¶

Field	Type	Label	Description
name	string		name=tasks/{id}
history_length	int32

HTTPAuthSecurityScheme¶

Field	Type	Label	Description
description	string		Description of this security scheme.
scheme	string		The name of the HTTP Authentication scheme to be used in the Authorization header as defined in RFC7235. The values used SHOULD be registered in the IANA Authentication Scheme registry. The value is case-insensitive, as defined in RFC7235.
bearer_format	string		A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.

ImplicitOAuthFlow¶

Field	Type	Label	Description
authorization_url	string		The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS
refresh_url	string		The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
scopes	ImplicitOAuthFlow.ScopesEntry	repeated	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.

ImplicitOAuthFlow.ScopesEntry¶

Field	Type	Label	Description
key	string
value	string

ListTaskPushNotificationConfigRequest¶

Field	Type	Label	Description
parent	string		parent=tasks/{id}
page_size	int32		For AIP-158 these fields are present. Usually not used/needed. The maximum number of configurations to return. If unspecified, all configs will be returned.
page_token	string		A page token received from a previous ListTaskPushNotificationConfigRequest call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListTaskPushNotificationConfigRequest must match the call that provided the page token.

ListTaskPushNotificationConfigResponse¶

Field	Type	Label	Description
configs	TaskPushNotificationConfig	repeated
next_page_token	string		A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

Message¶

Message is one unit of communication between client and server. It is associated with a context and optionally a task. Since the server is responsible for the context definition, it must always provide a context_id in its messages. The client can optionally provide the context_id if it knows the context to associate the message to. Similarly for task_id, except the server decides if a task is created and whether to include the task_id.

Field	Type	Label	Description
message_id	string		The message id of the message. This is required and created by the message creator.
context_id	string		The context id of the message. This is optional and if set, the message will be associated with the given context.
task_id	string		The task id of the message. This is optional and if set, the message will be associated with the given task.
role	Role		A role for the message.
content	Part	repeated	protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Content is the container of the message content.
metadata	google.protobuf.Struct		protolint:enable REPEATED_FIELD_NAMES_PLURALIZED Any optional metadata to provide along with the message.
extensions	string	repeated	The URIs of extensions that are present or contributed to this Message.

OAuth2SecurityScheme¶

Field	Type	Label	Description
description	string		Description of this security scheme.
flows	OAuthFlows		An object containing configuration information for the flow types supported

OAuthFlows¶

Field	Type	Label	Description
authorization_code	AuthorizationCodeOAuthFlow
client_credentials	ClientCredentialsOAuthFlow
implicit	ImplicitOAuthFlow
password	PasswordOAuthFlow

OpenIdConnectSecurityScheme¶

Field	Type	Label	Description
description	string		Description of this security scheme.
open_id_connect_url	string		Well-known URL to discover the [[OpenID-Connect-Discovery]] provider metadata.

Part¶

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).

Field	Type	Label	Description
text	string
file	FilePart
data	DataPart

PasswordOAuthFlow¶

Field	Type	Label	Description
token_url	string		The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
refresh_url	string		The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
scopes	PasswordOAuthFlow.ScopesEntry	repeated	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.

PasswordOAuthFlow.ScopesEntry¶

Field	Type	Label	Description
key	string
value	string

PushNotificationConfig¶

Configuration for setting up push notifications for task updates.

Field	Type	Label	Description
id	string		A unique id for this push notification.
url	string		Url to send the notification too
token	string		Token unique for this task/session
authentication	AuthenticationInfo		Information about the authentication to sent with the notification

Security¶

Field	Type	Label	Description
schemes	Security.SchemesEntry	repeated

Security.SchemesEntry¶

Field	Type	Label	Description
key	string
value	StringList

SecurityScheme¶

Field	Type	Label	Description
api_key_security_scheme	APIKeySecurityScheme
http_auth_security_scheme	HTTPAuthSecurityScheme
oauth2_security_scheme	OAuth2SecurityScheme
open_id_connect_security_scheme	OpenIdConnectSecurityScheme

SendMessageConfiguration¶

Configuration of a send message request.

Field	Type	Label	Description
accepted_output_modes	string	repeated	The output modes that the agent is expected to respond with.
push_notification	PushNotificationConfig		A configuration of a webhook that can be used to receive updates
history_length	int32		The maximum number of messages to include in the history. if 0, the history will be unlimited.
blocking	bool		If true, the message will be blocking until the task is completed. If false, the message will be non-blocking and the task will be returned immediately. It is the caller's responsibility to check for any task updates.

SendMessageRequest¶

Request Messages ///////////

Field	Type	Label	Description
request	Message
configuration	SendMessageConfiguration
metadata	google.protobuf.Struct

SendMessageResponse¶

Response Messages ///////////

Field	Type	Label	Description
task	Task
msg	Message

StreamResponse¶

The stream response for a message. The stream should be one of the following sequences: If the response is a message, the stream should contain one, and only one, message and then close If the response is a task lifecycle, the first response should be a Task object followed by zero or more TaskStatusUpdateEvents and TaskArtifactUpdateEvents. The stream should complete when the Task if in an interrupted or terminal state. A stream that ends before these conditions are met are

Field	Type	Label	Description
task	Task
msg	Message
status_update	TaskStatusUpdateEvent
artifact_update	TaskArtifactUpdateEvent

StringList¶

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED

Field	Type	Label	Description
list	string	repeated

Task¶

Task is the core unit of action for A2A. 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.

Field	Type	Label	Description
id	string		Unique identifier for a task, created by the A2A server.
context_id	string		Unique identifier for the contextual collection of interactions (tasks and messages). Created by the A2A server.
status	TaskStatus		The current status of a Task, including state and a message.
artifacts	Artifact	repeated	A set of output artifacts for a Task.
history	Message	repeated	protolint:disable REPEATED_FIELD_NAMES_PLURALIZED The history of interactions from a task.
metadata	google.protobuf.Struct		protolint:enable REPEATED_FIELD_NAMES_PLURALIZED A key/value object to store custom metadata about a task.

TaskArtifactUpdateEvent¶

TaskArtifactUpdateEvent represents a task delta where an artifact has been generated.

Field	Type	Label	Description
task_id	string		The id of the task for this artifact
context_id	string		The id of the context that this task belongs too
artifact	Artifact		The artifact itself
append	bool		Whether this should be appended to a prior one produced
last_chunk	bool		Whether this represents the last part of an artifact
metadata	google.protobuf.Struct		Optional metadata associated with the artifact update.

TaskPushNotificationConfig¶

Field	Type	Label	Description
name	string		name=tasks/{id}/pushNotificationConfigs/{id}
push_notification_config	PushNotificationConfig

TaskStatus¶

A container for the status of a task

Field	Type	Label	Description
state	TaskState		The current state of this task
update	Message		A message associated with the status.
timestamp	google.protobuf.Timestamp		Timestamp when the status was recorded. Example: "2023-10-27T10:00:00Z"

TaskStatusUpdateEvent¶

TaskStatusUpdateEvent is a delta even on a task indicating that a task has changed.

Field	Type	Label	Description
task_id	string		The id of the task that is changed
context_id	string		The id of the context that the task belongs to
status	TaskStatus		The new status of the task.
final	bool		Whether this is the last status update expected for this task.
metadata	google.protobuf.Struct		Optional metadata to associate with the task update.

TaskSubscriptionRequest¶

Field	Type	Label	Description
name	string		name=tasks/{id}

Role¶

Name	Number	Description
ROLE_UNSPECIFIED	0
ROLE_USER	1	USER role refers to communication from the client to the server.
ROLE_AGENT	2	AGENT role refers to communication from the server to the client.

TaskState¶

The set of states a Task can be in.

Name	Number	Description
TASK_STATE_UNSPECIFIED	0
TASK_STATE_SUBMITTED	1	Represents the status that acknowledges a task is created
TASK_STATE_WORKING	2	Represents the status that a task is actively being processed
TASK_STATE_COMPLETED	3	Represents the status a task is finished. This is a terminal state
TASK_STATE_FAILED	4	Represents the status a task is done but failed. This is a terminal state
TASK_STATE_CANCELLED	5	Represents the status a task was cancelled before it finished. This is a terminal state.
TASK_STATE_INPUT_REQUIRED	6	Represents the status that the task requires information to complete. This is an interrupted state.
TASK_STATE_REJECTED	7	Represents the status that the agent has decided to not perform the task. This may be done during initial task creation or later once an agent has determined it can't or won't proceed. This is a terminal state.
TASK_STATE_AUTH_REQUIRED	8	Represents the state that some authentication is needed from the upstream client. Authentication is expected to come out-of-band thus this is not an interrupted or terminal state.

A2AService¶

A2AService defines the gRPC version of the A2A protocol. This has a slightly different shape than the JSONRPC version to better conform to AIP-127, where appropriate. The nouns are AgentCard, Message, Task and TaskPushNotificationConfig. - Messages are not a standard resource so there is no get/delete/update/list interface, only a send and stream custom methods. - Tasks have a get interface and custom cancel and subscribe methods. - TaskPushNotificationConfig are a resource whose parent is a task. They have get, list and create methods. - AgentCard is a static resource with only a get method. fields are not present as they don't comply with AIP rules, and the optional history_length on the get task method is not present as it also violates AIP-127 and AIP-131.

Method Name	Request Type	Response Type	Description
SendMessage	SendMessageRequest	SendMessageResponse	Send a message to the agent. This is a blocking call that will return the task once it is completed, or a LRO if requested.
SendStreamingMessage	SendMessageRequest	StreamResponse stream	SendStreamingMessage is a streaming call that will return a stream of task update events until the Task is in an interrupted or terminal state.
GetTask	GetTaskRequest	Task	Get the current state of a task from the agent.
CancelTask	CancelTaskRequest	Task	Cancel a task from the agent. If supported one should expect no more task updates for the task.
TaskSubscription	TaskSubscriptionRequest	StreamResponse stream	TaskSubscription is a streaming call that will return a stream of task update events. This attaches the stream to an existing in process task. If the task is complete the stream will return the completed task (like GetTask) and close the stream.
CreateTaskPushNotificationConfig	CreateTaskPushNotificationConfigRequest	TaskPushNotificationConfig	Set a push notification config for a task.
GetTaskPushNotificationConfig	GetTaskPushNotificationConfigRequest	TaskPushNotificationConfig	Get a push notification config for a task.
ListTaskPushNotificationConfig	ListTaskPushNotificationConfigRequest	ListTaskPushNotificationConfigResponse	Get a list of push notifications configured for a task.
GetAgentCard	GetAgentCardRequest	AgentCard	GetAgentCard returns the agent card for the agent.
DeleteTaskPushNotificationConfig	DeleteTaskPushNotificationConfigRequest	.google.protobuf.Empty	Delete a push notification config for a task.

Scalar Value Types¶

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)