// Older protoc compilers don't understand edition yet.
syntax = "proto3";
package a2a.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "A2a.V1";
option go_package = "google.golang.org/a2a/v1";
option java_multiple_files = true;
option java_outer_classname = "A2A";
option java_package = "com.google.a2a.v1";

// A2AService defines the operations of the A2A protocol.
service A2AService {
  // Send a message to the agent.
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {
    option (google.api.http) = {
      post: "/message:send"
      body: "*"
      additional_bindings: {
        post: "/{tenant}/message:send"
        body: "*"
      }
    };
  }
  // SendStreamingMessage is a streaming version of SendMessage.
  rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse) {
    option (google.api.http) = {
      post: "/message:stream"
      body: "*"
      additional_bindings: {
        post: "/{tenant}/message:stream"
        body: "*"
      }
    };
  }

  // Get the current state of a task from the agent.
  rpc GetTask(GetTaskRequest) returns (Task) {
    option (google.api.http) = {
      get: "/tasks/{id=*}"
      additional_bindings: {
        get: "/{tenant}/tasks/{id=*}"
      }
    };
    option (google.api.method_signature) = "id";
  }
  // List tasks with optional filtering and pagination.
  rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
    option (google.api.http) = {
      get: "/tasks"
      additional_bindings: {
        get: "/{tenant}/tasks"
      }
    };
  }
  // Cancel a task.
  rpc CancelTask(CancelTaskRequest) returns (Task) {
    option (google.api.http) = {
      post: "/tasks/{id=*}:cancel"
      body: "*"
      additional_bindings: {
        post: "/{tenant}/tasks/{id=*}:cancel"
        body: "*"
      }
    };
  }
  // SubscribeToTask allows subscribing to task updates for tasks not in terminal state.
  // Returns UnsupportedOperationError if task is in terminal state (completed, failed, canceled, rejected).
  rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse) {
    option (google.api.http) = {
      get: "/tasks/{id=*}:subscribe"
      additional_bindings: {
        get: "/{tenant}/tasks/{id=*}:subscribe"
      }
    };
  }

  // Create a push notification config for a task.
  rpc CreateTaskPushNotificationConfig(CreateTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) {
    option (google.api.http) = {
      post: "/tasks/{task_id=*}/pushNotificationConfigs"
      body: "config"
      additional_bindings: {
        post: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs"
        body: "config"
      }
    };
    option (google.api.method_signature) = "task_id,config";
  }
  // Get a push notification config for a task.
  rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) {
    option (google.api.http) = {
      get: "/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
      additional_bindings: {
        get: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
      }
    };
    option (google.api.method_signature) = "task_id,id";
  }
  // Get a list of push notifications configured for a task.
  rpc ListTaskPushNotificationConfig(ListTaskPushNotificationConfigRequest) returns (ListTaskPushNotificationConfigResponse) {
    option (google.api.http) = {
      get: "/tasks/{task_id=*}/pushNotificationConfigs"
      additional_bindings: {
        get: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs"
      }
    };
    option (google.api.method_signature) = "task_id";
  }
  // GetExtendedAgentCard returns the extended agent card for authenticated agents.
  rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard) {
    option (google.api.http) = {
      get: "/extendedAgentCard"
      additional_bindings: {
        get: "/{tenant}/extendedAgentCard"
      }
    };
  }
  // Delete a push notification config for a task.
  rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
      additional_bindings: {
        delete: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
      }
    };
    option (google.api.method_signature) = "task_id,id";
  }
}

///////// Data Model ////////////

// --8<-- [start:SendMessageConfiguration]
// Configuration of a send message request.
message SendMessageConfiguration {
  // A list of media types the client is prepared to accept for response parts. Agents SHOULD use this to tailor their output.
  repeated string accepted_output_modes = 1;
  // Configuration for the agent to send push notifications for task updates.
  PushNotificationConfig push_notification_config = 2;
  // The maximum number of most recent messages from the task's history to retrieve in
  // the response. An unset value means the client does not impose any limit. A
  // value of zero is a request to not include any messages. The server MUST NOT
  // return more messages than the provided value, but MAY apply a lower limit.
  optional int32 history_length = 3;
  // If true, the operation waits until the task reaches a terminal or interrupted state before returning. Default is false.
  bool blocking = 4;
}
// --8<-- [end:SendMessageConfiguration]

