Package a2a.v1

Index

• A2AService (interface)
• APIKeySecurityScheme (message)
• AgentCapabilities (message)
• AgentCard (message)
• AgentCardSignature (message)
• AgentExtension (message)
• AgentInterface (message)
• AgentProvider (message)
• AgentSkill (message)
• Artifact (message)
• AuthenticationInfo (message)
• AuthorizationCodeOAuthFlow (message)
• CancelTaskRequest (message)
• ClientCredentialsOAuthFlow (message)
• CreateTaskPushNotificationConfigRequest (message)
• DataPart (message)
• DeleteTaskPushNotificationConfigRequest (message)
• FilePart (message)
• GetAgentCardRequest (message)
• GetTaskPushNotificationConfigRequest (message)
• GetTaskRequest (message)
• HTTPAuthSecurityScheme (message)
• ImplicitOAuthFlow (message)
• ListTaskPushNotificationConfigRequest (message)
• ListTaskPushNotificationConfigResponse (message)
• Message (message)
• MutualTlsSecurityScheme (message)
• OAuth2SecurityScheme (message)
• OAuthFlows (message)
• OpenIdConnectSecurityScheme (message)
• Part (message)
• PasswordOAuthFlow (message)
• PushNotificationConfig (message)
• Role (enum)
• Security (message)
• SecurityScheme (message)
• SendMessageConfiguration (message)
• SendMessageRequest (message)
• SendMessageResponse (message)
• StreamResponse (message)
• StringList (message)
• Task (message)
• TaskArtifactUpdateEvent (message)
• TaskPushNotificationConfig (message)
• TaskState (enum)
• TaskStatus (message)
• TaskStatusUpdateEvent (message)
• TaskSubscriptionRequest (message)

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.

CancelTask
rpc CancelTask(CancelTaskRequest) returns (Task) Cancel a task from the agent. If supported one should expect no more task updates for the task. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

CreateTaskPushNotificationConfig
rpc CreateTaskPushNotificationConfig(CreateTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) Set a push notification config for a task. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

DeleteTaskPushNotificationConfig
rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (Empty) Delete a push notification config for a task. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

GetAgentCard
rpc GetAgentCard(GetAgentCardRequest) returns (AgentCard) GetAgentCard returns the agent card for the agent. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

GetTask
rpc GetTask(GetTaskRequest) returns (Task) Get the current state of a task from the agent. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

GetTaskPushNotificationConfig
rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) Get a push notification config for a task. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

ListTaskPushNotificationConfig
rpc ListTaskPushNotificationConfig(ListTaskPushNotificationConfigRequest) returns (ListTaskPushNotificationConfigResponse) Get a list of push notifications configured for a task. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

