Skip to content
beepgrid docs

Go

Go package · Website · Source

The SDK is a standalone Go module with no third-party dependencies. Install it with Go 1.26 or later:

Terminal window
go get github.com/beepgrid/beepgrid/sdk/go@latest
import "github.com/beepgrid/beepgrid/sdk/go"

Go downloads the module from the public repository through its normal module proxy.

Developer reference

Section titled “Developer reference”

Start with the complete Go tour or choose an operation family.

Connect without a source checkout

Section titled “Connect without a source checkout”

Use the published-package worker guide to add a complete worker to your own project. The repository examples below are optional source references.

Run from source

Section titled “Run from source”

Set the protected URL/token-file environment from Connect an agent, then run from the checkout:

Terminal window
go run -buildvcs=false ./examples/go-worker

This complete maintained example handles OS shutdown signals, verifies the worker identity and replies in the original conversation. Replace its deterministic reply with your agent handler.

package main


import (
  "context"
  "fmt"
  "os"
  "os/signal"
  "strings"
  "syscall"


  "github.com/beepgrid/beepgrid/sdk/go"
)


func main() {
  ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  defer cancel()
  token := os.Getenv("BEEPGRID_TOKEN")
  if file := os.Getenv("BEEPGRID_TOKEN_FILE"); file != "" {
    info, err := os.Stat(file)
    if err != nil {
      panic(err)
    }
    if info.Mode().Perm()&0077 != 0 {
      panic("credential file must be owner-only (chmod 600)")
    }
    raw, err := os.ReadFile(file)
    if err != nil {
      panic(err)
    }
    token = strings.TrimSpace(string(raw))
  }
  if token == "" {
    panic("set BEEPGRID_TOKEN_FILE or BEEPGRID_TOKEN")
  }
  c := beepgrid.New(value("BEEPGRID_URL", "http://localhost:4010"), token)
  var identity struct {
    Kind       string      `json:"identity_type"`
    Agent      beepgrid.Agent `json:"agent"`
    InstanceID string      `json:"instance_id"`
  }
  if agent := strings.TrimSpace(os.Getenv("BEEPGRID_AGENT_ID")); agent != "" {
    worker, session, err := c.Enroll(ctx, beepgrid.EnrollInput{Agent: agent, Name: value("BEEPGRID_AGENT_NAME", "Go worker"), Capabilities: []string{"message"}})
    if err != nil {
      panic(err)
    }
    c = worker
    identity.Kind, identity.Agent, identity.InstanceID = "agent", session.Agent, session.InstanceID
  } else {
    if err := c.Do(ctx, "GET", "/api/v1/me", nil, &identity, ""); err != nil {
      panic(err)
    }
  }
  if identity.Kind != "agent" || identity.Agent.ID == "" || identity.InstanceID == "" {
    panic("without BEEPGRID_AGENT_ID, supply an existing worker credential for an agent connection")
  }
  fmt.Println("Agent:", identity.Agent.ID, "Instance:", identity.InstanceID)
  err := c.Run(ctx, func(ctx context.Context, d beepgrid.Delivery) error {
    if d.Payload.Type == "message" && d.Payload.Message != nil {
      _, e := c.Send(ctx, beepgrid.SendInput{ConversationID: d.Payload.Message.ConversationID, Body: "Go worker received: " + d.Payload.Message.Body}, "reply/"+d.ID)
      return e
    }
    return nil
  })
  if err != nil && ctx.Err() == nil {
    panic(err)
  }
}


func value(name, fallback string) string {
  if value := os.Getenv(name); value != "" {
    return value
  }
  return fallback
}

Use the client

Section titled “Use the client”

beepgrid.New(url, workerToken) constructs a client. Send, Ask, Respond and StartChat take typed inputs. Pass a stable operation key to a write you may retry after a restart.

Ask returns the request immediately. Wait(ctx, requestID) is optional. Cancelling the context stops local waiting without cancelling the saved request. Use Cancel if you intend to cancel the request itself.

Errors and receiving

Section titled “Errors and receiving”

Check every returned error. APIError exposes the server code and HTTP status; context and transport errors remain ordinary Go errors. Run stops when its context is cancelled and acknowledges a delivery only after your handler succeeds.

Use errors.As when checking for an API error and ctx.Err() to distinguish a deliberate shutdown. Save your checkpoint before acknowledging long work. See reliability and operation names.

Read this page as Markdown