Package io.a2a.util

Class Utils

java.lang.Object
io.a2a.util.Utils
public class Utils extends Object
Utility class providing common helper methods for A2A Protocol operations.

This class contains static utility methods for JSON serialization/deserialization, null-safe operations, artifact management, and other common tasks used throughout the A2A Java SDK.

Key capabilities:

See Also:

  • Method Details

    • defaultIfNull

      public static <T> T defaultIfNull(@Nullable T value, T defaultValue)
      Returns the provided value if non-null, otherwise returns the default value.

      This is a null-safe utility for providing default values when a parameter might be null.

      Type Parameters:
      T - the value type
      Parameters:
      value - the value to check
      defaultValue - the default value to return if value is null
      Returns:
      value if non-null, otherwise defaultValue

    • rethrow

      public static <T extends Throwable> void rethrow(Throwable t) throws T
      Rethrows a checked exception as an unchecked exception.

      This method uses type erasure to bypass checked exception handling, allowing checked exceptions to be thrown without explicit declaration. Use with caution as it bypasses Java's compile-time exception checking.

      Type Parameters:
      T - the throwable type
      Parameters:
      t - the throwable to rethrow
      Throws:
      T - the rethrown exception

    • appendArtifactToTask

      public static Task appendArtifactToTask(Task task, TaskArtifactUpdateEvent event, String taskId)
      Appends or updates an artifact in a task based on a TaskArtifactUpdateEvent.

      This method handles streaming artifact updates, supporting both:

      • Adding new artifacts to the task
      • Replacing existing artifacts (when append=false)
      • Appending parts to existing artifacts (when append=true)

      The append flag in the event determines the behavior:

      • false or null: Replace/add the entire artifact
      • true: Append the new artifact's parts to an existing artifact with matching artifactId
      Parameters:
      task - the current task to update
      event - the artifact update event containing the new/updated artifact
      taskId - the task ID (for logging purposes)
      Returns:
      a new Task instance with the updated artifacts list
      See Also:

    • getFavoriteInterface

      public static AgentInterface getFavoriteInterface(AgentCard agentCard) throws A2AClientException
      Get the first defined URL in the supported interaces of the agent card.
      Parameters:
      agentCard - the agentcard where the interfaces are defined.
      Returns:
      the first defined URL in the supported interaces of the agent card.
      Throws:
      A2AClientException - if no server interface is available in the AgentCard

    • buildBaseUrl

      public static String buildBaseUrl(AgentInterface agentInterface, @Nullable String tenant)
      Builds a base URL for A2A operations by combining the agent's URL with a tenant path.

      This method:

      • Uses the tenant from the AgentInterface as the default
      • Allows overriding with a custom tenant path if provided
      • Normalizes trailing slashes on the base URL
      • Validates and normalizes the tenant path

      Example: 

      
 AgentInterface iface = new AgentInterface("jsonrpc", "http://example.com", "default-tenant");
 String url = Utils.buildBaseUrl(iface, null);
 // Returns: "http://example.com/default-tenant"

 String url2 = Utils.buildBaseUrl(iface, "custom-tenant");
 // Returns: "http://example.com/custom-tenant"
      Parameters:
      agentInterface - the agent interface containing the base URL and default tenant, must not be null
      tenant - the tenant override from the request, may be null to use the interface default
      Returns:
      the complete base URL with tenant path appended
      Throws:
      IllegalArgumentException - if agentInterface is null or tenant validation fails