Go SDK - Komodor

The Go SDK builds agent workers in Go: register a worker, receive work, and stream runs, spans, and results to the control plane with no Python in the container. This page covers the worker loop, configuration, what the agent advertises about itself, and the telemetry surface available inside a handler.

Install

go get github.com/komodorio/agentops-go

Requires Go 1.26 or newer.

A minimal worker

package main

import (
	"context"
	"errors"
	"log"
	"os/signal"
	"syscall"

	"github.com/komodorio/agentops-go"
)

func main() {
	w, err := agentops.New(agentops.Config{
		Agent: agentops.Agent{Name: "my-worker", Version: "0.1.0"},
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	err = w.Run(ctx, func(ctx context.Context, run *agentops.Run) (map[string]any, error) {
		span := run.Span("investigate", agentops.KindAgent)
		defer span.End()

		run.Message("assistant", "looking into it…")

		return map[string]any{"text": "done"}, nil
	})
	if err != nil && !errors.Is(err, context.Canceled) {
		log.Fatal(err)
	}
}

Run blocks and manages the whole lifecycle — register, heartbeat, hold the reverse channel, claim work, dispatch it — until the context is cancelled. Returning the output map completes the run; returning an error fails it, and a panic is recovered into a run failure.

Output convention, same as every other surface: a text key in the returned map is the run’s descriptive output — what a person sees as the answer — and every other key is structured detail.

Configuration

Config fields fall back to environment variables when unset:

Field	Environment variable	Required	Notes
`BaseURL`	`AGENTOPS_BASE_URL`	Yes	The control-plane URL
`AgentID`	`AGENTOPS_AGENT_ID`	Yes	The agent’s friendly name, sent as its identifier
`Token`	`AGENTOPS_WORKER_TOKEN`	Yes	The worker token it authenticates with
`WorkerID`	`AGENTOPS_WORKER_ID`	No	Defaults to the agent name plus the hostname; give replicas distinct, stable ids

Two more are worth knowing:

MaxConcurrent (AGENTOPS_MAX_CONCURRENT, default 1) — how many runs the worker handles at once. One at a time is the default; raise it for I/O-bound agents whose runs can overlap, and each run still gets its own Run and its own goroutine.
DrainTimeout (default 30s) — how long an in-flight run may continue after shutdown begins before its context is cancelled.

Cluster placement is reported automatically from AGENTOPS_CLUSTER_NAME, AGENTOPS_NAMESPACE, and AGENTOPS_POD_NAME when they are set.

What the agent advertises

Config.Agent is the worker’s self-description, sent once at registration and surfaced in the fleet:

Field	Purpose
`Name`, `Description`, `Version`	Identity in the fleet. `Version` defaults to `dev`.
`Labels`	Fleet labels, which label-scoped grants match against
`Model`	The primary model the agent uses
`DefaultInput`, `InputSchema`	Seeds the invoke form, and declares the input accepted
`Skills`	Instruction documents — markdown, not invocable
`UseCases`	Invocable use cases, each with its own input and output schema; the platform turns each into a tool on the agent’s own tool surface. See Use cases
`Triggers`	How the platform should invoke the agent automatically, synced at registration

Skills and UseCases are easy to confuse and are not the same thing. A skill is know-how the agent reads; a use case is an entry point something else can call, and a handler branches on run.UseCase() to tell which one it was invoked for.

Inside a handler

Call	What it does
`run.Input`	The invocation payload
`run.Secrets`	Run-scoped credentials, delivered for this run
`run.Span(name, kind)`	Open a trace span; `End()` or `Fail(err)` it
`run.Message(role, content)`	Stream a message to the run timeline
`run.Log(level, message)`	Stream a log line
`run.ToolCall(id, name, args)` / `run.ToolResult(id, name, result)`	Record a tool invocation and its result, matched by id, rendered as tool cards in the transcript
`run.RecordUsage(usage)`	Report token and cost usage per model call; calls accumulate and the total is attached when the run completes
`run.UpdateOutput(map)`	Stream a partial output snapshot before the run finishes
`run.SaveArtifact(ctx, name, content, mimeType)`	Persist a text artifact on the run and get its id back
`run.Snapshot` / `run.SetSnapshot(map)`	Read and write the session-state envelope used to resume a later run

The session snapshot is sent as-is and is not secret-masked — masking it would corrupt the state it exists to preserve. Keep credentials out of it.

Next steps

Python SDK

The same contract in Python, with framework adapters.

Agent identity

Where the worker token comes from.

Triggers & schedules

What a declared trigger becomes on the platform side.

Runs & evidence

Where the spans and messages you stream end up.

​Install

​A minimal worker

​Configuration

​What the agent advertises

​Inside a handler

​Next steps

Python SDK

Agent identity

Triggers & schedules

Runs & evidence

Install

A minimal worker

Configuration

What the agent advertises

Inside a handler

Next steps