name: openkbs description: OpenKBS AI agent development framework. Use when creating, modifying, or deploying AI agents with backend handlers (onRequest, onResponse, actions.js), frontend components (contentRender.js), or elastic services (functions, postgres, storage, pulse). Trigger keywords: openkbs, kb, agent, handler, contentRender, elastic, memory, scheduled task.

OpenKBS Development

OpenKBS is a framework for building AI-powered applications - from simple agents to full-stack platforms.

Two Usage Modes

1. Agent-Only Mode

Build a single conversational AI agent with backend handlers and custom UI.

openkbs create my-agent
openkbs push

Simplest way to get started - just an agent with memory, commands, and custom frontend.

2. Platform Mode (Full-Stack)

Build complete SaaS platforms that include agents plus additional infrastructure.

openkbs deploy          # Deploy from openkbs.json
openkbs stack status    # View deployed resources

Platform mode extends agent capabilities with:

Multiple Agents: Run several agents on one platform (in agents/ folder)
Elastic Functions: Serverless Lambda (Node.js, Python, Java)
Elastic Postgres: Managed PostgreSQL (Neon) for relational data
Elastic Storage: S3 buckets + CloudFront CDN for files
Elastic Pulse: Real-time WebSocket pub/sub
Whitelabel: Custom domains (example.com) with static site (site/ folder)

Architecture Note: The whitelabel itself is an app with its own kbId (a service agent, not user-facing). This "parent" kbId is used throughout the stack for elastic services. Each agent in agents/ has its own separate kbId.

Project Structure

Agent Structure

my-agent/
├── app/
│   ├── settings.json       # Agent configuration (model, itemTypes, MCP)
│   └── instructions.txt    # System prompt for LLM
├── src/
│   ├── Events/
│   │   ├── onRequest.js    # Pre-process user messages
│   │   ├── onResponse.js   # Parse LLM output, execute commands
│   │   ├── actions.js      # Command implementations
│   │   ├── onCronjob.js    # Scheduled periodic tasks
│   │   └── onPublicAPIRequest.js  # Webhook handler
│   └── Frontend/
│       ├── contentRender.js    # Custom React UI
│       └── contentRender.json  # Frontend dependencies
│

Platform Structure

my-platform/
├── agents/                        # Multiple AI agents
│   ├── marketing-assistant/       # Each agent has full structure
│   │   ├── app/
│   │   │   ├── settings.json
│   │   │   └── instructions.txt
│   │   └── src/
│   │       ├── Events/
│   │       │   ├── onRequest.js
│   │       │   ├── onResponse.js
│   │       │   └── actions.js
│   │       └── Frontend/
│   │           └── contentRender.js
│   └── support-agent/             # Another agent
│       ├── app/
│       └── src/
├── functions/                     # Serverless Lambda functions
│   └── api/
│       └── index.mjs
├── site/                          # Static site for whitelabel domain
│   └── index.html
└── openkbs.json                   # Elastic services config

openkbs.json

{
  "elastic": {
    "postgres": true,
    "storage": true,
    "pulse": true,
    "functions": {
      "api": { "runtime": "nodejs24.x", "memory": 512 }
    }
  }
}

Quick Commands

Agent Commands

openkbs create <name>    # Create new agent
openkbs push             # Deploy to cloud
openkbs pull             # Download from cloud
openkbs update skills    # Update this skill

Platform Commands

openkbs deploy           # Deploy all elastic services
openkbs stack status     # Show deployed resources
openkbs destroy          # Remove all resources (DANGEROUS)

Elastic Services

openkbs fn list          # List Lambda functions
openkbs fn push api      # Deploy function
openkbs fn logs api      # View function logs
openkbs postgres shell   # Connect to Postgres
openkbs storage ls       # List S3 objects
openkbs pulse status     # WebSocket status
openkbs site push        # Deploy static site

Image Generation Service

