Getting a Client

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

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

// Reads ANTHROPIC_API_KEY from the environment.
client := anthropic.NewClient()

// Or pass it explicitly, if you load config yourself.
client := anthropic.NewClient(option.WithAPIKey(key))

Build the client once, at startup, and pass it around. It is safe for concurrent use and holds a connection pool — constructing one per request throws away keep-alive and gives you a fresh TLS handshake every time.

The First Call

resp, err := client.Messages.New(ctx, anthropic.MessageNewParams{
    Model:     "claude-opus-5",
    MaxTokens: 16000,
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("Summarise this changelog in three bullets.")),
    },
})
if err != nil {
    return fmt.Errorf("summarise changelog: %w", err)
}

Two things about that snippet are worth slowing down on.

The model is a plain string. The SDK ships typed constants (anthropic.ModelClaudeOpus4_8 and friends), but anthropic.Model is an alias for string, so a model that has no constant yet is passed as its id. Either form compiles; check the SDK release notes before assuming a constant exists for the model you want.

MaxTokens is a ceiling, not a target. It is the point at which generation is cut off mid-sentence, and the model is not told about it. Setting it to 500 because you want a short answer does not produce a short answer — it produces a truncated one. Ask for brevity in the prompt and leave the ceiling generous. For non-streaming requests, something around 16000 keeps you clear of both truncation and the SDK’s HTTP timeout.

Content Is a List of Blocks, Not a String

This is where the first hour usually goes. A response is not resp.Text. It is resp.Content, a slice of union values that can hold text, thinking, tool calls and more:

for _, block := range resp.Content {
    switch variant := block.AsAny().(type) {
    case anthropic.TextBlock:
        fmt.Println(variant.Text)
    case anthropic.ThinkingBlock:
        // Reasoning, when you have asked for it to be shown.
        log.Debug("model reasoning", "text", variant.Thinking)
    }
}

block.AsAny() is the accessor that gets you a concrete type to switch on. Reaching for resp.Content[0].Text and hoping works right up until the day a thinking block or a tool call lands in position zero, at which point you silently return an empty string. Write the type switch once, in a helper, and use it everywhere:

// firstText returns the first text block in a response, or "" if there is none.
func firstText(msg *anthropic.Message) string {
    for _, block := range msg.Content {
        if t, ok := block.AsAny().(anthropic.TextBlock); ok {
            return t.Text
        }
    }
    return ""
}

Thinking, and Why You Probably Want It On

Current Claude models can reason before answering. The recommended mode is adaptive — you do not budget tokens for it, the model decides how much thinking a given request deserves:

adaptive := anthropic.ThinkingConfigAdaptiveParam{}

params := anthropic.MessageNewParams{
    Model:     "claude-opus-5",
    MaxTokens: 16000,
    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
    Messages:  messages,
}

There is no ThinkingConfigParamOfAdaptive helper — you construct the union literal and take the address of the variant, as above. That trips people up because almost every other option in the SDK does have a constructor function.

A word of warning if you are carrying settings over from older code: the fixed thinking budget (ThinkingConfigParamOfEnabled(N)) is gone on current models and returns a 400 rather than being ignored. If you want to spend less, the lever is effort, not a token budget — and effort lives inside output_config, not at the top level of the request.

The counter-intuitive part: on the newest models, turning thinking off is not reliably a cost saving. Lower effort with thinking on generally beats thinking off, and disabling it has failure modes of its own. Leave it on and turn effort down.

Streaming

Anything a user waits for should stream. It is not just perceived speed — a long non-streaming request is also the easiest way to hit an HTTP timeout.

stream := client.Messages.NewStreaming(ctx, anthropic.MessageNewParams{
    Model:     "claude-opus-5",
    MaxTokens: 64000,
    Messages:  messages,
})

for stream.Next() {
    event := stream.Current()
    switch ev := event.AsAny().(type) {
    case anthropic.ContentBlockDeltaEvent:
        switch delta := ev.Delta.AsAny().(type) {
        case anthropic.TextDelta:
            fmt.Print(delta.Text)
        }
    }
}
if err := stream.Err(); err != nil {
    return fmt.Errorf("stream response: %w", err)
}

