1# Claude API — Go
2 
3> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go.
4 
5## Installation
6 
7```bash
8go get github.com/anthropics/anthropic-sdk-go
9```
10 
11## Client Initialization
12 
13```go
14import (
15    "github.com/anthropics/anthropic-sdk-go"
16    "github.com/anthropics/anthropic-sdk-go/option"
17)
18 
19// Default (uses ANTHROPIC_API_KEY env var)
20client := anthropic.NewClient()
21 
22// Explicit API key
23client := anthropic.NewClient(
24    option.WithAPIKey("your-api-key"),
25)
26```
27 
28---
29 
30## Model Constants
31 
32The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthropic.ModelClaudeOpus4_8`, `anthropic.ModelClaudeOpus4_7`, `anthropic.ModelClaudeSonnet4_6`, `anthropic.ModelClaudeHaiku4_5_20251001`. Use `ModelClaudeOpus4_8` unless the user specifies otherwise; if they ask for Fable or the most powerful model, use `anthropic.ModelClaudeFable5` (see `shared/models.md` for the full resolution table).
33 
34---
35 
36## Basic Message Request
37 
38```go
39response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
40    Model:     anthropic.ModelClaudeOpus4_8,
41    MaxTokens: 16000,
42    Messages: []anthropic.MessageParam{
43        anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
44    },
45})
46if err != nil {
47    log.Fatal(err)
48}
49for _, block := range response.Content {
50    switch variant := block.AsAny().(type) {
51    case anthropic.TextBlock:
52        fmt.Println(variant.Text)
53    }
54}
55```
56 
57---
58 
59## Thinking
60 
61Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`.
62 
63**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control.
64 
65Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `ThinkingConfigAdaptiveParam`).
66 
67```go
68// There is no ThinkingConfigParamOfAdaptive helper — construct the union
69// struct-literal directly and take the address of the variant.
70adaptive := anthropic.ThinkingConfigAdaptiveParam{}
71params := anthropic.MessageNewParams{
72    Model:     anthropic.ModelClaudeSonnet4_6,
73    MaxTokens: 16000,
74    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
75    Messages: []anthropic.MessageParam{
76        anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
77    },
78}
79 
80resp, err := client.Messages.New(context.Background(), params)
81if err != nil {
82    log.Fatal(err)
83}
84 
85// ThinkingBlock(s) precede TextBlock in content
86for _, block := range resp.Content {
87    switch b := block.AsAny().(type) {
88    case anthropic.ThinkingBlock:
89        fmt.Println("[thinking]", b.Thinking)
90    case anthropic.TextBlock:
91        fmt.Println(b.Text)
92    }
93}
94```
95 
96> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `ThinkingConfigParamOfEnabled(budgetTokens)` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
97> **Older models:** Use `anthropic.ThinkingConfigParamOfEnabled(N)` (budget must be < `MaxTokens`, min 1024).
98 
99To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`.
100 
101---
102 
103## Prompt Caching
104 
105`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
106 
107```go
108System: []anthropic.TextBlockParam{{
109    Text:         longSystemPrompt,
110    CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
111}},
112```
113 
114For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block.
115 
116Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`.
117 
118---
119 
120## Stop Details
121 
122When `StopReason` is `anthropic.StopReasonRefusal`, the response includes structured `StopDetails`:
123 
124```go
125if resp.StopReason == anthropic.StopReasonRefusal {
126    fmt.Println("Category:", resp.StopDetails.Category)     // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or "" — see docs for the full set
127    fmt.Println("Explanation:", resp.StopDetails.Explanation)
128}
129```
130 
131**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. In `claude-fable-5` code, include `Fallbacks: []anthropic.BetaFallbackParam{{Model: "claude-opus-4-8"}}` plus the `anthropic.AnthropicBetaServerSideFallback2026_06_01` beta on `client.Beta.Messages.New` by default — a policy decline is re-served by the fallback model inside the same call. Not available on Amazon Bedrock, Vertex AI, or Microsoft Foundry — register the client-side middleware there: `option.WithMiddleware(betafallback.BetaRefusalFallbackMiddleware(...))` from `lib/betafallback`, with per-conversation state via `betafallback.WithBetaFallbackState(&betafallback.BetaFallbackState{})`. Full semantics (billing, sticky routing, streaming) and a runnable example: `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason, and the Go SDK repo's `examples/` (WebFetch via `shared/live-sources.md`).
132 
133---
134 
135## PDF / Document Input
136 
137`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set.
138 
139```go
140b64 := base64.StdEncoding.EncodeToString(pdfBytes)
141 
142msg := anthropic.NewUserMessage(
143    anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
144    anthropic.NewTextBlock("Summarize this document"),
145)
146```
147 
148Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`.
149 
150---
151 
152## Context Editing / Compaction (Beta)
153 
154Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip.
155 
156```go
157params := anthropic.BetaMessageNewParams{
158    Model:     anthropic.ModelClaudeOpus4_8,  // also supported: ModelClaudeSonnet4_6
159    MaxTokens: 16000,
160    Betas:     []anthropic.AnthropicBeta{"compact-2026-01-12"},
161    ContextManagement: anthropic.BetaContextManagementConfigParam{
162        Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
163            {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
164        },
165    },
166    Messages: []anthropic.BetaMessageParam{ /* ... */ },
167}
168 
169resp, err := client.Beta.Messages.New(ctx, params)
170if err != nil {
171    log.Fatal(err)
172}
173 
174// Round-trip: append response to history via .ToParam()
175params.Messages = append(params.Messages, resp.ToParam())
176 
177// Read compaction blocks from the response
178for _, block := range resp.Content {
179    if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
180        fmt.Println("compaction summary:", c.Content)
181    }
182}
183```
184 
185Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam` — these need `Betas: []anthropic.AnthropicBeta{"context-management-2025-06-27"}`, not `compact-2026-01-12`.
186