Repository navigation
Expand file tree
/
Copy pathA2ACardResolver.java
More file actions
193 lines (176 loc) · 8.45 KB
/
Copy pathA2ACardResolver.java
File metadata and controls
193 lines (176 loc) · 8.45 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
package io.a2a.client.http;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.Map;
import io.a2a.grpc.utils.JSONRPCUtils;
import io.a2a.grpc.utils.ProtoUtils;
import io.a2a.jsonrpc.common.json.JsonProcessingException;
import io.a2a.spec.A2AClientError;
import io.a2a.spec.A2AClientJSONError;
import io.a2a.spec.AgentCard;
import io.a2a.spec.A2AError;
import org.jspecify.annotations.Nullable;
import static io.a2a.util.Assert.checkNotNullParam;
import io.a2a.spec.AgentInterface;
/**
* Utility for fetching agent cards from A2A agents.
*
* <p>Retrieves agent cards from the standard {@code /.well-known/agent-card.json} endpoint
* with support for tenant-specific paths and authentication headers.
*
* <h2>Features</h2>
* <ul>
* <li>Standard agent card endpoint discovery ({@code /.well-known/agent-card.json})</li>
* <li>Tenant-specific path support ({@code /tenant/.well-known/agent-card.json})</li>
* <li>Custom authentication header injection</li>
* <li>Pluggable HTTP client via {@link A2AHttpClientFactory}</li>
* <li>Support for both public and extended agent cards</li>
* </ul>
*
* <h2>Usage Examples</h2>
* <pre>{@code
* // Basic usage - fetch agent card
* A2ACardResolver resolver = new A2ACardResolver("http://localhost:9999");
* AgentCard card = resolver.getAgentCard();
*
* // With tenant path
* A2ACardResolver resolver = new A2ACardResolver("http://localhost:9999", "my-tenant");
* AgentCard card = resolver.getAgentCard();
*
* // With custom HTTP client
* A2AHttpClient httpClient = A2AHttpClientFactory.create();
* A2ACardResolver resolver = new A2ACardResolver(httpClient, "http://localhost:9999", "my-tenant");
* AgentCard card = resolver.getAgentCard();
*
* // With authentication headers
* A2AHttpClient httpClient = A2AHttpClientFactory.create();
* Map<String, String> authHeaders = Map.of("Authorization", "Bearer token");
* A2ACardResolver resolver = new A2ACardResolver(
* httpClient,
* "http://localhost:9999",
* "my-tenant",
* null, // use default agent card path
* authHeaders
* );
* AgentCard card = resolver.getAgentCard();
*
* // Fetch extended agent card (if available)
* AgentCard extendedCard = resolver.getExtendedAgentCard();
* }</pre>
*
* @see AgentCard
* @see A2AHttpClient
*/
public class A2ACardResolver {
private final A2AHttpClient httpClient;
private final String url;
private final @Nullable Map<String, String> authHeaders;
private static final String DEFAULT_AGENT_CARD_PATH = "/.well-known/agent-card.json";
/**
* Creates an agent card resolver. An HTTP client will be auto-selected via {@link A2AHttpClientFactory}.
*
* @param baseUrl the base URL for the agent whose agent card we want to retrieve, must not be null
* @throws A2AClientError if the URL for the agent is invalid
* @throws IllegalArgumentException if baseUrl is null
*/
public A2ACardResolver(String baseUrl) throws A2AClientError {
this(A2AHttpClientFactory.create(), baseUrl, null, null);
}
/**
* Get the agent card for an A2A agent. An HTTP client will be auto-selected via {@link A2AHttpClientFactory}.
*
* @param baseUrl the base URL for the agent whose agent card we want to retrieve, must not be null
* @param tenant the tenant path to use when fetching the agent card, may be null for no tenant
* @throws A2AClientError if the URL for the agent is invalid
* @throws IllegalArgumentException if baseUrl is null
*/
public A2ACardResolver(String baseUrl, @Nullable String tenant) throws A2AClientError {
this(A2AHttpClientFactory.create(), baseUrl, tenant, null);
}
/**
* Constructs an A2ACardResolver with a specific HTTP client and base URL.
*
* @param httpClient the HTTP client to use for fetching the agent card, must not be null
* @param baseUrl the base URL for the agent whose agent card we want to retrieve, must not be null
* @param tenant the tenant path to use when fetching the agent card, may be null for no tenant
* @throws A2AClientError if the URL for the agent is invalid
* @throws IllegalArgumentException if httpClient or baseUrl is null
*/
public A2ACardResolver(A2AHttpClient httpClient, String baseUrl, @Nullable String tenant) throws A2AClientError {
this(httpClient, baseUrl, tenant, null);
}
/**
* Constructs an A2ACardResolver with a specific HTTP client, base URL, and custom agent card path.
*
* @param httpClient the HTTP client to use for fetching the agent card, must not be null
* @param baseUrl the base URL for the agent whose agent card we want to retrieve, must not be null
* @param tenant the tenant path to use when fetching the agent card, may be null for no tenant
* @param agentCardPath optional path to the agent card endpoint relative to the base
* agent URL, defaults to "/.well-known/agent-card.json" if null or empty
* @throws A2AClientError if the URL for the agent is invalid
* @throws IllegalArgumentException if httpClient or baseUrl is null
*/
public A2ACardResolver(A2AHttpClient httpClient, String baseUrl, @Nullable String tenant, @Nullable String agentCardPath) throws A2AClientError {
this(httpClient, baseUrl, tenant, agentCardPath, null);
}
/**
* Constructs an A2ACardResolver with full configuration including authentication headers.
*
* @param httpClient the HTTP client to use for fetching the agent card, must not be null
* @param baseUrl the base URL for the agent whose agent card we want to retrieve, must not be null
* @param tenant the tenant path to use when fetching the agent card, may be null for no tenant
* @param agentCardPath optional path to the agent card endpoint relative to the base
* agent URL, defaults to "/.well-known/agent-card.json" if null or empty
* @param authHeaders the HTTP authentication headers to use, may be null
* @throws A2AClientError if the URL for the agent is invalid
* @throws IllegalArgumentException if httpClient or baseUrl is null
*/
public A2ACardResolver(A2AHttpClient httpClient, String baseUrl, @Nullable String tenant, @Nullable String agentCardPath,
@Nullable Map<String, String> authHeaders) throws A2AClientError {
checkNotNullParam("httpClient", httpClient);
checkNotNullParam("baseUrl", baseUrl);
this.httpClient = httpClient;
String effectiveAgentCardPath = (agentCardPath == null || agentCardPath.isEmpty()) ? DEFAULT_AGENT_CARD_PATH : agentCardPath;
try {
this.url = new URI(io.a2a.util.Utils.buildBaseUrl(new AgentInterface("JSONRPC", baseUrl, ""), tenant)).resolve(effectiveAgentCardPath).toString();
} catch (URISyntaxException e) {
throw new A2AClientError("Invalid agent URL", e);
}
this.authHeaders = authHeaders;
}
/**
* Get the agent card for the configured A2A agent.
*
* @return the agent card
* @throws A2AClientError If an HTTP error occurs fetching the card
* @throws A2AClientJSONError If the response body cannot be decoded as JSON or validated against the AgentCard schema
*/
public AgentCard getAgentCard() throws A2AClientError, A2AClientJSONError {
A2AHttpClient.GetBuilder builder = httpClient.createGet()
.url(url)
.addHeader("Content-Type", "application/json");
if (authHeaders != null) {
for (Map.Entry<String, String> entry : authHeaders.entrySet()) {
builder.addHeader(entry.getKey(), entry.getValue());
}
}
String body;
try {
A2AHttpResponse response = builder.get();
if (!response.success()) {
throw new A2AClientError("Failed to obtain agent card: " + response.status());
}
body = response.body();
} catch (IOException | InterruptedException e) {
throw new A2AClientError("Failed to obtain agent card", e);
}
try {
io.a2a.grpc.AgentCard.Builder agentCardBuilder = io.a2a.grpc.AgentCard.newBuilder();
JSONRPCUtils.parseJsonString(body, agentCardBuilder, "");
return ProtoUtils.FromProto.agentCard(agentCardBuilder);
} catch (A2AError | JsonProcessingException e) {
throw new A2AClientJSONError("Could not unmarshal agent card response", e);
}
}
}