Aus Code starten

Für Entwickler. Wähle im Entwicklerhandbuch zwischen API-Anbindung, App-Veröffentlichung und Projektarbeit.

Das Programm openbot deckt die meisten Bedürfnisse ab. Wenn du mehr brauchst, kannst du OpenBot aus deinem eigenen Programm starten. Dann kannst du eigene Models, Werkzeuge, Routen und Quellen für den App Index hinzufügen.

OpenBot ist mit Effect gebaut. Du baust es aus Layers zusammen. Ein Layer ist ein Rezept in Effect, das Dienste baut. Wenn du einen Layer erstellst, öffnet das weder das Netzwerk noch die Datenbank. Das passiert erst, wenn du ihn startest.

---

Das kleinste Programm

Dieses Programm macht dasselbe wie openbot:

import { Launch, Server } from "@openbot-build/openbot"

Launch.main(Server.layerLive)

Launch.main liest zuerst die Kommandozeile. Mit --help zeigt es die Hilfe und endet. Dafür braucht es keine Einstellungen. Dann liest es die Variablen aus Konfiguration, aus der Umgebung oder aus geheimen Dateien. Es sperrt ausgehende Verbindungen zu privaten Adressen und schreibt einen fehlgeschlagenen Start ins Log. Dann führt es den Layer aus, den du ihm gibst, bis der Prozess endet. Es gibt diesem Layer die Node.js-Dienste und den Fetch-HTTP-Client. Launch.server ist dasselbe Programm als Effect, wenn du es selbst ausführst. Gib ihm NodeServices.layer.

EnvironmentConfiguration.load gibt dieselben Einstellungen zurück: host, port, databaseUrl, secretKeys, clusterSecret, clusterHost und outboundAllow. Du kannst diese Werte auch im Code schreiben.

Das Programm braucht trotzdem eine Plattform. Führe das Einrichtungsprogramm einmal aus, bevor Menschen es nutzen. Siehe Platform.

Was das Paket exportiert

Export	Was es ist
Server.layerLive(options)	OpenBot mit eigenem Node.js-Server für HTTP und den echten Diensten von außen. openbot-server führt es aus.
Server.layer(options)	Derselbe Server, ohne die Dienste, die er braucht. Siehe Dienste, die OpenBot braucht.
Server.layerFixed(options)	Wie Server.layer, aber es schreibt zuerst eine Anmelde-Konfiguration in die Plattform-Einstellungen. Für Tests und Entwicklung.
Server.layerApp(options)	Die OpenBot-Routen und -Dienste, für einen HTTP-Server, den du schon hast.
Server.layerApi	Nur die HTTP-Routen.
Launch.main(make), Launch.server(make)	Führt den Layer aus make so aus wie openbot-server.
OpenBot.layerShared(options)	Die Dienste, die so lange leben wie die Instanz: der Datenbank-Pool, die geheimen Schlüssel und die gemeinsamen Einstellungen.
OpenBot.layer(options)	Die Dienste hinter den Routen: Anmeldung, Tokens, Berechtigungen, Speicher, Chats und Apps.
OpenBot.layerOutside	Die echten Dienste von außerhalb von OpenBot, zum Beispiel das Netzwerk der Apps.
OpenBot.layerLive(options)	OpenBot.layer mit den echten Diensten von außen und ohne Werkzeuge des Hosts.
HostTools	Die Werkzeuge, die dein Programm jedem Chat gibt. Siehe Ein Werkzeug hinzufügen.
DatabasePostgres	Der Datenbank-Layer und das Programm migrate.
EnvironmentConfiguration	Liest die Einstellungen der Instanz aus Umgebungsvariablen.
Auth, Chats, AppHost, AppTools, Configuration	Diensttypen für fortgeschrittene Aufbauten.

Der Unterpfad @openbot-build/openbot/Development exportiert den Entwicklungsserver. Siehe Den Entwicklungsserver starten.

