@@ -151,6 +151,34 @@ Client client = Client
         .build();
 ```
 
+### Setting a Custom `Host` Header
+
+The JDK-based `JdkA2AHttpClient` (the default) delegates to `java.net.http.HttpClient`,
+which rejects an explicit `Host` header (`addHeader("Host", ...)`) with an
+`IllegalArgumentException` unless the JVM is started with
+`-Djdk.httpclient.allowRestrictedHeaders=host`. This is a JDK-wide restriction and
+cannot be worked around per-client-instance.
+
+If you need to send a custom `Host` header — for example, connecting directly to an
+instance by IP while presenting the hostname a load balancer would normally supply —
+either set that JVM property, or use the `VertxA2AHttpClient` from the
+`a2a-java-sdk-http-client-vertx` extra, which does not build on `java.net.http.HttpClient`
+and has no such restriction:
+
+```java
+// Both resources are closed separately because Client.close() does not close an injected
+// A2AHttpClient. VertxA2AHttpClient's no-args constructor also owns the Vert.x instance.
+try (VertxA2AHttpClient httpClient = new VertxA2AHttpClient()) {
+    try (Client client = Client
+            .builder(agentCard)
+            .withTransport(JSONRPCTransport.class,
+                    new JSONRPCTransportConfig(httpClient))
+            .build()) {
+        // use client...
+    }
+}
+```
+
 ### REST with a Custom HTTP Client
 
 ```java
 
@@ -13,6 +13,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockserver.integration.ClientAndServer;
+import org.mockserver.verify.VerificationTimes;
 
 public class VertxA2AHttpClientIntegrationTest {
 
@@ -87,6 +88,28 @@ public void testDeleteRequestSuccess() throws Exception {
         assertTrue(response.success());
     }
 
+    @Test
+    public void testCustomHostHeaderOverride() throws Exception {
+        // Unlike the JDK-based client, VertxA2AHttpClient does not build on
+        // java.net.http.HttpClient and so is not subject to its restricted-header
+        // check: callers can override "Host" while still connecting to the URL's
+        // own host:port (e.g. to reach an instance directly while presenting the
+        // hostname a load balancer would normally supply).
+        mockServer
+                .when(request().withMethod("GET").withPath("/test"))
+                .respond(response().withStatusCode(200).withBody("ok"));
+
+        A2AHttpResponse response = client.createGet()
+                .url(getBaseUrl() + "/test")
+                .addHeader("Host", "custom-logical-host.example.com")
+                .get();
+
+        assertEquals(200, response.status());
+        mockServer.verify(
+                request().withPath("/test").withHeader("Host", "custom-logical-host.example.com"),
+                VerificationTimes.once());
+    }
+
     @Test
     public void test401AuthenticationErrorOnGet() throws Exception {
         mockServer
 
@@ -46,6 +46,18 @@
  * {@link org.a2aproject.sdk.client.http.A2AHttpClient.PostBuilder#followRedirects(boolean)
  * followRedirects(true)} on the builder. Both steps are required.
  *
+ * <p><b>{@code Host} header limitation:</b> the underlying JDK {@link HttpClient}
+ * rejects {@code addHeader("Host", ...)} with an {@code IllegalArgumentException}
+ * ("restricted header name") unless the JVM is started with
+ * {@code -Djdk.httpclient.allowRestrictedHeaders=host}. This is a JDK-wide
+ * restriction that cannot be worked around per-client-instance. Applications that
+ * need to send an explicit {@code Host} header (for example, connecting directly to
+ * an instance while presenting the hostname a load balancer normally supplies) should
+ * either set that system property or use an {@link A2AHttpClient} implementation that
+ * does not build on {@code java.net.http.HttpClient}, such as
+ * {@code org.a2aproject.sdk.client.http.vertx.VertxA2AHttpClient} (the
+ * {@code a2a-java-sdk-http-client-vertx} extra), which has no such restriction.
+ *
  * <p><b>Provider Priority:</b> 0 (lowest - used as fallback)
  *
  * <p>This implementation is registered via {@link JdkA2AHttpClientProvider}
 
@@ -18,6 +18,7 @@
 import java.net.http.HttpResponse;
 import java.net.http.WebSocket;
 import java.time.Duration;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -39,6 +40,7 @@
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeFalse;
 import static org.mockserver.model.HttpRequest.request;
 import static org.mockserver.model.HttpResponse.response;
 
@@ -69,6 +71,34 @@ public void testDefaultConstructorCreatesUsableClient() throws Exception {
         assertEquals("ok", response.body());
     }
 
+    @Test
+    public void testCustomHostHeaderRejectedByJdkHttpClient() {
+        // Documents a JDK-wide restriction (not specific to this SDK): java.net.http.HttpClient
+        // rejects an explicit "Host" header unless the JVM is started with
+        // -Djdk.httpclient.allowRestrictedHeaders=host. Callers who need to send a custom Host
+        // header should use that JVM property or a non-JDK A2AHttpClient implementation, e.g.
+        // VertxA2AHttpClient from the a2a-java-sdk-http-client-vertx extra.
+        //
+        // Skip if the JVM running this test already allows a restricted "Host" header: in that
+        // (documented, supported) configuration the JDK client legitimately accepts it instead.
+        assumeFalse(jdkAllowsRestrictedHostHeader(), "JVM allows a restricted Host header "
+                + "via jdk.httpclient.allowRestrictedHeaders; the JDK client no longer rejects it");
+
+        JdkA2AHttpClient client = new JdkA2AHttpClient();
+
+        assertThrows(IllegalArgumentException.class, () -> client.createGet()
+                .url("http://localhost:1/unused")
+                .addHeader("Host", "custom.example.com")
+                .get());
+    }
+
+    private static boolean jdkAllowsRestrictedHostHeader() {
+        String allowed = System.getProperty("jdk.httpclient.allowRestrictedHeaders", "");
+        return Arrays.stream(allowed.split(","))
+                .map(String::trim)
+                .anyMatch("host"::equalsIgnoreCase);
+    }
+
     @Test
     public void testConstructorUsesProvidedHttpClient() throws Exception {
         server = ClientAndServer.startClientAndServer(0);