// --8<-- [start: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.
message Task {
  // Unique identifier (e.g. UUID) for the task, generated by the server for a
  // new task.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
  // Unique identifier (e.g. UUID) for the contextual collection of interactions
  // (tasks and messages). Created by the A2A server.
  string context_id = 2 [(google.api.field_behavior) = REQUIRED];
  // The current status of a Task, including state and a message.
  TaskStatus status = 3 [(google.api.field_behavior) = REQUIRED];
  // A set of output artifacts for a Task.
  repeated Artifact artifacts = 4;
  // protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
  // The history of interactions from a task.
  repeated Message history = 5;
  // protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
  // A key/value object to store custom metadata about a task.
  google.protobuf.Struct metadata = 6;
}
// --8<-- [end:Task]

// --8<-- [start:TaskState]
// Defines the possible lifecycle states of a Task.
enum TaskState {
  // The task is in an unknown or indeterminate state.
  TASK_STATE_UNSPECIFIED = 0;
  // Represents the status that acknowledges a task is created.
  TASK_STATE_SUBMITTED = 1;
  // Represents the status that a task is actively being processed.
  TASK_STATE_WORKING = 2;
  // Represents the status a task is finished. This is a terminal state.
  TASK_STATE_COMPLETED = 3;
  // Represents the status a task is done but failed. This is a terminal state.
  TASK_STATE_FAILED = 4;
  // Represents the status a task was canceled before it finished.
  // This is a terminal state.
  TASK_STATE_CANCELED = 5;
  // Represents the status that the task requires information to complete.
  // This is an interrupted state.
  TASK_STATE_INPUT_REQUIRED = 6;
  // 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_REJECTED = 7;
  // Represents the state that some authentication is needed from the upstream
  // client. This is an interrupted state. Authentication is expected to come out-of-band.
  TASK_STATE_AUTH_REQUIRED = 8;
}
// --8<-- [end:TaskState]

// --8<-- [start:TaskStatus]
// A container for the status of a task
message TaskStatus {
  // The current state of this task.
  TaskState state = 1 [(google.api.field_behavior) = REQUIRED];
  // A message associated with the status.
  Message message = 2;
  // ISO 8601 Timestamp when the status was recorded.
  // Example: "2023-10-27T10:00:00Z"
  google.protobuf.Timestamp timestamp = 3;
}
// --8<-- [end:TaskStatus]

// --8<-- [start: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).
message Part {
  oneof content {
    // The string content of the text part.
    string text = 1;
    // The raw byte content of a file. In JSON serialization, this is encoded as a base64 string.
    bytes raw = 2;
    // A URL pointing to the file's content.
    string url = 3;
    // Arbitrary structured data as a JSON value (object, array, string, number, boolean, or null).
    google.protobuf.Value data = 4;
  }
  // Optional metadata associated with this part.
  google.protobuf.Struct metadata = 5;
  // An optional name for the file (e.g., "document.pdf").
  string filename = 6;
  // The media type (MIME type) of the part content (e.g., "text/plain", "application/json", "image/png").
  // This field is available for all part types.
  string media_type = 7;
}
// --8<-- [end:Part]

// --8<-- [start:Role]
// Defines the sender of a message in A2A protocol communication.
enum Role {
  ROLE_UNSPECIFIED = 0;
  // USER role refers to communication from the client to the server.
  ROLE_USER = 1;
  // AGENT role refers to communication from the server to the client.
  ROLE_AGENT = 2;
}
// --8<-- [end:Role]

