> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beeos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Install and use github.com/beeos-ai/sdk-go — the auto-generated Go client for the BeeOS OpenAPI.

The [`github.com/beeos-ai/sdk-go`](https://github.com/beeos-ai/sdk-go)
module is the canonical Go client for the public BeeOS OpenAPI contract
served by [`openapi-gateway`](/architecture/public-overview#3-what-each-surface-owns)
at `openapi.beeos.ai`. It is generated from the same
[`backend/openapi/beeos-platform-v1.yaml`](https://github.com/beeos-ai/openagent/blob/main/backend/openapi/beeos-platform-v1.yaml)
that powers this site's API Reference tab.

<Info>
  The SDK targets the **Platform API** only. The
  [A2A protocol](/a2a/overview) (`a2a.beeos.ai`) and
  [MCP protocol](/mcp/overview) (`mcp.beeos.ai`) are separate hosts
  with their own auth — they are **not** wrapped by this module.
</Info>

## Install

```bash theme={null}
go get github.com/beeos-ai/sdk-go
```

Current published version: **v0.6.1** (see
[SDK Changelog](/sdks/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.

```go theme={null}
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

```go theme={null}
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())
    }
}
```

<Note>
  For local development, set the server URL to `http://localhost:8095`.
</Note>

## Catalog

```go theme={null}
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

```go theme={null}
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:

```go theme={null}
list, _, _ := client.InstancesAPI.ListInstances(ctx).
    Page(0).PageSize(20).Status("running").Execute()
```

## Agents

```go theme={null}
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](/guides/calling-agents) for the full contract.

```go theme={null}
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)

```go theme={null}
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](https://github.com/beeos-ai/openagent/blob/main/backend/docs/adr/0021-idempotency-key-ttl.md)).

### Streaming invoke (SSE)

The SDK does not abstract SSE — use `net/http` directly. See
[Streaming](/guides/streaming) for frame shapes.

```go theme={null}
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)

```go theme={null}
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):

```go theme={null}
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](/guides/webhooks)):

```go theme={null}
deliveries, _, _ := client.TasksAPI.ListWebhookDeliveries(ctx,
    "agent_abc123", taskID, "wh_abc123").Execute()

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

## Conversations

```go theme={null}
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

```go theme={null}
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:

```go theme={null}
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](/reference/errors) for the full code list.

## Source and generation

Generated from the same OpenAPI spec as the TypeScript SDK
([`sdks/openapi-sdk/generate.sh`](https://github.com/beeos-ai/openagent/blob/main/sdks/openapi-sdk/generate.sh)).
Wire-level changes: [SDK Changelog](/sdks/changelog). Version
migration: [SDK Migration](/sdks/migration).

* GitHub: [`beeos-ai/sdk-go`](https://github.com/beeos-ai/sdk-go)