快速开始

本指南带你从零到一个能聊天的运行中智能体，通过 BeeOS 公开 OpenAPI 完成。同样的流程可对本地 http://localhost:8095 和生产 https://openapi.beeos.ai。

准备

一个 beeos.ai 账户。
一个用户 API Key（oag_…），到 Settings → API Keys 创建。这是长期 bearer 凭证 —— 见认证了解作用域和轮换。

1. 安装 SDK

npm install @beeos-ai/sdk

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

python -m pip install beeos

# 不需要安装 —— 直接用 curl。

已发布的 @beeos-ai/sdk 由 OpenAPI Generator（typescript-fetch）从 OpenAPI 契约自动生成。它导出一个 Configuration 值和每个 OpenAPI tag 一个 class —— DeployApi、InstancesApi、AgentsApi、TasksApi、 ConversationsApi、FilesApi。没有 BeeOS 顶层 client。

2. 配置 client

import {
  Configuration,
  DeployApi,
  InstancesApi,
  AgentsApi,
} from "@beeos-ai/sdk";

const config = new Configuration({
  basePath: "https://openapi.beeos.ai",
  headers: { Authorization: `Bearer ${process.env.BEEOS_API_KEY}` },
});

const deploy = new DeployApi(config);
const instances = new InstancesApi(config);
const agents = new AgentsApi(config);

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()
    _ = client
    _ = ctx
    fmt.Println("client ready")
}

import os
import beeos

configuration = beeos.Configuration(
    host="https://openapi.beeos.ai",
    access_token=os.environ["BEEOS_API_KEY"],
)

client = beeos.ApiClient(configuration)
deploy = beeos.sdk.DeployApi(client)
instances = beeos.sdk.InstancesApi(client)
agents = beeos.sdk.AgentsApi(client)

export BEEOS_API_KEY="oag_…"
export BASE=https://openapi.beeos.ai

Python 用户建议安装官方稳定入口 beeos。完整的 OpenAPI 生成接口仍可通过 beeos.sdk 使用，详见 Python SDK。

3. 查看部署目录

const providers = await deploy.listProviders();
console.log(providers.data?.map(p => `${p.meta?.id} — ${p.meta?.name}`));

const regions = await deploy.listDeployRegions({ providerId: "default" });
const models = await deploy.listDeployModels({ harness: "beeos-claw" });

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

curl -s "$BASE/api/v1/providers" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

curl -s "$BASE/api/v1/deploy/regions?providerId=default" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

curl -s "$BASE/api/v1/deploy/models?harness=beeos-claw" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

4. 部署一个智能体实例

const created = await instances.deployInstance({
  deployInstanceRequest: {
    name: "my-first-agent",
    harness: "beeos-claw",
    modelPrimary: "gpt-4o",
  },
});
const instanceId = created.data!.id;
console.log(`实例 ${instanceId} — 状态: ${created.data!.status}`);

req := beeos.DeployInstanceRequest{
    Name:           "my-first-agent",
    Harness: "beeos-claw",
    ModelPrimary:   "gpt-4o",
}
created, _, _ := client.InstancesAPI.DeployInstance(ctx).
    DeployInstanceRequest(req).Execute()
fmt.Printf("实例 %s — 状态: %s\n", created.Data.GetId(), created.Data.GetStatus())

curl -s -X POST "$BASE/api/v1/instances" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "harness": "beeos-claw",
    "modelPrimary": "gpt-4o"
  }' | jq '.data'

部署需要几秒钟。轮询 GET /instances/{id} 直到 status === "running"，或在 dashboard 上看。

5. 拿到智能体 ID

一个部署的实例托管一个或多个智能体。调用要用的是智能体 ID（实例可以被替换而不破坏你的集成；智能体身份是稳定的）。

const list = await agents.listAgents({ instanceId, limit: 20 });
const agentId = list.data![0].id;
console.log(`调用智能体 ${agentId}`);

list, _, _ := client.AgentsAPI.ListAgents(ctx).
    InstanceId(instanceId).Limit(20).Execute()
agentID := list.GetData()[0].GetId()

AGENT_ID=$(curl -s "$BASE/api/v1/agents?instanceId=$INSTANCE_ID&limit=20" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq -r '.data[0].id')
echo "调用智能体 $AGENT_ID"

6. 调用智能体

阻塞调用在智能体完成回复后返回一个 JSON 载荷。长 prompt 见流式。

const reply = await agents.invokeAgent({
  agentId,
  invokeAgentRequest: {
    message: "你好 —— 你能做什么？",
  },
});
console.log("回复:", reply.data?.text);
console.log("Channel:", reply.data?.context_id);

reply, _, _ := client.AgentsAPI.InvokeAgent(ctx, agentID).
    InvokeAgentRequest(beeos.InvokeAgentRequest{
        Message: "你好 —— 你能做什么？",
    }).Execute()
fmt.Println("回复:", reply.GetData().GetText())

curl -s -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "你好 —— 你能做什么？"}' | jq '.data'

流式变体

同一个端点设 Accept: text/event-stream 即可接收 agent_reply_delta 分块，最后由一个 agent_reply 关闭。SDK 不抽象 SSE —— 回落到 fetch / http.Client。

curl -N -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "讲个短故事。"}'

6.5. invoke 调用会出现在哪里？

每次 invoke 都会创建一个短生命周期的 protocol=openapi 任务通道，而不是会话。可以通过下面的命令查看：

curl -s "$BASE/api/v1/agents/$AGENT_ID/tasks?state=all" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq

GET /agents/{agentId}/conversations 只返回你通过 POST /conversations 显式创建的长生命周期对话通道。invoke 之后立即调用该接口返回空列表属于预期行为 —— 见调用智能体指南，了解何时该用 conversation 何时该用 invoke。

7. 清理

curl -s -X DELETE "$BASE/api/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq

下一步去哪

选择协议

在 OpenAPI（本指南）、A2A、MCP 之间做出选择。

调用智能体

幂等键、附件、任务、会话、错误处理。

Webhook

HMAC 签名的终态回调 + 重试 + 审计日志。

A2A 协议

a2a.beeos.ai 上的 JSON-RPC + 智能体卡片。

指南

架构

A2A 协议

MCP

集成

SDK

参考

快速开始

准备

1. 安装 SDK

2. 配置 client

3. 查看部署目录

4. 部署一个智能体实例

5. 拿到智能体 ID

6. 调用智能体

流式变体

6.5. invoke 调用会出现在哪里？

7. 清理

下一步去哪

选择协议

调用智能体

Webhook

A2A 协议

​准备

​1. 安装 SDK

​2. 配置 client

​3. 查看部署目录

​4. 部署一个智能体实例

​5. 拿到智能体 ID

​6. 调用智能体

​流式变体

​6.5. invoke 调用会出现在哪里？

​7. 清理

​下一步去哪

选择协议

调用智能体

Webhook

A2A 协议

准备

1. 安装 SDK

2. 配置 client

3. 查看部署目录

4. 部署一个智能体实例

5. 拿到智能体 ID

6. 调用智能体

流式变体

6.5. invoke 调用会出现在哪里？

7. 清理

下一步去哪