0
# Client Setup and Configuration
1

2
This document covers how to create, configure, and customize the Anthropic Java client for different deployment scenarios.
3

4
## Client Creation
5

6
The SDK provides factory methods through `AnthropicOkHttpClient` for creating client instances.
7

8
### Basic Client Creation
9

10
```java { .api }
11
package com.anthropic.client.okhttp;
12

13
public class AnthropicOkHttpClient {
14
    // Create from environment variables and system properties
15
    @JvmStatic
16
    public static AnthropicClient fromEnv();
17

18
    // Create builder for manual configuration
19
    @JvmStatic
20
    public static Builder builder();
21
}
22
```
23

24
**Environment-based creation** (recommended):
25

26
```java
27
import com.anthropic.client.AnthropicClient;
28
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
29

30
// Reads ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL
31
// Or anthropic.apiKey, anthropic.authToken, anthropic.baseUrl system properties
32
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
33
```
34

35
**Manual configuration**:
36

37
```java
38
import com.anthropic.client.AnthropicClient;
39
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
40

41
AnthropicClient client = AnthropicOkHttpClient.builder()
42
    .apiKey("my-anthropic-api-key")
43
    .build();
44
```
45

46
**Hybrid approach** (environment + overrides):
47

48
```java
49
import com.anthropic.client.AnthropicClient;
50
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
51

52
AnthropicClient client = AnthropicOkHttpClient.builder()
53
    .fromEnv()  // Load defaults from environment
54
    .apiKey("my-anthropic-api-key")  // Override specific values
55
    .build();
56
```
57

58
## Authentication
59

60
The SDK supports multiple authentication mechanisms with flexible configuration.
61

62
### API Keys and Auth Tokens
63

64
```java { .api }
65
public class AnthropicOkHttpClient.Builder {
66
    // Set API key for authentication
67
    public Builder apiKey(String apiKey);
68

69
    // Set auth token for authentication
70
    public Builder authToken(String authToken);
71
}
72
```
73

74
**Environment Variables**:
75

76
| Environment Variable | Description |
77
|---------------------|-------------|
78
| `ANTHROPIC_API_KEY` | Your Anthropic API key |
79
| `ANTHROPIC_AUTH_TOKEN` | Alternative authentication token |
80
| `ANTHROPIC_BASE_URL` | Custom API base URL (default: `https://api.anthropic.com`) |
81
82
**System Properties**:
83

84
| System Property | Description |
85
|----------------|-------------|
86
| `anthropic.apiKey` | Your Anthropic API key |
87
| `anthropic.authToken` | Alternative authentication token |
88
| `anthropic.baseUrl` | Custom API base URL |
89
90
**Priority**: System properties take precedence over environment variables.
91

92
**Example with explicit credentials**:
93

94
```java
95
import com.anthropic.client.AnthropicClient;
96
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
97

98
AnthropicClient client = AnthropicOkHttpClient.builder()
99
    .apiKey(System.getenv("MY_CUSTOM_API_KEY"))
100
    .baseUrl("https://custom-api.example.com")
101
    .build();
102
```
103

104
## Configuration Options
105

106
The `AnthropicOkHttpClient.Builder` provides comprehensive configuration methods.
107

108
### Core Configuration Methods
109

110
```java { .api }
111
public class AnthropicOkHttpClient.Builder {
112
    // Load configuration from environment
113
    public Builder fromEnv();
114

115
    // Authentication
116
    public Builder apiKey(String apiKey);
117
    public Builder authToken(String authToken);
118

119
    // Base URL configuration
120
    public Builder baseUrl(String baseUrl);
121

122
    // Network settings
123
    public Builder timeout(Duration timeout);
124
    public Builder maxRetries(int maxRetries);
125

126
    // Custom headers and query parameters
127
    public Builder headers(Map<String, Iterable<String>> headers);
128
    public Builder queryParams(Map<String, Iterable<String>> queryParams);
129

130
    // JSON serialization
131
    public Builder jsonMapper(JsonMapper jsonMapper);
132

133
    // HTTP client customization (advanced)
134
    public Builder proxy(Proxy proxy);
135
    public Builder sslSocketFactory(SSLSocketFactory factory);
136
    public Builder trustManager(X509TrustManager manager);
137
    public Builder hostnameVerifier(HostnameVerifier verifier);
138

139
    // Platform backends
140
    public Builder backend(Backend backend);
141

142
    // Build the client
143
    public AnthropicClient build();
144
}
145
```
146

147
### Timeout Configuration
148

149
Configure request timeouts globally or per-request:
150

