跳转到主要内容
@beeos-ai/sdk package 是公开 BeeOS OpenAPI 契约的规范 TypeScript 客户端，契约由 openapi-gateway 在 openapi.beeos.ai 提供服务。它从同一份 backend/openapi/beeos-platform-v1.yaml 生成 —— 本站 API Reference tab 看到啥，SDK 里就是啥。
SDK 只针对 Platform API。A2A 协议 （a2a.beeos.ai）和 MCP 协议 （mcp.beeos.ai）是独立主机、独立鉴权 —— 不被本 package 包装。 对那些主机用 HTTPS 直连即可。

​
安装

npm install @beeos-ai/sdk
当前发布版本：0.4.0（wire delta 见 SDK 变更日志）。

​
配置

生成代码遵循 OpenAPI Generator typescript-fetch 模板：一个 Configuration 值 + 每个 OpenAPI tag 一个 class。 
import {
  Configuration,
  DeployApi,
  InstancesApi,
  AgentsApi,
  TasksApi,
  ConversationsApi,
  FilesApi,
} 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);
const tasks = new TasksApi(config);
const conversations = new ConversationsApi(config);
const files = new FilesApi(config);
本地开发把 basePath 设成 http://localhost:8095（ Procfile.staging 里 openapi-gw 的默认端口）。

​
Catalog

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

​
实例生命周期

const created = await instances.deployInstance({
  deployInstanceRequest: {
    name: "my-agent",
    agentFramework: "beeos-claw",
    modelPrimary: "gpt-4o",
  },
});

const inst = await instances.getInstance({ id: created.data!.id });

await instances.startInstance({ id: inst.data!.id });
await instances.stopInstance({ id: inst.data!.id });
await instances.restartInstance({ id: inst.data!.id });
await instances.destroyInstance({ id: inst.data!.id });
listInstances 支持分页 + 状态过滤： 
const list = await instances.listInstances({
  page: 0,
  pageSize: 20,
  status: "running",
});

​
智能体

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

const agent = await agents.getAgent({ agentId: "agent_abc123" });

await agents.patchAgent({
  agentId: agent.data!.id,
  patchAgentRequest: { visibility: "public" },
});

​
Invoke（阻塞）

旗舰级 per-agent 操作。完整契约见 调用智能体。 
const reply = await agents.invokeAgent({
  agentId: "agent_abc123",
  invokeAgentRequest: {
    message: "Hello, what can you do?",
  },
});
console.log("Reply:", reply.data?.text);
console.log("Channel:", reply.data?.context_id);

​
带 idempotency + 附件的 Invoke（0.4.0）

const reply = await agents.invokeAgent({
  agentId: "agent_abc123",
  invokeAgentRequest: {
    message: "Summarize the attached PDF.",
    idempotency_key: "user_42:summarize_q3_report",
    attachments: [{ file_id: "file_abc123", filename: "q3-report.pdf" }],
    metadata: { campaign: "marketing-q3" },
  },
});
idempotency_key 让调用在 TTL 窗口内可安全重试（契约见 ADR 0021）。 同 key 重复 → 相同响应、不会双重 invoke。

​
流式 Invoke（SSE）

SDK 不抽象 SSE —— 退回到 fetch + Accept: text/event-stream。 frame 形状见 流式： 
const res = await fetch(
  "https://openapi.beeos.ai/api/v1/agents/agent_abc123/invoke",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BEEOS_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "text/event-stream",
    },
    body: JSON.stringify({ message: "Tell me a long story." }),
  },
);

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

​
任务（异步 invocation）

const created = await tasks.createTask({
  agentId: "agent_abc123",
  createTaskRequest: {
    message: "Run the full Q3 audit.",
    idempotency_key: "audit_q3_2026",
  },
});
const taskId = created.data!.task_id;

// Poll
let task = await tasks.getTask({ agentId: "agent_abc123", taskId });
while (task.data?.status !== "succeeded" && task.data?.status !== "failed") {
  await new Promise(r => setTimeout(r, 2_000));
  task = await tasks.getTask({ agentId: "agent_abc123", taskId });
}

// 跨智能体列表（0.4.0 新增）
const all = await tasks.listUserTasks({ state: "running", limit: 50 });

// 取消
await tasks.cancelTask({ agentId: "agent_abc123", taskId });
需要服务端推送通知时，注册带 HMAC 签名的 webhook： 
await tasks.registerTaskWebhook({
  agentId: "agent_abc123",
  taskId,
  registerTaskWebhookRequest: {
    url: "https://example.com/hooks/beeos",
    secret: "whsec_…",
    events: ["completed", "failed", "cancelled"],
  },
});
Webhook payload 用 HMAC-SHA256 签名；投递日志可通过 listWebhookDeliveries 查询、通过 redeliverWebhook 重放（0.4.0 新端点 —— 见 Webhooks）。

​
会话

const conv = await conversations.createConversation({
  agentId: "agent_abc123",
  createConversationRequest: { title: "Quarterly planning" },
});

await conversations.sendConversationMessage({
  agentId: "agent_abc123",
  conversationId: conv.data!.conversationId,
  sendConversationMessageRequest: { message: "Start the planning session." },
});

const msgs = await conversations.listConversationMessages({
  agentId: "agent_abc123",
  conversationId: conv.data!.conversationId,
  since: 0,
});
与任务对比：任务一次性、有终止态；会话开着直到你删它。 见 会话。

​
文件

const presigned = await files.presignUpload({
  presignUploadRequest: {
    filename: "report.pdf",
    contentType: "application/pdf",
  },
});

await fetch(presigned.data!.url, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: pdfBytes,
});

// 之后回读元数据 + 一个新的签名下载 URL
const meta = await files.presignDownload({ id: presigned.data!.file_id });
把得到的 file_id 放进 invokeAgent 或 createTask 的 attachments[].file_id。

​
错误处理

非 2xx 响应抛 Response（底层 fetch Response）。 检查 .status 和 .json() 拿 BeeOS error 信封 （{ success: false, error: { code, message } }）： 
import { ResponseError } from "@beeos-ai/sdk";

try {
  await instances.getInstance({ id: "nonexistent" });
} catch (e) {
  if (e instanceof ResponseError) {
    const body = await e.response.json();
    console.error("API error:", body.error.code, body.error.message);
  } else {
    throw e;
  }
}
完整 code 列表见 错误参考。

​
TypeScript 类型

每个请求和响应都全类型化： 
import type {
  DeployInstanceRequest,
  InvokeAgentRequest,
  InvokeAgentResponse,
  TaskResponse,
  ListTasksResponse,
  ConversationResponse,
  PresignUploadRequest,
} from "@beeos-ai/sdk";

​
源码与生成

SDK 用 OpenAPI Generator （sdks/openapi-sdk/generate.sh） 从 backend/openapi/beeos-platform-v1.yaml 自动生成。wire 级变更归档在 SDK 变更日志、 迁移配方见 SDK 迁移。