Skip to main content
This guide walks you from zero to a running agent that you can chat with via the BeeOS public OpenAPI. The same flow works against http://localhost:8095 for local dev or https://openapi.beeos.ai for production.

​
Prerequisites

  • A BeeOS account at beeos.ai.
  • A User API Key (oag_...) from Settings → API Keys. The key acts as a long-lived bearer credential bound to your user — see Authentication for the credential format and rotation guidance.

​
1. Install the SDK

npm install @beeos-ai/sdk
The published @beeos-ai/sdk is auto-generated from the OpenAPI contract using OpenAPI Generator (typescript-fetch). It exposes a Configuration value plus one class per OpenAPI tag — DeployApi, InstancesApi, AgentsApi, TasksApi, ConversationsApi, FilesApi. There is no BeeOS umbrella client.

​
2. Configure the 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);

​
3. List the deploy catalog

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({ agentFramework: "beeos-claw" });

​
4. Deploy an agent instance

const created = await instances.deployInstance({
  deployInstanceRequest: {
    name: "my-first-agent",
    agentFramework: "beeos-claw",
    modelPrimary: "gpt-4o",
  },
});
const instanceId = created.data!.id;
console.log(`Instance ${instanceId} — status: ${created.data!.status}`);
Provisioning takes a few seconds. Poll GET /instances/{id} until status === "running", or watch the dashboard.

​
5. Find the agent ID

A deployed instance hosts one or more agents. The agent ID is what you invoke against (an instance can be replaced without breaking your integration; the agent identity is stable). 
const list = await agents.listAgents({ instanceId, limit: 20 });
const agentId = list.data![0].id;
console.log(`Invoking agent ${agentId}`);

​
6. Invoke the agent

The blocking call returns a single JSON payload once the agent finishes its reply. For long prompts, see Streaming. 
const reply = await agents.invokeAgent({
  agentId,
  invokeAgentRequest: {
    message: "Hello — what can you do?",
  },
});
console.log("Reply:", reply.data?.text);
console.log("Channel:", reply.data?.context_id);

​
Streaming variant

Set Accept: text/event-stream on the same endpoint to receive agent_reply_delta chunks followed by a single agent_reply close frame. The SDK does not abstract SSE — drop to 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": "Tell me a short story."}'

​
6.5. Where does the invoke show up?

Each invoke creates a short-lived protocol=openapi task channel, not a conversation. List it with: 
curl -s "$BASE/api/v1/agents/$AGENT_ID/tasks?state=all" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq
GET /agents/{agentId}/conversations returns only long-lived dialog channels you opened explicitly with POST /conversations. If that list is empty right after an invoke, that is expected — see the calling agents guide for when to pick conversation vs invoke.

​
7. Clean up

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

​
Where to go next

Choosing a protocol

Decide between OpenAPI (this guide), A2A, and MCP.

Calling agents

Idempotency, attachments, tasks, conversations, error handling.

Webhooks

HMAC-signed terminal-state callbacks with retry + audit log.

A2A protocol

JSON-RPC + agent cards on a2a.beeos.ai.