// --8<-- [start:Message]
// Message is one unit of communication between client and server. It can be
// associated with a context and/or a task. For server messages, context_id must
// be provided, and task_id only if a task was created. For client messages, both
// fields are optional, with the caveat that if both are provided, they have to
// match (the context_id has to be the one that is set on the task). If only
// task_id is provided, the server will infer context_id from it.
message Message {
  // The unique identifier (e.g. UUID) of the message. This is required and
  // created by the message creator.
  string message_id = 1 [(google.api.field_behavior) = REQUIRED];
  // The context id of the message. This is optional and if set, the message
  // will be associated with the given context.
  string context_id = 2;
  // The task id of the message. This is optional and if set, the message
  // will be associated with the given task.
  string task_id = 3;
  // Identifies the sender of the message.
  Role role = 4 [(google.api.field_behavior) = REQUIRED];
  // protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
  // Parts is the container of the message content.
  repeated Part parts = 5 [(google.api.field_behavior) = REQUIRED];
  // protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
  // Any optional metadata to provide along with the message.
  google.protobuf.Struct metadata = 6;
  // The URIs of extensions that are present or contributed to this Message.
  repeated string extensions = 7;
  // A list of task IDs that this message references for additional context.
  repeated string reference_task_ids = 8;
}
// --8<-- [end:Message]

// --8<-- [start:Artifact]
// Artifacts represent task outputs.
message Artifact {
  // Unique identifier (e.g. UUID) for the artifact. It must be at least unique
  // within a task.
  string artifact_id = 1 [(google.api.field_behavior) = REQUIRED];
  // A human readable name for the artifact.
  string name = 3;
  // A human readable description of the artifact, optional.
  string description = 4;
  // The content of the artifact. Must contain at least one part.
  repeated Part parts = 5 [(google.api.field_behavior) = REQUIRED];
  // Optional metadata included with the artifact.
  google.protobuf.Struct metadata = 6;
  // The URIs of extensions that are present or contributed to this Artifact.
  repeated string extensions = 7;
}
// --8<-- [end:Artifact]

// --8<-- [start:TaskStatusUpdateEvent]
// An event sent by the agent to notify the client of a change in a task's
// status.
message TaskStatusUpdateEvent {
  // The id of the task that is changed
  string task_id = 1 [(google.api.field_behavior) = REQUIRED];
  // The id of the context that the task belongs to
  string context_id = 2 [(google.api.field_behavior) = REQUIRED];
  // The new status of the task.
  TaskStatus status = 3 [(google.api.field_behavior) = REQUIRED];
  reserved 4;
  // Optional metadata to associate with the task update.
  google.protobuf.Struct metadata = 5;
}
// --8<-- [end:TaskStatusUpdateEvent]

// --8<-- [start:TaskArtifactUpdateEvent]
// TaskArtifactUpdateEvent represents a task delta where an artifact has
// been generated.
message TaskArtifactUpdateEvent {
  // The id of the task for this artifact.
  string task_id = 1 [(google.api.field_behavior) = REQUIRED];
  // The id of the context that this task belongs to.
  string context_id = 2 [(google.api.field_behavior) = REQUIRED];
  // The artifact that was generated or updated.
  Artifact artifact = 3 [(google.api.field_behavior) = REQUIRED];
  // If true, the content of this artifact should be appended to a previously
  // sent artifact with the same ID.
  bool append = 4;
  // If true, this is the final chunk of the artifact.
  bool last_chunk = 5;
  // Optional metadata associated with the artifact update.
  google.protobuf.Struct metadata = 6;
}
// --8<-- [end:TaskArtifactUpdateEvent]

// --8<-- [start:PushNotificationConfig]
// 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;
  // Authentication information required to send the notification
  AuthenticationInfo authentication = 4;
}
// --8<-- [end:PushNotificationConfig]

