Agents

Stores conversations and runs AI assistants inside your SpacetimeDB module, with tools that can read and update your application's data.

  • TypeScript
npm i @spacetimedb/agents

This module adds AI assistant capabilities to a SpacetimeDB application, handling conversation storage, message routing to external language model providers, and tool execution that can read or write the host application's own data.

  • Customer support bots: An app that wants a support assistant with access to user account data and order history, without building a separate backend service.
  • In-game AI companions: A multiplayer game that needs persistent per-player conversations with an NPC that can query game state as a tool.
  • Multi-tenant SaaS assistants: A platform where each user gets their own conversation threads and the host controls per-user spending limits before any model call is made.
  • Operator-configurable agents: A product where non-developer administrators need to swap models, update system prompts, or rotate API keys without a code deployment.
  • Retrieval-augmented features: An application that already stores embeddings and wants to rank and retrieve relevant context to include in assistant responses.

The module stores conversations as threads and messages inside SpacetimeDB, alongside lightweight locks that prevent two model runs from operating on the same thread at once. When a user sends a message, the module queues a run, checks any quota logic the host application provides, then contacts the configured language model provider over HTTP. Responses and token usage are written back to the database as the run completes, and a background sweeper cleans up locks from runs that were interrupted.

Agents are defined in application code with a set of allowed models, a default system prompt, and a collection of tools. Each tool is a function that runs inside a SpacetimeDB transaction, so it can read or modify any table the host application owns. If a tool fails, only the current turn rolls back while earlier turns and the user's original message remain stored. Settings can be layered: the agent definition provides defaults, a thread can override the model, and an administrator can override both at runtime without redeploying.

Access control and spending limits are entirely the host application's responsibility. The module provides hooks that run before each model call, where the host can inspect the caller's identity, check a quota table, and reject the run by throwing. All conversation tables are private to the module, but the host can expose filtered views so clients only see their own threads and messages.

Related modules

Auth

Adds user accounts, password and OAuth sign-in, email verification, and session management to a SpacetimeDB module. Exposes helpers to identify the caller in reducers and HTTP routes.

SpacetimeDB0/wk

Authz

Roles, scopes and grants for multi-user modules: wildcard permissions, role inheritance, scope trees, expiring grants, invite links, an audit log and row-level security, with no privilege escalation.

Lethalchip0/wk

Cron

Schedules recurring tasks in a SpacetimeDB module using calendar expressions or fixed intervals. Supports time zones, per-job arguments, failure limits, and runtime schedule changes.

SpacetimeDB0/wk
Submodule

Edit details

One short paragraph describing the module.

A few bullets for scenarios where this is a good fit.

A few short paragraphs at the conceptual level.