Generate images directly from CLI using OpenKBS AI services:

# Generate with GPT
openkbs service -m gpt-image -d '{"action":"createImage","prompt":"a logo"}' -o logo.png

# Generate with Gemini
openkbs service -m gemini-image -d '{"action":"createImage","prompt":"hero image"}' -o hero.png

# Edit existing image
openkbs service -m gpt-image -d '{"action":"createImage","prompt":"make it blue","imageUrls":["https://..."]}' -o edited.png

Available models:

gpt-image - OpenAI GPT Image (gpt-image-1.5)
gemini-image - Google Gemini Flash (gemini-2.5-flash-image)

Options for gpt-image:

Option	Values	Default
prompt	(required)	-
size	"1024x1024", "1024x1536", "1536x1024", "auto"	"auto"
quality	"low", "medium", "high", "auto"	"auto"
n	Number of images	1
output_format	"png", "jpg", "webp"	"png"
background	"transparent", "opaque", "auto"	"auto"
output_compression	0-100	100
imageUrls	Array of URLs for editing	-

Options for gemini-image:

Option	Values	Default
prompt	(required)	-
aspect_ratio	"1:1", "16:9", "9:16", "4:3", "3:4"	"1:1"
imageUrls	Array of URLs for reference	-

Backend Handler Pattern

Commands are XML tags with JSON content that the LLM outputs:

<commandName>{"param": "value"}</commandName>

The handler.js parses these tags, matches regex patterns in actions.js, and executes async functions:

// actions.js pattern
[/<googleSearch>([\s\S]*?)<\/googleSearch>/s, async (match) => {
    const data = JSON.parse(match[1].trim());
    const results = await openkbs.googleSearch(data.query);
    return {
        type: 'SEARCH_RESULTS',
        data: results,
        _meta_actions: ["REQUEST_CHAT_MODEL"]  // Loop back to LLM
    };
}]

Meta Actions

Control flow after command execution:

["REQUEST_CHAT_MODEL"] - Send result back to LLM for processing
[] - Display result to user, stop conversation

Memory System

Configure in settings.json:

{
  "itemTypes": {
    "memory": {
      "attributes": [
        { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
        { "attrName": "body", "attrType": "body", "encrypted": true }
      ]
    }
  },
  "options": {
    "priorityItems": [{ "prefix": "memory_", "limit": 100 }]
  }
}

Priority items are auto-injected into LLM context.

Additional Resources

Reference Documentation

reference/backend-sdk.md - Backend SDK methods (openkbs.*)
reference/frontend-sdk.md - Frontend React patterns
reference/commands.md - XML command definitions
reference/elastic-services.md - Functions, Postgres, Storage, Pulse

Ready-to-Use Patterns

Production-tested code blocks for common tasks:

Content & Media:

patterns/image-generation.md - AI image generation with upload
patterns/video-generation.md - Async video generation with polling
patterns/file-upload.md - Presigned URL file uploads
patterns/web-publishing.md - HTML page publishing

Memory & Storage:

patterns/memory-system.md - Memory CRUD with settings.json config
patterns/vectordb-archive.md - Long-term archive with semantic search

Scheduling & Automation:

patterns/scheduled-tasks.md - Task scheduling (one-time & recurring)
patterns/cronjob-batch-processing.md - Batch file processing with state
patterns/cronjob-monitoring.md - Continuous monitoring with pulse control

External Integrations:

patterns/telegram.md - Telegram bot commands (send messages)
patterns/telegram-webhook.md - Telegram webhook (receive messages)
patterns/public-api-item-proxy.md - Public API with geolocation

Complete Examples

examples/ai-copywriter-agent/ - Content generation agent
examples/ai-marketing-agent/ - Marketing automation agent
examples/monitoring-bot/ - Cronjob + Telegram monitoring agent
examples/nodejs-demo/ - Platform with elastic functions

Unnamed Skill

$ Instalar