Quickstart

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

go get github.com/beeos-ai/sdk-go

python -m pip install beeos

# No installation needed — use curl directly.

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

package main

import (
    "context"
    "fmt"
    "os"

    beeos "github.com/beeos-ai/sdk-go"
)

func main() {
    cfg := beeos.NewConfiguration()
    cfg.Servers = beeos.ServerConfigurations{
        {URL: "https://openapi.beeos.ai"},
    }
    cfg.DefaultHeader["Authorization"] = "Bearer " + os.Getenv("BEEOS_API_KEY")

    client := beeos.NewAPIClient(cfg)
    ctx := context.Background()
    _ = client
    _ = ctx
    fmt.Println("client ready")
}

import os
import beeos

configuration = beeos.Configuration(
    host="https://openapi.beeos.ai",
    access_token=os.environ["BEEOS_API_KEY"],
)

client = beeos.ApiClient(configuration)
deploy = beeos.sdk.DeployApi(client)
instances = beeos.sdk.InstancesApi(client)
agents = beeos.sdk.AgentsApi(client)

export BEEOS_API_KEY="oag_…"
export BASE=https://openapi.beeos.ai

Python users should install beeos, the stable official entry point. The complete generated OpenAPI surface remains available as beeos.sdk; see the Python SDK guide.

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

providers, _, _ := client.DeployAPI.ListProviders(ctx).Execute()
for _, p := range providers.GetData() {
    fmt.Printf("%s — %s\n", p.Meta.GetId(), p.Meta.GetName())
}

curl -s "$BASE/api/v1/providers" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

curl -s "$BASE/api/v1/deploy/regions?providerId=default" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

curl -s "$BASE/api/v1/deploy/models?agentFramework=beeos-claw" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

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

req := beeos.DeployInstanceRequest{
    Name:           "my-first-agent",
    AgentFramework: "beeos-claw",
    ModelPrimary:   "gpt-4o",
}
created, _, _ := client.InstancesAPI.DeployInstance(ctx).
    DeployInstanceRequest(req).Execute()
fmt.Printf("Instance %s — status: %s\n", created.Data.GetId(), created.Data.GetStatus())

curl -s -X POST "$BASE/api/v1/instances" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "agentFramework": "beeos-claw",
    "modelPrimary": "gpt-4o"
  }' | jq '.data'

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

list, _, _ := client.AgentsAPI.ListAgents(ctx).
    InstanceId(instanceId).Limit(20).Execute()
agentID := list.GetData()[0].GetId()

AGENT_ID=$(curl -s "$BASE/api/v1/agents?instanceId=$INSTANCE_ID&limit=20" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq -r '.data[0].id')
echo "Invoking agent $AGENT_ID"

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

reply, _, _ := client.AgentsAPI.InvokeAgent(ctx, agentID).
    InvokeAgentRequest(beeos.InvokeAgentRequest{
        Message: "Hello — what can you do?",
    }).Execute()
fmt.Println("Reply:", reply.GetData().GetText())

curl -s -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello — what can you do?"}' | jq '.data'

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.

Getting Started

Guides

Architecture

A2A Protocol

MCP

Integrations

SDKs

Reference

Prerequisites

1. Install the SDK

2. Configure the client

3. List the deploy catalog

4. Deploy an agent instance

5. Find the agent ID

6. Invoke the agent

Streaming variant

6.5. Where does the invoke show up?

7. Clean up

Where to go next

Choosing a protocol

Calling agents

Webhooks

A2A protocol

​Prerequisites

​1. Install the SDK

​2. Configure the client

​3. List the deploy catalog

​4. Deploy an agent instance

​5. Find the agent ID

​6. Invoke the agent

​Streaming variant

​6.5. Where does the invoke show up?

​7. Clean up

​Where to go next

Choosing a protocol

Calling agents

Webhooks

A2A protocol

Prerequisites

1. Install the SDK

2. Configure the client

3. List the deploy catalog

4. Deploy an agent instance

5. Find the agent ID

6. Invoke the agent

Streaming variant

6.5. Where does the invoke show up?

7. Clean up

Where to go next