Package org.a2aproject.sdk.spec

Class AgentCard.Builder

java.lang.Object
org.a2aproject.sdk.spec.AgentCard.Builder
Enclosing class:
AgentCard
public static class AgentCard.Builder extends Object
Builder for constructing immutable AgentCard instances.

The Builder pattern is used to enforce immutability of AgentCard objects while providing a fluent API for setting required and optional fields. This approach ensures that once an AgentCard is created, its state cannot be modified, which is important for thread-safety and protocol correctness.

Example usage: 


 AgentCard card = AgentCard.builder()
     .name("Weather Agent")
     .description("Provides weather information")
     .supportedInterfaces(List.of(
         new AgentInterface("JSONRPC", "http://localhost:9999")))
     .version("1.0.0")
     .capabilities(new AgentCapabilities.Builder()
         .streaming(true)
         .build())
     .defaultInputModes(List.of("text"))
     .defaultOutputModes(List.of("text"))
     .skills(List.of(
         new AgentSkill.Builder()
             .id("weather_query")
             .name("Weather Queries")
             .build()
     ))
     .build();

  • Method Details

    • name

      public AgentCard.Builder name(String name)
      Sets the human-readable name of the agent.
      Parameters:
      name - the agent name (required)
      Returns:
      this builder for method chaining

    • description

      public AgentCard.Builder description(String description)
      Sets a brief description of the agent's purpose and functionality.
      Parameters:
      description - the agent description (required)
      Returns:
      this builder for method chaining

    • provider

      public AgentCard.Builder provider(AgentProvider provider)
      Sets information about the organization or entity providing the agent.
      Parameters:
      provider - the agent provider (optional)
      Returns:
      this builder for method chaining

    • version

      public AgentCard.Builder version(String version)
      Sets the version of the agent implementation.
      Parameters:
      version - the agent version (required)
      Returns:
      this builder for method chaining

    • documentationUrl

      public AgentCard.Builder documentationUrl(String documentationUrl)
      Sets the URL to human-readable documentation for the agent.
      Parameters:
      documentationUrl - the documentation URL (optional)
      Returns:
      this builder for method chaining

    • capabilities

      public AgentCard.Builder capabilities(AgentCapabilities capabilities)
      Sets the capabilities supported by this agent.

      Capabilities define optional features such as streaming responses, push notifications, and state transition history.

      Parameters:
      capabilities - the agent capabilities (required)
      Returns:
      this builder for method chaining
      See Also:

    • defaultInputModes

      public AgentCard.Builder defaultInputModes(List<String> defaultInputModes)
      Sets the list of supported input modes.

      Input modes define the formats the agent can accept, such as "text", "audio", or "image".

      Parameters:
      defaultInputModes - the list of input modes (required, must not be empty)
      Returns:
      this builder for method chaining

    • defaultOutputModes

      public AgentCard.Builder defaultOutputModes(List<String> defaultOutputModes)
      Sets the list of supported output modes.

      Output modes define the formats the agent can produce, such as "text", "audio", or "image".

      Parameters:
      defaultOutputModes - the list of output modes (required, must not be empty)
      Returns:
      this builder for method chaining

    • skills

      public AgentCard.Builder skills(List<AgentSkill> skills)
      Sets the list of skills that this agent can perform.

      Skills represent distinct capabilities or operations the agent can execute, such as "weather_query" or "language_translation".

      Parameters:
      skills - the list of agent skills (required, must not be empty)
      Returns:
      this builder for method chaining
      See Also:

    • securitySchemes

      public AgentCard.Builder securitySchemes(Map<String,SecurityScheme> securitySchemes)
      Sets the map of security scheme definitions.

      Security schemes define authentication and authorization methods supported by the agent, such as OAuth2, API keys, or HTTP authentication.

      Parameters:
      securitySchemes - map of scheme names to definitions (optional)
      Returns:
      this builder for method chaining
      See Also:

    • securityRequirements

      public AgentCard.Builder securityRequirements(List<SecurityRequirement> securityRequirements)
      Sets the list of security requirements for accessing the agent.
      Parameters:
      securityRequirements - the list of security requirements (optional)
      Returns:
      this builder for method chaining
      See Also:

    • iconUrl

      public AgentCard.Builder iconUrl(String iconUrl)
      Sets the URL to an icon representing the agent.
      Parameters:
      iconUrl - the icon URL (optional)
      Returns:
      this builder for method chaining

    • supportedInterfaces

      public AgentCard.Builder supportedInterfaces(List<AgentInterface> supportedInterfaces)
      Sets the ordered list of supported protocol interfaces (first entry is preferred).

      Each interface defines a combination of protocol binding (e.g., "JSONRPC", "GRPC", "REST") and URL endpoint for accessing the agent. This is the primary field for declaring how clients can communicate with the agent as of protocol version 1.0.0.

      Example: 

      
 .supportedInterfaces(List.of(
     new AgentInterface("JSONRPC", "http://localhost:9999"),
     new AgentInterface("GRPC", "grpc://localhost:9090")
 ))
      Parameters:
      supportedInterfaces - the ordered list of supported interfaces (required)
      Returns:
      this builder for method chaining
      See Also:

    • signatures

      public AgentCard.Builder signatures(List<AgentCardSignature> signatures)
      Sets the digital signatures verifying the authenticity of the agent card.

      Signatures provide cryptographic proof that the agent card was issued by a trusted authority and has not been tampered with.

      Parameters:
      signatures - the list of signatures (optional)
      Returns:
      this builder for method chaining
      See Also:

    • preferredTransport

      public AgentCard.Builder preferredTransport(String preferredTransport)

    • url

      public AgentCard.Builder url(String url)

    • additionalInterfaces

      public AgentCard.Builder additionalInterfaces(List<Legacy_0_3_AgentInterface> additionalInterfaces)

    • build

      public AgentCard build()
      Builds an immutable AgentCard from the current builder state.

      This method applies default values for optional fields.

      Returns:
      a new AgentCard instance
      Throws:
      IllegalArgumentException - if any required field is null