Class A2ACardResolver

java.lang.Object

org.a2aproject.sdk.client.http.A2ACardResolver

public class A2ACardResolver
extends Object

Utility for fetching agent cards from A2A agents.

Retrieves agent cards from the standard /.well-known/agent-card.json endpoint with support for tenant-specific paths and authentication headers.

Features

• Standard agent card endpoint discovery (/.well-known/agent-card.json)
• Tenant-specific path support (/.well-known/{tenant}/agent-card.json)
• Custom card path support for non-standard agent card locations
• Custom authentication header injection
• Pluggable HTTP client via A2AHttpClientFactory

Usage Examples

// Basic usage - fetch the agent card from a base URL
A2ACardResolver resolver = A2ACardResolver.builder()
    .baseUrl("http://localhost:9999")
    .build();
AgentCard card = resolver.getAgentCard();

// With tenant — fetches from /.well-known/my-tenant/agent-card.json
A2ACardResolver resolver = A2ACardResolver.builder()
    .baseUrl("http://localhost:9999")
    .tenant("my-tenant")
    .build();
AgentCard card = resolver.getAgentCard();

// With custom HTTP client and authentication
A2AHttpClient httpClient = A2AHttpClientFactory.create();
A2ACardResolver resolver = A2ACardResolver.builder()
    .httpClient(httpClient)
    .baseUrl("http://localhost:9999")
    .tenant("my-tenant")
    .authHeader("Authorization", "Bearer token")
    .build();
AgentCard card = resolver.getAgentCard();

// With a custom agent card path
A2ACardResolver resolver = A2ACardResolver.builder()
    .baseUrl("http://localhost:9999")
    .agentCardPath("/custom/agent.json")
    .build();
AgentCard card = resolver.getAgentCard();

// Using a complete URL (e.g., with path prefix like /spec03)
A2ACardResolver resolver = A2ACardResolver.builder()
    .baseUrl("https://example.com/spec03")
    .build();
AgentCard card = resolver.getAgentCard();

See Also:

• AgentCard
• A2AHttpClient

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	A2ACardResolver.Builder	Builder for creating A2ACardResolver instances with a fluent API.

Method Summary

Modifier and Type	Method	Description
static A2ACardResolver.Builder	builder()	Creates a new builder for constructing an A2ACardResolver.
AgentCard	getAgentCard()	Fetches the agent card for this resolver's configured agent.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

builder

public static A2ACardResolver.Builder builder()

Creates a new builder for constructing an A2ACardResolver.

Returns:

a new builder instance

getAgentCard

public AgentCard getAgentCard()
                       throws A2AClientError,
A2AClientJSONError

Fetches the agent card for this resolver's configured agent.

Fetches from the custom agentCardPath when one was supplied, otherwise fetches from the standard /.well-known/agent-card.json (or tenant-specific variant) endpoint. When no custom path was provided and the computed card URL differs from the originally supplied base URL, a 404 response from the primary URL triggers a single retry against the original base URL before propagating the error.

Returns:

the agent card

Throws:

A2AClientHTTPError - If the server returns a non-2xx response (carries status, body, and headers)

A2AClientError - If a network error occurs fetching the card

A2AClientJSONError - If the response body cannot be decoded as JSON or validated against the AgentCard schema