Respecting AIP response payloads in HTTP

[darrelmiller]

To facilitate keeping the gRPC and HTTP protocol binding in sync, and enable middleware to automatically translate between the protocol bindings, without using SDKs, the current path for A2A is to use AIP conventions.

In most cases, the conformance to AIP guidelines is fairly transparent as it uses common HTTP conventions. However, there are some conventions that are a bit unusual.

AIP has some very specific guidance around what it means by a "Resource" and how those resources should be named. https://google.aip.dev/122

One that is causing some challenges at this point is:

Resources must expose a name field that contains its resource name

This is most obvious in the GetTaskPushNotificationConfig method

  rpc SetTaskPushNotificationConfig(SetTaskPushNotificationConfigRequest)
      returns (TaskPushNotificationConfig) {
    option (google.api.http) = {
      post: "/v1/{parent=tasks/*/pushNotificationConfigs}"
      body: "config"
    };
    option (google.api.method_signature) = "parent,config";
  }

This method returns TaskPushNotificationConfig which looks like

message TaskPushNotificationConfig {
  // The resource name of the config.
  // Format: tasks/{task_id}/pushNotificationConfigs/{config_id}
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  // The push notification configuration details.
  PushNotificationConfig push_notification_config = 2 [(google.api.field_behavior) = REQUIRED];
}

and finally PushNotificationConfig looks like this

// Configuration for setting up push notifications for task updates.
message PushNotificationConfig {
  // A unique identifier (e.g. UUID) for this push notification.
  string id = 1;
  // Url to send the notification too
  string url = 2 [(google.api.field_behavior) = REQUIRED];
  // Token unique for this task/session
  string token = 3;
  // Information about the authentication to sent with the notification
  AuthenticationInfo authentication = 4;
}

This extra layering of TaskPushNotificationConfig containing a PushNotificationConfig is a bit redundant. I mistakenly assumed this was a gRPC specific issue and described the abstract operation as returning PushNotificationConfig. However, this is not a gRPC issue, it is a AIP convention that requires "Resources" to contain a name field. This means that both the HTTP and gRPC binding require the name field if they are to be AIP compliant.

It is not clear to me whether this particular convention would actually affect the mechanical translation, but the path of willful violations is paved with regret. It is also worth noting that the community derivative of AIP, confusingly called AEP renames the name field to path but also requires it. https://aep.dev/122/

It is my opinion that we should aspire to keep these AIP specific conventions out of the abstract protocol definition. However, what this means is that we need to recognize that the documented HTTP binding, is going to be an AIP HTTP binding, and needs to layer AIP conventions onto the abstract protocol.

This opens the door for a future community effort to create an AEP HTTP binding that conforms to its conventions.

I am assuming this means that we will need to create a "resource" message type to contain a "Task" and I have no idea what to do with GetExtendedAgentCard.

[herczyn]

the AIP issue seems to be only about marking the field with google.api.resource_reference, right? the name field is on the message already.

btw: i think the redundancy comes from the reuse of PushNotificationConfig in the send message config, although i'm not sure why in SendMessage we are not expected to send the resource name and in SetTaskPushNotificationConfig we are.
also not sure what is the difference between TaskPushNotificationConfig.name and PushNotificationConfig.id, colapsing these two messages sounds like a good idea for simplification.

[darrelmiller]

For PushNotificationConfig there is already a name field. But there isn't for Task. And for AgentCard this is a name field but it is for a human readable name, not the URL path.

I think SendMessage is different because it is an "operation" rather than a standard CRUD method on a resource.

TaskPushNotificationConfig.name and PushNotificationConfig.id

PushNotificationConfig.Id is the GUID value that appears in the last segment of the URL. It is what you might use for constructing the URL path. The name value is the entire path including the taskId and PushNotificationConfig.Id.

[muscariello]

@darrelmiller on AIP I notice that running the linter on the current a2a.proto

~/go/bin/api-linter --config .api-linter.yaml --set-exit-status --proto-path . --proto-path .googleapis a2a.proto
we get

Summary Table

Category	Count	Examples
URI naming	5	Use uri instead of url in field names (e.g., refresh_url → refresh_uri)
Field behavior annotations	~40+	Missing google.api.field_behavior annotations (REQUIRED, OPTIONAL, etc.)
Reserved words	2	final and protected are reserved words in common languages
HTTP body	1	Custom POST methods should set body: "*"
Response message naming	4	Custom methods should return messages with Response suffix
Abbreviations	2	Use Config instead of Configuration
Comments formatting	3	Empty lines between comments and definitions
Base64 fields	2	Fields mentioning base64 should be type bytes, not string
Timestamp naming	1	Timestamp fields should end in _time
Resource references	4	Missing google.api.resource_reference annotations
File layout	1	Messages should precede all top-level enums
State field annotations	2	State fields must have OUTPUT_ONLY behavior
List/Get request fields	5+	Unknown fields in request messages
Method signature	1	Get methods should include (google.api.method_signature) = "name"
Prepositions in method names	1	Method names should not include prepositions ("to")
Nesting	1	TaskState should be nested within Task as State
HTTP URI name	1	HTTP URI should include a name variable

[muscariello]

If we keep the rules below we need to fix the proto file as reported by the linting tool.
The tool can fix that all at once and I can post a test.

