Go SDK

The github.com/beeos-ai/sdk-go module is the canonical Go client for the public BeeOS OpenAPI contract served by openapi-gateway at openapi.beeos.ai. It is generated from the same backend/openapi/beeos-platform-v1.yaml that powers this site’s API Reference tab.

The SDK targets the Platform API only. The A2A protocol (a2a.beeos.ai) and MCP protocol (mcp.beeos.ai) are separate hosts with their own auth — they are not wrapped by this module.

Install

go get github.com/beeos-ai/sdk-go

Current published version: v0.6.1 (see SDK Changelog for wire deltas).

Stable task facade (recommended)

Version 0.6.0 adds Client, a hand-maintained facade for the common agent-task lifecycle. Its API remains stable when the generated OpenAPI surface is regenerated.

package main

import (
    "context"
    "os"

    beeos "github.com/beeos-ai/sdk-go"
)

func main() {
    client, err := beeos.NewClient(beeos.ClientOptions{
        APIKey:  os.Getenv("BEEOS_API_KEY"),
        BaseURL: "https://openapi.beeos.ai",
    })
    if err != nil {
        panic(err)
    }

    agents, err := client.ListAgents(context.Background())
    if err != nil {
        panic(err)
    }
    _ = agents
}

The facade also provides CreateTask, GetTask, CancelTask, and TaskEvents. The complete generated client remains available as client.API or through NewAPIClient.

Full generated client

package main

import (
    "context"
    "fmt"
    "os"

    beeos "github.com/beeos-ai/sdk-go"
)

func main() {
    cfg := beeos.NewConfiguration()
    cfg.Servers = beeos.ServerConfigurations{
        {URL: "https://openapi.beeos.ai"},
    }
    cfg.DefaultHeader["Authorization"] = "Bearer " + os.Getenv("BEEOS_API_KEY")

    client := beeos.NewAPIClient(cfg)
    ctx := context.Background()

    providers, _, err := client.DeployAPI.ListProviders(ctx).Execute()
    if err != nil {
        panic(err)
    }
    for _, p := range providers.GetData() {
        fmt.Printf("%s — %s\n", p.Meta.GetId(), p.Meta.GetName())
    }
}

For local development, set the server URL to http://localhost:8095.

Catalog

providers, _, _ := client.DeployAPI.ListProviders(ctx).Execute()

regions, _, _ := client.DeployAPI.ListDeployRegions(ctx).
    ProviderId("default").Execute()

models, _, _ := client.DeployAPI.ListDeployModels(ctx).
    AgentFramework("beeos-claw").Execute()

Instance lifecycle

req := beeos.DeployInstanceRequest{
    Name:           "my-agent",
    AgentFramework: "beeos-claw",
    ModelPrimary:   "gpt-4o",
}
created, _, _ := client.InstancesAPI.DeployInstance(ctx).
    DeployInstanceRequest(req).Execute()

instanceID := created.GetData().GetId()

inst, _, _ := client.InstancesAPI.GetInstance(ctx, instanceID).Execute()

client.InstancesAPI.StartInstance(ctx, instanceID).Execute()
client.InstancesAPI.StopInstance(ctx, instanceID).Execute()
client.InstancesAPI.RestartInstance(ctx, instanceID).Execute()
client.InstancesAPI.DestroyInstance(ctx, instanceID).Execute()

ListInstances supports pagination + status filter:

list, _, _ := client.InstancesAPI.ListInstances(ctx).
    Page(0).PageSize(20).Status("running").Execute()

Agents

list, _, _ := client.AgentsAPI.ListAgents(ctx).
    InstanceId(instanceID).Limit(20).Execute()

agent, _, _ := client.AgentsAPI.GetAgent(ctx, "agent_abc123").Execute()

patchReq := beeos.PatchAgentRequest{Visibility: beeos.PtrString("public")}
_, _, _ = client.AgentsAPI.PatchAgent(ctx, agent.GetData().GetId()).
    PatchAgentRequest(patchReq).Execute()

Invoke (blocking)

See Calling agents for the full contract.

req := beeos.InvokeAgentRequest{
    Message: "Hello, what can you do?",
}
reply, _, err := client.AgentsAPI.InvokeAgent(ctx, "agent_abc123").
    InvokeAgentRequest(req).Execute()
if err != nil {
    // see "Error handling" below
}
fmt.Println("Reply:", reply.GetData().GetText())
fmt.Println("Channel:", reply.GetData().GetContextId())

Invoke with idempotency + attachments (0.4.0)

req := beeos.InvokeAgentRequest{
    Message:        "Summarize the attached PDF.",
    IdempotencyKey: beeos.PtrString("user_42:summarize_q3_report"),
    Attachments: []beeos.Attachment{
        {FileId: "file_abc123", Filename: beeos.PtrString("q3-report.pdf")},
    },
    Metadata: map[string]interface{}{"campaign": "marketing-q3"},
}
reply, _, _ := client.AgentsAPI.InvokeAgent(ctx, "agent_abc123").
    InvokeAgentRequest(req).Execute()

IdempotencyKey makes the call safe to retry within the TTL window (see ADR 0021).

Streaming invoke (SSE)

The SDK does not abstract SSE — use net/http directly. See Streaming for frame shapes.

import (
    "bufio"
    "net/http"
    "strings"
)

