跳转到主要内容
@beeos-ai/sdk 包是 BeeOS 平台 API（openapi.beeos.ai）的自动生成 TypeScript 客户端，覆盖实例生命周期管理和智能体消息调用—— 以编程方式部署智能体并向其发送消息所需的核心平台操作。
SDK 仅覆盖平台 API。A2A 协议（a2a.beeos.ai）和 MCP 协议（mcp.beeos.ai）是独立的协议入口，拥有各自的 认证方式，不包含在此 SDK 中。

​
安装

npm install @beeos-ai/sdk

​
配置

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

const config = new Configuration({
  basePath: "https://openapi.beeos.ai",
  headers: {
    Authorization: "Bearer oag_YOUR_KEY",
  },
});

const deployApi = new DeployApi(config);
const instancesApi = new InstancesApi(config);
const agentsApi = new AgentsApi(config);
本地开发时，将 basePath 设为 http://localhost:8095。

​
目录

​
列出 Provider

const providers = await deployApi.listProviders();
console.log(providers.data);
// [{ meta: { id: "default", name: "BeeOS Cloud", ... }, capabilities: { ... } }]

​
列出区域

const regions = await deployApi.listDeployRegions({ providerId: "default" });
console.log(regions.data);
// [{ id: "us-east-1", name: "US East", available: true }]

​
列出部署模型

const models = await deployApi.listDeployModels({ agentFramework: "beeos-claw" });
console.log(models.data);
// [{ id: "gpt-4o", name: "GPT-4o", tier: "premium", reasoning: false }]

​
实例

​
部署实例

const instance = await instancesApi.deployInstance({
  deployInstanceRequest: {
    name: "my-agent",
    agentFramework: "beeos-claw",
    modelPrimary: "gpt-4o",
  },
});
console.log(instance.data.id, instance.data.status);

​
列出实例

const list = await instancesApi.listInstances({
  page: 0,
  pageSize: 20,
  status: "running",
});

for (const inst of list.data) {
  console.log(inst.id, inst.name, inst.status);
}

​
获取实例

const inst = await instancesApi.getInstance({ id: "inst_abc123" });
console.log(inst.data);

​
生命周期操作

await instancesApi.startInstance({ id: "inst_abc123" });
await instancesApi.stopInstance({ id: "inst_abc123" });
await instancesApi.restartInstance({ id: "inst_abc123" });
await instancesApi.destroyInstance({ id: "inst_abc123" });

​
智能体

​
列出智能体

const agents = await agentsApi.listAgents({
  instanceId: "inst_abc123",
  limit: 20,
});

for (const agent of agents.data) {
  console.log(agent.id, agent.name, agent.status);
}

​
获取智能体详情

const agent = await agentsApi.getAgent({ agentId: "agent_abc123" });
console.log(agent.data.name, agent.data.visibility);

​
调用智能体

发送消息并接收阻塞回复： 
const reply = await agentsApi.invokeAgent({
  agentId: "agent_abc123",
  invokeAgentRequest: {
    message: "你好，你能做什么？",
  },
});

console.log(reply.data.reply);
获取流式响应，请使用原生 fetch 配合 Accept: text/event-stream： 
const res = await fetch(
  "https://openapi.beeos.ai/api/v1/agents/agent_abc123/invoke",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer oag_YOUR_KEY",
      "Content-Type": "application/json",
      Accept: "text/event-stream",
    },
    body: JSON.stringify({ message: "你好！" }),
  }
);

const reader = res.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

​
错误处理

SDK 在非 2xx 响应时会抛出异常。使用 try/catch 包装调用： 
try {
  await instancesApi.getInstance({ id: "nonexistent" });
} catch (error) {
  if (error instanceof Response) {
    const body = await error.json();
    console.error("API 错误:", body);
  }
}

​
TypeScript 类型

所有请求/响应类型均已导出： 
import type {
  InstanceDataDTO,
  DeployInstanceRequest,
  ProviderCatalogItem,
  AgentDTO,
  InvokeAgentRequest,
  InvokeAgentResponse,
} from "@beeos-ai/sdk";

​
源码与生成

SDK 从 beeos-platform-v1.yaml 使用 OpenAPI Generator（typescript-fetch）自动生成。发布的包镜像 monorepo 中的生成输出。