---

Optionen

Server.layerLive nimmt Instanz-Optionen und App-Optionen. Server.layer und Server.layerFixed nehmen dieselben Optionen, aber nicht secretKeys, weil dein Programm ihnen die gemeinsamen Dienste gibt.

Instanz-Optionen

Option	Typ	Was es ist
host	string	Pflicht. Die Adresse, auf der der Server hört, zum Beispiel 127.0.0.1.
port	number	Pflicht. Der Port, auf dem der Server hört, zum Beispiel 3000.
databaseUrl	Redacted<string>	Pflicht. Die PostgreSQL-URL.
secretKeys	Redacted<string>	Die Liste der geheimen Schlüssel. Siehe Geheime Schlüssel.
clusterSecret	Redacted<string>	Erforderlich. Mindestens 32 Zeichen. Alle Knoten nutzen dasselbe Geheimnis für private RPC.
clusterHost	string	Optional. Die von anderen Knoten erreichbare Adresse. Standard ist die gebundene HTTP-Adresse.

Anmeldung

Der Server nimmt keine Anmelde-Optionen. Er liest den öffentlichen Origin, den Anbieter der Plattform und das Anmelde-Geheimnis aus den Plattform-Einstellungen.

• Vor der Einrichtung antwortet jede Route außer /health mit 503 und SetupRequired.
• OpenBot liest diese Einstellungen jedes Mal, wenn es sie braucht. Wenn sich eine davon ändert, nutzt schon die nächste Anfrage den neuen Wert. Der Server wird nur einmal gebaut, also gehen laufende Anfragen und Turns weiter.

Server.layerFixed nimmt eine auth-Konfiguration. Beim Start schreibt es den öffentlichen Origin, das Anmelde-Geheimnis und den Anbieter von auth in die Plattform-Einstellungen. Danach arbeitet es wie Server.layer, also wirkt auch eine spätere Änderung der Plattform-Einstellungen sofort. Tests und der Entwicklungsserver nutzen es. Jeder Server gibt die App-Dienste auch an dein Programm weiter, damit Tests sie nutzen können.

App-Optionen

Option	Was sie tut
builtinModels	Models, die jede Organisation nutzen kann, im Code angegeben. Siehe Models.
builtinModels.defaultModel	Das Model eines neuen Chats, wenn sein Bot keines nennt. Es ist eines aus builtinModels. Nur eine simulierte Plattform setzt es.
routes	Ein Layer mit deinen eigenen HTTP-Routen.
indexSources	Weitere Quellen für die Suche im App Index, neben dem OpenBot Index.
indexWork	Zeitplan des App-Index-Workers: { intervalMs, retryMs }.

Einige Werte waren früher Optionen. Jetzt sind sie Einstellungen in der Datenbank. So teilen alle Instanzen sie:

Alte Option	Einstellung
appRestrictions	appRestrictions in den Plattform-Einstellungen.
appReadRules	appReadRules in den Organisations-Einstellungen.
bots.helperModel	rulesModel und botMemoryModel in den Organisations-Einstellungen.
bots.requestTimeout	requestTimeoutMs in den Organisations-Einstellungen.
bots.memory	botMemory in den Organisations-Einstellungen.
appEncryptionKey	Die Instanz-Option secretKeys.

---

Dienste, die OpenBot braucht

OpenBot.layer, Server.layer und Server.layerFixed bauen die Dienste nicht, die von außerhalb von OpenBot kommen. Sie brauchen sie, und dein Programm gibt sie als Layers. So kann ein Test Fälschungen geben, und dein Programm kann eigene geben.

