Package org.a2aproject.sdk

Class A2A

java.lang.Object
org.a2aproject.sdk.A2A
public class A2A extends Object
Utility class providing convenience methods for working with the A2A Protocol.

This class offers static helper methods for common A2A operations:

  • Message creation: Simplified construction of user and agent messages
  • Agent card retrieval: Fetching agent metadata from URLs

These utilities simplify client code by providing concise alternatives to the builder APIs for routine operations.

Example usage: 


 // Get agent card
 AgentCard card = A2A.getAgentCard("http://localhost:9999");

 // Create and send a user message
 Message userMsg = A2A.toUserMessage("What's the weather today?");
 client.sendMessage(userMsg);

 // Create a message with context and task IDs
 Message contextMsg = A2A.createUserTextMessage(
     "Continue the conversation",
     "session-123",  // contextId
     "task-456"      // taskId
 );
 client.sendMessage(contextMsg);
See Also:

  • Constructor Details

    • A2A

      public A2A()

  • Method Details

    • toUserMessage

      public static Message toUserMessage(String text)
      Create a simple user message from text.

      This is the most common way to create messages when sending requests to agents. The message will have:

      • role: USER
      • parts: Single TextPart with the provided text
      • Auto-generated message ID

      Example: 

      
 Message msg = A2A.toUserMessage("Tell me a joke");
 client.sendMessage(msg);
      Parameters:
      text - the message text (required)
      Returns:
      a user message with the specified text
      See Also:

    • toUserMessage

      public static Message toUserMessage(String text, String messageId)
      Create a user message from text with a specific message ID.

      Use this when you need to control the message ID for tracking or correlation purposes.

      Example: 

      
 String messageId = UUID.randomUUID().toString();
 Message msg = A2A.toUserMessage("Process this request", messageId);
 // Store messageId for later correlation
 client.sendMessage(msg);
      Parameters:
      text - the message text (required)
      messageId - the message ID to use
      Returns:
      a user message with the specified text and ID
      See Also:

    • toAgentMessage

      public static Message toAgentMessage(String text)
      Create a simple agent message from text.

      This is typically used in testing or when constructing agent responses programmatically. Most client applications receive agent messages via MessageEvent rather than creating them manually.

      Example: 

      
 // Testing scenario
 Message agentResponse = A2A.toAgentMessage("Here's the answer: 42");
      Parameters:
      text - the message text (required)
      Returns:
      an agent message with the specified text
      See Also:

    • toAgentMessage

      public static Message toAgentMessage(String text, String messageId)
      Create an agent message from text with a specific message ID.

      Example: 

      
 Message agentResponse = A2A.toAgentMessage("Processing complete", "msg-789");
      Parameters:
      text - the message text (required)
      messageId - the message ID to use
      Returns:
      an agent message with the specified text and ID

    • createUserTextMessage

      public static Message createUserTextMessage(String text, String contextId, String taskId)
      Create a user message with text content and optional context and task IDs.

      This method is useful when continuing a conversation or working with a specific task:

      • contextId: Links message to a conversation session
      • taskId: Associates message with an existing task

      Example - continuing a conversation: 

      
 // First message creates context
 Message msg1 = A2A.toUserMessage("What's your name?");
 client.sendMessage(msg1);
 String contextId = ...; // Get from response

 // Follow-up message uses contextId
 Message msg2 = A2A.createUserTextMessage(
     "What else can you do?",
     contextId,
     null  // no specific task
 );
 client.sendMessage(msg2);

      Example - adding to an existing task: 

      
 Message msg = A2A.createUserTextMessage(
     "Add this information too",
     "session-123",
     "task-456"  // Continue working on this task
 );
 client.sendMessage(msg);
      Parameters:
      text - the message text (required)
      contextId - the context ID to use (optional)
      taskId - the task ID to use (optional)
      Returns:
      a user message with the specified text, context, and task IDs
      See Also:

    • createAgentTextMessage

      public static Message createAgentTextMessage(String text, String contextId, String taskId)
      Create an agent message with text content and optional context and task IDs.

      This is typically used in testing or when constructing agent responses programmatically.

      Parameters:
      text - the message text (required)
      contextId - the context ID to use (optional)
      taskId - the task ID to use (optional)
      Returns:
      an agent message with the specified text, context, and task IDs
      See Also:

    • createAgentPartsMessage

      public static Message createAgentPartsMessage(List<Part<?>> parts, String contextId, String taskId)
      Create an agent message with custom parts and optional context and task IDs.

      This method allows creating messages with multiple parts (text, images, files, etc.) instead of just simple text. Useful for complex agent responses or testing.

      Example - message with text and image: 

      
 List<Part<?>> parts = List.of(
     new TextPart("Here's a chart of the data:"),
     new ImagePart("https://example.com/chart.png", "Chart showing sales data")
 );
 Message msg = A2A.createAgentPartsMessage(parts, "session-123", "task-456");
      Parameters:
      parts - the message parts (required, must not be empty)
      contextId - the context ID to use (optional)
      taskId - the task ID to use (optional)
      Returns:
      an agent message with the specified parts, context, and task IDs
      Throws:
      IllegalArgumentException - if parts is null or empty
      See Also:

    • getAgentCard

      public static AgentCard getAgentCard(String agentUrl) throws A2AClientError, A2AClientJSONError
      Retrieve the agent card for an A2A agent.

      This is the standard way to discover an agent's capabilities before creating a client. The agent card is fetched from the well-known endpoint: <agentUrl>/.well-known/agent-card.json

      Example: 

      
 // Get agent card
 AgentCard card = A2A.getAgentCard("http://localhost:9999");

 // Check capabilities
 System.out.println("Agent: " + card.name());
 System.out.println("Supports streaming: " + card.capabilities().streaming());

 // Create client
 Client client = Client.builder(card)
     .withTransport(...)
     .build();
      Parameters:
      agentUrl - the base URL for the agent whose agent card we want to retrieve
      Returns:
      the agent card
      Throws:
      A2AClientError - if an HTTP error occurs fetching the card
      A2AClientJSONError - if the response body cannot be decoded as JSON or validated against the AgentCard schema
      See Also:

    • getAgentCard

      public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl) throws A2AClientError, A2AClientJSONError
      Retrieve the agent card using a custom HTTP client.

      Use this variant when you need to customize HTTP behavior (timeouts, SSL configuration, connection pooling, etc.).

      Example: 

      
 A2AHttpClient customClient = new CustomHttpClient()
     .withTimeout(Duration.ofSeconds(10))
     .withSSLContext(mySSLContext);

 AgentCard card = A2A.getAgentCard(customClient, "https://secure-agent.com");
      Parameters:
      httpClient - the http client to use
      agentUrl - the base URL for the agent whose agent card we want to retrieve
      Returns:
      the agent card
      Throws:
      A2AClientError - if an HTTP error occurs fetching the card
      A2AClientJSONError - if the response body cannot be decoded as JSON or validated against the AgentCard schema
      See Also:

    • getAgentCard

      public static AgentCard getAgentCard(String agentUrl, String relativeCardPath, Map<String,String> authHeaders) throws A2AClientError, A2AClientJSONError
      Retrieve the agent card with custom path and authentication.

      Use this variant when:

      • The agent card is at a non-standard location
      • Authentication is required to access the agent card

      Example with authentication: 

      
 Map<String, String> authHeaders = Map.of(
     "Authorization", "Bearer my-api-token",
     "X-API-Key", "my-api-key"
 );

 AgentCard card = A2A.getAgentCard(
     "https://secure-agent.com",
     null,  // Use default path
     authHeaders
 );

      Example with custom path: 

      
 AgentCard card = A2A.getAgentCard(
     "https://agent.com",
     "api/v2/agent-info",  // Custom path
     null  // No auth needed
 );
 // Fetches from: https://agent.com/api/v2/agent-info
      Parameters:
      agentUrl - the base URL for the agent whose agent card we want to retrieve
      relativeCardPath - optional path to the agent card endpoint relative to the base agent URL, defaults to ".well-known/agent-card.json"
      authHeaders - the HTTP authentication headers to use
      Returns:
      the agent card
      Throws:
      A2AClientError - if an HTTP error occurs fetching the card
      A2AClientJSONError - if the response body cannot be decoded as JSON or validated against the AgentCard schema

    • getAgentCard

      public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl, String relativeCardPath, Map<String,String> authHeaders) throws A2AClientError, A2AClientJSONError
      Retrieve the agent card with full customization options.

      This is the most flexible variant, allowing customization of:

      • HTTP client implementation
      • Agent card endpoint path
      • Authentication headers

      Example: 

      
 A2AHttpClient customClient = new CustomHttpClient();
 Map<String, String> authHeaders = Map.of("Authorization", "Bearer token");

 AgentCard card = A2A.getAgentCard(
     customClient,
     "https://agent.com",
     "custom/agent-card",
     authHeaders
 );
      Parameters:
      httpClient - the http client to use
      agentUrl - the base URL for the agent whose agent card we want to retrieve
      relativeCardPath - optional path to the agent card endpoint relative to the base agent URL, defaults to ".well-known/agent-card.json"
      authHeaders - the HTTP authentication headers to use
      Returns:
      the agent card
      Throws:
      A2AClientError - if an HTTP error occurs fetching the card
      A2AClientJSONError - if the response body cannot be decoded as JSON or validated against the AgentCard schema