1# Tool Use — Go
2 
3For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
4 
5## Tool Use
6 
7### Tool Runner (Beta — Recommended)
8 
9**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package.
10 
11```go
12import (
13    "context"
14    "fmt"
15    "log"
16 
17    "github.com/anthropics/anthropic-sdk-go"
18    "github.com/anthropics/anthropic-sdk-go/toolrunner"
19)
20 
21// Define tool input with jsonschema tags for automatic schema generation
22type GetWeatherInput struct {
23    City string `json:"city" jsonschema:"required,description=The city name"`
24}
25 
26// Create a tool with automatic schema generation from struct tags
27weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
28    "get_weather",
29    "Get current weather for a city",
30    func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
31        return anthropic.BetaToolResultBlockParamContentUnion{
32            OfText: &anthropic.BetaTextBlockParam{
33                Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
34            },
35        }, nil
36    },
37)
38if err != nil {
39    log.Fatal(err)
40}
41 
42// Create a tool runner that handles the conversation loop automatically
43runner := client.Beta.Messages.NewToolRunner(
44    []anthropic.BetaTool{weatherTool},
45    anthropic.BetaToolRunnerParams{
46        BetaMessageNewParams: anthropic.BetaMessageNewParams{
47            Model:     anthropic.ModelClaudeOpus4_8,
48            MaxTokens: 16000,
49            Messages: []anthropic.BetaMessageParam{
50                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
51            },
52        },
53        MaxIterations: 5,
54    },
55)
56 
57// Run until Claude produces a final response
58message, err := runner.RunToCompletion(context.Background())
59if err != nil {
60    log.Fatal(err)
61}
62 
63// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
64// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock,
65// not TextBlock):
66for _, block := range message.Content {
67    switch block := block.AsAny().(type) {
68    case anthropic.BetaTextBlock:
69        fmt.Println(block.Text)
70    }
71}
72```
73 
74**Key features of the Go tool runner:**
75 
76- Automatic schema generation from Go structs via `jsonschema` tags
77- `RunToCompletion()` for simple one-shot usage
78- `All()` iterator for processing each message in the conversation
79- `NextMessage()` for step-by-step iteration
80- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()`
81 
82### Manual Loop
83 
84For 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.
85 
86Derived from `anthropic-sdk-go/examples/tools/main.go`.
87 
88```go
89package main
90 
91import (
92    "context"
93    "encoding/json"
94    "fmt"
95    "log"
96 
97    "github.com/anthropics/anthropic-sdk-go"
98)
99 
100func main() {
101    client := anthropic.NewClient()
102 
103    // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
104    addTool := anthropic.ToolParam{
105        Name:        "add",
106        Description: anthropic.String("Add two integers"),
107        InputSchema: anthropic.ToolInputSchemaParam{
108            Properties: map[string]any{
109                "a": map[string]any{"type": "integer"},
110                "b": map[string]any{"type": "integer"},
111            },
112        },
113    }
114    // ToolParam must be wrapped in ToolUnionParam for the Tools slice
115    tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
116 
117    messages := []anthropic.MessageParam{
118        anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
119    }
120 
121    for {
122        resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
123            Model:     anthropic.ModelClaudeSonnet4_6,
124            MaxTokens: 16000,
125            Messages:  messages,
126            Tools:     tools,
127        })
128        if err != nil {
129            log.Fatal(err)
130        }
131 
132        // 2. Append the assistant response to history BEFORE processing tool calls.
133        //    resp.ToParam() converts Message → MessageParam in one call.
134        messages = append(messages, resp.ToParam())
135 
136        // 3. Walk content blocks. ContentBlockUnion is a flattened struct;
137        //    use block.AsAny().(type) to switch on the actual variant.
138        toolResults := []anthropic.ContentBlockParamUnion{}
139        for _, block := range resp.Content {
140            switch variant := block.AsAny().(type) {
141            case anthropic.TextBlock:
142                fmt.Println(variant.Text)
143            case anthropic.ToolUseBlock:
144                // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
145                //    raw JSON — block.Input is json.RawMessage, not the parsed value.
146                var in struct {
147                    A int `json:"a"`
148                    B int `json:"b"`
149                }
150                if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
151                    log.Fatal(err)
152                }
153                result := fmt.Sprintf("%d", in.A+in.B)
154                // 5. NewToolResultBlock(toolUseID, content, isError) builds the
155                //    ContentBlockParamUnion for you. block.ID is the tool_use_id.
156                toolResults = append(toolResults,
157                    anthropic.NewToolResultBlock(block.ID, result, false))
158            }
159        }
160 
161        // 6. Exit when Claude stops asking for tools
162        if resp.StopReason != anthropic.StopReasonToolUse {
163            break
164        }
165 
166        // 7. Tool results go in a user message (variadic: all results in one turn)
167        messages = append(messages, anthropic.NewUserMessage(toolResults...))
168    }
169}
170```
171 
172**Key API surface:**
173 
174| Symbol | Purpose |
175|---|---|
176| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history |
177| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants |
178| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) |
179| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block |
180| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn |
181| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination |
182| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` |
183 
184---
185 
186## Anthropic-Defined Tools
187 
188Version-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. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally — see `shared/tool-use-concepts.md`).
189 
190```go
191Tools: []anthropic.ToolUnionParam{
192    {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
193    {OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
194    {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
195    {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
196},
197```
198 
199Also available: `WebFetchTool20260209Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. For the advisor and memory tools, use `BetaAdvisorTool20260301Param` / `BetaMemoryTool20250818Param` in the beta namespace on `client.Beta.Messages.New`.
200 
201### Advisor tool (beta)
202 
203Server-side — no tool_result round-trip. The advisor model must be ≥ the executor (top-level) model; invalid pairs return 400.
204 
205```go
206response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
207    Model:     anthropic.ModelClaudeSonnet4_6,
208    MaxTokens: 4096,
209    Tools: []anthropic.BetaToolUnionParam{
210        {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
211            Model: anthropic.ModelClaudeOpus4_8,
212        }},
213    },
214    Messages: []anthropic.BetaMessageParam{ /* ... */ },
215    Betas:    []anthropic.AnthropicBeta{anthropic.AnthropicBetaAdvisorTool2026_03_01},
216})
217```
218 
219---
220 
221