Two nested type switches is not the prettiest Go you will write, but the shape is stable: outer switch on the event, inner switch on the delta.

Always check stream.Err(). stream.Next() returning false means “no more events” — it does not tell you whether that was a clean finish or a dropped connection. A loop that ignores Err() will happily serve a truncated answer as if it were complete.

If you want the whole message and the incremental deltas, accumulate as you go. There is no GetFinalMessage() on the Go stream:

stream := client.Messages.NewStreaming(ctx, params)

var message anthropic.Message
for stream.Next() {
    message.Accumulate(stream.Current())
    // ... also forward the delta to the user here
}
if err := stream.Err(); err != nil {
    return err
}
// message.Content is now the complete response.

Raising MaxTokens to 64000 in the streaming example is deliberate. Timeouts stop being the binding constraint once you stream, so you can give the model room.

Streaming to a Browser

Server-sent events are the path of least resistance, and Go’s http.ResponseController makes the flushing straightforward:

func (h *Handler) stream(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("X-Accel-Buffering", "no") // stop nginx buffering the stream

    rc := http.NewResponseController(w)

    stream := h.client.Messages.NewStreaming(r.Context(), params)
    for stream.Next() {
        ev, ok := stream.Current().AsAny().(anthropic.ContentBlockDeltaEvent)
        if !ok {
            continue
        }
        delta, ok := ev.Delta.AsAny().(anthropic.TextDelta)
        if !ok {
            continue
        }

        // SSE data frames must not contain raw newlines.
        payload, _ := json.Marshal(delta.Text)
        if _, err := fmt.Fprintf(w, "data: %s\n\n", payload); err != nil {
            return // client hung up
        }
        if err := rc.Flush(); err != nil {
            return
        }
    }

    if err := stream.Err(); err != nil {
        slog.Error("llm stream failed", "err", err)
        fmt.Fprint(w, "event: error\ndata: {}\n\n")
        _ = rc.Flush()
        return
    }
    fmt.Fprint(w, "event: done\ndata: {}\n\n")
    _ = rc.Flush()
}

Three details that cost me an afternoon each:

• X-Accel-Buffering: no. Without it nginx buffers your stream and delivers the whole thing at the end, which looks exactly like streaming being broken. (Nginx has strong opinions about proxied responses generally — I ran into a related set of them in making Nginx cache cookie aware.)
• JSON-encode the delta. A model can and will emit a newline mid-sentence, and a bare newline terminates an SSE frame.
• Pass r.Context(), not context.Background(). When the user closes the tab, the request context cancels, the SDK aborts the HTTP call, and you stop paying for tokens nobody will read.

Deadlines and Cancellation

Context is not decoration here. It is the only thing standing between a slow model call and a goroutine that lives forever:

ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
defer cancel()

resp, err := client.Messages.New(ctx, params)

Set the deadline against how long the work should take, not a habit. A classification call has no business taking 90 seconds; a long agentic turn on a hard problem might legitimately run for several minutes. If you have not internalised how deadlines propagate through a call chain, understanding Golang context covers the machinery.

The corollary at shutdown: an in-flight model call is exactly the kind of long request that a naive SIGTERM handler will sever. Drain it properly — see graceful shutdown in Go web services.

Errors Worth Distinguishing

The SDK returns typed errors. Use errors.As to get at the status code rather than matching on message strings:

resp, err := client.Messages.New(ctx, params)
if err != nil {
    var apiErr *anthropic.Error
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case http.StatusTooManyRequests:
            return fmt.Errorf("rate limited: %w", ErrRetryable)
        case http.StatusBadRequest:
            // Your request is malformed. Retrying will not help.
            return fmt.Errorf("bad request to model: %w", err)
        default:
            return fmt.Errorf("model call failed (%d): %w", apiErr.StatusCode, err)
        }
    }
    // Not an API error: context cancellation, DNS, TLS, connection reset.
    return fmt.Errorf("model call failed: %w", err)
}

Wrapping with %w at each layer is what lets the HTTP boundary decide the status code without every layer needing to know about HTTP — the same pattern I laid out in error handling in Go.

The SDK already retries for you. By default it retries a couple of times on 408, 409, 429, 5xx and connection errors, with backoff. Two consequences people miss:

