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## Streaming
60 
61```go
62stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{
63    Model:     anthropic.ModelClaudeOpus4_6,
64    MaxTokens: 64000,
65    Messages: []anthropic.MessageParam{
66        anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
67    },
68})
69 
70for stream.Next() {
71    event := stream.Current()
72    switch eventVariant := event.AsAny().(type) {
73    case anthropic.ContentBlockDeltaEvent:
74        switch deltaVariant := eventVariant.Delta.AsAny().(type) {
75        case anthropic.TextDelta:
76            fmt.Print(deltaVariant.Text)
77        }
78    }
79}
80if err := stream.Err(); err != nil {
81    log.Fatal(err)
82}
83```
84 
85**Accumulating the final message** (there is no `GetFinalMessage()` on the stream):
86 
87```go
88stream := client.Messages.NewStreaming(ctx, params)
89message := anthropic.Message{}
90for stream.Next() {
91    message.Accumulate(stream.Current())
92}
93if err := stream.Err(); err != nil { log.Fatal(err) }
94// message.Content now has the complete response
95```
96 
97 
98---
99 
100## Tool Use
101 
102### Tool Runner (Beta — Recommended)
103 
104**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package.
105 
106```go
107import (
108    "context"
109    "fmt"
110    "log"
111 
112    "github.com/anthropics/anthropic-sdk-go"
113    "github.com/anthropics/anthropic-sdk-go/toolrunner"
114)
115 
116// Define tool input with jsonschema tags for automatic schema generation
117type GetWeatherInput struct {
118    City string `json:"city" jsonschema:"required,description=The city name"`
119}
120 
121// Create a tool with automatic schema generation from struct tags
122weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
123    "get_weather",
124    "Get current weather for a city",
125    func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
126        return anthropic.BetaToolResultBlockParamContentUnion{
127            OfText: &anthropic.BetaTextBlockParam{
128                Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
129            },
130        }, nil
131    },
132)
133if err != nil {
134    log.Fatal(err)
135}
136 
137// Create a tool runner that handles the conversation loop automatically
138runner := client.Beta.Messages.NewToolRunner(
139    []anthropic.BetaTool{weatherTool},
140    anthropic.BetaToolRunnerParams{
141        BetaMessageNewParams: anthropic.BetaMessageNewParams{
142            Model:     anthropic.ModelClaudeOpus4_6,
143            MaxTokens: 16000,
144            Messages: []anthropic.BetaMessageParam{
145                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
146            },
147        },
148        MaxIterations: 5,
149    },
150)
151 
152// Run until Claude produces a final response
153message, err := runner.RunToCompletion(context.Background())
154if err != nil {
155    log.Fatal(err)
156}
157 
158// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
159// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock,
160// not TextBlock):
161for _, block := range message.Content {
162    switch block := block.AsAny().(type) {
163    case anthropic.BetaTextBlock:
164        fmt.Println(block.Text)
165    }
166}
167```
168 
169**Key features of the Go tool runner:**
170 
171- Automatic schema generation from Go structs via `jsonschema` tags
172- `RunToCompletion()` for simple one-shot usage
173- `All()` iterator for processing each message in the conversation
174- `NextMessage()` for step-by-step iteration
175- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()`
176 
177### Manual Loop
178 
179For fine-grained control over the agentic loop, define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back. This is the pattern when you need to intercept, validate, or log tool calls.
180 
181Derived from `anthropic-sdk-go/examples/tools/main.go`.
182 
183```go
184package main
185 
186import (
187    "context"
188    "encoding/json"
189    "fmt"
190    "log"
191 
192    "github.com/anthropics/anthropic-sdk-go"
193)
194 
195func main() {
196    client := anthropic.NewClient()
197 
198    // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
199    addTool := anthropic.ToolParam{
200        Name:        "add",
201        Description: anthropic.String("Add two integers"),
202        InputSchema: anthropic.ToolInputSchemaParam{
203            Properties: map[string]any{
204                "a": map[string]any{"type": "integer"},
205                "b": map[string]any{"type": "integer"},
206            },
207        },
208    }
209    // ToolParam must be wrapped in ToolUnionParam for the Tools slice
210    tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
211 
212    messages := []anthropic.MessageParam{
213        anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
214    }
215 
216    for {
217        resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
218            Model:     anthropic.ModelClaudeSonnet4_6,
219            MaxTokens: 16000,
220            Messages:  messages,
221            Tools:     tools,
222        })
223        if err != nil {
224            log.Fatal(err)
225        }
226 
227        // 2. Append the assistant response to history BEFORE processing tool calls.
228        //    resp.ToParam() converts Message → MessageParam in one call.
229        messages = append(messages, resp.ToParam())
230 
231        // 3. Walk content blocks. ContentBlockUnion is a flattened struct;
232        //    use block.AsAny().(type) to switch on the actual variant.
233        toolResults := []anthropic.ContentBlockParamUnion{}
234        for _, block := range resp.Content {
235            switch variant := block.AsAny().(type) {
236            case anthropic.TextBlock:
237                fmt.Println(variant.Text)
238            case anthropic.ToolUseBlock:
239                // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
240                //    raw JSON — block.Input is json.RawMessage, not the parsed value.
241                var in struct {
242                    A int `json:"a"`
243                    B int `json:"b"`
244                }
245                if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
246                    log.Fatal(err)
247                }
248                result := fmt.Sprintf("%d", in.A+in.B)
249                // 5. NewToolResultBlock(toolUseID, content, isError) builds the
250                //    ContentBlockParamUnion for you. block.ID is the tool_use_id.
251                toolResults = append(toolResults,
252                    anthropic.NewToolResultBlock(block.ID, result, false))
253            }
254        }
255 
256        // 6. Exit when Claude stops asking for tools
257        if resp.StopReason != anthropic.StopReasonToolUse {
258            break
259        }
260 
261        // 7. Tool results go in a user message (variadic: all results in one turn)
262        messages = append(messages, anthropic.NewUserMessage(toolResults...))
263    }
264}
265```
266 
267**Key API surface:**
268 
269| Symbol | Purpose |
270|---|---|
271| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history |
272| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants |
273| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) |
274| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block |
275| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn |
276| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination |
277| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` |
278 
279---
280 
281## Thinking
282 
283Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`.
284 
285**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.
286 
287Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `ThinkingConfigAdaptiveParam`).
288 
289```go
290// There is no ThinkingConfigParamOfAdaptive helper — construct the union
291// struct-literal directly and take the address of the variant.
292adaptive := anthropic.ThinkingConfigAdaptiveParam{}
293params := anthropic.MessageNewParams{
294    Model:     anthropic.ModelClaudeSonnet4_6,
295    MaxTokens: 16000,
296    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
297    Messages: []anthropic.MessageParam{
298        anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
299    },
300}
301 
302resp, err := client.Messages.New(context.Background(), params)
303if err != nil {
304    log.Fatal(err)
305}
306 
307// ThinkingBlock(s) precede TextBlock in content
308for _, block := range resp.Content {
309    switch b := block.AsAny().(type) {
310    case anthropic.ThinkingBlock:
311        fmt.Println("[thinking]", b.Thinking)
312    case anthropic.TextBlock:
313        fmt.Println(b.Text)
314    }
315}
316```
317 
318> **Deprecated:** `ThinkingConfigParamOfEnabled(budgetTokens)` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
319 
320To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`.
321 
322---
323 
324## Prompt Caching
325 
326`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`.
327 
328```go
329System: []anthropic.TextBlockParam{{
330    Text:         longSystemPrompt,
331    CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
332}},
333```
334 
335For 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.
336 
337Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`.
338 
339---
340 
341## Server-Side Tools
342 
343Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field.
344 
345```go
346Tools: []anthropic.ToolUnionParam{
347    {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
348    {OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
349    {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
350    {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
351},
352```
353 
354Also available: `WebFetchTool20260209Param`, `MemoryTool20250818Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. For the advisor tool, use `BetaAdvisorTool20260301Param` in the beta namespace.
355 
356---
357 
358## Stop Details
359 
360When `StopReason` is `anthropic.StopReasonRefusal`, the response includes structured `StopDetails`:
361 
362```go
363if resp.StopReason == anthropic.StopReasonRefusal {
364    fmt.Println("Category:", resp.StopDetails.Category)     // "cyber" | "bio" | ""
365    fmt.Println("Explanation:", resp.StopDetails.Explanation)
366}
367```
368 
369---
370 
371## PDF / Document Input
372 
373`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set.
374 
375```go
376b64 := base64.StdEncoding.EncodeToString(pdfBytes)
377 
378msg := anthropic.NewUserMessage(
379    anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
380    anthropic.NewTextBlock("Summarize this document"),
381)
382```
383 
384Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`.
385 
386---
387 
388## Files API (Beta)
389 
390Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding.
391 
392```go
393f, _ := os.Open("./upload_me.txt")
394defer f.Close()
395 
396meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
397    File:  anthropic.File(f, "upload_me.txt", "text/plain"),
398    Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
399})
400// meta.ID is the file_id to reference in subsequent message requests
401```
402 
403Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`.
404 
405---
406 
407## Context Editing / Compaction (Beta)
408 
409Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip.
410 
411```go
412params := anthropic.BetaMessageNewParams{
413    Model:     anthropic.ModelClaudeOpus4_6,  // also supported: ModelClaudeSonnet4_6
414    MaxTokens: 16000,
415    Betas:     []anthropic.AnthropicBeta{"compact-2026-01-12"},
416    ContextManagement: anthropic.BetaContextManagementConfigParam{
417        Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
418            {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
419        },
420    },
421    Messages: []anthropic.BetaMessageParam{ /* ... */ },
422}
423 
424resp, err := client.Beta.Messages.New(ctx, params)
425if err != nil {
426    log.Fatal(err)
427}
428 
429// Round-trip: append response to history via .ToParam()
430params.Messages = append(params.Messages, resp.ToParam())
431 
432// Read compaction blocks from the response
433for _, block := range resp.Content {
434    if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
435        fmt.Println("compaction summary:", c.Content)
436    }
437}
438```
439 
440Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam`.
441