Backend calls a custom harness

This guide connects the two sides of one scenario: an agent process that runs your own agent loop, and a product backend that sends it work. The sides use different SDKs and are documented in separate sections; this page is the only place where they meet.

Harness side: register the custom harness

The agent process runs your agent loop and registers it with BeeOS Cloud as a harness. It uses the Harness SDK only: it registers the runtime, receives the chat messages Cloud routes to it, and completes the replies. Setup and handler contracts are in the Harness SDK documentation, and Build a custom agent walks through the steps for a custom loop.

When registration succeeds the harness is listed for its instance. Note its harness ID; the backend needs it, and it is different from the instance ID.

Cloud side: send work from the product backend

The product backend uses the Cloud SDK, from trusted backend code only. Install and authenticate covers the client and the key. Select the registered harness with harnesses.list, then send it a Response whose metadata.harness_id is that ID.

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

const cloud = new BeeOSClient({
  baseURL: process.env.BEEOS_CLOUD_API_URL!, // https://api.cloud.beeos.ai/v1
  apiKey: process.env.BEEOS_API_KEY!, // bsk_…, backend only
});

// Pick the registered custom harness from the list; keep its ID in BEEOS_HARNESS_ID.
const harnesses = await cloud.harnesses.list();

const response = await cloud.responses.create({
  input: "Hello from my product",
  metadata: { harness_id: process.env.BEEOS_HARNESS_ID! },
}, crypto.randomUUID());
console.log(response.output);

A Response has its own ID, status, and output. For another turn pass previous_response_id; for background work set background: true and read progress with responses.get. The responses domain lists every operation and field, and Manage harnesses covers changing skills or applying a template from the backend. Keep the key on the backend; see product frontend integration for how a browser or mobile app gets results.