// --8<-- [start:PushNotificationAuthenticationInfo]
// Defines authentication details, used for push notifications.
message AuthenticationInfo {
  // HTTP Authentication Scheme from the [IANA registry](https://www.iana.org/assignments/http-authschemes/).
  // Common values: `Bearer`, `Basic`, `Digest`. Scheme names are case-insensitive per [RFC 9110 Section 11.1](https://www.rfc-editor.org/rfc/rfc9110#section-11.1).
  string scheme = 1 [(google.api.field_behavior) = REQUIRED];
  // Push Notification credentials. Format depends on the scheme (e.g., token for Bearer).
  string credentials = 2;
}
// --8<-- [end:PushNotificationAuthenticationInfo]

// --8<-- [start:AgentInterface]
// Declares a combination of a target URL, transport and protocol version for interacting with the agent.
// This allows agents to expose the same functionality over multiple protocol binding mechanisms.
message AgentInterface {
  // The URL where this interface is available. Must be a valid absolute HTTPS URL in production.
  // Example: "https://api.example.com/a2a/v1", "https://grpc.example.com/a2a"
  string url = 1 [(google.api.field_behavior) = REQUIRED];
  // The protocol binding supported at this URL. This is an open form string, to be
  // easily extended for other protocol bindings. The core ones officially
  // supported are `JSONRPC`, `GRPC` and `HTTP+JSON`.
  string protocol_binding = 2 [(google.api.field_behavior) = REQUIRED];
  // Tenant to be set in the request when calling the agent.
  string tenant = 3;
  // The version of the A2A protocol this interface exposes.
  // Use the latest supported minor version per major version.
  // Examples: "0.3", "1.0"
  string protocol_version = 4 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:AgentInterface]

// --8<-- [start:AgentCard]
// AgentCard is a self-describing manifest for an agent. It provides essential
// metadata including the agent's identity, capabilities, skills, supported
// communication methods, and security requirements.
// Next ID: 20
message AgentCard {
  // Reserve these field numbers as they were previously used by removed
  // fields.
  reserved 3, 9, 14, 15, 16;
  // A human readable name for the agent.
  // Example: "Recipe Agent"
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  // A human-readable description of the agent, assisting users and other agents
  // in understanding its purpose.
  // Example: "Agent that helps users with recipes and cooking."
  string description = 2 [(google.api.field_behavior) = REQUIRED];
  // Ordered list of supported interfaces. First entry is preferred.
  repeated AgentInterface supported_interfaces = 19 [(google.api.field_behavior) = REQUIRED];
  // The service provider of the agent.
  AgentProvider provider = 4;
  // The version of the agent.
  // Example: "1.0.0"
  string version = 5 [(google.api.field_behavior) = REQUIRED];
  // A url to provide additional documentation about the agent.
  optional string documentation_url = 6;
  // A2A Capability set supported by the agent.
  AgentCapabilities capabilities = 7 [(google.api.field_behavior) = REQUIRED];
  // The security scheme details used for authenticating with this agent.
  map<string, SecurityScheme> security_schemes = 8;
  // Security requirements for contacting the agent.
  repeated SecurityRequirement security_requirements = 13;
  // 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 media types.
  repeated string default_input_modes = 10 [(google.api.field_behavior) = REQUIRED];
  // The media types supported as outputs from this agent.
  repeated string default_output_modes = 11 [(google.api.field_behavior) = REQUIRED];
  // Skills represent an ability of an agent. It is largely
  // a descriptive concept but represents a more focused set of behaviors that the
  // agent is likely to succeed at.
  repeated AgentSkill skills = 12 [(google.api.field_behavior) = REQUIRED];
  // JSON Web Signatures computed for this AgentCard.
  repeated AgentCardSignature signatures = 17;
  // An optional URL to an icon for the agent.
  optional string icon_url = 18;
}
// --8<-- [end:AgentCard]

// --8<-- [start:AgentProvider]
// Represents the service provider of an agent.
message AgentProvider {
  // A URL for the agent provider's website or relevant documentation.
  // Example: "https://ai.google.dev"
  string url = 1 [(google.api.field_behavior) = REQUIRED];
  // The name of the agent provider's organization.
  // Example: "Google"
  string organization = 2 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:AgentProvider]