SendMessage
rpc SendMessage(SendMessageRequest) returns (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. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

SendStreamingMessage
rpc SendStreamingMessage(SendMessageRequest) returns (StreamResponse) SendStreamingMessage is a streaming call that will return a stream of task update events until the Task is in an interrupted or terminal state. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

TaskSubscription

rpc TaskSubscription(TaskSubscriptionRequest) returns (StreamResponse) 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. Authorization scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

APIKeySecurityScheme

Fields
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

Fields
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 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 Next ID: 19

Fields
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 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	map<string, SecurityScheme> The security scheme details used for authenticating with this agent.
security[]	Security protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Security requirements for contacting the agent. This list can be seen as an OR of ANDs. Each object in the list describes one possible set of security requirements that must be present on a request. This allows specifying, for example, "callers must either use OAuth OR an API Key AND mTLS." Example: security { schemes { key: "oauth" value { list: ["read"] } } } security { schemes { key: "api-key" } schemes { key: "mtls" } }
default_input_modes[]	string 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 The mime types supported as outputs from this agent.
skills[]	AgentSkill 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.
signatures[]	AgentCardSignature JSON Web Signatures computed for this AgentCard.
icon_url	string An optional URL to an icon for the agent.

AgentCardSignature

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

Fields
protected	string Required. The protected JWS header for the signature. This is always a base64url-encoded JSON object. Required.
signature	string Required. The computed signature, base64url-encoded. Required.
header	Struct The unprotected JWS header values.

AgentExtension

A declaration of an extension supported by an Agent.

Fields
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	Struct Optional configuration for the extension.

AgentInterface

Defines additional transport information for the agent.

Fields
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.
tenant	string Tenant to be set in the request when calling the agent. Experimental, might still change for 1.0 release.

AgentProvider

Represents information about the service provider of an agent.

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

Fields
id	string Unique identifier 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 A set of tags for the skill to enhance categorization/utilization. Example: ["cooking", "customer support", "billing"]
examples[]	string 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 Possible input modalities supported.
output_modes[]	string Possible output modalities produced
security[]	Security protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Security schemes necessary for the agent to leverage this skill. As in the overall AgentCard.security, this list represents a logical OR of security requirement objects. Each object is a set of security schemes that must be used together (a logical AND). protolint:enable REPEATED_FIELD_NAMES_PLURALIZED

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.

Fields
artifact_id	string Unique identifier (e.g. UUID) 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 The content of the artifact.
metadata	Struct Optional metadata included with the artifact.
extensions[]	string The URIs of extensions that are present or contributed to this Artifact.

AuthenticationInfo

Defines authentication details, used for push notifications.

Fields
schemes[]	string Supported authentication schemes - e.g. Basic, Bearer, etc
credentials	string Optional credentials

AuthorizationCodeOAuthFlow

Fields
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	map<string, string> 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.

CancelTaskRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
name	string The resource name of the task to cancel. Format: tasks/{task_id}

ClientCredentialsOAuthFlow

Fields
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	map<string, string> 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.

CreateTaskPushNotificationConfigRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
parent	string Required. The parent task resource for this config. Format: tasks/{task_id}
config_id	string Required. The ID for the new config.
config	TaskPushNotificationConfig Required. The configuration to create.

DataPart

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

Fields
data	Struct

DeleteTaskPushNotificationConfigRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
name	string The resource name of the config to delete. Format: tasks/{task_id}/pushNotificationConfigs/{config_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.

Fields
mime_type	string
name	string
Union field file. file can be only one of the following:
file_with_uri	string
file_with_bytes	bytes

GetAgentCardRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.

GetTaskPushNotificationConfigRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
name	string The resource name of the config to retrieve. Format: tasks/{task_id}/pushNotificationConfigs/{config_id}

GetTaskRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
name	string Required. The resource name of the task. Format: tasks/{task_id}
history_length	int32 The number of most recent messages from the task's history to retrieve.

HTTPAuthSecurityScheme

Fields
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

Fields
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	map<string, string> 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.

ListTaskPushNotificationConfigRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
parent	string The parent task resource. Format: tasks/{task_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

Fields
configs[]	TaskPushNotificationConfig The list of push notification configurations.
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.

Fields
message_id	string The unique identifier (e.g. UUID)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 protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Content is the container of the message content.
metadata	Struct protolint:enable REPEATED_FIELD_NAMES_PLURALIZED Any optional metadata to provide along with the message.
extensions[]	string The URIs of extensions that are present or contributed to this Message.

MutualTlsSecurityScheme

Fields
description	string Description of this security scheme.

OAuth2SecurityScheme

Fields
description	string Description of this security scheme.
flows	OAuthFlows An object containing configuration information for the flow types supported
oauth2_metadata_url	string URL to the oauth2 authorization server metadata RFC8414. TLS is required.

OAuthFlows

Fields
Union field flow. flow can be only one of the following:
authorization_code	AuthorizationCodeOAuthFlow
client_credentials	ClientCredentialsOAuthFlow
implicit	ImplicitOAuthFlow
password	PasswordOAuthFlow

OpenIdConnectSecurityScheme

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

Fields
metadata	Struct Optional metadata associated with this part.
Union field part. part can be only one of the following:
text	string
file	FilePart
data	DataPart

PasswordOAuthFlow

Fields
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	map<string, string> 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.

PushNotificationConfig

Configuration for setting up push notifications for task updates.

Fields
id	string A unique identifier (e.g. UUID) 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

Role

Enums
ROLE_UNSPECIFIED
ROLE_USER	USER role refers to communication from the client to the server.
ROLE_AGENT	AGENT role refers to communication from the server to the client.

Security

Fields
schemes	map<string, StringList>

SecurityScheme

Fields
Union field scheme. scheme can be only one of the following:
api_key_security_scheme	APIKeySecurityScheme
http_auth_security_scheme	HTTPAuthSecurityScheme
oauth2_security_scheme	OAuth2SecurityScheme
open_id_connect_security_scheme	OpenIdConnectSecurityScheme
mtls_security_scheme	MutualTlsSecurityScheme

SendMessageConfiguration

Configuration of a send message request.

Fields
accepted_output_modes[]	string 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 ///////////

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
request	Message Required. The message to send to the agent.
configuration	SendMessageConfiguration Configuration for the send request.
metadata	Struct Optional metadata for the request.

SendMessageResponse

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

Fields
Union field payload. payload can be only one of the following:
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

Fields
Union field payload. payload can be only one of the following:
task	Task
msg	Message
status_update	TaskStatusUpdateEvent
artifact_update	TaskArtifactUpdateEvent

StringList

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED

Fields
list[]	string

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.

Fields
id	string Unique identifier (e.g. UUID) for the task, generated by the server for a new task.
context_id	string Unique identifier (e.g. UUID) 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 A set of output artifacts for a Task.
history[]	Message protolint:disable REPEATED_FIELD_NAMES_PLURALIZED The history of interactions from a task.
metadata	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.

Fields
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	Struct Optional metadata associated with the artifact update.

TaskPushNotificationConfig

Fields
name	string The resource name of the config. Format: tasks/{task_id}/pushNotificationConfigs/{config_id}
push_notification_config	PushNotificationConfig The push notification configuration details.

TaskState

The set of states a Task can be in.

Enums
TASK_STATE_UNSPECIFIED
TASK_STATE_SUBMITTED	Represents the status that acknowledges a task is created
TASK_STATE_WORKING	Represents the status that a task is actively being processed
TASK_STATE_COMPLETED	Represents the status a task is finished. This is a terminal state
TASK_STATE_FAILED	Represents the status a task is done but failed. This is a terminal state
TASK_STATE_CANCELLED	Represents the status a task was cancelled before it finished. This is a terminal state.
TASK_STATE_INPUT_REQUIRED	Represents the status that the task requires information to complete. This is an interrupted state.
TASK_STATE_REJECTED	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	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.

TaskStatus

A container for the status of a task

Fields
state	TaskState The current state of this task
update	Message A message associated with the status.
timestamp	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.

Fields
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	Struct Optional metadata to associate with the task update.

TaskSubscriptionRequest

Fields
tenant	string Optional tenant, provided as a path parameter. Experimental, might still change for 1.0 release.
name	string The resource name of the task to subscribe to. Format: tasks/{task_id}