go-sdk

Go SDK for AI Agent Assembly — runtime governance for AI agent tool calls.

The SDK initialises in a few lines, propagates agent identity through context.Context, wraps your agent's tool slice with policy enforcement, and forwards every check + result to the AAASM gateway over gRPC or HTTP.

Project status

go-sdk is pre-release — see the releases page (or the release badge above) for the current published tag. The VERSION file pins the gateway protocol version the SDK is built against (currently 0.0.0). The public assembly package API may still change between pre-release tags — pin an exact tag in your go.mod and review the release notes before upgrading. See Core-runtime compatibility for the version/protocol contract.

Anything outside the assembly/ package (internal/, examples/) is not part of the public API and may change without notice.

Framework compatibility

The first-class agent-framework adapter is LangChainGo (github.com/tmc/langchaingo), tested on the v0.1.x line (CI and the examples/go/langchaingo sample pin v0.1.14). assembly.WrapChain governs a LangChainGo chains.Chain; assembly.WrapTools governs any tool.

The SDK requires no framework by default — go.mod imports neither langchaingo nor any other framework. assembly.Tool is structurally identical to LangChainGo's tools.Tool (Name/Description/Call), so WrapTools governs an arbitrary slice of langchaingo/tools.Tool values (or any other type with the same three methods) with no adapter. Go-side coverage is LangChainGo plus this generic tool-wrapping — there are no other per-framework adapters.

Go framework compatibility is documented authoritatively in docs/compatibility.md — the LangChainGo adapter and WrapTools live in this SDK. The core docs provide a cross-SDK index/hub that links to this page and the Python/Node equivalents at https://ai-agent-assembly.github.io/agent-assembly/stable/reference/framework-compatibility.html (a /stable/ link that 404s until GA by design).

Prerequisites

• Go ≥ 1.26 — the floor declared in go.mod.
• For production: an operator-issued gateway URL and API key. For local development you can skip both — Init discovers a gateway on http://localhost:7391 (see Configuration).
• (Optional) a C compiler — only needed if you build with -tags aa_ffi_go to enable the native FFI transport. The default transport is pure-Go and runs cleanly with CGO_ENABLED=0.

Installation

go get github.com/ai-agent-assembly/go-sdk

Supply-chain verification

The only canonical module is:

github.com/ai-agent-assembly/go-sdk

Anything else (a different owner, a typosquat, or a vendored copy you did not pull yourself) is not us. Verify what you actually pulled:

• Checksum DB — go get and go mod download authenticate every module version against the public Go checksum database (sum.golang.org) and record the hashes in go.sum. A mismatch fails the build, so a tampered or substituted module cannot install silently.
• Re-verify on demand — run go mod verify to confirm the modules in your local cache still match go.sum. To force a clean re-fetch and re-check against the checksum DB, clear the cache (go clean -modcache) then go mod download github.com/ai-agent-assembly/go-sdk. Keep the default checksum settings (do not set GOFLAGS=-insecure or add the module to GONOSUMDB/GOPRIVATE), which would disable this check.
• SBOM — every release tag attaches a CycloneDX SBOM (sbom.cdx.json) to its GitHub Release, generated by the tag-triggered release workflow. Cross-check it against your advisory feed to audit the dependency set.
• Release gate — a release tag only publishes after go mod verify + govulncheck pass in CI, so a release cannot ship on a known-vuln dependency.

Layout

assembly/
  init.go
  runtime.go
  options.go
  defaults.go
  validation.go
  governance_client.go
  policy_model.go
  governance_errors.go
  tool_wrapper.go
  wrap_tools.go
  sidecar.go
  interceptor.go
examples/minimal/

Quick Start

import (
    "context"
    "log"

    "github.com/ai-agent-assembly/go-sdk/assembly"
)

ctx := assembly.WithAgentID(context.Background(), "my-agent")
a, err := assembly.Init(ctx, assembly.WithGatewayURL(url), assembly.WithAPIKey(key))
if err != nil {
    log.Fatal(err)
}
defer a.Close()

