The fxbot object

What createFxbot resolves to: every call on bots, chats, providers, settings, the library, and add-ons.

Every call returns a promise, unless its row says it is synchronous. A call that fails throws an Error with a status, as in Errors. A bot id is 12 hex characters: another shape fails with 400, and an unknown bot with 404.

Bots

The fields of a bot:

Other keys are ignored. An update also takes pinned:

• pinned: true fails with 400 when maxPinned (3) bots are pinned already.
• A new provider without a new model sets model to "".
• A new provider for a bot with a chat compacts the chat. The old provider summarizes it, or, when it can't, the new one summarizes the stored messages. The bot starts a new chat from that summary, its handoff, and the old chat moves to earlier. This fails with 400 when the old provider can't summarize and the new one has no model, and with 502 when neither provider could summarize.
• provider: "" fails with 400 for a bot with a chat.

Memories

memoryId is a memory's id, or mem:<id>. An unknown one fails with 404. See Work with memories.

Chat

send takes a Message:

• text is required, unless the message has files.
• messageId is 1 to 128 letters, digits, ., _, or -. The same messageId again reaches the same turn and runs nothing new.
• files is up to 8 { name, type, data }, with data in base64. An image is PNG, JPEG, GIF, or WebP, checked by its bytes: at most 3.75 MiB each, and 6 MiB for a message's images together. Any other file must be UTF-8 text with no NUL. It goes to the model as text, under its name. Every file is saved to the library, tagged with the bot and its chat.
• $name anywhere in the text, or /name at its start, names one of the bot's skills. That skill's instructions go with the message.
• It fails with 400 when the bot has no provider, or no model of its own and no default model on its provider.
• The first message starts the bot's chat and sets its sessionId.

stream:

• A line is one of libfx's stream lines. Its fields are the client's StreamLine.
• A turn_start for a message with files or skills carries the input and files that fxbot saved, which libfx's line lacks.
• cursor is a whole number, or the call fails with 400. 0 replays the whole chat. Each line's cursor is where to start again to get the lines after it.
• For a bot with no chat yet, or whose provider is gone, the stream ends at once.

See Stream replies.

Providers

The kinds are in Providers and the kinds table.

providers.add takes a NewProvider:

• kind is a key kind or a server kind. chatgpt, grok, and vercel are added by signing in, and fail here with 400.
• baseUrl is fixed for a key kind. A server kind takes one, or uses its default, and custom needs one. It is https, or http on localhost, 127.0.0.1, or [::1], with no credentials, query, or fragment.
• apiKey is required for a key kind, optional for custom, and up to 4,096 characters. The check lists the provider's models with it. A 401 or 403 fails with 400, "The provider rejected this key." A 404 passes.
• name defaults to the kind's label. model is the default model for the provider's bots. contextWindow is for server kinds only: a whole number of tokens, or null. It overrides what the server reports.

providers.update fails with 400 for apiKey on a kind that signs in, and for baseUrl on a kind that isn't a server. A new key, address, or team drops the kept model list.

Sign-ins

A device code sign-in adds a ChatGPT plan, a Grok plan, or a Vercel account. See Connect providers.

A new Vercel account with one team gets that team.

Settings

• remote needs both embeddingProvider and embeddingModel, or the update fails with 400.
• A new remote source embeds a test string first. If that fails, the update fails with 400, and the old settings stay.
• A change to memory search's fields starts filling in vectors again, in the background.

settings.embedding() gives the model in use, or null when vectors are off or the embedder doesn't answer, the fill-in's last error, and the counts. fxbot's server adds local, switching, and canSwitch, which make an EmbeddingStatus.

Library

An item's url is /api/library/<id>/file, a route of fxbot's server.

Add-ons

Remote MCP servers and skills. See Give bots tools.

An AddonRef is one of:

A server's allowed starts as its read-only tools. A header value is one line, up to 8 KiB, for a header the server was added with.

OAuth

oauth signs in to a server whose auth is oauth.

origin is the page's origin, which the server has checked against its own host.

Release and close

Tools every bot gets

Every agent has these tools. Each one acts for the bot whose chat runs it.

A bot's instructions on each turn are its own, then its handoff, its newest memories in up to 2% of the model's context window, and the list of its skills in up to 1%.

Exports

From @fxbot/sdk, besides createFxbot:

Every type the calls take or return is exported too, with FxbotOptions and Fxbot, the type of this object. Turn and Part come from @fxbot/sdk/client.

Types

type Fields = { name: string; instructions: string; model: string; provider: string; shape: Shape; color: Color };

type Profile = Fields & {
  id: string;
  sessionId: string | null; // the current chat, from the first message
  preview: string | null; // the start of the latest reply
  handoff: string | null; // the summary a provider switch carried over
  busy: boolean; // a turn runs in this process
  pinned: boolean;
};

type Message = { text: string; messageId: string; files?: Upload[] };
type Upload = { name: string; type: string; url?: string; data?: string }; // data: base64 on the way in

type Provider = {
  id: string;
  kind: Kind;
  name: string;
  baseUrl: string | null;
  model: string;
  contextWindow: number | null;
  teamId: string | null;
  hasKey: boolean;
  signedIn: boolean;
  error: string | null; // why its agent didn't start
};

type Settings = { defaultProvider: string; embedder: "local" | "remote" | "off"; embeddingProvider: string; embeddingModel: string; messageVectors: number };

type EmbeddingStatus = {
  model: string | null;
  error: string | null;
  messages: number;
  withVectors: number;
  memories: number;
  memoriesWithVectors: number;
  local: "cpu" | "gpu" | "off" | null; // from fxbot's server
  switching: { to: "cpu" | "gpu" | "off"; error?: string } | null; // from fxbot's server
  canSwitch: boolean; // from fxbot's server
};

type Memory = {
  id: string;
  text: string;
  savedBy: "bot" | "owner";
  messageId: string | null; // the msg:<id> that chat_history knows, of the turn that saved it
  createdAt: string;
  updatedAt: string;
};