1. Do not add your own retry loop on top without lowering the SDK’s. Three of yours around two of its is nine attempts and a long tail of latency.
2. Wall-clock can reach timeout × (attempts + 1). Your context deadline is the real budget — set it deliberately, because the retry behaviour will happily use all of it.

A Refusal Is Not an Error

This one surprises people. If a safety classifier declines a request, you get HTTP 200 — a perfectly successful response whose StopReason says the model declined:

if resp.StopReason == anthropic.StopReasonRefusal {
    slog.Warn("model declined",
        "category", resp.StopDetails.Category,
        "explanation", resp.StopDetails.Explanation)
    return "", ErrDeclined
}

err is nil. resp.Content may hold nothing useful. Code that goes straight from if err != nil to reading Content[0] treats this as an empty answer and moves on. Check StopReason before you read content — and note the other values you care about: max_tokens means you were truncated, and tool_use means the model is waiting on you (which is a whole article of its own).

Watch the Usage Numbers

Every response carries a token accounting:

slog.Info("model call",
    "input_tokens", resp.Usage.InputTokens,
    "output_tokens", resp.Usage.OutputTokens,
    "cache_read", resp.Usage.CacheReadInputTokens,
    "cache_write", resp.Usage.CacheCreationInputTokens,
)

Log these from day one. They are the only ground truth about what a feature costs, and CacheReadInputTokens in particular is how you find out that your prompt caching silently stopped working three deploys ago — the failure mode there is not an error, just a bigger invoice. That is its own post, because it is the single biggest lever on what an LLM feature costs to run.

A structured logger pays for itself here: these are five numeric fields per call that you will want to aggregate later, which is exactly the case for structured logging with log/slog.

Checklist

• One client, built at startup, shared across handlers.
• Iterate resp.Content with a type switch; never index blindly into it.
• Adaptive thinking on; tune cost with effort, not by disabling it.
• Stream anything a human waits for, and always check stream.Err().
• r.Context() all the way down, with a deliberate deadline.
• errors.As into *anthropic.Error for status-code branching.
• Do not stack your retries on the SDK’s.
• Check StopReason before reading content — a refusal returns 200.
• Log the usage fields from the first commit.

Conclusion

The API surface is small — one endpoint, one loop, a handful of block types. What makes an LLM call different from any other HTTP call in your service is that it is slow, occasionally non-deterministic, priced per token, and able to succeed while declining to do what you asked. Go gives you good tools for exactly those problems, provided you use the context properly and read the response as the structured thing it is rather than the string you wish it were.

Why Structured Logs Beat Formatted Strings

Here is a line the old log package might produce:

2026/08/04 10:15:02 user 42 checkout failed after 1.2s: payment declined

It reads fine. Now try answering “how many checkouts failed for users on the EU cluster last Tuesday between 14:00 and 15:00?” You are writing a regular expression.

The same event as structured data:

{"time":"2026-08-04T10:15:02.113Z","level":"ERROR","msg":"checkout failed",
 "user_id":42,"duration_ms":1204,"reason":"payment declined","cluster":"eu"}

Now it is a query. Every log aggregator — Loki, Elasticsearch, CloudWatch, BigQuery — indexes those fields directly. The point of structured logging is not prettier output; it is that your logs become a queryable dataset.

The Smallest Useful Setup

package main

import (
    "log/slog"
    "os"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))

    // Make it the package-level default so slog.Info et al. use it too.
    slog.SetDefault(logger)

    slog.Info("service started", "port", 8080, "env", "production")
}

Output:

{"time":"2026-08-04T10:15:02.09Z","level":"INFO","msg":"service started","port":8080,"env":"production"}

The variadic arguments are alternating keys and values. If you prefer something the compiler can check, use typed attributes instead:

slog.Info("service started",
    slog.Int("port", 8080),
    slog.String("env", "production"),
)

Both forms are fine, and you can mix them. The typed form costs a little more typing and saves you from the classic odd-number-of-arguments bug, where a stray value ends up under the key !BADKEY.

For local development, swap the handler and keep everything else:

var handler slog.Handler
if os.Getenv("ENV") == "development" {
    handler = slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug})
} else {
    handler = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
}
slog.SetDefault(slog.New(handler))

