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