TypeScript SDK

The @beeos-ai/sdk package is the canonical TypeScript client for the public BeeOS OpenAPI contract served by openapi-gateway at openapi.beeos.ai. It is generated from the same backend/openapi/beeos-platform-v1.yaml that powers this site’s API Reference tab — what you see in the spec is what you get in the SDK.

The SDK targets the Platform API only. The A2A protocol (a2a.beeos.ai) and MCP protocol (mcp.beeos.ai) are separate hosts with their own auth — they are not wrapped by this package. Mix-and-match by issuing direct HTTPS requests against those hosts.

Install

npm install @beeos-ai/sdk

Current published version: 0.6.1 (see SDK Changelog for wire deltas).

Stable task facade (recommended)

Version 0.6.0 adds BeeOSClient, a hand-maintained facade for the common agent-task lifecycle. Its API remains stable when the generated OpenAPI surface is regenerated.

import { BeeOSClient } from "@beeos-ai/sdk";

const client = new BeeOSClient({
  apiKey: process.env.BEEOS_API_KEY!,
  baseUrl: "https://openapi.beeos.ai",
});

const agents = await client.listAgents();
const created = await client.createTask(agents[0].id, {
  message: "Summarize the latest device status.",
});
const task = await client.getTask(agents[0].id, created.data.taskId);
await client.cancelTask(agents[0].id, created.data.taskId);

client.taskEvents(agentId, taskId) is an async generator for the task SSE stream. The full generated API remains available through the package root and the explicit @beeos-ai/sdk/facade export.

Full generated client

The generated code follows the OpenAPI Generator typescript-fetch template: one Configuration value plus one class per OpenAPI tag.

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

For local development, set basePath to http://localhost:8095 (the default openapi-gw port in Procfile.staging).

Catalog

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

Instance lifecycle

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 supports pagination + status filter:

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

Agents

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

The flagship per-agent operation. See Calling agents for the full contract.

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

Invoke with idempotency + attachments (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 makes the call safe to retry within the TTL window (see ADR 0021 for the contract). Repeat the same key → identical response, no double-invocation.

Streaming invoke (SSE)

The SDK does not abstract SSE — fall back to fetch with Accept: text/event-stream. See Streaming for the frame shapes:

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

Tasks (async 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 !== "completed" && task.data?.status !== "failed") {
  await new Promise(r => setTimeout(r, 2_000));
  task = await tasks.getTask({ agentId: "agent_abc123", taskId });
}

// Or list cross-agent (new in 0.4.0)
const all = await tasks.listUserTasks({ state: "running", limit: 50 });

// Cancel
await tasks.cancelTask({ agentId: "agent_abc123", taskId });

For server-push notifications, register a webhook with HMAC signing:

await tasks.registerTaskWebhook({
  agentId: "agent_abc123",
  taskId,
  registerTaskWebhookRequest: {
    url: "https://example.com/hooks/beeos",
    secret: "whsec_…",
    events: ["completed", "failed", "cancelled"],
  },
});

The webhook payload is HMAC-SHA256 signed; the delivery log is queryable via listWebhookDeliveries + replayable via redeliverWebhook (new endpoints in 0.4.0 — see Webhooks).

Conversations

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

Compare against tasks: tasks are single-shot with a terminal state; conversations stay open until you delete them. See Conversations.

Files

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

// Later: read back metadata + a fresh signed download URL
const meta = await files.presignDownload({ id: presigned.data!.file_id });

Use the resulting file_id in attachments[].file_id on invokeAgent or createTask.

Error handling

Non-2xx responses throw Response (the underlying fetch Response). Inspect .status and .json() for the BeeOS error envelope ({ 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;
  }
}

See Error reference for the full code list.

TypeScript types

Every request and response is fully typed:

import type {
  DeployInstanceRequest,
  InvokeAgentRequest,
  InvokeAgentResponse,
  TaskResponse,
  ListTasksResponse,
  ConversationResponse,
  PresignUploadRequest,
} from "@beeos-ai/sdk";

Source and generation

The SDK is auto-generated from backend/openapi/beeos-platform-v1.yaml using OpenAPI Generator (sdks/openapi-sdk/generate.sh). Wire-level changes land in SDK Changelog and migration recipes live in SDK Migration.

npm: @beeos-ai/sdk
GitHub: beeos-ai/sdk

Getting Started

Guides

Architecture

A2A Protocol

MCP

Integrations

SDKs

Reference

TypeScript SDK

Install

Stable task facade (recommended)

Full generated client

Catalog

Instance lifecycle

Agents

Invoke (blocking)

Invoke with idempotency + attachments (0.4.0)

Streaming invoke (SSE)

Tasks (async invocation)

Conversations

Files

Error handling

TypeScript types

Source and generation

​Install

​Stable task facade (recommended)

​Full generated client

​Catalog

​Instance lifecycle

​Agents

​Invoke (blocking)

​Invoke with idempotency + attachments (0.4.0)

​Streaming invoke (SSE)

​Tasks (async invocation)

​Conversations

​Files

​Error handling

​TypeScript types

​Source and generation

Install

Stable task facade (recommended)

Full generated client

Catalog

Instance lifecycle

Agents

Invoke (blocking)

Invoke with idempotency + attachments (0.4.0)

Streaming invoke (SSE)

Tasks (async invocation)

Conversations

Files

Error handling

TypeScript types

Source and generation