Go

The Adjudon Go SDK is the integration path for Go services running AI-adjacent backend logic — the typical fintech "trade-execution gateway in front of a model" or "fraud-scoring edge service" pattern. The package targets Go 1.22+ and ships as github.com/adjudon/adjudon-go on proxy.golang.org. Runtime dependencies are limited to the standard library: net/http, encoding/json, context. No third-party HTTP client, no log framework wrapper, no transitive surprises in a regulated build.

Status: Public roadmap

The Go SDK is on the published roadmap with a proxy.golang.org release target of Q3 2026. Until then, Go integrations call the Traces API directly with net/http + encoding/json; the wire contract is identical and a hand-rolled client ports cleanly to the SDK once it ships. This page documents the SDK shape as it will land.

Install

go get (target Q3 2026)

go get github.com/adjudon/adjudon-go

go.mod

require github.com/adjudon/adjudon-go v0.1.0

First call

Plain Go

package main

import (
    "context"
    "log"
    "os"

    "github.com/adjudon/adjudon-go/adjudon"
)

func main() {
    client, err := adjudon.New(adjudon.Options{
        APIKey:  os.Getenv("ADJUDON_API_KEY"), // adj_agent_<48-hex>
        AgentID: "customer-support-bot",
    })
    if err != nil {
        log.Fatal(err)
    }

    trace, err := client.Trace(context.Background(), adjudon.TraceRequest{
        InputContext: map[string]any{
            "prompt": "Can I get a refund for order #1234?",
        },
        OutputDecision: map[string]any{
            "action":     "initiate_refund",
            "confidence": 0.91,
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    if trace.Status == adjudon.StatusBlocked {
        log.Println("blocked by policy")
        return
    }
}

net/http handler

func RefundHandler(client *adjudon.Client) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        trace, err := client.Trace(r.Context(), adjudon.TraceRequest{
            InputContext:   readInputContext(r),
            OutputDecision: map[string]any{"action": "initiate_refund"},
        })
        if err != nil {
            http.Error(w, "adjudon unreachable", http.StatusServiceUnavailable)
            return
        }

        switch trace.Status {
        case adjudon.StatusBlocked:
            http.Error(w, "blocked by policy", http.StatusForbidden)
        case adjudon.StatusFlagged:
            w.WriteHeader(http.StatusAccepted)
        default:
            w.WriteHeader(http.StatusOK)
        }
    }
}

The client is goroutine-safe; share one *adjudon.Client across the application and pass r.Context() per request to honour cancellation deadlines from the inbound HTTP context.

Versions

Runtime	Supported
Go 1.22	✓ (minimum)
Go 1.23	✓
Go 1.24	✓ (current)
Go 1.21 and earlier	— (out of upstream support)

Configuration

Option	Default	Description
APIKey	(required)	adj_agent_<48-hex>
AgentID	(required)	Stable agent identifier
BaseURL	https://api.adjudon.com	Override for self-hosted Adjudon
FailMode	FailOpen	FailOpen returns a passthrough trace on failure; FailClosed returns the underlying error
Timeout	10 * time.Second	Per-request timeout (separate from context.Context deadline)
MaxRetries	3	Retry attempts on 429 / 5xx with exponential backoff
HTTPClient	(default)	Inject a custom *http.Client for mTLS, proxy, or instrumentation

Errors

The SDK returns a single error type, *adjudon.Error, with a Code field that matches the Error Codes taxonomy:

Code	Trigger
ADJ_UNAUTHORIZED	Invalid API key; never retried
ADJ_RATE_LIMITED	Retries exhausted on 429 (only when FailMode = FailClosed)
ADJ_TIMEOUT	Retries exhausted on timeout (only when FailMode = FailClosed)
ADJ_BLOCKED_BY_POLICY	Policy returned block; always propagated as a compliance signal

errors.As(err, &adjudon.Error{}) is the idiomatic way to inspect the code. FailMode = FailOpen returns (TraceResponse{Status: StatusPassthrough}, nil) for every error except ADJ_BLOCKED_BY_POLICY and ADJ_UNAUTHORIZED — the first is a compliance signal you must not swallow, the second is a configuration bug.

Idempotency

client.TraceWithIdempotency(ctx, req, key) accepts a string. If omitted (via client.Trace), the SDK generates a UUID v4 per call. Duplicate keys within the 24-hour window return the cached response, so retry storms during a transient network hiccup never inflate the org's metered trace count.

Context cancellation & custom transports

context.Context is the first argument on every method. The SDK respects deadlines and cancellations the standard-library way: an inbound HTTP handler that times out at 5 s passes its context to client.Trace(ctx, ...) and the SDK aborts the in-flight request before its own 10 s default fires.

For mTLS to a self-hosted Adjudon, set Options.HTTPClient to a *http.Client with the appropriate tls.Config on its Transport. The SDK does not wrap the transport itself; bring your own. This is also the injection point for OpenTelemetry's otelhttp.NewTransport if the team already runs an OTel collector — the SDK does not duplicate trace instrumentation that the platform layer can do better.

Resources

• Quickstart — first trace in 60 seconds
• Authentication — API key formats and rotation
• Traces API — the underlying HTTP surface this SDK calls (use this directly until the Go module release lands)
• Error Codes — HTTP-level errors this SDK raises
• GitHub: github.com/adjudon/adjudon-go (target repository for source, issues, and releases when the SDK ships)