Go SDK

github.com/beeos-ai/sdk-go 模块是公开 BeeOS OpenAPI 契约的规范 Go 客户端，契约由 openapi-gateway 在 openapi.beeos.ai 提供服务。它从同一份 backend/openapi/beeos-platform-v1.yaml 生成，与本站 API Reference tab 同源。

SDK 只针对 Platform API。A2A 协议（a2a.beeos.ai）和 MCP 协议（mcp.beeos.ai）是独立主机、独立鉴权 —— 不被本模块包装。

安装

go get github.com/beeos-ai/sdk-go
export BEEOS_API_KEY="oag_your_key"

当前发布版本：v0.8.0（wire delta 见 SDK 变更日志）。

稳定任务 facade（推荐）

Client 是覆盖常用 Agent 任务生命周期的手工维护 facade； OpenAPI 生成代码重新生成时，它的调用方式保持稳定。

package main

import (
    "context"

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

func main() {
    client, err := beeos.NewClient()
    if err != nil {
        panic(err)
    }

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

beeos.NewClient() 会自动读取 BEEOS_API_KEY，并默认连接 https://openapi.beeos.ai。如需切换环境，可设置 BEEOS_API_URL；也可以传入一个 beeos.ClientOptions 显式覆盖配置。 facade 同时提供 CreateTask、GetTask、CancelTask 和 TaskEvents。完整生成客户端仍可通过 client.API 或 NewAPIClient 使用。

完整生成客户端

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())
    }
}

本地开发把 server URL 设成 http://localhost:8095。

Catalog

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

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

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

实例生命周期

req := beeos.DeployInstanceRequest{
    Name:           "my-agent",
    Harness:        "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 支持分页 + 状态过滤：

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

智能体

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（阻塞）

完整契约见调用智能体。

req := beeos.InvokeAgentRequest{
    Message: "Hello, what can you do?",
}
reply, _, err := client.AgentsAPI.InvokeAgent(ctx, "agent_abc123").
    InvokeAgentRequest(req).Execute()
if err != nil {
    // 见下面 "错误处理"
}
fmt.Println("Reply:", reply.GetData().GetText())
fmt.Println("Channel:", reply.GetData().GetContextId())

带 idempotency + 附件的 Invoke（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 让调用在 TTL 窗口内可安全重试（见 ADR 0021）。

流式 Invoke（SSE）

SDK 不抽象 SSE —— 直接用 net/http。frame 形状见流式。

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())
}

任务（异步 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)
}

// 跨智能体列表（0.4.0 新增）
all, _, _ := client.TasksAPI.ListUserTasks(ctx).State("running").Limit(50).Execute()

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

Webhook 注册（HMAC 签名投递）：

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()

投递历史 + 重放（0.4.0 新增 —— 见 Webhooks）：

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

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

会话

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()

文件

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

// 用 PUT 把字节上传到返回的签名 URL...
// 之后取元数据 + 一个新的下载 URL：
meta, _, _ := client.FilesAPI.PresignDownload(ctx, presigned.GetData().GetFileId()).Execute()

把 file_id 放进 InvokeAgentRequest 或 CreateTaskRequest 的 Attachments。

错误处理

非 2xx 响应返回 *GenericOpenAPIError，包装 BeeOS error 信封：

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)
    }
}

完整 code 列表见错误参考。

源码与生成

与 TypeScript SDK 从同一份 OpenAPI spec 生成（sdks/openapi-sdk/generate.sh）。 wire 级变更：SDK 变更日志。版本迁移： SDK 迁移。

GitHub：beeos-ai/sdk-go

快速开始

指南

架构

A2A 协议

MCP

集成

SDK

参考

安装

稳定任务 facade（推荐）

完整生成客户端

Catalog

实例生命周期

智能体

Invoke（阻塞）

带 idempotency + 附件的 Invoke（0.4.0）

流式 Invoke（SSE）

任务（异步 invocation）

会话

文件

错误处理

源码与生成

​安装

​稳定任务 facade（推荐）

​完整生成客户端

​Catalog

​实例生命周期

​智能体

​Invoke（阻塞）

​带 idempotency + 附件的 Invoke（0.4.0）

​流式 Invoke（SSE）

​任务（异步 invocation）

​会话

​文件

​错误处理

​源码与生成

安装

稳定任务 facade（推荐）

完整生成客户端

Catalog

实例生命周期

智能体

Invoke（阻塞）

带 idempotency + 附件的 Invoke（0.4.0）

流式 Invoke（SSE）

任务（异步 invocation）

会话

文件

错误处理

源码与生成