Skip to content

API Reference

API Reference

The authoritative, version-pinned API reference for go-sdk lives on pkg.go.dev. It is auto-generated from the godoc comments in the source on every released tag, so there’s no separate publish step to maintain — push a vX.Y.Z tag and pkg.go.dev renders it within minutes. That page is the source of truth for every exported symbol, its full signature, and its godoc.

The summary below is a curated map of the key public API so you can find the right entry point fast. Signatures here are quoted from the assembly package (github.com/ai-agent-assembly/go-sdk/assembly); pkg.go.dev has the rest.

Entry point 

func Init(ctx context.Context, options ...Option) (*Assembly, error)

Configures and boots the runtime, resolving the gateway URL and API key, then registering the agent with the gateway. Returns the *Assembly handle. See Configuration for the resolution order.

type Assembly struct{ /* unexported */ }

func (a *Assembly) Close() error

Assembly is the runtime handle. Close releases the runtime and stops any managed sidecar; always defer a.Close().

Tool governance 

type Tool interface {
    Name() string
    Description() string
    Call(ctx context.Context, input string) (string, error)
}

func WrapTools(toolList []Tool, client GovernanceClient, options ...Option) []Tool

WrapTools returns a new slice the same length as toolList, where each tool is governed: a policy Check runs before Call, a RecordResult after. Pass nil for client to get a passthrough wrapper.

Single-tool path (rarely needed directly):

type AssemblyTool struct{ /* unexported */ }

func NewAssemblyTool(inner Tool, client GovernanceClient, opts runtimeOptions) *AssemblyTool

runtimeOptions is unexported; you configure it through the With* options passed to WrapTools / Init, not by constructing it directly.

The governance client contract 

type GovernanceClient interface {
    Check(ctx context.Context, request CheckRequest) (Decision, error)
    WaitForApproval(ctx context.Context, request ApprovalRequest) (Decision, error)
    RecordResult(ctx context.Context, request RecordRequest) error
    Close() error
}

type Decision struct {
    Denied  bool
    Pending bool
    Reason  string
}

The wrapper calls this interface around each tool. CheckRequest, ApprovalRequest, and RecordRequest are the request payloads (see policy_model.go / pkg.go.dev for fields).

Options

All configuration is functional options of type Option:

type Option func(*runtimeOptions)
OptionSignature
WithGatewayURLfunc(gatewayURL string) Option
WithAPIKeyfunc(apiKey string) Option — optional; empty is allowed
WithFailClosedfunc(failClosed bool) Option
WithTimeoutfunc(timeout time.Duration) Option
WithEnforcementModefunc(mode EnforcementMode) Option
WithSelfAgentIDfunc(agentID string) Option
WithParentAgentIDfunc(parentAgentID string) Option
WithTeamIDfunc(teamID string) Option
WithDelegationReasonfunc(reason string) Option — ≤ 256 chars
WithSpawnedByToolfunc(tool string) Option
WithSidecarBinaryfunc(path string) Option

See Configuration for defaults and behaviour.

Enforcement modes 

type EnforcementMode string

const (
    EnforcementModeEnforce  EnforcementMode = "enforce"
    EnforcementModeObserve  EnforcementMode = "observe"
    EnforcementModeDisabled EnforcementMode = "disabled"
)

Context helpers 

func WithAgentID(ctx context.Context, agentID string) context.Context
func AgentIDFromContext(ctx context.Context) string

func WithTraceID(ctx context.Context, traceID string) context.Context
func TraceIDFromContext(ctx context.Context) string

func WithRunID(ctx context.Context, runID string) context.Context
func RunIDFromContext(ctx context.Context) string
func EnsureRunID(ctx context.Context) (context.Context, string)

Interceptors 

func HTTPMiddleware(next http.RoundTripper) http.RoundTripper
func UnaryClientInterceptor() grpc.UnaryClientInterceptor
func StreamClientInterceptor() grpc.StreamClientInterceptor

Framework integration 

type Chain interface {
    Call(ctx context.Context, inputs map[string]any) (map[string]any, error)
}

func WrapChain(a *Assembly, chain Chain) Chain

See Integrate with a framework.

Errors 

var ErrInvalidGateway        error // no gateway URL resolved
var ErrRuntimeNotInitialized error // used before Init / after Close
var ErrSidecarUnavailable    error // sidecar mode, no reachable sidecar
var ErrBinaryNotFound        error // aasm / sidecar binary missing

type PolicyViolationError struct { ToolName, Reason string } // gateway denied
type ConfigurationError    struct { Message string }         // can't resolve gateway
type GatewayError          struct { Message string }         // gateway unreachable

Match sentinels with errors.Is and structured types with errors.As. See Handle allow/deny decisions and errors and Troubleshooting.

Local preview

To read the same godoc against your working tree offline:

go install golang.org/x/tools/cmd/godoc@latest
godoc -http=:6060

Then open http://localhost:6060/pkg/github.com/ai-agent-assembly/go-sdk/assembly/.

See also

  • Core Concepts — why these APIs are shaped the way they are.
  • Quick Start — install, init, wrap your tools.
  • Contributing — the conventions enforced in review (context-first, %w wrapping, io.Closer, functional options, internal/ boundary).
Last updated on • Chisanan232