Dienste	Was sie sind	Layer für einen echten Server
Gemeinsame Dienste	Der Datenbank-Pool, die geheimen Schlüssel und die gemeinsamen Einstellungen.	OpenBot.layerShared(options)
Dienste von außen (OpenBot.Outside)	Die Treiber der Computer-Anbieter, die Live-Backends, die Leser der Passwort-Manager, das Netzwerk und die Prüfung der Apps, die DNS-Prüfung von Domains, das öffentliche Netzwerk des App Index und das Finden von Apps.	OpenBot.layerOutside
Werkzeuge des Hosts (HostTools)	Die Werkzeuge, die dein Programm jedem Chat gibt.	HostTools.none
Plattform-Dienste	Dateien, Pfade, Zufallszahlen und der HTTP-Client.	NodeServices.layer und FetchHttpClient.layer

Server.layerLive gibt alle davon außer den Plattform-Diensten. Launch.main gibt die Plattform-Dienste. Dieses Programm macht dasselbe wie Launch.main(Server.layerLive), und jeder Teil ist zu sehen:

import { HostTools, Launch, OpenBot, Server } from "@openbot-build/openbot"
import { Layer } from "effect"

Launch.main((settings) =>
  Server.layer(settings).pipe(
    Layer.provide(Layer.merge(OpenBot.layerOutside, HostTools.none)),
    Layer.provideMerge(OpenBot.layerShared(settings)),
  ),
)

Die Optionen chats, discovery, computerDrivers, liveBackends, vaultReaders, appProbe, appNetwork, domainControl und indexPublicNetwork gibt es nicht mehr. Gib an ihrer Stelle die Dienste.

---

Chats

Models kommen von den Model Providers in der Datenbank und aus builtinModels. Siehe Models. Bot Memory folgt botMemory in den Organisations-Einstellungen.

Der Server hält Dienste der Anwendung und aktive Ausführungen. Jeder Turn baut Model und Werkzeuge in seinem eigenen Scope. Die gespeicherte Identität hält Mitglied, ursprüngliches Token, Bot und die Grenzen der Delegation. Anfragen halten keine Laufzeit eines Mitglieds offen. Pro Chat darf ein Turn zugleich vorankommen. Befehle, gespeicherte Schritte, Ereignisse und Ergebnisse bleiben über Knoten und Neustarts hinweg in PostgreSQL. Das Schließen eines HTTP-Streams beendet die Beobachtung. Ein Abbruch braucht einen eigenen Befehl.

Ein Werkzeug hinzufügen

Ein Werkzeug (Tool) ist eine Funktion, die das Model aufrufen kann. Erstelle es mit Effect AI. Gib dann das Toolkit und seine Handler mit HostTools.layer an OpenBot. Jeder Turn jedes Chats kann das Werkzeug aufrufen. handlers bekommt die ID des Chats und gibt die Handler für seine Turns. Jeder Turn baut sie, wenn er startet, und schließt sie, wenn er endet.

import {
  type Configuration,
  HostTools,
  Launch,
  OpenBot,
  Server,
} from "@openbot-build/openbot"
import { DateTime, Effect, Layer, Schema } from "effect"
import { Tool, Toolkit } from "effect/ai"

const CurrentTime = Tool.make("CurrentTime", {
  description: "Returns the current time on the server.",
  parameters: Schema.Struct({}),
  success: Schema.String,
})
const toolkit = Toolkit.make(CurrentTime)
const handlers = toolkit.toLayer({
  CurrentTime: () => Effect.map(DateTime.now, DateTime.formatIso),
})

const server = (settings: Configuration.Settings) =>
  Server.layer(settings).pipe(
    Layer.provide(
      Layer.merge(
        OpenBot.layerOutside,
        HostTools.layer({ toolkit, handlers: () => handlers }),
      ),
    ),
    Layer.provideMerge(OpenBot.layerShared(settings)),
  )

Launch.main(server)

Füge needsApproval: true zu Tool.make hinzu, wenn jeder Aufruf eine Entscheidung braucht. OpenBot prüft dann dafür die Fähigkeit tools.call. Wenn der Aufruf einen Entscheider braucht, bekommt der Bot ein wartendes Ergebnis, und der Aufruf läuft später, wenn er erlaubt wird. Siehe Requests.

