> ## Documentation Index > Fetch the complete documentation index at: https://docs.beeos.ai/llms.txt > Use this file to discover all available pages before exploring further. # TypeScript SDK > Install and use @beeos-ai/sdk — the auto-generated TypeScript client for the BeeOS OpenAPI. The [`@beeos-ai/sdk`](https://www.npmjs.com/package/@beeos-ai/sdk) package is the canonical TypeScript client for the public BeeOS OpenAPI contract served by [`openapi-gateway`](/architecture/public-overview#3-what-each-surface-owns) at `openapi.beeos.ai`. It is generated from the same [`backend/openapi/beeos-platform-v1.yaml`](https://github.com/beeos-ai/openagent/blob/main/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/overview) (`a2a.beeos.ai`) and [MCP protocol](/mcp/overview) (`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 ```bash theme={null} npm install @beeos-ai/sdk ``` Current published version: **0.6.1** (see [SDK Changelog](/sdks/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. ```typescript theme={null} 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. ```typescript theme={null} 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](https://github.com/beeos-ai/openagent/blob/main/backend/Procfile.staging)). ## Catalog ```typescript theme={null} const providers = await deploy.listProviders(); const regions = await deploy.listDeployRegions({ providerId: "default" }); const models = await deploy.listDeployModels({ agentFramework: "beeos-claw" }); ``` ## Instance lifecycle ```typescript theme={null} 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: ```typescript theme={null} const list = await instances.listInstances({ page: 0, pageSize: 20, status: "running", }); ``` ## Agents ```typescript theme={null} 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](/guides/calling-agents) for the full contract. ```typescript theme={null} 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) ```typescript theme={null} 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](https://github.com/beeos-ai/openagent/blob/main/backend/docs/adr/0021-idempotency-key-ttl.md) 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](/guides/streaming) for the frame shapes: ```typescript theme={null} 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) ```typescript theme={null} 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: ```typescript theme={null} 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](/guides/webhooks)). ## Conversations ```typescript theme={null} 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](/guides/conversations). ## Files ```typescript theme={null} 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 } }`): ```typescript theme={null} 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](/reference/errors) for the full code list. ## TypeScript types Every request and response is fully typed: ```typescript theme={null} 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`](https://github.com/beeos-ai/openagent/blob/main/backend/openapi/beeos-platform-v1.yaml) using OpenAPI Generator ([`sdks/openapi-sdk/generate.sh`](https://github.com/beeos-ai/openagent/blob/main/sdks/openapi-sdk/generate.sh)). Wire-level changes land in [SDK Changelog](/sdks/changelog) and migration recipes live in [SDK Migration](/sdks/migration). * npm: [`@beeos-ai/sdk`](https://www.npmjs.com/package/@beeos-ai/sdk) * GitHub: [`beeos-ai/sdk`](https://github.com/beeos-ai/sdk)