feat!: Replace public Builder constructors with static factory methods

Author: kabir

spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java

@@ -148,12 +148,21 @@ public String getType() {
         return type;
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing immutable {@link APIKeySecurityScheme} instances.
      * <p>
      * Example usage:
      * <pre>{@code
-     * APIKeySecurityScheme scheme = new APIKeySecurityScheme.Builder()
+     * APIKeySecurityScheme scheme = APIKeySecurityScheme.builder()
      *     .location(Location.HEADER)
      *     .name("X-API-Key")
      *     .description("API key authentication")
@@ -165,6 +174,12 @@ public static class Builder {
         private String name;
         private String description;
 
+        /**
+         * Creates a new Builder with all fields unset.
+         */
+        private Builder() {
+        }
+
         /**
          * Sets the location where the API key should be sent.
          *

spec/src/main/java/io/a2a/spec/AgentCapabilities.java

@@ -34,6 +34,14 @@
 public record AgentCapabilities(boolean streaming, boolean pushNotifications, boolean stateTransitionHistory,
                                 List<AgentExtension> extensions) {
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
     /**
      * Builder for constructing immutable {@link AgentCapabilities} instances.
      * <p>
@@ -42,7 +50,7 @@ public record AgentCapabilities(boolean streaming, boolean pushNotifications, bo
      * <p>
      * Example usage:
      * <pre>{@code
-     * AgentCapabilities capabilities = new AgentCapabilities.Builder()
+     * AgentCapabilities capabilities = AgentCapabilities.builder()
      *     .streaming(true)
      *     .pushNotifications(false)
      *     .stateTransitionHistory(false)
@@ -59,7 +67,7 @@ public static class Builder {
         /**
          * Creates a new Builder with all capabilities set to false by default.
          */
-        public Builder() {
+        private Builder() {
         }
 
         /**

spec/src/main/java/io/a2a/spec/AgentCard.java

@@ -89,6 +89,29 @@ public List<AgentInterface> additionalInterfaces() {
         return supportedInterfaces;
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Create a new Builder initialized with values from an existing AgentCard.
+     * <p>
+     * This builder  creates defensive copies of mutable collections to ensure
+     * that modifications to the builder do not affect the original AgentCard.
+     *
+     * @param card the AgentCard to copy values from
+     * @return the builder
+     */
+    public static Builder builder(AgentCard card) {
+        return new Builder(card);
+    }
+
+
     /**
      * Builder for constructing immutable {@link AgentCard} instances.
      * <p>
@@ -99,7 +122,7 @@ public List<AgentInterface> additionalInterfaces() {
      * <p>
      * Example usage:
      * <pre>{@code
-     * AgentCard card = new AgentCard.Builder()
+     * AgentCard card = AgentCard.builder()
      *     .name("Weather Agent")
      *     .description("Provides weather information")
      *     .supportedInterfaces(List.of(
@@ -140,7 +163,7 @@ public static class Builder {
         /**
          * Creates a new Builder with all fields unset.
          */
-        public Builder() {
+        private Builder() {
 
         }
 
@@ -152,7 +175,7 @@ public Builder() {
          *
          * @param card the AgentCard to copy values from
          */
-        public Builder(AgentCard card) {
+        private Builder(AgentCard card) {
             this.name = card.name;
             this.description = card.description;
             this.provider = card.provider;

spec/src/main/java/io/a2a/spec/AgentCardSignature.java

@@ -44,12 +44,21 @@ public record AgentCardSignature(Map<String, Object> header, @SerializedName("pr
         Assert.checkNotNullParam("signature", signature);
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing immutable {@link AgentCardSignature} instances.
      * <p>
      * Example usage:
      * <pre>{@code
-     * AgentCardSignature sig = new AgentCardSignature.Builder()
+     * AgentCardSignature sig = AgentCardSignature.builder()
      *     .protectedHeader("eyJhbGciOiJFUzI1NiJ9")
      *     .signature("DtEhU3ljbEg8L38VWAfUAqOyKAM6...")
      *     .header(Map.of("kid", "2024-01"))
@@ -64,7 +73,7 @@ public static class Builder {
         /**
          * Creates a new Builder with all fields unset.
          */
-        public Builder() {
+        private Builder() {
         }
 
         /**

spec/src/main/java/io/a2a/spec/AgentExtension.java

@@ -34,12 +34,21 @@ public record AgentExtension (String description, Map<String, Object> params, bo
         Assert.checkNotNullParam("uri", uri);
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing immutable {@link AgentExtension} instances.
      * <p>
      * Example usage:
      * <pre>{@code
-     * AgentExtension ext = new AgentExtension.Builder()
+     * AgentExtension ext = AgentExtension.builder()
      *     .uri("https://example.com/extensions/custom-auth")
      *     .description("Custom authentication extension")
      *     .required(true)
@@ -56,7 +65,7 @@ public static class Builder {
         /**
          * Creates a new Builder with all fields unset.
          */
-        public Builder() {
+        private Builder() {
         }
 
         /**

spec/src/main/java/io/a2a/spec/AgentSkill.java

@@ -55,6 +55,15 @@ public record AgentSkill(String id, String name, String description, List<String
         Assert.checkNotNullParam("tags", tags);
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing immutable {@link AgentSkill} instances.
      * <p>
@@ -64,7 +73,7 @@ public record AgentSkill(String id, String name, String description, List<String
      * <p>
      * Example usage:
      * <pre>{@code
-     * AgentSkill skill = new AgentSkill.Builder()
+     * AgentSkill skill = AgentSkill.builder()
      *     .id("weather_query")
      *     .name("Weather Queries")
      *     .description("Get current weather conditions for any location")
@@ -92,7 +101,7 @@ public static class Builder {
         /**
          * Creates a new Builder with all fields unset.
          */
-        public Builder() {
+        private Builder() {
         }
 
         /**

spec/src/main/java/io/a2a/spec/Artifact.java

@@ -45,6 +45,28 @@ public record Artifact(String artifactId, String name, String description, List<
         }
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Create a new Builder initialized with values from an existing Artifact.
+     * <p>
+     * This builder creates defensive copies of mutable collections to ensure
+     * that modifications to the builder do not affect the original Artifact.
+     *
+     * @param artifact the Artifact to copy values from
+     * @return the builder
+     */
+    public static Builder builder(Artifact artifact) {
+        return new Builder(artifact);
+    }
+
     /**
      * Builder for constructing immutable {@link Artifact} instances.
      * <p>
@@ -53,7 +75,7 @@ public record Artifact(String artifactId, String name, String description, List<
      * <p>
      * Example usage:
      * <pre>{@code
-     * Artifact result = new Artifact.Builder()
+     * Artifact result = Artifact.builder()
      *     .artifactId("artifact-123")
      *     .name("Analysis Report")
      *     .description("Detailed analysis of user data")
@@ -72,15 +94,15 @@ public static class Builder {
         /**
          * Creates a new Builder with all fields unset.
          */
-        public Builder(){
+        private Builder(){
         }
 
         /**
          * Creates a new Builder initialized with values from an existing Artifact.
          *
          * @param existingArtifact the Artifact to copy values from
          */
-        public Builder(Artifact existingArtifact) {
+        private Builder(Artifact existingArtifact) {
             artifactId = existingArtifact.artifactId;
             name = existingArtifact.name;
             description = existingArtifact.description;

spec/src/main/java/io/a2a/spec/CancelTaskRequest.java

@@ -47,6 +47,15 @@ public CancelTaskRequest(Object id, TaskIdParams params) {
         this(null, id, params);
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing {@link CancelTaskRequest} instances.
      * <p>
@@ -58,6 +67,12 @@ public static class Builder {
         private Object id;
         private TaskIdParams params;
 
+        /**
+         * Creates a new Builder with all fields unset.
+         */
+        private Builder() {
+        }
+
         /**
          * Sets the JSON-RPC protocol version.
          *

spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigParams.java

@@ -40,6 +40,15 @@ public DeleteTaskPushNotificationConfigParams(String id, String pushNotification
         this(id, pushNotificationConfigId, null);
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing {@link DeleteTaskPushNotificationConfigParams} instances.
      * <p>
@@ -50,6 +59,12 @@ public static class Builder {
         String pushNotificationConfigId;
         Map<String, Object> metadata;
 
+        /**
+         * Creates a new Builder with all fields unset.
+         */
+        private Builder() {
+        }
+
         /**
          * Sets the task identifier.
          *

spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigRequest.java

@@ -43,6 +43,15 @@ public DeleteTaskPushNotificationConfigRequest(String id, DeleteTaskPushNotifica
         this(null, id, params);
     }
 
+    /**
+     * Create a new Builder
+     *
+     * @return the builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Builder for constructing {@link DeleteTaskPushNotificationConfigRequest} instances.
      * <p>
@@ -54,6 +63,12 @@ public static class Builder {
         private Object id;
         private DeleteTaskPushNotificationConfigParams params;
 
+        /**
+         * Creates a new Builder with all fields unset.
+         */
+        private Builder() {
+        }
+
         /**
          * Sets the JSON-RPC protocol version.
          *