---

Deine eigenen Routen

routes fügt demselben Server HTTP-Routen hinzu. Es ist ein Layer. Der Layer kann den Dienst Auth nutzen, um das Anmelde-Cookie zu prüfen.

import { HttpRouter, HttpServerResponse } from "effect/http"

const routes = HttpRouter.add(
  "GET",
  "/status",
  HttpServerResponse.text("ready"),
)

Server.layerLive({ ...settings, routes })

Nutze keine Pfade unter /auth/ oder /v1/. Sie gehören OpenBot.

Deinen eigenen HTTP-Server nutzen

Server.layerApp(options) gibt die OpenBot-Routen und -Dienste. Es braucht dieselben Dienste wie Server.layer. Server.layerApi gibt nur die OpenBot-Routen. Es fügt auch Fehler-Logs für fehlgeschlagene Anfragen hinzu.

Server.layerLive, Server.layer und Server.layerFixed starten ihren eigenen Node.js-Server. Wenn du OpenBot in einen Server einbauen willst, den du schon hast, baue dieselben Teile selbst. Lies packages/openbot/src/app/Server.ts, um zu sehen, wie Server.layer die App einmal baut und vor der Einrichtung mit SetupRequired antwortet. Bewahre das Anmelde-Geheimnis in den Plattform-Einstellungen auf, nicht in deiner eigenen Umgebungsvariable. Jede Instanz muss dasselbe nutzen.

---

Die Datenbank migrieren

DatabasePostgres.migrate bereitet das Schema und die erste Datenprüfung vor. Nur eine leere Datenbank kann dadurch bereit sein. Nutze für ein vollständiges Upgrade den Wartungsbefehl. Er braucht OPENBOT_DATABASE_URL und OPENBOT_SECRET_KEYS. Stoppe vorher alle Instanzen. OpenBot.layerShared prüft Schema und abgeschlossene Datenversion, bevor es Dienste startet. Seine gemeinsame Sperre bleibt für die ganze Serverlaufzeit offen. Die Schritte für Sicherung und Wiederherstellung stehen unter Deploy.

pnpm --filter @openbot-build/openbot migrate

Den Entwicklungsserver starten

pnpm dev startet den Entwicklungsserver. Er hat ein lokales Testkonto, simulierte Models und eine simulierte App. Ein Projekt, das auf OpenBot aufbaut, kann denselben Server aus seinem eigenen Programm starten:

import { NodeRuntime } from "@effect/platform-node"
import * as Development from "@openbot-build/openbot/Development"

NodeRuntime.runMain(Development.launch)

Development.launch liest dieselben Einstellungen wie Launch.main und OPENBOT_DEV_PUBLIC_ORIGIN. Wenn die Variablen OPENBOT_DEV_S3_* gesetzt sind, nutzt es diesen lokalen Objektspeicher für Dateien und legt seinen Bucket an. Development.layer ist der Server ohne diese Schritte. Er braucht die Plattform-Dienste, zum Beispiel NodeServices.layer und FetchHttpClient.layer, und Development.launch gibt sie ihm. Er schreibt die Plattform-Einstellungen selbst. Darum braucht er kein Einrichtungsprogramm. Development.developmentSecret macht das Anmelde-Geheimnis aus dem ersten geheimen Schlüssel. So bleibt es nach einem Neustart gleich. Nutze den Entwicklungsserver nie in der Produktion. Jeder, der ihn erreicht, kann sich anmelden.

Fehler-Logs an deinen eigenen Dienst senden

OpenBot schreibt Fehlschläge als Fehler-Logs. Füge deinen eigenen Effect-Logger hinzu, um sie an einen anderen Dienst zu senden. Was jedes Log enthält, und ein vollständiges Beispiel, findest du unter Fehler-Logs.