Package org.a2aproject.sdk.util

Class Utils

java.lang.Object
org.a2aproject.sdk.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:

  • Field Details

  • 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:

    • validateAbsoluteUrl

      public static void validateAbsoluteUrl(String url) throws URISyntaxException
      Validates that url is a syntactically valid absolute URI.
      Parameters:
      url - the URL to validate
      Throws:
      URISyntaxException - if the URL is syntactically invalid or not absolute

    • buildCardUrl

      public static String buildCardUrl(String baseUrl, String cardPath)
      Normalizes baseUrl and cardPath and concatenates them into a full card URL.

      Strips any trailing slash from baseUrl and ensures cardPath starts with a leading slash before concatenating, so both http://host/base/ and http://host/base produce the same result.

      Parameters:
      baseUrl - the agent base URL, must not be null
      cardPath - the card endpoint path, must not be null
      Returns:
      the normalized card URL

    • stripWellKnownSuffix

      public static String stripWellKnownSuffix(String baseUrl)
      Strips any trailing slash and the standard well-known suffix from baseUrl so that buildCardUrl(java.lang.String, java.lang.String) can append the desired path without doubling it.

      Only DEFAULT_AGENT_CARD_PATH is stripped; custom paths are never inferred from the URL structure.

      Parameters:
      baseUrl - the URL to strip
      Returns:
      the URL with any trailing slash and well-known suffix removed

    • buildBaseUrl

      public static String buildBaseUrl(String baseUrl, @Nullable String tenant)
      Builds a base URL by combining a raw base URL string with an optional tenant path.

      Normalizes trailing slashes on the base URL and validates/normalizes the tenant path.

      Parameters:
      baseUrl - the base URL string, must not be null
      tenant - the tenant path override, may be null for no tenant
      Returns:
      the complete base URL with tenant path appended
      Throws:
      IllegalArgumentException - if tenant validation fails

    • 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