151
```java
152
import com.anthropic.client.AnthropicClient;
153
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
154
import java.time.Duration;
155

156
// Set default timeout for all requests
157
AnthropicClient client = AnthropicOkHttpClient.builder()
158
    .fromEnv()
159
    .timeout(Duration.ofSeconds(30))
160
    .build();
161
```
162

163
**Default timeout behavior**:
164
- Non-streaming requests: 10 minutes by default
165
- For large `maxTokens` values (non-streaming): Dynamic timeout up to 60 minutes calculated as:
166
  ```
167
  min(3600 seconds, max(600 seconds, 3600 * maxTokens / 128000))
168
  ```
169

170
### Retry Configuration
171

172
Configure automatic retry behavior:
173

174
```java
175
import com.anthropic.client.AnthropicClient;
176
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
177

178
// Set maximum retry attempts (default: 2)
179
AnthropicClient client = AnthropicOkHttpClient.builder()
180
    .fromEnv()
181
    .maxRetries(4)
182
    .build();
183
```
184

185
**Retryable errors**:
186
- Connection errors (network issues)
187
- 408 Request Timeout
188
- 409 Conflict
189
- 429 Rate Limit
190
- 5xx Internal Server errors
191

192
### Custom Headers and Query Parameters
193

194
Add custom headers or query parameters to all requests:
195

196
```java
197
import com.anthropic.client.AnthropicClient;
198
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
199
import java.util.Map;
200
import java.util.List;
201

202
AnthropicClient client = AnthropicOkHttpClient.builder()
203
    .fromEnv()
204
    .headers(Map.of(
205
        "X-Custom-Header", List.of("value1", "value2")
206
    ))
207
    .queryParams(Map.of(
208
        "custom_param", List.of("value")
209
    ))
210
    .build();
211
```
212

213
## Request Options
214

215
Configure individual requests with `RequestOptions` to override client defaults.
216

217
### RequestOptions API
218

219
```java { .api }
220
package com.anthropic.core;
221

222
public class RequestOptions {
223
    public static Builder builder();
224

225
    public static class Builder {
226
        // Override timeout for this request
227
        public Builder timeout(Duration timeout);
228

229
        // Enable response validation for this request
230
        public Builder responseValidation(boolean validation);
231

232
        // Add custom headers
233
        public Builder putHeader(String name, String value);
234

235
        // Add custom query parameters
236
        public Builder putQueryParam(String key, String value);
237

238
        public RequestOptions build();
239
    }
240
}
241
```
242

243
### Per-Request Configuration
244

245
```java
246
import com.anthropic.core.RequestOptions;
247
import com.anthropic.models.messages.Message;
248
import com.anthropic.models.messages.MessageCreateParams;
249
import com.anthropic.models.messages.Model;
250
import java.time.Duration;
251

252
MessageCreateParams params = MessageCreateParams.builder()
253
    .maxTokens(1024L)
254
    .addUserMessage("Hello, Claude")
255
    .model(Model.CLAUDE_SONNET_4_5)
256
    .build();
257

258
// Override timeout for this specific request
259
RequestOptions options = RequestOptions.builder()
260
    .timeout(Duration.ofSeconds(60))
261
    .responseValidation(true)
262
    .build();
263

264
Message message = client.messages().create(params, options);
265
```
266

267
## Async Execution
268

269
The SDK provides both synchronous and asynchronous client variants.
270

271
### Async Client Creation
272

273
```java { .api }
274
package com.anthropic.client;
275

276
public interface AnthropicClient {
277
    // Convert sync client to async
278
    AnthropicClientAsync async();
279
}
280

281
public interface AnthropicClientAsync {
282
    // Convert async client to sync
283
    AnthropicClient sync();
284
}
285
```
286

287
**Create async client from sync**:
288

289
```java
290
import com.anthropic.client.AnthropicClient;
291
import com.anthropic.client.AnthropicClientAsync;
292
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
293
import com.anthropic.models.messages.Message;
294
import com.anthropic.models.messages.MessageCreateParams;
295
import com.anthropic.models.messages.Model;
296
import java.util.concurrent.CompletableFuture;
297

298
AnthropicClient syncClient = AnthropicOkHttpClient.fromEnv();
299
AnthropicClientAsync asyncClient = syncClient.async();
300

301
MessageCreateParams params = MessageCreateParams.builder()
302
    .maxTokens(1024L)
303
    .addUserMessage("Hello, Claude")
304
    .model(Model.CLAUDE_SONNET_4_5)
305
    .build();
306

307
CompletableFuture<Message> future = asyncClient.messages().create(params);
308
```
309