req, _ := http.NewRequestWithContext(ctx, "POST",
    "https://openapi.beeos.ai/api/v1/agents/agent_abc123/invoke",
    strings.NewReader(`{"message":"Tell me a long story."}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("BEEOS_API_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "text/event-stream")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
    fmt.Println(scanner.Text())
}

Tasks (async invocation)

createReq := beeos.CreateTaskRequest{
    Message:        "Run the full Q3 audit.",
    IdempotencyKey: beeos.PtrString("audit_q3_2026"),
}
created, _, _ := client.TasksAPI.CreateTask(ctx, "agent_abc123").
    CreateTaskRequest(createReq).Execute()
taskID := created.GetData().GetTaskId()

// Poll
for {
    task, _, _ := client.TasksAPI.GetTask(ctx, "agent_abc123", taskID).Execute()
    status := task.GetData().GetStatus()
    if status == "completed" || status == "failed" {
        break
    }
    time.Sleep(2 * time.Second)
}

// Or list cross-agent (new in 0.4.0)
all, _, _ := client.TasksAPI.ListUserTasks(ctx).State("running").Limit(50).Execute()

// Cancel
client.TasksAPI.CancelTask(ctx, "agent_abc123", taskID).Execute()

Webhook registration (HMAC-signed deliveries):

hookReq := beeos.RegisterTaskWebhookRequest{
    Url:    "https://example.com/hooks/beeos",
    Secret: beeos.PtrString("whsec_…"),
    Events: []string{"completed", "failed", "cancelled"},
}
_, _, _ = client.TasksAPI.RegisterTaskWebhook(ctx, "agent_abc123", taskID).
    RegisterTaskWebhookRequest(hookReq).Execute()

Delivery history + replay (new in 0.4.0 — see Webhooks):

deliveries, _, _ := client.TasksAPI.ListWebhookDeliveries(ctx,
    "agent_abc123", taskID, "wh_abc123").Execute()

_, _, _ = client.TasksAPI.RedeliverWebhook(ctx,
    "agent_abc123", taskID, "wh_abc123", "del_xyz").Execute()

Conversations

conv, _, _ := client.ConversationsAPI.CreateConversation(ctx, "agent_abc123").
    CreateConversationRequest(beeos.CreateConversationRequest{
        Title: beeos.PtrString("Quarterly planning"),
    }).Execute()

_, _, _ = client.ConversationsAPI.SendConversationMessage(ctx,
    "agent_abc123", conv.GetData().GetId()).
    SendConversationMessageRequest(beeos.SendConversationMessageRequest{
        Message: "Start the planning session.",
    }).Execute()

msgs, _, _ := client.ConversationsAPI.ListConversationMessages(ctx,
    "agent_abc123", conv.GetData().GetId()).Since(0).Execute()

Files

presignReq := beeos.PresignUploadRequest{
    Filename:    "report.pdf",
    ContentType: "application/pdf",
}
presigned, _, _ := client.FilesAPI.PresignUpload(ctx).
    PresignUploadRequest(presignReq).Execute()

// Upload bytes to the returned signed URL with PUT...
// Later, fetch metadata + a fresh download URL:
meta, _, _ := client.FilesAPI.PresignDownload(ctx, presigned.GetData().GetFileId()).Execute()

Use the file_id in Attachments on InvokeAgentRequest or CreateTaskRequest.

Error handling

Non-2xx responses return a *GenericOpenAPIError that wraps the BeeOS error envelope:

import (
    "encoding/json"
    "errors"
)

type beeosError struct {
    Success bool `json:"success"`
    Error   struct {
        Code    string `json:"code"`
        Message string `json:"message"`
    } `json:"error"`
}

if _, _, err := client.InstancesAPI.GetInstance(ctx, "nope").Execute(); err != nil {
    var apiErr *beeos.GenericOpenAPIError
    if errors.As(err, &apiErr) {
        var body beeosError
        _ = json.Unmarshal(apiErr.Body(), &body)
        fmt.Printf("api error: %s — %s\n", body.Error.Code, body.Error.Message)
    }
}

See Error reference for the full code list.

Source and generation

Generated from the same OpenAPI spec as the TypeScript SDK (sdks/openapi-sdk/generate.sh). Wire-level changes: SDK Changelog. Version migration: SDK Migration.

GitHub: beeos-ai/sdk-go

Getting Started

Guides

Architecture

A2A Protocol

MCP

Integrations

SDKs

Reference

Install

Stable task facade (recommended)

Full generated client

Catalog

Instance lifecycle

Agents

Invoke (blocking)

Invoke with idempotency + attachments (0.4.0)

Streaming invoke (SSE)

Tasks (async invocation)

Conversations

Files

Error handling

Source and generation

​Install

​Stable task facade (recommended)

​Full generated client

​Catalog

​Instance lifecycle

​Agents

​Invoke (blocking)

​Invoke with idempotency + attachments (0.4.0)

​Streaming invoke (SSE)

​Tasks (async invocation)

​Conversations

​Files

​Error handling

​Source and generation

Install

Stable task facade (recommended)

Full generated client

Catalog

Instance lifecycle

Agents

Invoke (blocking)

Invoke with idempotency + attachments (0.4.0)

Streaming invoke (SSE)

Tasks (async invocation)

Conversations

Files

Error handling

Source and generation