Skip to content

README.md

Latest commit

 

History

History
198 lines (144 loc) · 13.7 KB

README.md

File metadata and controls

198 lines (144 loc) · 13.7 KB
Raw

go-sdk

Go Reference GitHub release Tests Lint Coverage Go Report Card Docs License: Apache 2.0 Go Version

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.1-rc.6). 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://docs.agent-assembly.com/core/stable/reference/framework-compatibility.html (a /stable/ link that 404s until GA by design).

Prerequisites

  • Go ≥ 1.26 — the floor declared in go.mod.
    • Security — build with Go ≥ 1.26.5. GO-2026-5856 is a crypto/tls Encrypted-Client-Hello (ECH) privacy leak in the Go standard library, fixed in go1.26.5. Because the vulnerable code lives in the stdlib, the fix ships with your compiler, not this module — the module deliberately keeps a broad go 1.26.0 floor (and pins toolchain go1.26.5 for its own build and govulncheck gate), so a consumer compiling go-sdk with Go 1.26.0–1.26.4 still links the vulnerable stdlib. Security-conscious builds should use Go ≥ 1.26.5 to pick up the fix.
  • 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

Metadata at a glance

Field Value
Module github.com/ai-agent-assembly/go-sdk
Protocol version 0.0.1-rc.6
Go floor >= 1.26
Docs https://docs.agent-assembly.com/go-sdk/
Releases https://github.com/ai-agent-assembly/go-sdk/releases

Install:

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

Warning

Init requires a reachable sidecar address or a managed binary, or it returns ErrSidecarUnavailable. The snippet below passes WithSidecarAddress pointing at a running gateway's gRPC endpoint (default 127.0.0.1:50051) — without it (or WithSidecarBinary to have the SDK manage one), Init falls through to ErrSidecarUnavailable and the log.Fatal below fires. And even with a reachable address, agent registration itself is not reachable from a plain go get today — following this quick start will not make your agent appear in the dashboard. The register handshake runs only under the opt-in native cgo binding (-tags aa_ffi_go, CGO_ENABLED=1), and that native library (libaa_ffi_go) is not published anywhere yet. The default pure-Go build has no native transport, so it does not register even when WithSidecarAddress is set. See docs/quick-start.md for the full explanation; track status in AAASM-4547 and AAASM-4469.

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),
    assembly.WithSidecarAddress("127.0.0.1:50051"), // required — see warning above
)
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. Under the default fail-closed enforce posture, passing nil denies every wrapped call (ErrGovernanceUnavailable) rather than running it unchecked (AAASM-3109) — wire in a real client when you're ready to enforce. To get a passthrough wrapper instead (tools run, no gateway calls) while you're wiring one up, pass assembly.WithFailClosed(false) as an option. 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

AI Agent Assembly ecosystem

Support & Security

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)