CLI, SDK e librerieSDK client

SDK Go

Installa e configura l'SDK Go di Anthropic con cancellazione basata su context e opzioni funzionali

La libreria Go di Anthropic fornisce un accesso comodo all'API REST di Anthropic da applicazioni scritte in Go.

Per la documentazione delle funzionalità dell'API con esempi di codice, consulta il riferimento API. Questa pagina copre le funzionalità e la configurazione dell'SDK specifiche per Go.

Installazione

import (
	"github.com/anthropics/anthropic-sdk-go" // imported as anthropic
)

Installa con go get:

go get github.com/anthropics/anthropic-sdk-go

Requisiti

Questa libreria richiede Go 1.23+.

Utilizzo

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.ModelClaudeOpus5,
	})
	if err != nil {
		panic(err.Error())
	}
	for _, block := range message.Content {
		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
			fmt.Println(textBlock.Text)
		}
	}
}

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione.

Campi della richiesta

La libreria anthropic utilizza la semantica omitzero della release encoding/json di Go 1.24+ per i campi della richiesta.

I campi primitivi obbligatori (int64, string, ecc.) presentano il tag `json:"...,required"`. Questi campi vengono sempre serializzati, anche i loro valori zero.

I tipi primitivi opzionali sono racchiusi in un param.Opt[T]. Questi campi possono essere impostati con i costruttori forniti, anthropic.String(string), anthropic.Int(int64), ecc.

Qualsiasi param.Opt[T], map, slice, struct o string enum utilizza il tag `json:"...,omitzero"`. Il suo valore zero è considerato omesso.

La funzione param.IsOmitted(any) può confermare la presenza di qualsiasi campo omitzero.

p := anthropic.ExampleParams{
	ID:   "id_xxx",                // required property
	Name: anthropic.String("..."), // optional property

	Point: anthropic.Point{
		X: 0,                // required field will serialize as 0
		Y: anthropic.Int(1), // optional field will serialize as 1
		// ... i campi non obbligatori omessi non verranno serializzati
	},

	Origin: anthropic.Origin{}, // the zero value of [Origin] is considered omitted
}

Per inviare null invece di un param.Opt[T], usa param.Null[T](). Per inviare null invece di una struct T, usa param.NullStruct[T]().

p.Name = param.Null[string]()       // 'null' instead of string
p.Point = param.NullStruct[Point]() // 'null' instead of struct

param.IsNull(p.Name)  // true
param.IsNull(p.Point) // true

Le struct di richiesta contengono un metodo .SetExtraFields(map[string]any) che può inviare campi non conformi nel corpo della richiesta. I campi extra sovrascrivono qualsiasi campo della struct con una chiave corrispondente.

Per motivi di sicurezza, usa SetExtraFields solo con dati attendibili.

Per inviare un valore personalizzato invece di una struct, usa la funzione generica param.Override (ad esempio, param.Override[anthropic.FooParams](12)).

// Nei casi in cui l'API specifica un determinato tipo,
// ma vuoi inviare qualcos'altro, usa [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Invia un numero invece di un oggetto
custom := param.Override[anthropic.FooParams](12)

Union nelle richieste

Le union sono rappresentate come una struct con campi prefissati da "Of" per ciascuna delle sue varianti, solo un campo può essere diverso da zero. Il campo diverso da zero verrà serializzato.

Le sottoproprietà della union sono accessibili tramite metodi sulla struct della union. Questi metodi restituiscono un puntatore mutabile ai dati sottostanti, se presenti.

// Solo un campo può essere diverso da zero, usa param.IsOmitted() per verificare se un campo è impostato
type AnimalUnionParam struct {
	OfCat *Cat `json:",omitzero,inline"`
	OfDog *Dog `json:",omitzero,inline"`
}

animal := AnimalUnionParam{
	OfCat: &Cat{
		Name: "Whiskers",
		Owner: PersonParam{
			Address: AddressParam{Street: "3333 Coyote Hill Rd", ZipCode: 0},
		},
	},
}

// Modifica di un campo
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Deserializzazione dei param

param.SetJSON richiede l'SDK v1.20.0 o successivo.

I tipi param (tipi che terminano in Param, come MessageNewParams o ToolUnionParam) sono progettati solo per le richieste in uscita. Vengono serializzati correttamente in JSON ma non supportano completamente la deserializzazione round-trip. Se deserializzi JSON grezzo in una struct param, i campi union tipizzati come OfBashTool20250124 saranno nil anche quando il JSON sottostante è valido.