// --8<-- [start:AgentCapabilities]
// Defines optional capabilities supported by an agent.
message AgentCapabilities {
  // Indicates if the agent supports streaming responses.
  optional bool streaming = 1;
  // Indicates if the agent supports sending push notifications for asynchronous task updates.
  optional bool push_notifications = 2;
  // A list of protocol extensions supported by the agent.
  repeated AgentExtension extensions = 3;
  // Field 4 was previously used by state_transition_history capability.
  reserved 4;
  // Indicates if the agent supports providing an extended agent card when authenticated.
  optional bool extended_agent_card = 5;
}
// --8<-- [end:AgentCapabilities]

// --8<-- [start:AgentExtension]
// A declaration of a protocol extension supported by an Agent.
message AgentExtension {
  // The unique URI identifying the extension.
  string uri = 1;
  // A human-readable description of how this agent uses the extension.
  string description = 2;
  // If true, the client must understand and comply with the extension's requirements.
  bool required = 3;
  // Optional, extension-specific configuration parameters.
  google.protobuf.Struct params = 4;
}
// --8<-- [end:AgentExtension]

// --8<-- [start:AgentSkill]
// Represents a distinct capability or function that an agent can perform.
message AgentSkill {
  // A unique identifier for the agent's skill.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
  // A human-readable name for the skill.
  string name = 2 [(google.api.field_behavior) = REQUIRED];
  // A detailed description of the skill.
  string description = 3 [(google.api.field_behavior) = REQUIRED];
  // A set of keywords describing the skill's capabilities.
  repeated string tags = 4 [(google.api.field_behavior) = REQUIRED];
  // Example prompts or scenarios that this skill can handle.
  repeated string examples = 5;
  // The set of supported input media types for this skill, overriding the agent's defaults.
  repeated string input_modes = 6;
  // The set of supported output media types for this skill, overriding the agent's defaults.
  repeated string output_modes = 7;
  // Security schemes necessary for this skill.
  repeated SecurityRequirement security_requirements = 8;
}
// --8<-- [end:AgentSkill]

// --8<-- [start:AgentCardSignature]
// AgentCardSignature represents a JWS signature of an AgentCard.
// This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).
message AgentCardSignature {
  // The protected JWS header for the signature. This is always a
  // base64url-encoded JSON object. Required.
  string protected = 1 [(google.api.field_behavior) = REQUIRED];
  // The computed signature, base64url-encoded. Required.
  string signature = 2 [(google.api.field_behavior) = REQUIRED];
  // The unprotected JWS header values.
  google.protobuf.Struct header = 3;
}
// --8<-- [end:AgentCardSignature]

// --8<-- [start:TaskPushNotificationConfig]
// A container associating a push notification configuration with a specific
// task.
message TaskPushNotificationConfig {
  // Optional tenant
  string tenant = 4;

  // The id of the config.
  string id = 1 [(google.api.field_behavior) = REQUIRED];

  // The id of the task this config is associated with.
  string task_id = 3 [(google.api.field_behavior) = REQUIRED];

  // The push notification configuration details.
  PushNotificationConfig push_notification_config = 2 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:TaskPushNotificationConfig]

// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
message StringList {
  repeated string list = 1;
}
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED

message SecurityRequirement {
  map<string, StringList> schemes = 1;
}

// --8<-- [start:SecurityScheme]
// Defines a security scheme that can be used to secure an agent's endpoints.
// This is a discriminated union type based on the OpenAPI 3.2 Security Scheme Object.
// See: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object
message SecurityScheme {
  oneof scheme {
    // API key-based authentication.
    APIKeySecurityScheme api_key_security_scheme = 1;
    // HTTP authentication (Basic, Bearer, etc.).
    HTTPAuthSecurityScheme http_auth_security_scheme = 2;
    // OAuth 2.0 authentication.
    OAuth2SecurityScheme oauth2_security_scheme = 3;
    // OpenID Connect authentication.
    OpenIdConnectSecurityScheme open_id_connect_security_scheme = 4;
    // Mutual TLS authentication.
    MutualTlsSecurityScheme mtls_security_scheme = 5;
  }
}
// --8<-- [end:SecurityScheme]