310
**Create async client directly**:
311

312
```java
313
import com.anthropic.client.AnthropicClientAsync;
314
import com.anthropic.client.okhttp.AnthropicOkHttpClientAsync;
315
import com.anthropic.models.messages.Message;
316
import java.util.concurrent.CompletableFuture;
317

318
AnthropicClientAsync client = AnthropicOkHttpClientAsync.fromEnv();
319

320
CompletableFuture<Message> future = client.messages().create(params);
321
```
322

323
### Async Streaming Configuration
324

325
Configure thread pool for async streaming operations:
326

327
```java
328
import com.anthropic.client.AnthropicClient;
329
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
330
import java.util.concurrent.Executor;
331
import java.util.concurrent.Executors;
332

333
// Configure global executor for stream handlers
334
Executor executor = Executors.newFixedThreadPool(4);
335

336
AnthropicClient client = AnthropicOkHttpClient.builder()
337
    .fromEnv()
338
    .streamHandlerExecutor(executor)
339
    .build();
340
```
341

342
**Per-request executor override**:
343

344
```java
345
import java.util.concurrent.Executor;
346
import java.util.concurrent.Executors;
347

348
Executor customExecutor = Executors.newFixedThreadPool(2);
349

350
client.async().messages().createStreaming(params).subscribe(
351
    chunk -> System.out.println(chunk),
352
    customExecutor
353
);
354
```
355

356
## Modifying Configuration
357

358
Create modified client instances while reusing connection pools and resources.
359

360
### Using withOptions()
361

362
```java { .api }
363
package com.anthropic.client;
364

365
public interface AnthropicClient {
366
    // Create modified client with new options
367
    AnthropicClient withOptions(Consumer<ClientOptions.Builder> modifier);
368
}
369

370
public interface AnthropicClientAsync {
371
    // Create modified async client with new options
372
    AnthropicClientAsync withOptions(Consumer<ClientOptions.Builder> modifier);
373
}
374
```
375

376
**Example usage**:
377

378
```java
379
import com.anthropic.client.AnthropicClient;
380

381
// Create modified client without affecting the original
382
AnthropicClient modifiedClient = client.withOptions(optionsBuilder -> {
383
    optionsBuilder.baseUrl("https://example.com");
384
    optionsBuilder.maxRetries(5);
385
    optionsBuilder.timeout(Duration.ofMinutes(2));
386
});
387

388
// Original client is unchanged
389
// modifiedClient uses new configuration but shares connection pool
390
```
391

392
### ClientOptions.Builder Methods
393

394
```java { .api }
395
package com.anthropic.core;
396

397
public class ClientOptions.Builder {
398
    // HTTP client implementation
399
    public Builder httpClient(HttpClient httpClient);
400

401
    // JSON configuration
402
    public Builder jsonMapper(JsonMapper jsonMapper);
403
    public Builder checkJacksonVersionCompatibility(boolean check);
404

405
    // Async streaming
406
    public Builder streamHandlerExecutor(Executor executor);
407

408
    // Timing and delays
409
    public Builder sleeper(Sleeper sleeper);
410
    public Builder clock(Clock clock);
411

412
    // Base configuration
413
    public Builder baseUrl(String baseUrl);
414
    public Builder timeout(Duration timeout);
415
    public Builder maxRetries(int maxRetries);
416

417
    // Validation
418
    public Builder responseValidation(boolean validation);
419

420
    // Headers and query parameters
421
    public Builder putHeader(String name, String value);
422
    public Builder putQueryParam(String key, String value);
423

424
    public ClientOptions build();
425
}
426
```
427

428
## Network Options
429

430
Advanced network configuration for proxies, HTTPS, and custom HTTP clients.
431

432
### Proxy Configuration
433

434
Route requests through a proxy server:
435

436
```java { .api }
437
public class AnthropicOkHttpClient.Builder {
438
    public Builder proxy(Proxy proxy);
439
}
440
```
441

442
**Example**:
443

444
```java
445
import com.anthropic.client.AnthropicClient;
446
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
447
import java.net.InetSocketAddress;
448
import java.net.Proxy;
449

450
AnthropicClient client = AnthropicOkHttpClient.builder()
451
    .fromEnv()
452
    .proxy(new Proxy(
453
        Proxy.Type.HTTP,
454
        new InetSocketAddress("proxy.example.com", 8080)
455
    ))
456
    .build();
457
```
458

459
### HTTPS Configuration
460

