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

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;
};

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