// --8<-- [start:APIKeySecurityScheme]
// Defines a security scheme using an API key.
message APIKeySecurityScheme {
  // An optional description for the security scheme.
  string description = 1;
  // The location of the API key. Valid values are "query", "header", or "cookie".
  string location = 2 [(google.api.field_behavior) = REQUIRED];
  // The name of the header, query, or cookie parameter to be used.
  string name = 3 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:APIKeySecurityScheme]

// --8<-- [start:HTTPAuthSecurityScheme]
// Defines a security scheme using HTTP authentication.
message HTTPAuthSecurityScheme {
  // An optional description for the security scheme.
  string description = 1;
  // The name of the HTTP Authentication scheme to be used in the Authorization header,
  // as defined in RFC7235 (e.g., "Bearer").
  // This value should be registered in the IANA Authentication Scheme registry.
  string scheme = 2 [(google.api.field_behavior) = REQUIRED];
  // A hint to the client to identify how the bearer token is formatted (e.g., "JWT").
  // This is primarily for documentation purposes.
  string bearer_format = 3;
}
// --8<-- [end:HTTPAuthSecurityScheme]

// --8<-- [start:OAuth2SecurityScheme]
// Defines a security scheme using OAuth 2.0.
message OAuth2SecurityScheme {
  // An optional description for the security scheme.
  string description = 1;
  // An object containing configuration information for the supported OAuth 2.0 flows.
  OAuthFlows flows = 2 [(google.api.field_behavior) = REQUIRED];
  // URL to the oauth2 authorization server metadata
  // RFC8414 (https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
  string oauth2_metadata_url = 3;
}
// --8<-- [end:OAuth2SecurityScheme]

// --8<-- [start:OpenIdConnectSecurityScheme]
// Defines a security scheme using OpenID Connect.
message OpenIdConnectSecurityScheme {
  // An optional description for the security scheme.
  string description = 1;
  // The OpenID Connect Discovery URL for the OIDC provider's metadata.
  // See: https://openid.net/specs/openid-connect-discovery-1_0.html
  string open_id_connect_url = 2 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:OpenIdConnectSecurityScheme]

// --8<-- [start:MutualTLSSecurityScheme]
// Defines a security scheme using mTLS authentication.
message MutualTlsSecurityScheme {
  // An optional description for the security scheme.
  string description = 1;
}
// --8<-- [end:MutualTLSSecurityScheme]

// --8<-- [start:OAuthFlows]
// Defines the configuration for the supported OAuth 2.0 flows.
message OAuthFlows {
  oneof flow {
    // Configuration for the OAuth Authorization Code flow.
    AuthorizationCodeOAuthFlow authorization_code = 1;
    // Configuration for the OAuth Client Credentials flow.
    ClientCredentialsOAuthFlow client_credentials = 2;
    ImplicitOAuthFlow implicit = 3 [deprecated = true];
    PasswordOAuthFlow password = 4 [deprecated = true];
    // Configuration for the OAuth Device Code flow.
    DeviceCodeOAuthFlow device_code = 5;
  }
}
// --8<-- [end:OAuthFlows]

// --8<-- [start:AuthorizationCodeOAuthFlow]
// Defines configuration details for the OAuth 2.0 Authorization Code flow.
message AuthorizationCodeOAuthFlow {
  // The authorization URL to be used for this flow.
  string authorization_url = 1 [(google.api.field_behavior) = REQUIRED];
  // The token URL to be used for this flow.
  string token_url = 2 [(google.api.field_behavior) = REQUIRED];
  // The URL to be used for obtaining refresh tokens.
  string refresh_url = 3;
  // The available scopes for the OAuth2 security scheme.
  map<string, string> scopes = 4 [(google.api.field_behavior) = REQUIRED];
  // Indicates if PKCE (RFC 7636) is required for this flow.
  // PKCE should always be used for public clients and is recommended for all clients.
  bool pkce_required = 5;
}
// --8<-- [end:AuthorizationCodeOAuthFlow]