Levels, and Changing Them Without a Redeploy

slog has four built-in levels — Debug (-4), Info (0), Warn (4), Error (8) — as plain integers, so you can define your own in between if you really need to.

The more useful trick is a LevelVar, which lets you change the level at runtime:

var logLevel = new(slog.LevelVar) // defaults to Info

func main() {
    slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: logLevel,
    })))

    // Flip to debug on demand — from a signal handler, an admin endpoint,
    // or a config watcher.
    http.HandleFunc("/debug/level", func(w http.ResponseWriter, r *http.Request) {
        var l slog.Level
        if err := l.UnmarshalText([]byte(r.FormValue("level"))); err != nil {
            http.Error(w, "bad level", http.StatusBadRequest)
            return
        }
        logLevel.Set(l)
        slog.Warn("log level changed", "level", l)
    })
}

Being able to turn on debug logging for two minutes on a misbehaving pod, without a deploy, has saved me more time than any other logging feature. Put that endpoint behind authentication — the router access permission patterns I wrote about earlier work well for exactly this kind of internal route.

Attaching Context With With

logger.With returns a new logger that carries the given attributes on every subsequent call. This is how you stop repeating yourself:

// Once, at construction:
type Worker struct {
    log *slog.Logger
}

func NewWorker(id int, queue string) *Worker {
    return &Worker{
        log: slog.Default().With("worker_id", id, "queue", queue),
    }
}

func (w *Worker) process(job Job) {
    // Every line from this worker carries worker_id and queue automatically.
    w.log.Info("job started", "job_id", job.ID)
    // ...
    w.log.Info("job finished", "job_id", job.ID, "duration_ms", 42)
}

With does the attribute formatting work once, at call time, rather than on every log line — so a long-lived logger built with With is cheaper than passing the same attributes repeatedly.

Use WithGroup when you want to namespace a block of fields:

log := slog.Default().WithGroup("http")
log.Info("request", "method", "GET", "path", "/users")
// {"level":"INFO","msg":"request","http":{"method":"GET","path":"/users"}}

Or group inline, for one call:

slog.Info("upstream call",
    slog.String("service", "billing"),
    slog.Group("response",
        slog.Int("status", 502),
        slog.Duration("latency", 1200*time.Millisecond),
    ),
)

Request-Scoped Logging

The pattern that pays off most in a web service: put a logger carrying the request ID into the request context, then let every layer below pull it out. If you have not used context.Context for this kind of request-scoped data before, understanding Golang context covers the rules — including why the key must be an unexported type.

package logging

import (
    "context"
    "log/slog"
)

type ctxKey struct{}

// Into returns a copy of ctx carrying logger.
func Into(ctx context.Context, logger *slog.Logger) context.Context {
    return context.WithValue(ctx, ctxKey{}, logger)
}

// From returns the logger stored in ctx, or the default logger.
func From(ctx context.Context) *slog.Logger {
    if l, ok := ctx.Value(ctxKey{}).(*slog.Logger); ok {
        return l
    }
    return slog.Default()
}

The middleware that fills it in — a close cousin of the handler-wrapping in my Go middleware example:

func Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        requestID := r.Header.Get("X-Request-Id")
        if requestID == "" {
            requestID = uuid.NewString()
        }

        log := slog.Default().With(
            "request_id", requestID,
            "method", r.Method,
            "path", r.URL.Path,
        )

        start := time.Now()
        rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}

        next.ServeHTTP(rec, r.WithContext(logging.Into(r.Context(), log)))

        log.Info("request completed",
            "status", rec.status,
            "duration_ms", time.Since(start).Milliseconds(),
        )
    })
}

// statusRecorder remembers the status code written by the handler.
type statusRecorder struct {
    http.ResponseWriter
    status int
}

func (r *statusRecorder) WriteHeader(code int) {
    r.status = code
    r.ResponseWriter.WriteHeader(code)
}

Now any function that already takes a context.Context can log with full request context and no extra parameters:

func (s *Store) User(ctx context.Context, id int64) (*User, error) {
    logging.From(ctx).Debug("loading user", "user_id", id)
    // ...
}

Every line from that request — across every layer — shares a request_id. Tracing one user’s bad afternoon becomes a single filter in your log viewer.

