+ * This exception is thrown when client-side errors occur during A2A protocol + * interactions, such as communication failures, invalid responses, or + * protocol violations. + *
+ */ public class A2AClientError extends Exception { + /** + * Constructs a new A2AClientError with no detail message. + */ public A2AClientError() { } + /** + * Constructs a new A2AClientError with the specified detail message. + * + * @param message the detail message explaining the error + */ public A2AClientError(String message) { super(message); } + /** + * Constructs a new A2AClientError with the specified detail message and cause. + * + * @param message the detail message explaining the error + * @param cause the underlying cause of this exception + */ public A2AClientError(String message, Throwable cause) { super(message, cause); } diff --git a/spec/src/main/java/io/a2a/spec/A2AClientHTTPError.java b/spec/src/main/java/io/a2a/spec/A2AClientHTTPError.java index 95b59a764..7bdb742c2 100644 --- a/spec/src/main/java/io/a2a/spec/A2AClientHTTPError.java +++ b/spec/src/main/java/io/a2a/spec/A2AClientHTTPError.java @@ -2,10 +2,26 @@ import io.a2a.util.Assert; +/** + * Exception class representing HTTP-specific errors that occur in A2A client operations. + *+ * This exception extends {@link A2AClientError} and provides additional information + * about HTTP-related failures, including the HTTP status code and error message. + * It is thrown when HTTP communication errors occur during A2A protocol interactions. + *
+ */ public class A2AClientHTTPError extends A2AClientError { private final int code; private final String message; + /** + * Constructs a new A2AClientHTTPError with the specified HTTP status code, message, and data. + * + * @param code the HTTP status code associated with this error + * @param message the error message describing the HTTP error + * @param data additional data associated with the error (currently unused but reserved for future use) + * @throws IllegalArgumentException if message is null + */ public A2AClientHTTPError(int code, String message, Object data) { Assert.checkNotNullParam("code", code); Assert.checkNotNullParam("message", message); diff --git a/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java b/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java index 75988da1c..bdd88bfee 100644 --- a/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java +++ b/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java @@ -1,14 +1,37 @@ package io.a2a.spec; +/** + * Exception class representing JSON-specific errors that occur in A2A client operations. + *+ * This exception extends {@link A2AClientError} and is thrown when JSON parsing, + * serialization, or deserialization errors occur during A2A protocol interactions. + * Common scenarios include malformed JSON responses, invalid JSON structure, + * or JSON schema validation failures. + *
+ */ public class A2AClientJSONError extends A2AClientError { + /** + * Constructs a new A2AClientJSONError with no detail message. + */ public A2AClientJSONError() { } + /** + * Constructs a new A2AClientJSONError with the specified detail message. + * + * @param message the detail message explaining the JSON error + */ public A2AClientJSONError(String message) { super(message); } + /** + * Constructs a new A2AClientJSONError with the specified detail message and cause. + * + * @param message the detail message explaining the JSON error + * @param cause the underlying cause of this JSON error + */ public A2AClientJSONError(String message, Throwable cause) { super(message, cause); } diff --git a/spec/src/main/java/io/a2a/spec/A2AError.java b/spec/src/main/java/io/a2a/spec/A2AError.java index 4c9951df2..3817b5132 100644 --- a/spec/src/main/java/io/a2a/spec/A2AError.java +++ b/spec/src/main/java/io/a2a/spec/A2AError.java @@ -1,4 +1,17 @@ package io.a2a.spec; +/** + * Marker interface for all A2A protocol error events. + *+ * This interface extends {@link Event} and serves as a common type for all + * error-related events in the A2A protocol. It provides a way to categorize + * and handle error events uniformly across the system. + *
+ *+ * Implementations of this interface represent various types of errors that + * can occur during A2A protocol operations, such as validation errors, + * processing errors, or communication failures. + *
+ */ public interface A2AError extends Event { } diff --git a/spec/src/main/java/io/a2a/spec/A2AServerException.java b/spec/src/main/java/io/a2a/spec/A2AServerException.java index ca2611c2f..fc740c59f 100644 --- a/spec/src/main/java/io/a2a/spec/A2AServerException.java +++ b/spec/src/main/java/io/a2a/spec/A2AServerException.java @@ -5,18 +5,37 @@ */ public class A2AServerException extends A2AException { + /** + * Constructs a new A2AServerException with no detail message. + */ public A2AServerException() { super(); } + /** + * Constructs a new A2AServerException with the specified detail message. + * + * @param msg the detail message explaining the server error + */ public A2AServerException(final String msg) { super(msg); } + /** + * Constructs a new A2AServerException with the specified cause. + * + * @param cause the underlying cause of this server exception + */ public A2AServerException(final Throwable cause) { super(cause); } + /** + * Constructs a new A2AServerException with the specified detail message and cause. + * + * @param msg the detail message explaining the server error + * @param cause the underlying cause of this server exception + */ public A2AServerException(final String msg, final Throwable cause) { super(msg, cause); } diff --git a/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java b/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java index acf33feba..eb41d2dc1 100644 --- a/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java +++ b/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java @@ -55,10 +55,27 @@ public static Location fromString(String location) { } } + /** + * Constructs a new APIKeySecurityScheme with the specified parameters. + * + * @param in the location of the API key (header, query, or cookie) + * @param name the name of the API key parameter + * @param description a description of the security scheme + */ public APIKeySecurityScheme(String in, String name, String description) { this(in, name, description, API_KEY); } + /** + * Constructs a new APIKeySecurityScheme with the specified parameters. + * This constructor is used for JSON deserialization. + * + * @param in the location of the API key (header, query, or cookie) + * @param name the name of the API key parameter + * @param description a description of the security scheme + * @param type the type of security scheme (must be "apiKey") + * @throws IllegalArgumentException if the type is not "apiKey" + */ @JsonCreator public APIKeySecurityScheme(@JsonProperty("in") String in, @JsonProperty("name") String name, @JsonProperty("description") String description, @JsonProperty("type") String type) { @@ -79,38 +96,79 @@ public String getDescription() { } + /** + * Gets the location of the API key. + * + * @return the location where the API key should be placed (header, query, or cookie) + */ public String getIn() { return in; } + /** + * Gets the name of the API key parameter. + * + * @return the parameter name for the API key + */ public String getName() { return name; } + /** + * Gets the type of this security scheme. + * + * @return the security scheme type (always "apiKey") + */ public String getType() { return type; } + /** + * Builder class for constructing APIKeySecurityScheme instances. + */ public static class Builder { private String in; private String name; private String description; + /** + * Sets the location of the API key. + * + * @param in the location where the API key should be placed (header, query, or cookie) + * @return this builder instance for method chaining + */ public Builder in(String in) { this.in = in; return this; } + /** + * Sets the name of the API key parameter. + * + * @param name the parameter name for the API key + * @return this builder instance for method chaining + */ public Builder name(String name) { this.name = name; return this; } + /** + * Sets the description of the security scheme. + * + * @param description a description of the security scheme + * @return this builder instance for method chaining + */ public Builder description(String description) { this.description = description; return this; } + /** + * Builds and returns a new APIKeySecurityScheme instance. + * + * @return a new APIKeySecurityScheme with the configured parameters + */ public APIKeySecurityScheme build() { return new APIKeySecurityScheme(in, name, description); } diff --git a/spec/src/main/java/io/a2a/spec/AgentCapabilities.java b/spec/src/main/java/io/a2a/spec/AgentCapabilities.java index 641f56ccb..8da01b9c8 100644 --- a/spec/src/main/java/io/a2a/spec/AgentCapabilities.java +++ b/spec/src/main/java/io/a2a/spec/AgentCapabilities.java @@ -6,13 +6,22 @@ import com.fasterxml.jackson.annotation.JsonInclude; /** - * An agent's capabilities. + * Represents the optional A2A protocol features and capabilities supported by an agent. + * These capabilities define what advanced features the agent can handle beyond basic messaging. + * + * @param streaming whether the agent supports streaming responses for real-time communication + * @param pushNotifications whether the agent can send push notifications to clients + * @param stateTransitionHistory whether the agent maintains and provides access to state transition history + * @param extensions list of additional extensions or custom capabilities supported by the agent */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record AgentCapabilities(boolean streaming, boolean pushNotifications, boolean stateTransitionHistory, ListAn AgentCard conveys key information about an A2A Server: + *
+ * Agent extensions provide additional functionality or capabilities that can be + * added to an agent. Each extension is identified by a URI and can include + * parameters, a description, and a required flag indicating whether the + * extension is mandatory for the agent to function properly. + *
+ * + * @param description a human-readable description of the extension + * @param params a map of parameters specific to this extension + * @param required whether this extension is required for the agent to function + * @param uri the unique identifier URI for this extension + */ public record AgentExtension (String description, Map+ * This constructor ensures that the URI parameter is not null, as it is + * required to uniquely identify the extension. + *
+ * + * @throws IllegalArgumentException if uri is null + */ public AgentExtension { Assert.checkNotNullParam("uri", uri); } + /** + * Builder class for constructing AgentExtension instances. + */ public static class Builder { String description; Map+ * This constructor ensures that the artifact ID and parts are not null, + * and that the parts list is not empty, as artifacts must contain content. + *
+ * + * @throws IllegalArgumentException if artifactId is null, parts is null, or parts is empty + */ public Artifact { Assert.checkNotNullParam("artifactId", artifactId); Assert.checkNotNullParam("parts", parts); @@ -23,6 +40,9 @@ public record Artifact(String artifactId, String name, String description, List< } } + /** + * Builder class for constructing {@link Artifact} instances. + */ public static class Builder { private String artifactId; private String name; @@ -30,9 +50,17 @@ public static class Builder { private List+ * This record contains the authentication schemes supported by the agent + * and any associated credentials. The authentication information is used + * to establish secure communication between agents in the A2A protocol. + *
+ * + * @param schemes a list of supported authentication scheme names + * @param credentials the authentication credentials (optional) */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record AuthenticationInfo(List+ * This constructor ensures that the schemes list is not null, as at least + * one authentication scheme must be specified. + *
+ * + * @throws IllegalArgumentException if schemes is null + */ public AuthenticationInfo { Assert.checkNotNullParam("schemes", schemes); } diff --git a/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java b/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java index 0723a1281..404badea8 100644 --- a/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java +++ b/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java @@ -9,12 +9,20 @@ /** * Configuration for the OAuth Authorization Code flow. + * This flow is used for server-side applications where the client can securely store credentials. + * The authorization code flow involves redirecting the user to the authorization server, + * obtaining an authorization code, and then exchanging it for an access token. */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record AuthorizationCodeOAuthFlow(String authorizationUrl, String refreshUrl, Map+ * A DataPart contains structured data in the form of a map of key-value pairs. + * This type of part is used to transmit arbitrary structured data between + * agents, such as JSON objects, configuration data, or any other structured + * information that can be represented as a map. + *
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -19,10 +25,23 @@ public class DataPart extends Part+ * This interface defines the contract for file content that can be transmitted + * between agents. File content can be represented in two ways: + *
+ *+ * The interface uses a custom deserializer to handle the polymorphic nature + * of file content during JSON deserialization. + *
+ */ @JsonDeserialize(using = FileContentDeserializer.class) public sealed interface FileContent permits FileWithBytes, FileWithUri { + /** + * Gets the MIME type of the file content. + * + * @return the MIME type string (e.g., "text/plain", "image/jpeg") + */ String mimeType(); + /** + * Gets the name of the file. + * + * @return the file name including extension + */ String name(); } diff --git a/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java b/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java index aa763db42..9c55a5952 100644 --- a/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java +++ b/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java @@ -8,16 +8,41 @@ import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.deser.std.StdDeserializer; +/** + * Custom Jackson deserializer for FileContent objects. + * This deserializer handles the polymorphic nature of file content, which can be represented + * either as base64-encoded bytes or as a URI reference. It determines the appropriate + * FileContent subtype based on the presence of "bytes" or "uri" fields in the JSON. + */ public class FileContentDeserializer extends StdDeserializer+ * A FilePart contains file content that can be transmitted between agents. + * The file content can be either embedded as bytes ({@link FileWithBytes}) + * or referenced by a URI ({@link FileWithUri}). This part type is used + * for sharing documents, images, or any other file-based content. + *
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -19,10 +25,23 @@ public class FilePart extends Part+ * This implementation of {@link FileContent} contains the actual file data + * as a base64-encoded string. This approach is suitable for smaller files + * that can be efficiently transmitted as part of the message payload. + *
+ *+ * For larger files or when bandwidth is a concern, consider using + * {@link FileWithUri} instead, which references the file by URI. + *
+ * + * @param mimeType the MIME type of the file (e.g., "text/plain", "image/jpeg") + * @param name the name of the file including extension + * @param bytes the file content encoded as a base64 string + */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record FileWithBytes(String mimeType, String name, String bytes) implements FileContent { diff --git a/spec/src/main/java/io/a2a/spec/FileWithUri.java b/spec/src/main/java/io/a2a/spec/FileWithUri.java index 65db42dc5..06ba411c1 100644 --- a/spec/src/main/java/io/a2a/spec/FileWithUri.java +++ b/spec/src/main/java/io/a2a/spec/FileWithUri.java @@ -3,6 +3,24 @@ import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonInclude; +/** + * Represents file content referenced by a URI in the A2A protocol. + *+ * This implementation of {@link FileContent} contains a reference to file data + * via a URI instead of embedding the actual file content. This approach is + * more efficient for larger files or when bandwidth optimization is important, + * as it avoids including the file data directly in the message payload. + *
+ *+ * The URI can point to various locations such as HTTP/HTTPS URLs, file system + * paths, or other accessible resource identifiers. The receiving agent is + * responsible for retrieving the file content from the specified URI. + *
+ * + * @param mimeType the MIME type of the file (e.g., "text/plain", "image/jpeg") + * @param name the name of the file including extension + * @param uri the URI where the file content can be accessed + */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record FileWithUri(String mimeType, String name, String uri) implements FileContent { diff --git a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java index b353e0cc8..e87c3a72e 100644 --- a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java +++ b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java @@ -10,14 +10,28 @@ import java.util.UUID; /** - * A get task push notification request. + * A JSON-RPC request to retrieve the push notification configuration for a specific task. + * This request is used to get the current webhook configuration that the server uses + * to send asynchronous task updates to the client. Push notifications are useful for + * long-running tasks where the client may not maintain a persistent connection. */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class GetTaskPushNotificationConfigRequest extends NonStreamingJSONRPCRequestA JSON-RPC response must contain either a result (for success) or an error (for failure), + * but never both. The response also includes the JSON-RPC version and an optional ID that + * matches the corresponding request.
+ * + *This class enforces the JSON-RPC 2.0 specification constraints and provides common + * functionality for all response types in the A2A protocol.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -17,11 +25,21 @@ public abstract sealed class JSONRPCResponseThe configuration includes:
+ *Important behavioral notes:
+ *The parameters include:
+ *This error is typically returned when:
+ *According to JSON-RPC 2.0, this error uses code -32601.
+ */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public class MethodNotFoundError extends JSONRPCError { + /** The default JSON-RPC error code for method not found errors */ public final static Integer DEFAULT_CODE = -32601; + /** + * Constructs a new MethodNotFoundError with the specified error details. + * This constructor is used by Jackson for JSON deserialization. + * + * @param code the JSON-RPC error code (defaults to -32601 if null) + * @param message a human-readable error message (defaults to "Method not found" if null) + * @param data additional error data providing context (can be null) + */ @JsonCreator public MethodNotFoundError( @JsonProperty("code") Integer code, @@ -24,6 +47,10 @@ public MethodNotFoundError( data); } + /** + * Constructs a new MethodNotFoundError with default values. + * Uses the default error code (-32601) and message ("Method not found"). + */ public MethodNotFoundError() { this(DEFAULT_CODE, null, null); } diff --git a/spec/src/main/java/io/a2a/spec/MethodNotFoundJsonMappingException.java b/spec/src/main/java/io/a2a/spec/MethodNotFoundJsonMappingException.java index 7bd167ad1..1fe753a44 100644 --- a/spec/src/main/java/io/a2a/spec/MethodNotFoundJsonMappingException.java +++ b/spec/src/main/java/io/a2a/spec/MethodNotFoundJsonMappingException.java @@ -1,11 +1,40 @@ package io.a2a.spec; +/** + * Exception thrown during JSON deserialization when a requested method is not found. + * This exception is specifically used in the context of JSON-RPC request deserialization + * when the method field contains an unrecognized or unsupported method name. + * + *This exception extends {@code IdJsonMappingException} to preserve the request ID + * from the original JSON-RPC request, which is essential for proper error response + * generation according to the JSON-RPC 2.0 specification.
+ * + *Common scenarios where this exception is thrown:
+ *Non-streaming requests are used for operations that:
+ *This class is sealed and permits only the following concrete implementations:
+ *The class uses a custom deserializer ({@link NonStreamingJSONRPCRequestDeserializer}) + * to properly handle the polymorphic deserialization based on the method field.
+ * + * @paramOAuth 2.0 is a widely-used authorization framework that enables applications + * to obtain limited access to user accounts. In the A2A context, it allows agents + * to securely authenticate and authorize access to their services.
+ * + *The security scheme includes:
+ *This implementation follows the OpenAPI Security Scheme Object specification + * for OAuth 2.0 security schemes, ensuring compatibility with standard OAuth 2.0 + * implementations and tooling.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class OAuth2SecurityScheme implements SecurityScheme { public static final String OAUTH2 = "oauth2"; + + /** + * The OAuth flows supported by this security scheme. + * Defines the available OAuth 2.0 grant types and their configurations. + */ private final OAuthFlows flows; + + /** + * Optional description of the OAuth 2.0 security scheme. + * Provides human-readable information about the authentication requirements. + */ private final String description; + + /** + * The type of security scheme, always "oauth2" for OAuth 2.0. + */ private final String type; + /** + * Constructs an OAuth 2.0 security scheme with flows and description. + * + * @param flows the OAuth flows configuration (must not be null) + * @param description optional description of the security scheme (can be null) + */ public OAuth2SecurityScheme(OAuthFlows flows, String description) { this(flows, description, OAUTH2); } + /** + * Constructs an OAuth 2.0 security scheme with all parameters. + * This constructor is used for JSON deserialization. + * + * @param flows the OAuth flows configuration (must not be null) + * @param description optional description of the security scheme (can be null) + * @param type the security scheme type (must be "oauth2") + * @throws IllegalArgumentException if flows is null or type is not "oauth2" + */ @JsonCreator public OAuth2SecurityScheme(@JsonProperty("flows") OAuthFlows flows, @JsonProperty("description") String description, @JsonProperty("type") String type) { @@ -35,33 +81,77 @@ public OAuth2SecurityScheme(@JsonProperty("flows") OAuthFlows flows, @JsonProper this.type = type; } + /** + * Returns the optional description of this security scheme. + * + * @return the description, or null if not provided + */ @Override public String getDescription() { return description; } + /** + * Returns the OAuth flows configuration for this security scheme. + * + * @return the OAuth flows configuration + */ public OAuthFlows getFlows() { return flows; } + /** + * Returns the type of this security scheme. + * + * @return always "oauth2" for OAuth 2.0 security schemes + */ public String getType() { return type; } + /** + * Builder class for constructing OAuth2SecurityScheme instances. + * Provides a fluent API for setting optional properties. + */ public static class Builder { + /** + * The OAuth flows configuration for the security scheme. + */ private OAuthFlows flows; + + /** + * Optional description of the security scheme. + */ private String description; + /** + * Sets the OAuth flows configuration. + * + * @param flows the OAuth flows configuration + * @return this builder instance for method chaining + */ public Builder flows(OAuthFlows flows) { this.flows = flows; return this; } + /** + * Sets the optional description for the security scheme. + * + * @param description the description of the security scheme + * @return this builder instance for method chaining + */ public Builder description(String description) { this.description = description; return this; } + /** + * Builds and returns a new OAuth2SecurityScheme instance. + * + * @return a new OAuth2SecurityScheme with the configured properties + * @throws IllegalArgumentException if flows is null + */ public OAuth2SecurityScheme build() { return new OAuth2SecurityScheme(flows, description); } diff --git a/spec/src/main/java/io/a2a/spec/OAuthFlows.java b/spec/src/main/java/io/a2a/spec/OAuthFlows.java index fcd89bc3d..de82b0ec2 100644 --- a/spec/src/main/java/io/a2a/spec/OAuthFlows.java +++ b/spec/src/main/java/io/a2a/spec/OAuthFlows.java @@ -4,39 +4,93 @@ import com.fasterxml.jackson.annotation.JsonInclude; /** - * Allows configuration of the supported OAuth Flows. + * Represents the configuration for supported OAuth 2.0 flows in the A2A protocol. + * This record defines the various OAuth 2.0 grant types that an agent supports + * for authentication and authorization. + * + *OAuth flows define how clients can obtain access tokens to authenticate + * with the agent. Different flows are suitable for different types of applications:
+ *This implementation follows the OpenAPI OAuth Flows Object specification, + * ensuring compatibility with standard OAuth 2.0 implementations and tooling.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record OAuthFlows(AuthorizationCodeOAuthFlow authorizationCode, ClientCredentialsOAuthFlow clientCredentials, ImplicitOAuthFlow implicit, PasswordOAuthFlow password) { + /** + * Builder class for constructing OAuthFlows instances. + * Provides a fluent API for configuring supported OAuth 2.0 flows. + */ public static class Builder { + /** Configuration for the authorization code flow */ private AuthorizationCodeOAuthFlow authorizationCode; + + /** Configuration for the client credentials flow */ private ClientCredentialsOAuthFlow clientCredentials; + + /** Configuration for the implicit flow */ private ImplicitOAuthFlow implicit; + + /** Configuration for the password flow */ private PasswordOAuthFlow password; + /** + * Sets the authorization code flow configuration. + * + * @param authorizationCode the authorization code flow configuration + * @return this builder instance for method chaining + */ public Builder authorizationCode(AuthorizationCodeOAuthFlow authorizationCode) { this.authorizationCode = authorizationCode; return this; } + /** + * Sets the client credentials flow configuration. + * + * @param clientCredentials the client credentials flow configuration + * @return this builder instance for method chaining + */ public Builder clientCredentials(ClientCredentialsOAuthFlow clientCredentials) { this.clientCredentials = clientCredentials; return this; } + /** + * Sets the implicit flow configuration. + * + * @param implicit the implicit flow configuration + * @return this builder instance for method chaining + */ public Builder implicit(ImplicitOAuthFlow implicit) { this.implicit = implicit; return this; } + /** + * Sets the password flow configuration. + * + * @param password the password flow configuration + * @return this builder instance for method chaining + */ public Builder password(PasswordOAuthFlow password) { this.password = password; return this; } + /** + * Builds and returns a new OAuthFlows instance. + * + * @return a new OAuthFlows with the configured flow settings + */ public OAuthFlows build() { return new OAuthFlows(authorizationCode, clientCredentials, implicit, password); } diff --git a/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java b/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java index f8f059792..cf115e32d 100644 --- a/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java +++ b/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java @@ -6,7 +6,24 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * Represents an OpenID Connect security scheme. + * Represents an OpenID Connect security scheme configuration for the A2A protocol. + * This record defines the OpenID Connect (OIDC) authentication mechanism that allows + * agents to authenticate users through an identity provider. + * + *OpenID Connect is an identity layer built on top of OAuth 2.0 that enables + * clients to verify the identity of end-users based on authentication performed + * by an authorization server. It provides a standardized way to obtain basic + * profile information about the user.
+ * + *Key components of this security scheme:
+ *This implementation follows the OpenAPI Security Scheme Object specification + * for OpenID Connect, ensuring compatibility with standard OIDC implementations.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -45,20 +62,46 @@ public String getType() { return type; } + /** + * Builder class for constructing OpenIdConnectSecurityScheme instances. + * Provides a fluent API for configuring OpenID Connect security schemes. + */ public static class Builder { + /** The OpenID Connect discovery URL */ private String openIdConnectUrl; + + /** Description of the authentication mechanism */ private String description; + /** + * Sets the OpenID Connect discovery URL. + * This URL should point to the well-known configuration endpoint + * of the OpenID Connect provider (typically ending with /.well-known/openid_configuration). + * + * @param openIdConnectUrl the discovery URL for the OIDC provider + * @return this builder instance for method chaining + */ public Builder openIdConnectUrl(String openIdConnectUrl) { this.openIdConnectUrl = openIdConnectUrl; return this; } + /** + * Sets the human-readable description of the OpenID Connect authentication. + * + * @param description a description explaining how the authentication works + * @return this builder instance for method chaining + */ public Builder description(String description) { this.description = description; return this; } + /** + * Builds and returns a new OpenIdConnectSecurityScheme instance. + * + * @return a new OpenIdConnectSecurityScheme with the configured settings + */ public OpenIdConnectSecurityScheme build() { return new OpenIdConnectSecurityScheme(openIdConnectUrl, description); } diff --git a/spec/src/main/java/io/a2a/spec/Part.java b/spec/src/main/java/io/a2a/spec/Part.java index cf7f04a74..208b47e36 100644 --- a/spec/src/main/java/io/a2a/spec/Part.java +++ b/spec/src/main/java/io/a2a/spec/Part.java @@ -7,8 +7,11 @@ import com.fasterxml.jackson.annotation.JsonValue; /** - * A fundamental unit with a Message or Artifact. - * @paramSecurity Warning: The password flow is considered less secure than + * other OAuth 2.0 flows because it requires the client application to handle the user's + * credentials directly. It should only be used when:
+ *This flow is not recommended for new implementations and has been removed + * from OAuth 2.1. Consider using the Authorization Code flow with PKCE instead.
+ * + *Required components:
+ *Push notifications in the A2A protocol allow agents to proactively notify clients + * about task updates, completion status, or other important events without requiring + * the client to continuously poll for updates.
+ * + *The authentication information typically includes:
+ *This implementation supports various push notification services and protocols, + * ensuring flexible integration with different client platforms and notification systems.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record PushNotificationAuthenticationInfo(ListPush notifications provide a mechanism for agents to proactively notify client + * applications about important events, task updates, or status changes without + * requiring the client to continuously poll for updates. This improves efficiency + * and user experience by enabling real-time communication.
+ * + *The configuration includes:
+ *This implementation supports various push notification providers and protocols, + * allowing flexible integration with different client platforms and notification systems.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -15,10 +32,18 @@ public record PushNotificationConfig(String url, String token, PushNotificationA Assert.checkNotNullParam("url", url); } + /** + * Builder class for constructing PushNotificationConfig instances. + * Provides a fluent API for configuring push notification settings. + */ public static class Builder { + /** The URL endpoint for push notification delivery */ private String url; + /** The authentication token for push notification services */ private String token; + /** The authentication information for push notifications */ private PushNotificationAuthenticationInfo authentication; + /** Unique identifier for this push notification configuration */ private String id; public Builder() { @@ -30,27 +55,52 @@ public Builder(PushNotificationConfig notificationConfig) { this.authentication = notificationConfig.authentication; this.id = notificationConfig.id; } - + public Builder url(String url) { this.url = url; return this; } + /** + * Sets the authentication token for push notification services. + * + * @param token the authentication token + * @return this builder instance for method chaining + */ public Builder token(String token) { this.token = token; return this; } + /** + * Sets the authentication information for push notifications. + * This information is used to authenticate with push notification services + * when delivering notifications to client applications. + * + * @param authenticationInfo the authentication configuration for push notifications + * @return this builder instance for method chaining + */ public Builder authenticationInfo(PushNotificationAuthenticationInfo authenticationInfo) { this.authentication = authenticationInfo; return this; } + /** + * Sets the unique identifier for this push notification configuration. + * + * @param id the unique identifier + * @return this builder instance for method chaining + */ public Builder id(String id) { this.id = id; return this; } + /** + * Builds and returns a new PushNotificationConfig instance. + * + * @return a new PushNotificationConfig with the configured settings + */ public PushNotificationConfig build() { return new PushNotificationConfig(url, token, authentication, id); } diff --git a/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java b/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java index d639b7bab..a2cd7c84f 100644 --- a/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java +++ b/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java @@ -7,10 +7,27 @@ import com.fasterxml.jackson.annotation.JsonInclude; import com.fasterxml.jackson.annotation.JsonProperty; +/** + * Represents a JSON-RPC error indicating that push notifications are not supported. + * This error is returned when a client attempts to configure or use push notification + * functionality on an agent that does not support this feature. + * + *This error follows the JSON-RPC 2.0 error specification and uses a specific + * error code (-32003) to identify push notification support issues. It extends + * the base JSONRPCError class to provide structured error information.
+ * + *Common scenarios where this error occurs:
+ *+ * This interface defines the contract for various authentication and authorization + * mechanisms that can be used to secure A2A agent communications. The interface + * uses Jackson annotations to support polymorphic JSON serialization and + * deserialization based on the "type" property. + *
+ *+ * Supported security scheme types: + *
+ *The SendMessageRequest follows the JSON-RPC 2.0 specification and uses the + * "message/send" method. It encapsulates message parameters and configuration + * options for delivery and processing.
+ * + *This is a non-streaming request, meaning it expects a single response + * rather than a stream of responses. For streaming message scenarios, + * use SendStreamingMessageRequest instead.
+ * + *Example usage:
+ *
+ * MessageSendParams params = new MessageSendParams.Builder()
+ * .message("Hello, agent!")
+ * .build();
+ * SendMessageRequest request = new SendMessageRequest("request-123", params);
+ *
*/
@JsonInclude(JsonInclude.Include.NON_ABSENT)
@JsonIgnoreProperties(ignoreUnknown = true)
public final class SendMessageRequest extends NonStreamingJSONRPCRequestThe response follows the JSON-RPC 2.0 specification and contains either + * a successful result (EventKind) or an error. The result indicates the type + * of event that was generated as a result of sending the message.
+ * + *Possible outcomes:
+ *The EventKind result provides information about how the agent handled + * the message, such as whether it was accepted, queued, or processed immediately.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class SendMessageResponse extends JSONRPCResponseThe SendStreamingMessageRequest follows the JSON-RPC 2.0 specification and uses the + * "message/stream" method. It encapsulates message parameters and configuration options + * for streaming delivery and processing.
+ * + *Unlike SendMessageRequest which expects a single response, this streaming variant + * allows the agent to send multiple responses over time, making it suitable for: + *
Example usage:
+ *
+ * MessageSendParams params = new MessageSendParams.Builder()
+ * .message("Generate a long report")
+ * .build();
+ * SendStreamingMessageRequest request = new SendStreamingMessageRequest("stream-123", params);
+ *
*/
@JsonInclude(JsonInclude.Include.NON_ABSENT)
@JsonIgnoreProperties(ignoreUnknown = true)
public final class SendStreamingMessageRequest extends StreamingJSONRPCRequestThe response follows the JSON-RPC 2.0 specification and contains either + * a successful result (StreamingEventKind) or an error. The result indicates the type + * of streaming event that was generated as a result of initiating the streaming message.
+ * + *Unlike SendMessageResponse which contains a single EventKind, this streaming variant + * contains a StreamingEventKind that represents the initial response to starting a + * streaming conversation. Subsequent streaming responses will be delivered separately.
+ * + *Possible outcomes:
+ *The StreamingEventKind result provides information about how the agent handled + * the streaming request, such as whether it was accepted and streaming has begun.
*/ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class SendStreamingMessageResponse extends JSONRPCResponsePush notification configurations enable real-time communication between the agent + * and external systems, allowing for immediate notification delivery when task events occur. + * This is particularly useful for long-running tasks where clients need to be notified + * of progress or completion without polling.
+ * + *The request follows the JSON-RPC 2.0 specification and uses the method + * "tasks/pushNotificationConfig/set" to identify this operation type.
+ * + * @see TaskPushNotificationConfig + * @see NonStreamingJSONRPCRequest */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class SetTaskPushNotificationConfigRequest extends NonStreamingJSONRPCRequestThe response can contain either:
+ *This follows the JSON-RPC 2.0 specification for response messages, ensuring + * compatibility with standard JSON-RPC clients and tooling.
+ * + * @see SetTaskPushNotificationConfigRequest + * @see TaskPushNotificationConfig + * @see JSONRPCResponse */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class SetTaskPushNotificationConfigResponse extends JSONRPCResponseThis class extends the base JSONRPCRequest and provides specialized handling + * for streaming operations. Streaming requests typically involve:
+ *The class is sealed and only permits specific implementations: + * TaskResubscriptionRequest and SendStreamingMessageRequest, ensuring type safety + * and controlled extensibility.
+ * + *Deserialization is handled by the StreamingJSONRPCRequestDeserializer to + * properly route incoming JSON to the correct concrete implementation.
+ * + * @paramThe deserializer supports the following streaming request types:
+ *The deserialization process validates the JSON-RPC structure, extracts the method name, + * and routes to the appropriate concrete class constructor. If an unsupported method is + * encountered, a MethodNotFoundJsonMappingException is thrown.
+ * + * @paramJSON-RPC 2.0 allows request identifiers to be strings, numbers, or null. + * This class specifically handles the string variant, which is commonly used + * for human-readable or UUID-based request tracking.
+ * + *String IDs are particularly useful for:
+ *+ * This record encapsulates a task ID along with optional metadata. + * It is commonly used in API requests and responses that need to + * reference a specific task, such as task queries, updates, or + * status requests. + *
+ * + * @param id the unique identifier of the task + * @param metadata optional metadata associated with the task identifier */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record TaskIdParams(String id, Map+ * This constructor ensures that the task ID is not null, as it is + * required to uniquely identify the task. + *
+ * + * @throws IllegalArgumentException if id is null + */ public TaskIdParams { Assert.checkNotNullParam("id", id); } + /** + * Convenience constructor for creating TaskIdParams with only an ID. + * + * @param id the unique identifier of the task + */ public TaskIdParams(String id) { this(id, null); } diff --git a/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java b/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java index aa40a81d3..ceedd1d38 100644 --- a/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java +++ b/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java @@ -7,16 +7,49 @@ import com.fasterxml.jackson.annotation.JsonInclude; import com.fasterxml.jackson.annotation.JsonProperty; +/** + * Represents a JSON-RPC 2.0 error indicating that a task cannot be canceled. + * This error is returned when a client attempts to cancel a task that is not + * in a cancelable state, such as tasks that have already completed, failed, + * or are in a critical phase where cancellation is not permitted. + * + *Common scenarios where this error occurs:
+ *The error follows JSON-RPC 2.0 error object specification with a default + * error code of -32002 and a descriptive message. Additional context can be + * provided through the data field.
+ * + * @see JSONRPCError + */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public class TaskNotCancelableError extends JSONRPCError { + /** Default error code for task not cancelable errors */ public final static Integer DEFAULT_CODE = -32002; + /** + * Creates a TaskNotCancelableError with default values. + * Uses the default error code and message. + */ public TaskNotCancelableError() { this(null, null, null); } + /** + * Creates a TaskNotCancelableError with custom values. + * Any null parameters will be replaced with default values. + * + * @param code the error code (defaults to -32002 if null) + * @param message the error message (defaults to "Task cannot be canceled" if null) + * @param data additional error data (can be null) + */ @JsonCreator public TaskNotCancelableError( @JsonProperty("code") Integer code, diff --git a/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java b/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java index 26ee264e3..743b8e201 100644 --- a/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java +++ b/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java @@ -7,18 +7,49 @@ import static io.a2a.util.Utils.defaultIfNull; +/** + * Represents a JSON-RPC 2.0 error indicating that a requested task was not found. + * This error is returned when a client attempts to access, modify, or query a task + * that does not exist in the agent's task registry or has been removed. + * + *Common scenarios where this error occurs:
+ *The error follows JSON-RPC 2.0 error object specification with a default + * error code of -32001 and a descriptive message. Additional context such as + * the invalid task ID can be provided through the data field.
+ * + * @see JSONRPCError + */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public class TaskNotFoundError extends JSONRPCError { + /** Default error code for task not found errors */ public final static Integer DEFAULT_CODE = -32001; + /** + * Creates a TaskNotFoundError with default values. + * Uses the default error code and message. + */ public TaskNotFoundError() { this(null, null, null); } + /** + * Creates a TaskNotFoundError with custom values. + * Any null parameters will be replaced with default values. + * + * @param code the error code (defaults to -32001 if null) + * @param message the error message (defaults to "Task not found" if null) + * @param data additional error data, such as the invalid task ID (can be null) + */ @JsonCreator - public TaskNotFoundError( @JsonProperty("code") Integer code, @JsonProperty("message") String message, diff --git a/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java b/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java index 0e4163212..5b358ec1f 100644 --- a/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java +++ b/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java @@ -5,12 +5,37 @@ import io.a2a.util.Assert; /** - * Task push notification configuration. + * Represents the configuration for push notifications associated with a specific task. + * This record binds a task identifier to its corresponding push notification settings, + * enabling the agent to send real-time notifications about task status changes, + * progress updates, or completion events. + * + *Task push notification configurations are essential for:
+ *The configuration ensures that clients can receive timely updates about + * task execution without the need for continuous polling, improving efficiency + * and user experience.
+ * + * @param taskId the unique identifier of the task to monitor + * @param pushNotificationConfig the push notification configuration settings + * @see PushNotificationConfig */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record TaskPushNotificationConfig(String taskId, PushNotificationConfig pushNotificationConfig) { + /** + * Compact constructor that validates the required parameters. + * Ensures that both taskId and pushNotificationConfig are not null. + * + * @throws IllegalArgumentException if taskId or pushNotificationConfig is null + */ public TaskPushNotificationConfig { Assert.checkNotNullParam("taskId", taskId); Assert.checkNotNullParam("pushNotificationConfig", pushNotificationConfig); diff --git a/spec/src/main/java/io/a2a/spec/TaskQueryParams.java b/spec/src/main/java/io/a2a/spec/TaskQueryParams.java index 2587e5fb5..895e097f0 100644 --- a/spec/src/main/java/io/a2a/spec/TaskQueryParams.java +++ b/spec/src/main/java/io/a2a/spec/TaskQueryParams.java @@ -7,16 +7,30 @@ import io.a2a.util.Assert; /** - * Task query parameters. + * Represents parameters for querying task information in the A2A protocol. + *+ * This record encapsulates the parameters needed to query a specific task, + * including options to control the amount of historical data returned and + * additional metadata for the query. + *
* - * @param id the ID for the task to be queried - * @param historyLength the maximum number of items of history for the task to include in the response - * @param metadata additional properties + * @param id the unique identifier of the task to be queried + * @param historyLength the maximum number of historical items to include in the response (null for default) + * @param metadata additional properties and metadata for the query */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record TaskQueryParams(String id, Integer historyLength, Map+ * This constructor ensures that the task ID is not null and that + * the history length, if specified, is not negative. + *
+ * + * @throws IllegalArgumentException if id is null or historyLength is negative + */ public TaskQueryParams { Assert.checkNotNullParam("id", id); if (historyLength != null && historyLength < 0) { @@ -24,10 +38,21 @@ public record TaskQueryParams(String id, Integer historyLength, MapAs a streaming request, this operation establishes a persistent connection + * that delivers continuous updates until the task completes or the subscription + * is explicitly canceled. The request follows the JSON-RPC 2.0 specification + * and uses the method "tasks/resubscribe".
+ * + * @see StreamingJSONRPCRequest + * @see TaskIdParams */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class TaskResubscriptionRequest extends StreamingJSONRPCRequest+ * This constructor ensures that the task state is not null and automatically + * sets the timestamp to the current time if it is not provided. + *
+ * + * @throws IllegalArgumentException if state is null + */ public TaskStatus { Assert.checkNotNullParam("state", state); timestamp = timestamp == null ? LocalDateTime.now() : timestamp; } + /** + * Convenience constructor for creating a TaskStatus with only a state. + * The message will be null and timestamp will be set to the current time. + * + * @param state the current state of the task + */ public TaskStatus(TaskState state) { this(state, null, null); } diff --git a/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java b/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java index 7a44480da..d61e656f5 100644 --- a/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java +++ b/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java @@ -9,26 +9,79 @@ import io.a2a.util.Assert; /** - * A task status update event. + * Represents a task status update event in the A2A protocol. + * + * This event is emitted when a task's status changes during execution, + * providing real-time updates about task progress, completion, or failure. + * It implements both {@link EventKind} and {@link StreamingEventKind} to support + * different event processing patterns in the A2A framework. + * + * The event contains information about which task was updated, its new status, + * the context it belongs to, whether this is a final status change, and any + * additional metadata associated with the status update. */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public final class TaskStatusUpdateEvent implements EventKind, StreamingEventKind { public static final String STATUS_UPDATE = "status-update"; + /** + * The unique identifier of the task whose status was updated. + */ private final String taskId; + + /** + * The new status of the task after the update. + */ private final TaskStatus status; + + /** + * The identifier of the context/conversation this task belongs to. + */ private final String contextId; + + /** + * Indicates whether this status update represents a final state. + * If true, no further status updates are expected for this task. + */ private final boolean isFinal; + + /** + * Additional metadata associated with this status update. + * Can contain implementation-specific information about the status change. + */ private final MapCommon scenarios where this error occurs:
+ *The error follows JSON-RPC 2.0 error object specification with a default + * error code of -32004 and a descriptive message. Additional context about + * the unsupported operation can be provided through the data field.
+ * + * @see JSONRPCError + */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public class UnsupportedOperationError extends JSONRPCError { + /** Default error code for unsupported operation errors */ public final static Integer DEFAULT_CODE = -32004; + /** + * Creates an UnsupportedOperationError with custom values. + * Any null parameters will be replaced with default values. + * + * @param code the error code (defaults to -32004 if null) + * @param message the error message (defaults to "This operation is not supported" if null) + * @param data additional error data, such as the unsupported method name (can be null) + */ @JsonCreator public UnsupportedOperationError( @JsonProperty("code") Integer code, @@ -24,6 +52,10 @@ public UnsupportedOperationError( data); } + /** + * Creates an UnsupportedOperationError with default values. + * Uses the default error code and message. + */ public UnsupportedOperationError() { this(null, null, null); }