WithAgentID attaches the calling agent's identity to ctx; the SDK forwards it (and any WithTraceID / WithRunID values) to the gateway on every Check and RecordResult. See Context Propagation below for the full set of context helpers.

Then wrap your agent's tools so every call is governed:

governed := assembly.WrapTools(myTools, nil)

The second argument is the GovernanceClient that talks to the gateway; passing nil gives a passthrough wrapper (tools run, no gateway calls) — wire in a real client when you're ready to enforce. Each call against a tool in governed is then checked against the gateway policy before it runs and recorded after. Hand governed to your agent in place of the originals. See Quick Start for the end-to-end walk-through.

Documentation

• Live site — ai-agent-assembly.github.io/go-sdk (Hugo, Hextra theme; built and deployed from master).
• API reference — pkg.go.dev/github.com/ai-agent-assembly/go-sdk (auto-generated from godoc; preview locally with godoc -http=:6060).
• Core concepts — docs/core-concepts.md and docs/api-reference.md.
• Contributing — CONTRIBUTING.md.

AI Agent Assembly ecosystem

• Organization — github.com/ai-agent-assembly: org profile and the full production-repo map.
• Core runtime — ai-agent-assembly/agent-assembly: the gateway, policy engine, proxy, and eBPF layers this SDK talks to.
• Protocol spec — the gateway wire protocol this SDK is pinned to lives in the core monorepo at docs/src/protocol.
• Canonical docs — the org-wide documentation site at ai-agent-assembly.github.io/agent-assembly-docs.
• Runnable examples — ai-agent-assembly/agent-assembly-examples: learn by running small, framework-specific Go (and Python/Node) samples for policy enforcement, approvals, audit, trace, and runtime workflows.
• Release notes — github.com/ai-agent-assembly/go-sdk/releases.

Support & Security

• Questions / bugs / feature requests — open an issue at github.com/ai-agent-assembly/go-sdk/issues.
• Security vulnerabilities — do not file a public issue; report privately via the security policy.
• Troubleshooting — common errors and fixes are in docs/troubleshooting.md.

Development

make fmt              # gofmt -w on all .go files
make lint             # golangci-lint run ./...
make test             # go test ./...

go vet ./...
go test ./assembly                            # one package
go test ./assembly -run TestRegisterAgent     # one test
go test -count=1 -race ./...                  # race detector

See CONTRIBUTING.md for the full contributor workflow, including the optional CGo native FFI build (-tags aa_ffi_go) and the memory regression harness.

Context Propagation

• assembly.WithAgentID / assembly.AgentIDFromContext propagate and read agent identity.
• assembly.WithTraceID / assembly.TraceIDFromContext propagate explicit trace IDs and fallback to OpenTelemetry span context trace ID when unset.
• assembly.WithRunID / assembly.RunIDFromContext propagate run identity.
• assembly.EnsureRunID guarantees a stable run ID within the same context tree.

Gateway Context Handling

• GatewayClient.Check fails fast when ctx is already cancelled.
• If ctx has no deadline, GatewayClient.Check applies SDK timeout defaults (500ms unless overridden by WithTimeout).
• The final effective context (values + timeout/deadline) is passed to the gateway transport check call.

FFI Transport

• CGo bridge module lives in internal/ffi/cgo_bridge.go with #cgo LDFLAGS: -laa_ffi_go.
• Native FFI path is enabled with build tags: -tags aa_ffi_go (and CGO_ENABLED=1).
• Pure-Go UDS fallback is selected automatically when aa_ffi_go tag is not set.
• CGO_ENABLED=0 is explicitly supported via fallback transport and CI matrix coverage.
• Optional memory harness test (1M sends): AAASM_MEMORY_HARNESS=1 go test ./internal/ffi -run TestMemoryRegressionHarness.

SonarQube CI Setup

Configure these repository settings for the SonarQube workflow:

• Secret: SONAR_TOKEN
• Variable: SONAR_HOST_URL (for SonarCloud use https://sonarcloud.io)
• Variable: SONAR_PROJECT_KEY
• Variable: SONAR_ORGANIZATION (required for SonarCloud, optional for self-hosted SonarQube)