// --8<-- [start:ClientCredentialsOAuthFlow]
// Defines configuration details for the OAuth 2.0 Client Credentials flow.
message ClientCredentialsOAuthFlow {
  // The token URL to be used for this flow.
  string token_url = 1 [(google.api.field_behavior) = REQUIRED];
  // The URL to be used for obtaining refresh tokens.
  string refresh_url = 2;
  // The available scopes for the OAuth2 security scheme.
  map<string, string> scopes = 3 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:ClientCredentialsOAuthFlow]

// DEPRECATED
message ImplicitOAuthFlow {
  // 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
  string authorization_url = 1;
  // 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.
  string refresh_url = 2;
  // 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.
  map<string, string> scopes = 3;
}

// DEPRECATED
message PasswordOAuthFlow {
  // 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.
  string token_url = 1;
  // 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.
  string refresh_url = 2;
  // 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.
  map<string, string> scopes = 3;
}

// --8<-- [start:DeviceCodeOAuthFlow]
// Defines configuration details for the OAuth 2.0 Device Code flow (RFC 8628).
// This flow is designed for input-constrained devices such as IoT devices,
// and CLI tools where the user authenticates on a separate device.
message DeviceCodeOAuthFlow {
  // The device authorization endpoint URL.
  string device_authorization_url = 1 [(google.api.field_behavior) = REQUIRED];
  // The token URL to be used for this flow.
  string token_url = 2 [(google.api.field_behavior) = REQUIRED];
  // The URL to be used for obtaining refresh tokens.
  string refresh_url = 3;
  // The available scopes for the OAuth2 security scheme.
  map<string, string> scopes = 4 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:DeviceCodeOAuthFlow]

///////////// Request Messages ///////////
// --8<-- [start:SendMessageRequest]
// Represents a request for the `SendMessage` method.
message SendMessageRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 4;
  // The message to send to the agent.
  Message message = 1 [(google.api.field_behavior) = REQUIRED];
  // Configuration for the send request.
  SendMessageConfiguration configuration = 2;
  // A flexible key-value map for passing additional context or parameters.
  google.protobuf.Struct metadata = 3;
}
// --8<-- [end:SendMessageRequest]

// --8<-- [start:GetTaskRequest]
// Represents a request for the `GetTask` method.
message GetTaskRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 3;
  // The resource id of the task.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
  // The maximum number of most recent messages from the task's history to retrieve. An
  // unset value means the client does not impose any limit. A value of zero is
  // a request to not include any messages. The server MUST NOT return more
  // messages than the provided value, but MAY apply a lower limit.
  optional int32 history_length = 2;
}
// --8<-- [end:GetTaskRequest]

// --8<-- [start:ListTasksRequest]
// Parameters for listing tasks with optional filtering criteria.
message ListTasksRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 9;
  // Filter tasks by context ID to get tasks from a specific conversation or session.
  string context_id = 1;
  // Filter tasks by their current status state.
  TaskState status = 2;
  // Maximum number of tasks to return. Must be between 1 and 100.
  // Defaults to 50 if not specified.
  optional int32 page_size = 3;
  // Token for pagination. Use the next_page_token from a previous ListTasksResponse.
  string page_token = 4;
  // The maximum number of messages to include in each task's history.
  optional int32 history_length = 5;
  // Filter tasks which have a status updated after the provided timestamp in ISO 8601 format (e.g., "2023-10-27T10:00:00Z").
  // Only tasks with a status timestamp time greater than or equal to this value will be returned.
  google.protobuf.Timestamp status_timestamp_after = 6;
  // Whether to include artifacts in the returned tasks.
  // Defaults to false to reduce payload size.
  optional bool include_artifacts = 7;
}
// --8<-- [end:ListTasksRequest]

