Agents

An agent is a configured AI assistant hosted on Flapjack. Each agent has a system prompt that defines its behavior, a model that powers it, and optional tools that extend its capabilities.

Agent Fields

Field	Type	Description
id	string	Unique identifier (UUID)
org_id	string	Organization this agent belongs to
name	string	Display name
description	string | null	What this agent does
stable_preamble	string?	System prompt (only from getAgent(), not listAgents())
default_model	string	LLM model ID (e.g., gpt-5.4, claude-sonnet-4-6)
temperature	number?	Sampling temperature (0–1). Only from getAgent().
created_at	string	ISO 8601 timestamp
tool_profiles	ToolProfiles | null	Optional. Named tool subsets for mode-based interactions
default_profile	string | null	Optional. Default tool profile key
scheduled_tasks_enabled	boolean	Whether the agent can schedule reminders and recurring tasks
runtime_provider	string | null	Execution runtime: "tensorlake" (default) or "modal" (opt-in)

TypeScript Type

type Agent = {
  id: string;
  org_id: string;
  name: string;
  description: string | null;
  /** Populated by getAgent() but not by listAgents(). */
  stable_preamble?: string;
  default_model: string;
  /** Populated by getAgent() but not by listAgents(). */
  temperature?: number;
  created_at: string;
  published_chats?: { slug: string; is_active: boolean }[];
  computer?: ComputerConfig | { enabled: false };
  tool_profiles?: ToolProfiles | null;
  default_profile?: string | null;
  runtime_provider?: 'tensorlake' | 'modal' | null;
};

Runtime Provider

The runtime_provider field controls which execution backend handles LLM calls and tool dispatch for this agent. Flapjack currently supports two providers:

Provider	Status	Description
tensorlake	Default	Legacy runtime. All agents use this unless explicitly changed.
modal	Opt-in	New runtime built on Modal. Supports bundled Python packages and improved reliability.

You can switch an agent's runtime in the dashboard under Settings > Runtime, or via the API:

curl -X PATCH https://api.flapjack.dev/api/agents/abc-123 \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"runtimeProvider": "modal"}'

Current limitations of the Modal runtime:

• Stop button is best-effort — the active request ID is not tracked, so mid-flight cancellation relies on the abort signal.
• Tracing spans are not emitted yet. Modal-routed agents won't populate the spans table.
• Computer use in ephemeral/Tensorlake mode is not supported on Modal. Use a persistent sandbox provider (Vercel) instead.

Creating an Agent

Agents are created via the Flapjack dashboard or the API.

Via Dashboard

1. Go to Agents → Create Agent
2. Set name, description, and system prompt
3. Choose a model (default: gpt-5.4)
4. Optionally attach tools, MCP servers, knowledge, or integrations

Via API

curl -X POST https://api.flapjack.dev/api/agents \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Answers customer questions",
    "stablePreamble": "You are a helpful support agent. Be concise and accurate.",
    "defaultModel": "gpt-5.4"
  }'

📋 Copy as prompt

Create a Flapjack agent via the API called "Support Agent" with a system prompt "You are a helpful support agent. Be concise and accurate." using the gpt-5.4 model.

Via SDK

// Agents are created via dashboard or API, then accessed via SDK
const agents = await client.listAgents();
const agent = await client.getAgent('agent-id');

System Prompt

The stable_preamble field (called stablePreamble in API requests) is the system prompt. It defines the agent's personality, constraints, and behavior. Write it like any LLM system prompt:

You are a technical support agent for Acme Corp.

Rules:
- Be concise and helpful
- Only answer questions about Acme products
- If you don't know, say so
- Never share internal pricing

Supported Models

Model ID	Vendor	Best For
gpt-5.4	OpenAI	General purpose (default)
gpt-5.4-mini	OpenAI	Faster, cheaper
gpt-5.4-nano	OpenAI	High-volume, lowest cost
claude-opus-4-7	Anthropic	Deep reasoning, 1M context
claude-sonnet-4-6	Anthropic	Near-Opus quality, 1M context
claude-haiku-4-5	Anthropic	Fastest, lowest cost

Agent Capabilities

Agents can be extended with capabilities configured in the dashboard:

Capability	Description
Webhook Tools	Custom API endpoints the agent can call
MCP Servers	External tool servers via Model Context Protocol
Database Integrations	Direct Postgres/Supabase queries
Knowledge/RAG	Document upload for retrieval-augmented generation
Memory	Persistent recall and store across conversations
Web Tools	Search, research, read, and crawl the web
Computer Use	Execute code in sandboxed environments

These are configured through the dashboard and automatically available during conversations — no SDK-side configuration needed.

Next Steps

• Threads and Messages — how conversations work
• Tools — extending agent capabilities
• API: Agents — CRUD endpoints