461
Customize SSL/TLS settings for HTTPS connections:
462

463
```java { .api }
464
public class AnthropicOkHttpClient.Builder {
465
    public Builder sslSocketFactory(SSLSocketFactory factory);
466
    public Builder trustManager(X509TrustManager manager);
467
    public Builder hostnameVerifier(HostnameVerifier verifier);
468
}
469
```
470

471
**Example with custom SSL**:
472

473
```java
474
import com.anthropic.client.AnthropicClient;
475
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
476
import javax.net.ssl.SSLSocketFactory;
477
import javax.net.ssl.TrustManager;
478
import javax.net.ssl.X509TrustManager;
479
import javax.net.ssl.HostnameVerifier;
480

481
// Custom SSL configuration (use with caution)
482
AnthropicClient client = AnthropicOkHttpClient.builder()
483
    .fromEnv()
484
    .sslSocketFactory(customSSLSocketFactory)
485
    .trustManager(customTrustManager)
486
    .hostnameVerifier(customHostnameVerifier)
487
    .build();
488
```
489

490
**Note**: Most applications should use system defaults. Custom SSL configuration may reduce security optimizations.
491

492
### Retry and Timeout Behavior
493

494
**Exponential backoff**: Automatic exponential backoff between retry attempts with jitter.
495

496
**Timeout calculation for large responses**:
497

498
For non-streaming requests with large `maxTokens`:
499

500
```
501
timeout = min(3600, max(600, 3600 * maxTokens / 128000)) seconds
502
```
503

504
- Minimum: 10 minutes (600 seconds)
505
- Maximum: 60 minutes (3600 seconds)
506
- Scales with `maxTokens` value
507

508
**Long-running requests**: For requests expected to take longer than 10 minutes, use streaming or explicitly override the timeout.
509

510
### Platform Backends
511

512
Configure alternative API backends for cloud platforms:
513

514
```java { .api }
515
public class AnthropicOkHttpClient.Builder {
516
    public Builder backend(Backend backend);
517
}
518
```
519

520
**AWS Bedrock**:
521

522
```java
523
import com.anthropic.bedrock.backends.BedrockBackend;
524
import com.anthropic.client.AnthropicClient;
525
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
526

527
AnthropicClient client = AnthropicOkHttpClient.builder()
528
    .backend(BedrockBackend.fromEnv())
529
    .build();
530
```
531

532
**Google Vertex AI**:
533

534
```java
535
import com.anthropic.vertex.backends.VertexBackend;
536
import com.anthropic.client.AnthropicClient;
537
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
538

539
AnthropicClient client = AnthropicOkHttpClient.builder()
540
    .backend(VertexBackend.fromEnv())
541
    .build();
542
```
543

544
## Best Practices
545

546
### Client Reuse
547

548
**Important**: Create one client per application and reuse it across requests. Each client maintains connection pools and thread pools that are expensive to recreate.
549

550
```java
551
// Good: Single client instance
552
public class MyService {
553
    private static final AnthropicClient CLIENT = AnthropicOkHttpClient.fromEnv();
554

555
    public void processRequest() {
556
        Message response = CLIENT.messages().create(params);
557
    }
558
}
559

560
// Bad: New client per request
561
public void processRequest() {
562
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();  // Don't do this!
563
    Message response = client.messages().create(params);
564
}
565
```
566

567
### Resource Cleanup
568

569
Close clients when shutting down your application:
570

571
```java
572
import com.anthropic.client.AnthropicClient;
573

574
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
575

576
try {
577
    // Use client
578
    Message response = client.messages().create(params);
579
} finally {
580
    // Release resources
581
    client.close();
582
}
583
```
584

585
### Environment-Based Configuration
586

587
Use environment variables for deployment flexibility:
588

589
```java
590
// Development
591
// ANTHROPIC_API_KEY=sk-dev-key-123
592

593
// Production
594
// ANTHROPIC_API_KEY=sk-prod-key-456
595
// ANTHROPIC_BASE_URL=https://api.production.example.com
596

597
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
598
```
599

600
### Per-Request Overrides
601

602
Use `withOptions()` for temporary configuration changes:
603

604
```java
605
// Base client with standard settings
606
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
607

608
// High-priority request with extended timeout
609
AnthropicClient urgentClient = client.withOptions(opts -> {
610
    opts.timeout(Duration.ofMinutes(5));
611
});
612

613
Message urgentResponse = urgentClient.messages().create(urgentParams);
614

615
// Standard requests still use base client
616
Message normalResponse = client.messages().create(normalParams);
617
```
618