Se hai bisogno di ricostruire i param da JSON grezzo (ad esempio, da un database, un middleware o una richiesta precedente), chiama UnmarshalJSON per popolare i campi non-union, quindi usa param.SetJSON per allegare i byte grezzi per una corretta ri-serializzazione:

// Serializza i parametri (ad esempio, per l'archiviazione o l'inoltro)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// In seguito, ricostruisci i parametri dal JSON memorizzato
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model e gli altri campi scalari vengono popolati da UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 è nil (la limitazione delle union),
// ma il JSON grezzo viene preservato. Quando params viene nuovamente serializzato
// per la chiamata API, gli strumenti vengono serializzati correttamente.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Per questo caso d'uso, param.SetJSON (disponibile dalla v1.20.0) è preferibile rispetto al più generale param.Override[T](any) perché non richiede di specificare il parametro di tipo e rende esplicito l'intento di round-trip.

Oggetti di risposta

Tutti i campi nelle struct di risposta sono normali tipi valore (non puntatori o wrapper). Le struct di risposta includono anche un campo speciale JSON contenente metadati su ciascuna proprietà.

type Animal struct {
	Name   string `json:"name,nullable"`
	Owners int    `json:"owners"`
	Age    int    `json:"age"`
	JSON   struct {
		Name        respjson.Field
		Owners      respjson.Field
		Age         respjson.Field
		ExtraFields map[string]respjson.Field
	} `json:"-"`
}

Per gestire i dati opzionali, usa il metodo .Valid() sul campo JSON. .Valid() restituisce true quando il campo è presente, non-null ed è stato deserializzato con successo.

Se .Valid() è false, il campo corrispondente avrà il suo valore zero.

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// Accesso ai campi normali

res.Owners // 1
res.Name   // ""
res.Age    // 0

// Controlli sui campi opzionali

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid()   // false
res.JSON.Age.Valid()    // false

// Valori JSON grezzi

res.JSON.Owners.Raw()                  // "1"
res.JSON.Name.Raw() == "null"          // true
res.JSON.Name.Raw() == respjson.Null   // true
res.JSON.Age.Raw() == ""               // true
res.JSON.Age.Raw() == respjson.Omitted // true

Queste struct .JSON includono anche una map ExtraFields contenente qualsiasi proprietà nella risposta json che non è stata specificata nella struct. Questo può essere utile per funzionalità dell'API non ancora presenti nell'SDK.

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

Union nelle risposte

Nelle risposte, le union sono rappresentate da una struct appiattita contenente tutti i campi possibili di ciascuna delle varianti dell'oggetto. Per convertirla in una variante usa il metodo .AsFooVariant() o il metodo .AsAny() se presente.

Se una union di valori di risposta contiene valori primitivi, i campi primitivi saranno accanto alle proprietà ma prefissati con Of e presenteranno il tag json:"...,inline".

type AnimalUnion struct {
	// Dalle varianti [Dog], [Cat]
	Owner Person `json:"owner"`
	// Dalla variante [Dog]
	DogBreed string `json:"dog_breed"`
	// Dalla variante [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

	JSON struct {
		Owner respjson.Field
		// ...
	} `json:"-"`
}

// Se variante animale
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Switch sulla variante
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Gestione degli errori

Quando l'API restituisce un codice di stato non di successo, l'SDK restituisce un errore di tipo *anthropic.Error. Questo contiene i valori StatusCode, *http.Request e *http.Response della richiesta, così come il JSON del corpo dell'errore (proprio come gli altri oggetti di risposta nell'SDK). L'errore include anche il RequestID dagli header della risposta, che è utile per la risoluzione dei problemi con il supporto di Anthropic.

Per gestire gli errori, usa il pattern errors.As:

