FrogBot concepts

FrogBot provides an application and data layer alongside the AI SDK’s model and agent primitives. Your TypeScript configuration defines the runtime; FrogBot does not scan folders or synchronize Markdown definitions into the database.

Configuration

A typed frogbot.config.ts file registers collections, AI providers, agents, plugins, and endpoints.

Collections

FrogBot collections provide schemas, access control, hooks, and generated APIs for application data.

AI

Providers, model aliases, access rules, hooks, and telemetry run through FrogBot’s embedded gateway.

Agents

Code-defined tool loops combine instructions, a model, tools, stopping rules, and access control.

Chat

Owner-scoped chats store AI SDK UI messages and restore server-owned history on later turns.

Plugins

Config transforms add or adjust application behavior before sanitization.

Configuration drives the runtime

FrogBot loads one configuration file during startup. buildConfig validates the public surface, runs plugins, resolves chat collection roles, initializes FrogBot, creates the embedded gateway, and builds the agent registry.

import { sqliteAdapter } from '@frogbotai/db-sqlite'
import { buildConfig } from 'frogbot'

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: sqliteAdapter({
    client: { url: 'file:./frogbot.db' }
  }),
  collections: [],
  ai: {
    providers: {
      openai: true
    }
  },
  agents: [
    {
      slug: 'assistant',
      model: 'openai/gpt-4.1-mini',
      instructions: 'Help the user.'
    }
  ]
})

Collections hold application data

Collections are source-controlled schema definitions. FrogBot turns them into Local, REST, and GraphQL APIs and applies their access rules and hooks. FrogBot adds role markers for chat customization:

chat: true adopts a collection as the chat store.
message: true adopts a collection as the message store.

If agents are configured and neither role is marked, FrogBot injects default chats and messages collections. Generated FrogBot types include the final merged schemas.

Agents run tool loops

An agent is an AgentConfig object, not a database document or Markdown file. FrogBot wraps an AI SDK ToolLoopAgent, resolves its model through the gateway, checks access, and supplies a request-aware context to tools.

import { z } from 'zod'
import type { AgentConfig, Tool } from 'frogbot'

const lookup: Tool = {
  slug: 'lookup-campaign',
  description: 'Read campaign performance',
  inputSchema: z.object({ campaignId: z.string() }),
  execute: async ({ campaignId }, ctx) => {
    return ctx.frogbot.findByID({
      collection: 'campaigns',
      id: campaignId,
      req: ctx.req,
      overrideAccess: false
    })
  }
}

export const mediaBuyer: AgentConfig = {
  slug: 'media-buyer',
  model: 'openai/gpt-4.1',
  instructions: 'Analyze campaign performance before recommending changes.',
  tools: [lookup]
}

Each run has a stable runId shared by tools and AI lifecycle hooks.

Chat stores model trajectories

Authenticated agent HTTP calls create or continue owner-scoped chats. Messages retain the complete UIMessage.parts structure, including tool calls and results, so later inference sees the same trajectory rather than a flattened transcript. The server owns history. A continuation request sends chatId and only the next user message; FrogBot loads existing messages, validates them against the agent’s tools, and persists both sides of the new turn. Anonymous calls remain stateless. Local generate() calls also remain stateless unless you pass an existing chatId.

Requests connect the layers

FrogBotRequest extends FrogBot’s request with req.frogbot. Pass the same request through Local API operations and agent calls to preserve the authenticated user, transaction, locale, and hook context. Access is enforced only when overrideAccess: false. HTTP agent endpoints always enforce configured agent and collection access. Local operations default to trusted server behavior, so opt into access checks when running on behalf of a user.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Configuration

Collections

AI

Agents

Chat

Plugins

Configuration drives the runtime

Collections hold application data

Agents run tool loops

Chat stores model trajectories

Requests connect the layers

Configuration

Collections

AI

Agents

Chat

Plugins

​Configuration drives the runtime

​Collections hold application data

​Agents run tool loops

​Chat stores model trajectories

​Requests connect the layers

Configuration drives the runtime

Collections hold application data

Agents run tool loops

Chat stores model trajectories

Requests connect the layers