SDK Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Anthropic SDK for Go is a generated library designed to provide a structured, type-safe interface for interacting with the Claude API. It supports standard RESTful interactions, server-sent events (SSE) for streaming, and specialized authentication layers for cloud providers like AWS Bedrock and Google Vertex AI. Sources: README.md:1-15, CONTRIBUTING.md:12-15
The architecture prioritizes developer experience by offering clear service boundaries, consistent request/response patterns, and automated pagination for list-based endpoints. Most of the SDK is generated code, ensuring high fidelity to the Anthropic OpenAPI specification while allowing for manual overrides in specific directories like lib/ and examples/. Sources: CONTRIBUTING.md:12-15, betaskill.go:27-40
Core Client and Service Pattern
The SDK follows a hierarchical service pattern. A central Client acts as the entry point, which then exposes specialized services such as Messages, Beta, and MessageBatches. These services encapsulate the logic for specific API segments.
Service Initialization
Each service is typically initialized through a constructor (e.g., NewBetaSkillService) that accepts option.RequestOption types. These options are applied to every request made through that service, following a hierarchy where parent client options are applied first, followed by service-level options, and finally request-specific options. Sources: betaskill.go:42-47, messagebatch.go:34-39
The diagram shows the hierarchical relationship between the main client and its sub-services, as well as the precedence order for request configurations. Sources: betaskill.go:27-55, messagebatch.go:26-50
Request Execution Flow
The SDK uses an internal requestconfig package to manage the lifecycle of an HTTP request. This involves parameter marshaling, header injection (especially for beta features), and response unmarshaling.
Key Components of Request Handling
- Parameter Mapping: Request parameters are defined as Go structs with tags for
json,query, orheader. Sources: betaskill.go:240-270 - Beta Header Injection: For beta services, specific headers like
anthropic-betaare automatically appended to the request options. Sources: betaskill.go:51-53 - JSON Schema Transformation: The SDK includes utility functions to transform standard JSON schemas into Anthropic-compatible formats, particularly for tool use and structured outputs. Sources: schemautil.go:45-65
This sequence illustrates how a request moves from application code through schema validation and authentication layers before reaching the API. Sources: schemautil.go:120-140, internal/awsauth/awsauth.go:215-235, betaskill.go:50-60
Authentication and Cloud Integration
The SDK provides robust support for multi-provider authentication, particularly for AWS and Google Cloud environments.
AWS SigV4 Signing
The internal/awsauth package manages the complexity of AWS Signature Version 4 signing. It supports resolving credentials from environment variables (AWS_REGION, AWS_ACCESS_KEY_ID, etc.) or programmatic configuration. Sources: internal/awsauth/awsauth.go:70-100
| Component | Description |
|---|---|
ResolveConfig | Resolves region, base URL, and auth mode (API Key vs SigV4). |
BuildAWSConfig | Loads AWS credentials from the environment or static providers. |
SigV4Middleware | An HTTP middleware that intercepts requests to apply SigV4 headers. |
CreateClientOptions | Generates request options including base URLs and auth headers. |
Sources: internal/awsauth/awsauth.go:68-235
Data Transformation and Schemas
To ensure compatibility with the Claude API's strict JSON schema requirements, the SDK implements a transformation layer in schemautil.go.
Schema Transformation Logic
The transformSchema function enforces specific constraints:
- Property Filtering: Only supported keys (e.g.,
type,properties,items) are preserved. Sources: schemautil.go:66-90 - Strict Objects: Automatically sets
additionalProperties: falsefor object types. Sources: schemautil.go:167-183 - Format Constraints: Filters string formats to a whitelist including
date-time,uuid, andemail. Sources: schemautil.go:50-65 - Unsupported Properties: Moves unsupported schema keys into the
descriptionfield to preserve metadata without violating API validation. Sources: schemautil.go:195-225
Batch and Async Processing
The MessageBatchService handles long-running operations that can take up to 24 hours. This service supports:
- Idempotent Polling: Using
Getto check processing status. Sources: messagebatch.go:64-75 - Result Streaming: Retrieving final results as a
.jsonlstream to handle large volumes of processed messages efficiently. Sources: messagebatch.go:138-152 - Cancellation: Stopping in-progress batches before they finalize. Sources: messagebatch.go:119-130
Message Batch Statuses
| Status | Description |
|---|---|
in_progress | The batch is currently being processed by Anthropic. |
canceling | Cancellation has been initiated but not yet finalized. |
ended | Processing has completed (success, error, or expired). |
Sources: messagebatch.go:198-204
Summary
The Anthropic Go SDK architecture is built on a foundation of generated services that maintain strict adherence to the API schema while providing flexible extension points for authentication and beta features. By centralizing request lifecycle management and implementing a sophisticated schema transformation layer, the SDK ensures that complex features like tool use and cloud-native authentication remain accessible and type-safe for Go developers. Sources: README.md, schemautil.go, internal/awsauth/awsauth.go