• "core::0140::uri" # A2A uses 'url' intentionally
• "core::0140::reserved-words" # 'final' and 'protected' are intentional
• "core::0140::base64" # JWS requires string type per RFC 7515
• "core::0142::time-field-names"
• "core::0216::nesting" # TaskState is used broadly
• "core::0216::state-field-output-only"
• "core::0140::abbreviations" # Keep 'Configuration' for clarity
• "core::0136::prepositions" # 'SubscribeToTask' is clear
• "core::0136::response-message-name"
• "core::0131::request-name-required"
• "core::0132::request-parent-required"
• "core::0131::request-name-reference"
• "core::0132::request-parent-reference"
• "core::0135::request-name-reference"
• "core::0131::request-unknown-fields"
• "core::0132::request-unknown-fields"
• "core::0131::method-signature"
• "core::0131::http-uri-name"
• "core::0136::http-body"
• "core::0136::http-uri-suffix"
• "core::0191::file-layout"

1. URI Naming (AIP-140)

Rename url fields to uri:

// Before
string url = 2;
string authorization_url = 1;
string token_url = 2;
string refresh_url = 3;

// After
string uri = 2;
string authorization_uri = 1;
string token_uri = 2;
string refresh_uri = 3;

Affected locations:

• PushNotificationConfig.url (line 342)
• AgentInterface.url (line 363)
• AuthorizationCodeOAuthFlow.authorization_url, token_url, refresh_url (lines 631-633)
• ClientCredentialsOAuthFlow.token_url, refresh_url (lines 643-644)
• ImplicitOAuthFlow.authorization_url, refresh_url (lines 654-656)
• PasswordOAuthFlow.token_url, refresh_url (lines 666-668)

2. Field Behavior Annotations (AIP-203)

Add [(google.api.field_behavior) = OPTIONAL] or REQUIRED to all fields:

// Before
string context_id = 2;

// After
string context_id = 2 [(google.api.field_behavior) = OPTIONAL];

Key fields needing annotations:

• Message.context_id, task_id, metadata, extensions, reference_task_ids
• SendMessageConfiguration fields
• PushNotificationConfig fields (id, token, authentication, credentials)
• All request message fields without annotations

3. Reserved Words (AIP-140)

Rename fields using reserved words:

// Before
bool final = 4;
string protected = 1;

// After
bool is_final = 4;      // or 'last', 'completed'
string protected_header = 1;  // or rename based on context

Affected locations:

• TaskStatusUpdateEvent.final (line 308)
• AgentCardSignature.protected (line 499)

4. Timestamp Naming (AIP-142)

Rename timestamp fields to end with _time:

// Before
google.protobuf.Timestamp timestamp = 3;

// After
google.protobuf.Timestamp update_time = 3;

Affected location:

• TaskStatus.timestamp (line 185)

5. State Field Output-Only (AIP-216)

Mark state fields as OUTPUT_ONLY:

// Before
TaskState state = 1 [(google.api.field_behavior) = REQUIRED];

// After
TaskState state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

Affected locations:

• TaskStatus.state (line 180)
• ListTasksRequest.status (line 705) - this is a filter, may need different treatment

6. File Layout (AIP-191)

Move the TaskState enum after all messages, or nest it inside Task:

message Task {
  enum State {
    STATE_UNSPECIFIED = 0;
    STATE_SUBMITTED = 1;
    // ...
  }
  State state = 1;
  // ...
}

7. Base64 Fields (AIP-140)

Fields mentioning base64 should use bytes type (but JWS spec requires strings):

// This is intentional per JWS RFC 7515 - consider adding a linter exception
string protected = 1;  // base64url-encoded, but JWS spec mandates string
string signature = 2;  // base64url-encoded, but JWS spec mandates string

8. Abbreviations (AIP-140)

Use Config instead of Configuration:

// Before
message SendMessageConfiguration { ... }
SendMessageConfiguration configuration = 2;

// After
message SendMessageConfig { ... }
SendMessageConfig config = 2;

9. Resource References (AIP-131, AIP-132, AIP-135)

Add resource reference annotations:

import "google/api/resource.proto";

message Task {
  option (google.api.resource) = {
    type: "a2a.googleapis.com/Task"
    pattern: "tasks/{task}"
  };
  // ...
}

message GetTaskRequest {
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "a2a.googleapis.com/Task"
    }
  ];
}

10. Method Signature for GetExtendedAgentCard (AIP-131)

Add method signature and name field:

rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard) {
  option (google.api.http) = {
    get: "/v1/{name=extendedAgentCards/*}"
  };
  option (google.api.method_signature) = "name";
}

message GetExtendedAgentCardRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

11. ListTasks Parent Field (AIP-132)

Add parent field for list operations:

message ListTasksRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // ... existing fields
}

[darrelmiller]

1. I don't think we should make this change
2. I guess I am ok adding the Optional noise, even though that is the default behavior and we need to acknowledge that google.api.field_behavior.OPTIONAL is not the same as proto optional.
3. I think we can get rid of the final property. I think there is an open issue for that. I'm fine with renaming protected.
4. I like this rename
5. Sure. Seems goodness
6. I'm ok with moving it. Let's not nest it because it will break our docs stuff.
7. I'm not sure I understand the consequences of this. I think I would suppress it.
8. Ok
9. Meh. sure.
10. makes no sense because there is only one. Not sure what we are supposed to do here. How does AIP handle singletons?
11. Sure, that seems right.