Reference

Go SDK

The library workers use to provide functions and jobs to the platform — what it is, the one import rule that trips everyone, and where the depth lives.

github.com/dibbla-agents/sdk-go is how your Go code becomes something the platform can call: functions that workflow nodes invoke, and jobs that pipelines run on a schedule.

A worker is a long-lived process. It connects over gRPC, announces what it provides, and stays connected — so a function exists exactly as long as its worker does.

server, err := sdk.New(
  sdk.WithServerName("my-worker"),
  sdk.WithServerApiToken(os.Getenv("SERVER_API_TOKEN")),
)
if err != nil {
  log.Fatal(err)
}

server.RegisterFunction(myFunction)   // callable from a workflow node
server.RegisterJob(&MyJob{})          // runnable as a pipeline

// Registration must happen before Start(): Start advertises what is
// registered, then blocks forever serving dispatches.
log.Fatal(server.Start())

Functions

Build them with sdk.NewSimpleFunction[In, Out](name, version, description), then attach the handler with .WithHandler(...) — it is a builder, not a constructor that takes your function. Your input and output structs are the schema: their JSON field names become the node’s ports and their Go types become what the validator checks.

Use SimpleFunction — the advanced builder is not reachable from your module

The advanced Function[In, Out] signature exposes types from the SDK’s internal/ packages, and Go forbids importing those from any module other than sdk-go itself. Code that uses it was written inside the SDK repository and will not compile in yours. This is the single most common wasted hour with this library.

Jobs

A job implements GetJobID, GetJobName, GetParameters and Execute. Its parameters become the form the pipeline wizard renders, and its logging calls are the entire content of the run screen:

Call	What it draws
`TaskStarted` / `TaskCompleted` / `TaskSkipped`	the task list
`Progress(i, total, msg)`	the progress indicator
`Info` / `Warn` / `Error`	log lines

A job that logs nothing renders an empty run — worth knowing before you write your first one.

Environment

$SERVER_NAME=my-worker
$SERVER_API_TOKEN=…
$GRPC_SERVER_ADDRESS=…       # set this explicitly, always
$GRPC_USE_TLS=true|false

The default gRPC address is production

GRPC_SERVER_ADDRESS defaults to grpc.dibbla.com:443. A worker started without it — in a test, in CI, on your laptop — registers against production and starts serving real dispatches. Set it in every environment, including the one where the answer seems obvious.

Deployed workers get their identity automatically: an app running on the platform authenticates to the workflow engine with a workload identity rather than a token you provision, so there is nothing to rotate or leak.

Where the depth is

This page is a map, not the manual. For server options, the JobContext argument helpers, OAuth on behalf of a user, and the full builder surface:

Custom functions — writing and wiring one, with the cycle rule for agent tools.
Pipelines and schedules — the job side, end to end.
The dibbla agent skill — dibbla skills install dibbla puts the SDK reference where your coding agent can read it.
The repository — dibbla-agents/sdk-go.

← Previous

Skill format