proto/agent_communication.proto

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.agentcommunication.v1;

import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/any.proto";
import "google/rpc/status.proto";

option csharp_namespace = "Google.Cloud.AgentCommunication.V1";
option go_package = "cloud.google.com/go/agentcommunication/apiv1/agentcommunicationpb;agentcommunicationpb";
option java_multiple_files = true;
option java_outer_classname = "AgentCommunicationProto";
option java_package = "com.google.cloud.agentcommunication.v1";
option php_namespace = "Google\\Cloud\\AgentCommunication\\V1";
option ruby_package = "Google::Cloud::AgentCommunication::V1";

// AgentCommunication service allowing agents to send and receiving messages.
service AgentCommunication {
  option (google.api.default_host) = "agentcommunication.googleapis.com";

  // Bi-di streaming between the server and resource on a communication channel.
  rpc StreamAgentMessages(stream StreamAgentMessagesRequest)
      returns (stream StreamAgentMessagesResponse) {}

  // Send a message to a client. This is equivalent to sending a message via
  // StreamAgentMessages with a single message and waiting for the response.
  // Channel ID and Resource ID are required to be sent in the header.
  rpc SendAgentMessage(SendAgentMessageRequest)
      returns (SendAgentMessageResponse) {}
}

// Sends an AgentMessage.
message SendAgentMessageRequest {
  // Required. ID of the channel for the connection.
  // The channel ID must:
  //  - Be 1-63 characters in length.
  //  - Match the regular expression ^[a-z]([-a-z0-9]*[a-z0-9])?$. This means
  //  that the first character must be a lowercase letter, and all the following
  //  characters must be hyphens, lowercase letters, or digits, except the last
  //  character, which cannot be a hyphen.
  string channel_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. ID of the resource for the connection.
  // This must only contain UTF-8 encoded characters and be 1-255 characters in
  // length.
  string resource_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The message to be sent.
  MessageBody message_body = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response to a sent message.
message SendAgentMessageResponse {
  // The message response, if any.
  MessageBody message_body = 1;
}

// Registers this connection.
message RegisterConnection {
  // Required. Protocol version to use.
  int32 protocol_version = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. ID of the channel for the connection.
  // The channel ID must:
  //  - Be 1-63 characters in length.
  //  - Match the regular expression ^[a-z]([-a-z0-9]*[a-z0-9])?$. This means
  //  that the first character must be a lowercase letter, and all the following
  //  characters must be hyphens, lowercase letters, or digits, except the last
  //  character, which cannot be a hyphen.
  string channel_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. ID of the resource for the connection.
  // This must only contain UTF-8 encoded characters and be 1-255 characters in
  // length.
  string resource_id = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response to a sent message.
message MessageResponse {
  // Output only. Status for this message response, for non OK status
  // ErrorInfo.reason will be one of StreamAgentMessagesResponse.ErrorReason.
  // Expected agent responses:
  // OK - message was successfully received.
  // Expected service responses:
  // OK - message was successfully received.
  // RESOURCE_EXHAUSTED - this connection is rate limited, message delivery
  // should be slowed.
  google.rpc.Status status = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The message to be delivered.
message MessageBody {
  // Optional. Labels to use for this message for easy lookup and client side
  // filtering. Labels must meet the following constraints:
  //
  // * Keys and values can contain only lowercase letters, numeric characters,
  // underscores, and dashes.
  // * All characters must use UTF-8 encoding, and international characters are
  // allowed.
  // * Keys must start with a lowercase letter or international character.
  // * Each message is limited to a maximum of 12 labels and less than 1024
  // bytes.
  map<string, string> labels = 1 [(google.api.field_behavior) = OPTIONAL];

  // Required. The actual message.
  google.protobuf.Any body = 2 [(google.api.field_behavior) = REQUIRED];
}

// A streaming request message to send messages to the server on a particular
// channel.
message StreamAgentMessagesRequest {
  // Required. The ID of the message sent to the service, this ID is used to
  // uniquely identify this message so service can ack.
  string message_id = 1 [(google.api.field_behavior) = REQUIRED];

  // The type of message.
  oneof type {
    // Initial stream message. Must be sent before any other messages on this
    // stream.
    RegisterConnection register_connection = 2;

    // Response to a message sent from the service.
    // Should be sent as soon as the agent receives a message.
    MessageResponse message_response = 3;

    // A message meant for a client.
    MessageBody message_body = 4;
  }
}

// The streaming rpc message that will send messages to the agent.
message StreamAgentMessagesResponse {
  // Reasons returned in ErrorInfo when the status field of MessageResponse is
  // not OK.
  enum ErrorReason {
    // Default value. This value is unused.
    ERROR_REASON_UNSPECIFIED = 0;

    // Message rate is too high.
    AGENT_MESSAGE_RATE_QUOTA_EXCEEDED = 1;

    // Message Bandwidth rate is too high.
    AGENT_BANDWIDTH_RATE_QUOTA_EXCEEDED = 2;
  }

  // The ID of the message sent to the agent, this ID is used to uniquely
  // identify this message so agent can ack.
  string message_id = 1;

  // The type of message.
  oneof type {
    // Response to a message sent to the service.
    // Will be sent as soon as the service receives a message.
    MessageResponse message_response = 2;

    // A message sent from a client.
    MessageBody message_body = 3;
  }
}

// Reasons returned in ErrorInfo with any messages containing google.rpc.Status.
enum ErrorReason {
  // Default value. This value is unused.
  ERROR_REASON_UNSPECIFIED = 0;

  // The message was missing a message ID.
  MISSING_MESSAGE_ID = 1;

  // The message type was missing or invalid.
  INVALID_MESSAGE_TYPE = 2;

  // The was not acked.
  MESSAGE_NOT_ACKED = 3;

  // The MessageResponse is invalid.
  INVALID_MESSAGE_RESPONSE = 4;

  // The register request was invalid.
  INVALID_REGISTER_REQUEST = 5;

  // Stream headers are missing or invalid.
  INVALID_STREAM_HEADERS = 6;

  // Service enablement check failed.
  SERVICE_CHECK_FAILURE = 7;

  // Rate of new connections is too high.
  AGENT_CONNECTION_RATE_QUOTA_EXCEEDED = 8;

  // Rate of messages too high. This will only happen if message rate far
  // exceeds quota, well behaved agents are expected to respond to
  // AGENT_MESSAGE_RATE_QUOTA_EXCEEDED in StreamAgentMessagesResponse.
  AGENT_MESSAGE_RATE_QUOTA_EXCEEDED = 9;

  // Message bandwidth of new connections is too high.
  AGENT_BANDWIDTH_RATE_QUOTA_EXCEEDED = 10;

  // The SendAgentMessageRequest is invalid.
  INVALID_SEND_AGENT_MESSAGE_REQUEST = 11;
}