Redacting Secrets With ReplaceAttr

HandlerOptions.ReplaceAttr runs on every attribute before it is written. It is the right place to enforce policy centrally instead of trusting each call site.

var sensitive = map[string]bool{
    "password": true, "token": true, "authorization": true,
    "api_key": true, "secret": true, "set-cookie": true,
}

handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level:     slog.LevelInfo,
    AddSource: true, // include file:line — useful for errors
    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
        if sensitive[strings.ToLower(a.Key)] {
            return slog.String(a.Key, "[REDACTED]")
        }
        // Rename "time" to "timestamp" to match the rest of our pipeline.
        if a.Key == slog.TimeKey && len(groups) == 0 {
            a.Key = "timestamp"
        }
        return a
    },
})

For types you control, implementing LogValuer is even better — the value redacts itself wherever it is logged:

type Password string

// LogValue implements slog.LogValuer so a Password never reaches a log sink.
func (Password) LogValue() slog.Value {
    return slog.StringValue("[REDACTED]")
}

slog.Info("login attempt", "user", "alex", "password", Password("hunter2"))
// {"level":"INFO","msg":"login attempt","user":"alex","password":"[REDACTED]"}

LogValuer is also how you log a struct compactly. Give your User type a LogValue that returns a group with just the ID and role, and you never accidentally dump an entire record — with its email address and hashed password — into a log line.

Logging Errors Properly

Log the error value, not a formatted string, and let the handler decide how to render it:

if err != nil {
    slog.Error("checkout failed", "err", err, "user_id", userID)
    return fmt.Errorf("checkout: %w", err)
}

Two habits worth keeping:

• Log once, at the boundary. If you log here and return the error, every caller up the stack logs it again. That is the same rule I covered in error handling in Go, and slog does not change it.
• Do not log context.Canceled as an error. A user closing a tab is not an incident.

switch {
case errors.Is(err, context.Canceled):
    slog.Debug("client disconnected", "path", r.URL.Path)
case err != nil:
    slog.Error("request failed", "err", err, "path", r.URL.Path)
}

Bridging Libraries That Use the Old log Package

Dependencies still writing to the standard log package do not have to break your JSON output:

// Route everything from the standard logger through slog at Info level.
slog.SetLogLoggerLevel(slog.LevelInfo)

// Or hand a specific component its own *log.Logger backed by slog.
srv := &http.Server{
    Addr:     ":8080",
    Handler:  mux,
    ErrorLog: slog.NewLogLogger(slog.Default().Handler(), slog.LevelError),
}

That second line is worth adding to every server you write — http.Server logs connection errors through ErrorLog, and by default they land on stderr as unstructured text that your aggregator will not parse.

Performance Notes

slog is designed so the common path allocates very little, but a few habits matter:

• Guard genuinely expensive debug work behind Enabled:

  if slog.Default().Enabled(ctx, slog.LevelDebug) {
      slog.Debug("payload", "body", expensiveDump(req))
  }
  

• Prefer LogAttrs in hot paths — it takes typed attributes and skips the any boxing:

  slog.LogAttrs(ctx, slog.LevelInfo, "cache hit",
      slog.String("key", key),
      slog.Int("size", len(val)),
  )
  

• Build the per-request logger once with With, not per log line.

None of this matters at ten requests per second. All of it matters in a hot loop — the same way caching with Ristretto only pays off once you are actually calling the expensive thing often.

Checklist

• One handler, configured once in main, installed with slog.SetDefault.
• JSON in production, text locally.
• A LevelVar so you can raise verbosity without a redeploy.
• A request-scoped logger in the context, carrying the request ID.
• ReplaceAttr or LogValuer for anything secret.
• Errors logged once, at the boundary, as values.
• http.Server.ErrorLog wired through slog.

Conclusion

log/slog removed the last dependency I used to add reflexively to every new Go service. It is fast enough, it is in the standard library, and its handler interface means you can change output format or destination without touching a single call site. If you are still logging with fmt.Sprintf, the migration is mostly mechanical — and the first time you filter a week of logs by request_id, you will not want to go back.

It pays off especially well for anything token-billed, where a handful of numeric fields per call is the only record of what a feature costs — calling an LLM from Go covers which ones to log.