Claude SDK for Go

The toolrunner package allows you to create BetaTool objects, which pair a tool's JSON schema definition with a Go handler function. The generic type of the handler is automatically inferred from its signature. There are three primary ways to define a tool:

1. Automatic Schema Generation (Recommended): Use NewBetaToolFromJSONSchema. This uses jsonschema tags on a Go struct to generate the required JSON schema.
2. JSON Bytes: Use NewBetaToolFromBytes to provide a raw JSON schema as a byte slice.
3. Explicit Schema: Use NewBetaTool to pass a BetaToolInputSchemaParam for full manual control.

If you want to handle parsing manually, you can use json.RawMessage or []byte as the input type in your handler.

type GetWeatherInput struct {
	City  string `json:"city" jsonschema:"required,description=The city name"`
	Units string `json:"units,omitempty" jsonschema:"enum=celsius,enum=fahrenheit,description=Temperature units"`
}

weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
	"get_weather",
	"Get current weather for a city",
	func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
		return anthropic.BetaToolResultBlockParamContentUnion{
			OfText: &anthropic.BetaTextBlockParam{
				Text: fmt.Sprintf("Weather in %s: 72°F, sunny", input.City),
			},
		}, nil
},
)

The BetaToolRunner manages the iterative loop between Claude and your tools. It automatically sends messages, executes tool calls in parallel, adds results back to the conversation, and repeats until Claude provides a final response.

Execution Modes

• RunToCompletion: Executes the entire loop until no more tool calls are requested.
• Iterating (All): Use runner.All(ctx) to iterate over every message generated during the conversation.
• Step-by-Step (NextMessage): Use runner.NextMessage(ctx) to advance the conversation one turn at a time for manual control.

Streaming

For real-time responses, use NewToolRunnerStreaming(). You can iterate over events using runner.AllStreaming(ctx) or step through them with runner.NextStreaming(ctx).

tools := []anthropic.BetaTool{weatherTool}

runner := client.Beta.Messages.NewToolRunner(tools, anthropic.BetaToolRunnerParams{
	BetaMessageNewParams: anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeSonnet4_5_20250929,
		MaxTokens: 1024,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Tokyo?")),
		},
	},
})

// Run the entire conversation to completion
message, err := runner.RunToCompletion(context.Background())

To use the SDK, initialize a client using anthropic.NewClient. You can provide an API key using option.WithAPIKey. If no option is provided, the client defaults to looking up the ANTHROPIC_API_KEY environment variable.

To create a message, use the client.Messages.New method, which requires a context.Context and a anthropic.MessageNewParams object. The parameters object allows you to specify MaxTokens, the Messages array (constructed using helpers like anthropic.NewUserMessage), and the Model (e.g., anthropic.ModelClaudeOpus4_6).

package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	client := anthropic.NewClient(
		option.WithAPIKey("my-anthropic-api-key"), // defaults to os.LookupEnv("ANTHROPIC_API_KEY")
	)
	message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("What is a quaternion?")),
		},
		Model: anthropic.ModelClaudeOpus4_6,
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", message.Content)
}