_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{{
		Content: []anthropic.ContentBlockParamUnion{{
			OfText: &anthropic.TextBlockParam{
				Text: "What is a quaternion?",
			},
		}},
		Role: anthropic.MessageParamRoleUser,
	}},
	Model: anthropic.ModelClaudeOpus5,
})
if err != nil {
	var apierr *anthropic.Error
	if errors.As(err, &apierr) {
		println("Request ID:", apierr.RequestID)
		println(string(apierr.DumpRequest(true)))  // Prints the serialized HTTP request
		println(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response
	}
	panic(err.Error()) // POST "/v1/messages": 400 Bad Request (Request-ID: req_xxx) { ... }
}

Quando si verificano altri errori, vengono restituiti senza wrapping; ad esempio, se il trasporto HTTP fallisce, potresti ricevere *url.Error che racchiude *net.OpError.

Tentativi ripetuti

Alcuni errori verranno automaticamente ritentati 2 volte per impostazione predefinita, con un breve backoff esponenziale. L'SDK ritenta per impostazione predefinita tutti gli errori di connessione, 408 Request Timeout, 409 Conflict, 429 Rate Limit e gli errori interni >=500.

Puoi usare l'opzione WithMaxRetries per configurare o disabilitare questo comportamento:

// Configura il valore predefinito per tutte le richieste:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Sovrascrivi per singola richiesta:
// ...
	client.Messages.New(
		context.TODO(),
		anthropic.MessageNewParams{
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{{
				Content: []anthropic.ContentBlockParamUnion{{
					OfText: &anthropic.TextBlockParam{
						Text: "What is a quaternion?",
					},
				}},
				Role: anthropic.MessageParamRoleUser,
			}},
			Model: anthropic.ModelClaudeOpus5,
		},
		option.WithMaxRetries(5),
	)

Timeout

Le richieste Messages non in streaming vanno in timeout dopo 10 minuti per impostazione predefinita; le altre richieste non hanno un timeout predefinito. Usa il context per configurare un timeout per il ciclo di vita di una richiesta.

Nota che se una richiesta viene ritentata, il timeout del context non riparte da capo. Per impostare un timeout per ogni tentativo, usa option.WithRequestTimeout().

// Questo imposta il timeout per la richiesta, inclusi tutti i tentativi.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
// ...
	client.Messages.New(
		ctx,
		anthropic.MessageNewParams{
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{{
				Content: []anthropic.ContentBlockParamUnion{{
					OfText: &anthropic.TextBlockParam{
						Text: "What is a quaternion?",
					},
				}},
				Role: anthropic.MessageParamRoleUser,
			}},
			Model: anthropic.ModelClaudeOpus5,
		},
		// Questo imposta il timeout per ogni tentativo
		option.WithRequestTimeout(20*time.Second),
	)

Richieste lunghe

Considera l'uso dell'API Messages in streaming per le richieste di lunga durata.

Evita di impostare un valore MaxTokens elevato senza usare lo streaming, poiché alcune reti potrebbero interrompere le connessioni inattive dopo un certo periodo di tempo, il che può causare il fallimento della richiesta o il timeout senza ricevere una risposta da Anthropic.

Questo SDK restituirà anche un errore se si prevede che una richiesta non in streaming duri più di circa 10 minuti. Chiamare .Messages.NewStreaming() o impostare un timeout personalizzato disabilita questo errore.

Caricamento di file

I parametri di richiesta che corrispondono a caricamenti di file nelle richieste multipart sono tipizzati come io.Reader. Il contenuto dell'io.Reader verrà inviato per impostazione predefinita come parte di un form multipart con il nome file "anonymous_file" e content-type "application/octet-stream", quindi l'approccio consigliato è specificare un content-type personalizzato con l'helper anthropic.File(reader io.Reader, filename string, contentType string), che racchiude qualsiasi io.Reader con il nome file e il content type appropriati.

// Un file dal file system
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Un file da una stringa
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

Il nome del file e il content-type possono anche essere personalizzati implementando Name() string o ContentType() string sul tipo run-time di io.Reader. Nota che os.File implementa Name() string, quindi un file restituito da os.Open verrà inviato con il nome del file su disco.

Paginazione

Questa libreria fornisce alcune comodità per lavorare con gli endpoint di elenco paginati.

Puoi usare i metodi .ListAutoPaging() per iterare sugli elementi attraverso tutte le pagine:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Recupera automaticamente altre pagine secondo necessità.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Oppure puoi usare i semplici metodi .List() per recuperare una singola pagina e ricevere un oggetto di risposta standard con metodi helper aggiuntivi come .GetNextPage():

page, err := client.Messages.Batches.List(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
for page != nil {
	for _, batch := range page.Data {
		fmt.Printf("%+v\n", batch)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	panic(err.Error())
}

RequestOptions

Questa libreria utilizza il pattern delle opzioni funzionali. Le funzioni definite nel pacchetto option restituiscono una RequestOption, che è una closure che modifica una RequestConfig. Queste opzioni possono essere fornite al client o a singole richieste. Ad esempio:

client := anthropic.NewClient(
	// Aggiunge un header a ogni richiesta effettuata dal client
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Sovrascrivi l'header
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Aggiungi un campo non documentato al corpo della richiesta, usando la sintassi sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

L'opzione di richiesta option.WithDebugLog(nil) può essere utile durante il debug.

Consulta l'elenco completo delle opzioni di richiesta.

Personalizzazione del client HTTP

Per il middleware delle richieste (option.WithMiddleware) e la sostituzione dell'http.Client predefinito (option.WithHTTPClient), consulta Middleware SDK.

Integrazioni con le piattaforme

Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta:

L'SDK Go supporta le seguenti piattaforme:

Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Usa vertex.WithGoogleAuth(ctx, region, projectID) o vertex.WithCredentials(ctx, region, projectID, creds).
Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Usa bedrock.NewMantleClient per l'endpoint Bedrock dell'API Messages (streaming tramite SSE), oppure bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (percorso bedrock-runtime). L'importazione del pacchetto bedrock registra globalmente un decoder per application/vnd.amazon.eventstream con il livello di streaming dell'SDK (tramite l'init() del pacchetto). Questo si applica sia che tu usi il percorso bedrock-runtime WithConfig/WithLoadDefaultConfig sia NewMantleClient.
Claude Platform su AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Usa anthropicaws.NewClient(ctx, cfg) con un valore anthropicaws.ClientConfig per costruire un client; imposta WorkspaceID nella configurazione o la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID. L'alias di importazione anthropicaws evita una collisione di nomi con github.com/aws/aws-sdk-go-v2/aws quando entrambi vengono importati. Disponibile in beta.
Foundry: Attualmente non supportato nell'SDK Go. Consulta Claude in Microsoft Foundry per gli SDK supportati.

Usa bedrock.NewMantleClient per i nuovi progetti; bedrock.WithLoadDefaultConfig/WithConfig rimangono per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

Utilizzo avanzato

Accesso ai dati grezzi della risposta (ad esempio, gli header della risposta)

Puoi accedere ai dati grezzi della risposta HTTP usando l'opzione di richiesta option.WithResponseInto(). Questo è utile quando hai bisogno di esaminare gli header della risposta, i codici di stato o altri dettagli.

// Crea una variabile per memorizzare la risposta HTTP
var response *http.Response
message, err := client.Messages.New(
	context.TODO(),
	anthropic.MessageNewParams{
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{{
			Content: []anthropic.ContentBlockParamUnion{{
				OfText: &anthropic.TextBlockParam{
					Text: "What is a quaternion?",
				},
			}},
			Role: anthropic.MessageParamRoleUser,
		}},
		Model: anthropic.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// gestisci l'errore
}
fmt.Printf("%+v\n", message)

fmt.Printf("Status Code: %d\n", response.StatusCode)
fmt.Printf("Headers: %+#v\n", response.Header)

Effettuare richieste personalizzate/non documentate

Questa libreria è tipizzata per un accesso comodo all'API documentata. Se hai bisogno di accedere a endpoint, parametri o proprietà di risposta non documentati, la libreria può comunque essere utilizzata.

Endpoint non documentati

Per effettuare richieste a endpoint non documentati, puoi usare client.Get, client.Post e altri verbi HTTP. Le RequestOptions sul client, come i tentativi ripetuti, verranno rispettate quando si effettuano queste richieste.

var (
	// params può essere un io.Reader, un []byte, un oggetto serializzabile con encoding/json,
	// oppure una struct "...Params" definita in questa libreria.
	params map[string]any

	// result può essere un []byte, un *http.Response, un oggetto deserializzabile con encoding/json,
	// oppure un modello definito in questa libreria.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Parametri di richiesta non documentati

Per effettuare richieste usando parametri non documentati, puoi usare i metodi option.WithQuerySet() o option.WithJSONSet().

params := FooNewParams{
	ID: "id_xxxx",
	Data: FooNewParamsData{
		FirstName: anthropic.String("John"),
	},
}
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))

Proprietà di risposta non documentate

Per accedere a proprietà di risposta non documentate, puoi accedere al JSON grezzo della risposta come stringa con result.JSON.RawJSON(), oppure ottenere il JSON grezzo di un particolare campo sul risultato con result.JSON.Foo.Raw().

Tutti i campi che non sono presenti nella struct di risposta vengono salvati e sono accessibili tramite result.JSON.ExtraFields, che è una map[string]respjson.Field.

Versionamento semantico

Questo pacchetto segue generalmente le convenzioni SemVer, anche se alcune modifiche non retrocompatibili potrebbero essere rilasciate come versioni minori:

Modifiche agli interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per l'uso esterno.
Modifiche che non ci si aspetta abbiano un impatto sulla stragrande maggioranza degli utenti nella pratica.

La retrocompatibilità è presa sul serio per garantire che tu possa contare su un'esperienza di aggiornamento senza problemi.

Il tuo feedback è benvenuto; apri una issue con domande, bug o suggerimenti.

Risorse aggiuntive

Was this page helpful?

CLI, SDK e librerieSDK client

SDK Go

Installa e configura l'SDK Go di Anthropic con cancellazione basata su context e opzioni funzionali

La libreria Go di Anthropic fornisce un accesso comodo all'API REST di Anthropic da applicazioni scritte in Go.

Per la documentazione delle funzionalità dell'API con esempi di codice, consulta il riferimento API. Questa pagina copre le funzionalità e la configurazione dell'SDK specifiche per Go.

Installazione

import (
	"github.com/anthropics/anthropic-sdk-go" // imported as anthropic
)

Installa con go get:

go get github.com/anthropics/anthropic-sdk-go

Requisiti

Questa libreria richiede Go 1.23+.

Utilizzo

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.ModelClaudeOpus5,
	})
	if err != nil {
		panic(err.Error())
	}
	for _, block := range message.Content {
		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
			fmt.Println(textBlock.Text)
		}
	}
}

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione.

Campi della richiesta

La libreria anthropic utilizza la semantica omitzero della release encoding/json di Go 1.24+ per i campi della richiesta.

I campi primitivi obbligatori (int64, string, ecc.) presentano il tag `json:"...,required"`. Questi campi vengono sempre serializzati, anche i loro valori zero.

I tipi primitivi opzionali sono racchiusi in un param.Opt[T]. Questi campi possono essere impostati con i costruttori forniti, anthropic.String(string), anthropic.Int(int64), ecc.

Qualsiasi param.Opt[T], map, slice, struct o string enum utilizza il tag `json:"...,omitzero"`. Il suo valore zero è considerato omesso.

La funzione param.IsOmitted(any) può confermare la presenza di qualsiasi campo omitzero.

p := anthropic.ExampleParams{
	ID:   "id_xxx",                // required property
	Name: anthropic.String("..."), // optional property

	Point: anthropic.Point{
		X: 0,                // required field will serialize as 0
		Y: anthropic.Int(1), // optional field will serialize as 1
		// ... i campi non obbligatori omessi non verranno serializzati
	},

	Origin: anthropic.Origin{}, // the zero value of [Origin] is considered omitted
}

Per inviare null invece di un param.Opt[T], usa param.Null[T](). Per inviare null invece di una struct T, usa param.NullStruct[T]().

p.Name = param.Null[string]()       // 'null' instead of string
p.Point = param.NullStruct[Point]() // 'null' instead of struct

param.IsNull(p.Name)  // true
param.IsNull(p.Point) // true

Per motivi di sicurezza, usa SetExtraFields solo con dati attendibili.

Per inviare un valore personalizzato invece di una struct, usa la funzione generica param.Override (ad esempio, param.Override[anthropic.FooParams](12)).

// Nei casi in cui l'API specifica un determinato tipo,
// ma vuoi inviare qualcos'altro, usa [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Invia un numero invece di un oggetto
custom := param.Override[anthropic.FooParams](12)

Union nelle richieste

Le union sono rappresentate come una struct con campi prefissati da "Of" per ciascuna delle sue varianti, solo un campo può essere diverso da zero. Il campo diverso da zero verrà serializzato.

Le sottoproprietà della union sono accessibili tramite metodi sulla struct della union. Questi metodi restituiscono un puntatore mutabile ai dati sottostanti, se presenti.

// Solo un campo può essere diverso da zero, usa param.IsOmitted() per verificare se un campo è impostato
type AnimalUnionParam struct {
	OfCat *Cat `json:",omitzero,inline"`
	OfDog *Dog `json:",omitzero,inline"`
}

animal := AnimalUnionParam{
	OfCat: &Cat{
		Name: "Whiskers",
		Owner: PersonParam{
			Address: AddressParam{Street: "3333 Coyote Hill Rd", ZipCode: 0},
		},
	},
}

// Modifica di un campo
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Deserializzazione dei param

param.SetJSON richiede l'SDK v1.20.0 o successivo.

// Serializza i parametri (ad esempio, per l'archiviazione o l'inoltro)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// In seguito, ricostruisci i parametri dal JSON memorizzato
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model e gli altri campi scalari vengono popolati da UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 è nil (la limitazione delle union),
// ma il JSON grezzo viene preservato. Quando params viene nuovamente serializzato
// per la chiamata API, gli strumenti vengono serializzati correttamente.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Oggetti di risposta

Tutti i campi nelle struct di risposta sono normali tipi valore (non puntatori o wrapper). Le struct di risposta includono anche un campo speciale JSON contenente metadati su ciascuna proprietà.

type Animal struct {
	Name   string `json:"name,nullable"`
	Owners int    `json:"owners"`
	Age    int    `json:"age"`
	JSON   struct {
		Name        respjson.Field
		Owners      respjson.Field
		Age         respjson.Field
		ExtraFields map[string]respjson.Field
	} `json:"-"`
}

Per gestire i dati opzionali, usa il metodo .Valid() sul campo JSON. .Valid() restituisce true quando il campo è presente, non-null ed è stato deserializzato con successo.

Se .Valid() è false, il campo corrispondente avrà il suo valore zero.

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// Accesso ai campi normali

res.Owners // 1
res.Name   // ""
res.Age    // 0

// Controlli sui campi opzionali

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid()   // false
res.JSON.Age.Valid()    // false

// Valori JSON grezzi

res.JSON.Owners.Raw()                  // "1"
res.JSON.Name.Raw() == "null"          // true
res.JSON.Name.Raw() == respjson.Null   // true
res.JSON.Age.Raw() == ""               // true
res.JSON.Age.Raw() == respjson.Omitted // true

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

Union nelle risposte

Se una union di valori di risposta contiene valori primitivi, i campi primitivi saranno accanto alle proprietà ma prefissati con Of e presenteranno il tag json:"...,inline".

type AnimalUnion struct {
	// Dalle varianti [Dog], [Cat]
	Owner Person `json:"owner"`
	// Dalla variante [Dog]
	DogBreed string `json:"dog_breed"`
	// Dalla variante [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

	JSON struct {
		Owner respjson.Field
		// ...
	} `json:"-"`
}

// Se variante animale
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Switch sulla variante
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Gestione degli errori

Per gestire gli errori, usa il pattern errors.As:

_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{{
		Content: []anthropic.ContentBlockParamUnion{{
			OfText: &anthropic.TextBlockParam{
				Text: "What is a quaternion?",
			},
		}},
		Role: anthropic.MessageParamRoleUser,
	}},
	Model: anthropic.ModelClaudeOpus5,
})
if err != nil {
	var apierr *anthropic.Error
	if errors.As(err, &apierr) {
		println("Request ID:", apierr.RequestID)
		println(string(apierr.DumpRequest(true)))  // Prints the serialized HTTP request
		println(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response
	}
	panic(err.Error()) // POST "/v1/messages": 400 Bad Request (Request-ID: req_xxx) { ... }
}

Quando si verificano altri errori, vengono restituiti senza wrapping; ad esempio, se il trasporto HTTP fallisce, potresti ricevere *url.Error che racchiude *net.OpError.

Tentativi ripetuti

Puoi usare l'opzione WithMaxRetries per configurare o disabilitare questo comportamento:

// Configura il valore predefinito per tutte le richieste:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Sovrascrivi per singola richiesta:
// ...
	client.Messages.New(
		context.TODO(),
		anthropic.MessageNewParams{
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{{
				Content: []anthropic.ContentBlockParamUnion{{
					OfText: &anthropic.TextBlockParam{
						Text: "What is a quaternion?",
					},
				}},
				Role: anthropic.MessageParamRoleUser,
			}},
			Model: anthropic.ModelClaudeOpus5,
		},
		option.WithMaxRetries(5),
	)

Timeout

Nota che se una richiesta viene ritentata, il timeout del context non riparte da capo. Per impostare un timeout per ogni tentativo, usa option.WithRequestTimeout().

// Questo imposta il timeout per la richiesta, inclusi tutti i tentativi.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
// ...
	client.Messages.New(
		ctx,
		anthropic.MessageNewParams{
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{{
				Content: []anthropic.ContentBlockParamUnion{{
					OfText: &anthropic.TextBlockParam{
						Text: "What is a quaternion?",
					},
				}},
				Role: anthropic.MessageParamRoleUser,
			}},
			Model: anthropic.ModelClaudeOpus5,
		},
		// Questo imposta il timeout per ogni tentativo
		option.WithRequestTimeout(20*time.Second),
	)

Richieste lunghe

Considera l'uso dell'API Messages in streaming per le richieste di lunga durata.

Caricamento di file

// Un file dal file system
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Un file da una stringa
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

Paginazione

Questa libreria fornisce alcune comodità per lavorare con gli endpoint di elenco paginati.

Puoi usare i metodi .ListAutoPaging() per iterare sugli elementi attraverso tutte le pagine:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Recupera automaticamente altre pagine secondo necessità.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Oppure puoi usare i semplici metodi .List() per recuperare una singola pagina e ricevere un oggetto di risposta standard con metodi helper aggiuntivi come .GetNextPage():

page, err := client.Messages.Batches.List(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
for page != nil {
	for _, batch := range page.Data {
		fmt.Printf("%+v\n", batch)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	panic(err.Error())
}

RequestOptions

client := anthropic.NewClient(
	// Aggiunge un header a ogni richiesta effettuata dal client
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Sovrascrivi l'header
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Aggiungi un campo non documentato al corpo della richiesta, usando la sintassi sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

L'opzione di richiesta option.WithDebugLog(nil) può essere utile durante il debug.

Consulta l'elenco completo delle opzioni di richiesta.

Personalizzazione del client HTTP

Per il middleware delle richieste (option.WithMiddleware) e la sostituzione dell'http.Client predefinito (option.WithHTTPClient), consulta Middleware SDK.

Integrazioni con le piattaforme

Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta:

L'SDK Go supporta le seguenti piattaforme:

Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Usa vertex.WithGoogleAuth(ctx, region, projectID) o vertex.WithCredentials(ctx, region, projectID, creds).
Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Usa bedrock.NewMantleClient per l'endpoint Bedrock dell'API Messages (streaming tramite SSE), oppure bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (percorso bedrock-runtime). L'importazione del pacchetto bedrock registra globalmente un decoder per application/vnd.amazon.eventstream con il livello di streaming dell'SDK (tramite l'init() del pacchetto). Questo si applica sia che tu usi il percorso bedrock-runtime WithConfig/WithLoadDefaultConfig sia NewMantleClient.
Claude Platform su AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Usa anthropicaws.NewClient(ctx, cfg) con un valore anthropicaws.ClientConfig per costruire un client; imposta WorkspaceID nella configurazione o la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID. L'alias di importazione anthropicaws evita una collisione di nomi con github.com/aws/aws-sdk-go-v2/aws quando entrambi vengono importati. Disponibile in beta.
Foundry: Attualmente non supportato nell'SDK Go. Consulta Claude in Microsoft Foundry per gli SDK supportati.

Usa bedrock.NewMantleClient per i nuovi progetti; bedrock.WithLoadDefaultConfig/WithConfig rimangono per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

Utilizzo avanzato

Accesso ai dati grezzi della risposta (ad esempio, gli header della risposta)

// Crea una variabile per memorizzare la risposta HTTP
var response *http.Response
message, err := client.Messages.New(
	context.TODO(),
	anthropic.MessageNewParams{
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{{
			Content: []anthropic.ContentBlockParamUnion{{
				OfText: &anthropic.TextBlockParam{
					Text: "What is a quaternion?",
				},
			}},
			Role: anthropic.MessageParamRoleUser,
		}},
		Model: anthropic.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// gestisci l'errore
}
fmt.Printf("%+v\n", message)

fmt.Printf("Status Code: %d\n", response.StatusCode)
fmt.Printf("Headers: %+#v\n", response.Header)

Effettuare richieste personalizzate/non documentate

Endpoint non documentati

var (
	// params può essere un io.Reader, un []byte, un oggetto serializzabile con encoding/json,
	// oppure una struct "...Params" definita in questa libreria.
	params map[string]any

	// result può essere un []byte, un *http.Response, un oggetto deserializzabile con encoding/json,
	// oppure un modello definito in questa libreria.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Parametri di richiesta non documentati

Per effettuare richieste usando parametri non documentati, puoi usare i metodi option.WithQuerySet() o option.WithJSONSet().

params := FooNewParams{
	ID: "id_xxxx",
	Data: FooNewParamsData{
		FirstName: anthropic.String("John"),
	},
}
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))

Proprietà di risposta non documentate

Tutti i campi che non sono presenti nella struct di risposta vengono salvati e sono accessibili tramite result.JSON.ExtraFields, che è una map[string]respjson.Field.

Versionamento semantico

Questo pacchetto segue generalmente le convenzioni SemVer, anche se alcune modifiche non retrocompatibili potrebbero essere rilasciate come versioni minori:

Modifiche agli interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per l'uso esterno.
Modifiche che non ci si aspetta abbiano un impatto sulla stragrande maggioranza degli utenti nella pratica.

La retrocompatibilità è presa sul serio per garantire che tu possa contare su un'esperienza di aggiornamento senza problemi.

Il tuo feedback è benvenuto; apri una issue con domande, bug o suggerimenti.

Risorse aggiuntive

Was this page helpful?

Installazione

Requisiti

Utilizzo

Conversations

System prompts

Streaming

Tool calling

Campi della richiesta

Union nelle richieste

Deserializzazione dei param

Oggetti di risposta

Union nelle risposte

Gestione degli errori

Tentativi ripetuti

Timeout

Richieste lunghe

Caricamento di file

Paginazione

RequestOptions

Personalizzazione del client HTTP

Integrazioni con le piattaforme

Utilizzo avanzato

Accesso ai dati grezzi della risposta (ad esempio, gli header della risposta)

Effettuare richieste personalizzate/non documentate

Endpoint non documentati

Parametri di richiesta non documentati

Proprietà di risposta non documentate

Versionamento semantico

Risorse aggiuntive

Installazione

Requisiti

Utilizzo

Conversations

System prompts

Streaming

Tool calling

Campi della richiesta

Union nelle richieste

Deserializzazione dei param

Oggetti di risposta

Union nelle risposte

Gestione degli errori

Tentativi ripetuti

Timeout

Richieste lunghe

Caricamento di file

Paginazione

RequestOptions

Personalizzazione del client HTTP

Integrazioni con le piattaforme

Utilizzo avanzato

Accesso ai dati grezzi della risposta (ad esempio, gli header della risposta)

Effettuare richieste personalizzate/non documentate

Endpoint non documentati

Parametri di richiesta non documentati

Proprietà di risposta non documentate

Versionamento semantico

Risorse aggiuntive

Installazione

Requisiti

Utilizzo

Campi della richiesta

Union nelle richieste

Deserializzazione dei param

Oggetti di risposta

Union nelle risposte

Gestione degli errori

Tentativi ripetuti

Timeout

Richieste lunghe

Caricamento di file

Paginazione

RequestOptions

Personalizzazione del client HTTP

Integrazioni con le piattaforme

Utilizzo avanzato

Accesso ai dati grezzi della risposta (ad esempio, gli header della risposta)

Effettuare richieste personalizzate/non documentate

Endpoint non documentati

Parametri di richiesta non documentati

Proprietà di risposta non documentate

Versionamento semantico

Risorse aggiuntive

Installazione

Requisiti

Utilizzo

Campi della richiesta

Union nelle richieste

Deserializzazione dei param

Oggetti di risposta

Union nelle risposte

Gestione degli errori

Tentativi ripetuti

Timeout

Richieste lunghe

Caricamento di file

Paginazione

RequestOptions

Personalizzazione del client HTTP

Integrazioni con le piattaforme

Utilizzo avanzato

Accesso ai dati grezzi della risposta (ad esempio, gli header della risposta)

Effettuare richieste personalizzate/non documentate

Endpoint non documentati

Parametri di richiesta non documentati

Proprietà di risposta non documentate

Versionamento semantico

Risorse aggiuntive