// --8<-- [start:ListTasksResponse]
// Result object for tasks/list method containing an array of tasks and pagination information.
message ListTasksResponse {
  // Array of tasks matching the specified criteria.
  repeated Task tasks = 1 [(google.api.field_behavior) = REQUIRED];
  // Token for retrieving the next page. Empty string if no more results.
  string next_page_token = 2 [(google.api.field_behavior) = REQUIRED];
  // The size of page requested.
  int32 page_size = 3 [(google.api.field_behavior) = REQUIRED];
  // Total number of tasks available (before pagination).
  int32 total_size = 4 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:ListTasksResponse]

// --8<-- [start:CancelTaskRequest]
// Represents a request for the `CancelTask` method.
message CancelTaskRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 2;
  // The resource id of the task to cancel.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:CancelTaskRequest]

// --8<-- [start:GetTaskPushNotificationConfigRequest]
message GetTaskPushNotificationConfigRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 2;
  // The parent task resource id.
  string task_id = 3 [(google.api.field_behavior) = REQUIRED];
  // The resource id of the config to retrieve.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:GetTaskPushNotificationConfigRequest]

// --8<-- [start:DeleteTaskPushNotificationConfigRequest]
// Represents a request for the `DeleteTaskPushNotificationConfig` method.
message DeleteTaskPushNotificationConfigRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 2;
  // The parent task resource id.
  string task_id = 3 [(google.api.field_behavior) = REQUIRED];
  // The resource id of the config to delete.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:DeleteTaskPushNotificationConfigRequest]

// --8<-- [start:CreateTaskPushNotificationConfigRequest]
// Represents a request for the `CreateTaskPushNotificationConfig` method.
message CreateTaskPushNotificationConfigRequest {
  reserved 3;
  // Optional tenant, provided as a path parameter.
  string tenant = 4;
  // The parent task resource id.
  string task_id = 1 [(google.api.field_behavior) = REQUIRED];
  // The ID for the new config.
  string config_id = 2 [(google.api.field_behavior) = REQUIRED];
  // The configuration to create.
  PushNotificationConfig config = 5 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:CreateTaskPushNotificationConfigRequest]

// --8<-- [start:SubscribeToTaskRequest]
message SubscribeToTaskRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 2;
  // The resource id of the task to subscribe to.
  string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:SubscribeToTaskRequest]

// --8<-- [start:ListTaskPushNotificationConfigRequest]
message ListTaskPushNotificationConfigRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 4;
  // The parent task resource id.
  string task_id = 1 [(google.api.field_behavior) = REQUIRED];

  // The maximum number of configurations to return.
  int32 page_size = 2;

  // A page token received from a previous ListTaskPushNotificationConfigRequest call.
  string page_token = 3;
}
// --8<-- [end:ListTaskPushNotificationConfigRequest]

// --8<-- [start:GetExtendedAgentCardRequest]
message GetExtendedAgentCardRequest {
  // Optional tenant, provided as a path parameter.
  string tenant = 1;
}
// --8<-- [end:GetExtendedAgentCardRequest]

//////// Response Messages ///////////
// --8<-- [start:SendMessageResponse]
message SendMessageResponse {
  oneof payload {
    Task task = 1;
    Message message = 2;
  }
}
// --8<-- [end:SendMessageResponse]

// --8<-- [start:StreamResponse]
// A wrapper object used in streaming operations to encapsulate different types of response data.
message StreamResponse {
  oneof payload {
    // A Task object containing the current state of the task.
    Task task = 1;
    // A Message object containing a message from the agent.
    Message message = 2;
    // An event indicating a task status update.
    TaskStatusUpdateEvent status_update = 3;
    // An event indicating a task artifact update.
    TaskArtifactUpdateEvent artifact_update = 4;
  }
}
// --8<-- [end:StreamResponse]

// --8<-- [start:ListTaskPushNotificationConfigResponse]
// Represents a successful response for the `ListTaskPushNotificationConfig`
// method.
message ListTaskPushNotificationConfigResponse {
  // The list of push notification configurations.
  repeated TaskPushNotificationConfig configs = 1;
  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}
// --8<-- [end:ListTaskPushNotificationConfigResponse]
