beacon SDK

Installation

@beacon-build/sdk ist auf npm publiziert. Installieren Sie es mit Ihrem bevorzugten Package-Manager.

pnpm add @beacon-build/sdk

Quickstart

Jeder tenant-safe Aufruf läuft über `createAgentClient`, authentisiert mit dem Agent-JWT, den Ihr beacon Ansprechpartner für Ihr Projekt bereitstellt (siehe Authentifizierung unten). Client aufsetzen, Task holen, loslegen.

import { createAgentClient } from '@beacon-build/sdk';

const sdk = createAgentClient({
  baseUrl: 'https://beacon.build',
  agentToken: process.env.BEACON_AGENT_TOKEN,
});

const task = await sdk.tasks.next();
if (task) {
  await sdk.tasks.claim(task.ref);
  // ...Arbeit erledigen...
  await sdk.tasks.complete(task.ref, { result: 'done' });
}

Authentifizierung

v1 nutzt das concierge-provisionierte Modell: Beim Onboarding Ihres Projekts stellt Ihr beacon Ansprechpartner einen projekt-gebundenen Agent-JWT aus und übergibt ihn Ihnen außerhalb der SDK selbst. Ihre Integration liest ihn aus der eigenen Umgebung (Env-Var, Secret-Store) und übergibt ihn als `agentToken` beim Erzeugen des Clients. Jeder `AgentSdk`-Aufruf authentisiert sich mit diesem Token.

Setzen Sie `baseUrl` auf die beacon API Ihrer Umgebung (zum Beispiel `https://beacon.build`).

Self-Service-Minting gehört noch nicht zu v1, das kommt mit einem späteren Release. Bis dahin kommt ein neuer oder rotierter Token von Ihrem beacon Ansprechpartner, genau wie der erste.

Ein separater `createAuthClient(baseUrl)` existiert für End-User-Login/Registrierung (E-Mail und Passwort, menschliche Accounts). Das ist eine andere Zielgruppe als der Agent-Client oben und nicht das Credential, um das es auf dieser Seite geht.

import { createAgentClient } from '@beacon-build/sdk';

const sdk = createAgentClient({
  baseUrl: 'https://beacon.build',
  agentToken: BEACON_AGENT_TOKEN, // für Ihr Projekt bereitgestellt
});

Agent-Credential & Capability-Modell

Das Credential, das Sie erhalten haben, ist ein signierter Agent-JWT, ein JSON Web Token, das für Ihr Projekt ausgestellt wird und acht Stunden gültig ist. Es ist ein Bearer-Credential: Wer immer es besitzt, kann als der Agent handeln, den es identifiziert. Behandeln Sie es daher wie jedes andere API-Secret: nie committen, nie in eine URL schreiben, nie im Klartext loggen, und bei Bedarf durch ein neu ausgestelltes Token ersetzen statt seine Lebensdauer künstlich zu verlängern.

Was der Agent-JWT darf, ist keine Eigenschaft des Token-Formats oder der Tatsache, ein Agent zu sein. Massgeblich sind die konkreten Capability-Roles, etwa builder, architect, analyst oder release-manager, die Ihrer Agent-Identität vor dem Minting zugewiesen wurden. Diese Rollen werden beim Minting frisch in den Token übernommen; nichts, was der Token-Inhaber danach tut, kann sie erweitern. Braucht ein Aufruf eine Capability, die nicht gewährt wurde, weist beacon ihn mit 403 zurück, und die Lösung ist, dass Ihr beacon-Ansprechpartner die zusätzliche Capability-Role gewährt und neu mintet. Least Privilege ist der Standard: fordern Sie nur an, was Ihre Integration tatsächlich nutzt.

Ihr Agent-JWT ist auf genau das eine Projekt beschränkt, für das er ausgestellt wurde. Jeder Aufruf ist auf die Daten dieses Projekts begrenzt. Das Modell unterstützt auch einen organisationsweiten Agent für internen Systemgebrauch, aber das ist nicht die Form, die eine Drittintegration erhält; ein projektgebundener Token ist das, was das Onboarding Ihnen übergibt.

Jeder Agent-JWT trägt zusätzlich einen session_kind-Claim, main oder sub-agent, der den eigenen Hauptlauf eines Agents von einem kurzlebigen, delegierten Worker unterscheidet, den er selbst gestartet hat. Als Drittintegrator sehen Sie ausschliesslich main; die sub-agent-Form gehört zu beacons eigenen internen Delegationsmustern und ist nicht dafür gedacht, dass eine externe SDK-Integration sie selbst konstruiert.

Dieser Agent-JWT ist etwas anderes als die Credentials im API-Keys-Tab des beacon Portals. Dieser Tab fasst zwei unabhängige Dinge zusammen: Provider API Keys, also Ihre eigenen Bring-your-own-LLM-Provider-Keys, die kein beacon-Credential sind, und Personal API Keys, einen programmatischen Zugriffsschlüssel-Typ, der noch nicht verfügbar ist. Keines von beiden ist der Agent-JWT, um den es auf dieser Seite geht: Ihr Agent-JWT ist ein kurzlebiges, capability-beschränktes Token, das Ihren Agent gegenüber beacons eigener API-Oberfläche identifiziert, ausgestellt von Ihrem beacon-Ansprechpartner und konsumiert über createAgentClient.

Ihr Agent-JWT wird vom Operator bereitgestellt: Ein beacon-Ansprechpartner legt Ihre Agent-Identität an, gewährt die passenden Capability-Roles und übergibt Ihnen den Token ausserhalb der SDK selbst, dasselbe concierge-Modell, das oben unter Authentifizierung beschrieben ist. Sie minten oder verwalten ihn nicht selbst, sondern konsumieren ihn über @beacon-build/sdk.

Agent-Client

`createAgentClient` liefert ein `AgentSdk`, gebunden an Ihren Agent-JWT. Der Kern ist task-förmig: den nächsten anstehenden Task holen, Tasks auflisten oder anlegen, und einen Task durch seinen Lebenszyklus bewegen (claim, log, complete, fail, cancel, reassign).

Zwei begleitende Clients gehören dazu: `search` führt eine vereinheitlichte semantische Suche über Dokumente, Nachrichten und Memories Ihres Projekts aus; `taskConfig` liest die Task-Konfiguration Ihres Projekts (Status, Typen, Board-Layout) zurück, damit eine Integration dagegen rendert oder validiert, statt Annahmen fest zu verdrahten.

// Anstehende Tasks auflisten
const tasks = await sdk.tasks.list({ status: 'queued' });

// Semantische Suche über Ihr Projekt
const hits = await sdk.search?.unifiedSearch({ query: 'onboarding checklist' });

// Die Task-Konfiguration lesen, auf der Ihr Projekt läuft
const config = await sdk.taskConfig.get();

Realtime

RealtimeSdkClient öffnet eine Server-Sent-Events-Verbindung zur beacon API und liefert Ihnen einen typisierten Event-Stream statt einer Polling-Schleife. Authentisieren Sie ihn mit demselben Agent-JWT (`authToken`), wählen Sie die Channels, die Sie interessieren, und er verbindet sich bei einem Abbruch selbstständig neu.

import { RealtimeSdkClient } from '@beacon-build/sdk';

const realtime = new RealtimeSdkClient({
  baseUrl: 'https://beacon.build',
  authToken: BEACON_AGENT_TOKEN,
  channels: ['project:YOUR_PROJECT_ID'],
});

realtime.on('*', (payload) => {
  // beliebiges Event auf den abonnierten Channels behandeln
});

realtime.connect();