# Kopern — AI Agent Builder, Orchestrator & Grader (Full Reference)

> The open-source platform to build, grade, optimize, and deploy AI agents — no code required. 130+ features shipped. Self-hosted via Docker.

## Platform Overview

Kopern is a SaaS platform for creating production-grade AI agents. Unlike simple chatbot builders, Kopern provides:
1. **Full tool calling** — agents execute custom JavaScript functions, fetch HTTP, run Python/Node/Bash code
2. **Deterministic grading** — 6 criterion types validate agent behavior with scheduled monitoring
3. **Self-optimization** — 6 AutoResearch modes automatically improve prompts
4. **Visual multi-agent orchestration** — React Flow v12 editor with drag-and-drop nodes
5. **External deployment** — 5 connectors + MCP protocol for IDE integration
6. **Service connectors** — agents read/send emails and manage calendars via OAuth
7. **Agent memory** — persistent cross-session memory with context compaction
8. **EU AI Act compliance** — automated compliance reports and tool approval

## Agent Configuration

Each agent has:
- **System Prompt**: Core behavior instructions (auto-injected with current date/time)
- **Model**: Choose from 30+ LLMs across 5 providers
- **Skills**: Markdown templates injected as XML context (reusable knowledge blocks)
- **Custom Tools**: JSON Schema input + sandboxed JS code — agents call these like functions
- **Built-in Tools**: web_fetch, code_interpreter, memory, email, calendar, GitHub, bug management
- **Extensions**: Lifecycle hooks triggered on 30+ events (tool_call_start, tool_call_end, message_sent, etc.)
- **Purpose Gate**: A question asked at session start to scope the conversation
- **TillDone Mode**: Agent keeps working until the task is complete (auto-prompting)
- **Branding**: Custom icons (15 options) and theme/accent colors per agent
- **Tool Overrides**: Temperature, max tokens, thinking level per agent
- **Memory Config**: Enable persistent memory, set max entries (LRU eviction), compaction threshold
- **Tool Approval Policy**: auto / confirm_destructive / confirm_all (EU AI Act Art. 14)
- **Connected Repos**: GitHub repositories accessible via OAuth

## Templates

### General Templates (28)
Ready-to-deploy agent configurations for common tasks: PR Review, Contract Analyzer, Customer Support, Lead Qualifier, Content Writer, Data Analyst, and more. Each includes system prompt, tools with real executable code, and grading suite.

### Vertical Business Templates (9)
Industry-specific templates with onboarding questionnaire:
- **BTP / Construction**: Quote estimation, appointment scheduling
- **Accounting**: Expense categorization, VAT checking, anomaly detection
- **Real Estate**: Price estimation, comparable search, buyer qualification
- **Restaurant**: Reservation management, menu recommendations
- **E-commerce**: Order tracking, product suggestions, FAQ
- **HR / Recruitment**: CV parsing, candidate scoring, interview scheduling
- **Beauty Salon**: Appointment booking, service recommendations
- **Fitness**: Program creation, nutrition tracking
- **Legal**: Contract analysis, risk flagging, clause extraction

## LLM Providers & Models

| Provider | Models | Tool Calling |
|----------|--------|-------------|
| Anthropic | Claude Opus 4.6, Sonnet 4.6/4.5, Haiku 4.5 | Native tool_use blocks |
| OpenAI | GPT-5.x (5.4, 5.3, 5.2, 5.1, 5), GPT-4o, GPT-4.1, o3/o4 | Function calling |
| Google | Gemini 2.5 Pro, 2.5 Flash, 2.0 Flash | functionCall |
| Mistral AI | Mistral Large 3, Small 4, Medium 3.1, Magistral, Codestral, Devstral | Function calling |
| Ollama | Any local model (Llama, Mixtral, etc.) | Via OpenAI-compatible API |

All models support streaming via SSE (Server-Sent Events).
Key rotation failover: up to 5 keys per provider, automatic retry on 429/rate_limit/overloaded.

## Built-in Agent Tools

### web_fetch
Server-side HTTP fetch in Vercel process. Supports GET/POST/PUT/DELETE with custom headers. HTML-to-text extraction. Anti-loop protection blocks requests to Kopern domains. 30s timeout.

### code_interpreter
Python, Node.js, and Bash execution via GCP Cloud Run (FastAPI + Docker).
- Pre-installed: numpy, pandas, matplotlib, requests, beautifulsoup4
- Auto-scale 0→10 instances, 300s timeout
- Output files via OUTPUT_DIR environment variable

### Agent Memory (4 tools)
- `remember(key, value, category)` — Store a fact (upsert, LRU eviction at maxEntries)
- `recall(query, limit)` — Search memories by keyword with temporal decay scoring
- `forget(key)` — Delete a memory
- `search_sessions(query, limit)` — Search across recent conversation sessions

Top 20 memories auto-injected into system prompt via `<agent-memory>` XML block.

### Email Tools (3 tools, via OAuth)
- `read_emails(query, maxResults)` — Search inbox (Gmail API / Microsoft Graph)
- `send_email(to, subject, body)` — Send email (destructive, requires approval)
- `reply_email(messageId, body)` — Reply to email (destructive)

### Calendar Tools (5 tools, via OAuth)
- `list_events(startDate, endDate)` — List calendar events
- `check_availability(startDate, endDate)` — Check free/busy slots
- `create_event(title, start, end, attendees)` — Create event (destructive)
- `update_event(eventId, changes)` — Update event (destructive)
- `cancel_event(eventId)` — Cancel event (destructive)

Daily limits: 20 emails/day, 10 events/day per agent. Tokens encrypted AES-256-GCM.

### Social Media Tools (9 tools, Bluesky AT Protocol)
- `social_create_post(text, images?)` — Publish a post to Bluesky
- `social_create_thread(posts[])` — Publish a multi-post thread
- `social_read_feed(limit?)` — Read the home feed
- `social_get_metrics(postUri)` — Get engagement metrics (likes, reposts, replies)
- `social_search_mentions(query, limit?)` — Search for mentions and keywords
- `social_reply(postUri, text)` — Reply to a post
- `social_delete_post(postUri)` — Delete a post (destructive)
- `social_get_profile(handle?)` — Get user profile info
- `social_list_connected()` — List connected social accounts

Credentials encrypted AES-256-GCM. Daily limits per platform. Destructive tools require approval.

### Image Generation
- `image_generation(prompt, aspect_ratio?)` — Generate images via Google Gemini (gemini-3.1-flash-image-preview)
- 10 aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
- Images uploaded to Firebase Storage, URL returned in tool result

### GitHub Tools
- `read_file(repo, path)` — Read file from connected repo
- `search_files(repo, query)` — Search across repo
- `create_branch(repo, branch)` — Create branch (destructive)
- `commit_files(repo, branch, files, message)` — Commit changes (destructive)
- `create_pull_request(repo, title, body, branch)` — Open PR (destructive)

## Grading System

6 criterion types for automated agent evaluation:
1. **output_match**: Exact or fuzzy text matching
2. **schema_validation**: JSON Schema validation of agent output
3. **tool_usage**: Verify the agent called specific tools with expected parameters
4. **safety_check**: Ensure agent doesn't produce harmful content
5. **custom_script**: Run arbitrary JavaScript assertions
6. **llm_judge**: Use another LLM to evaluate quality with custom rubric

### Scheduled Grading
- Vercel Cron with configurable schedule (daily/weekly/custom)
- Score drop alerts: notify when score decreases by more than X points
- Threshold alerts: notify when score falls below minimum
- 3 alert channels: email, Slack webhook, custom webhook
- Auto-generates improvement notes after each run

### AutoResearch — Optimization Lab (6 modes)

| Mode | Purpose | How it works |
|------|---------|-------------|
| AutoTune | Optimize prompts | Hill-climbing via LLM-guided mutations against grading suite |
| AutoFix | Fix failures | Diagnose failed test cases → generate patches → re-evaluate |
| Stress Lab | Red team | 3 phases: Probe → Exploit → Harden. Categories: injection, jailbreak, hallucination, edge cases |
| Tournament | Compare configs | Head-to-head model/prompt comparison with ELO-like scoring |
| Distillation | Reduce cost | Transfer quality from expensive to cheap models |
| Evolution | Multi-dimensional | Population-based genetic search across prompt x model x config |

AutoFix is self-sufficient: generates its own grading suite if none exists, runs grading, analyzes failures, patches prompt — all in one click.

## Visual Multi-Agent Orchestration

### Flow Editor (React Flow v12)
- 5 node types: Agent, Condition, Trigger, Output, Export
- Drag-and-drop from palette to canvas
- Double-click any node to edit configuration
- Full agent config editing without leaving the page (nested dialog)
- Agent branding (icons + colors) visible on nodes
- Runtime status updates during execution (idle/running/completed/failed)
- Auto-layout: parallel, sequential, conditional arrangements
- Export node: JSON, CSV, Markdown, PDF with auto-download option

### Team Features
- **Kanban Board**: 6-column drag-drop task management
- **Goal Tree**: Collapsible goal hierarchy with progress bars
- **Org Chart**: SVG organizational chart with Buchheim-Walker layout
- **Routine Scheduler**: CRON-based recurring team tasks
- **Activity Timeline**: 8-action audit trail
- **Budget Enforcer**: Team spend tracking and limits
- **delegate_task tool**: Coordinator agents delegate to specialists

### Pipelines
- Sequential chains where step N's output becomes step N+1's input
- Input/output mapping between steps
- Each step can use different tools and models

## External Connectors

### Embeddable Chat Widget
```html
<script src="https://kopern.ai/api/widget/script" data-key="kpn_xxx"></script>
```
- Shadow DOM for CSS isolation
- SSE streaming responses
- Markdown rendering (headers, code blocks, lists, links, tables)
- Mobile-responsive (full-screen < 640px)
- "Powered by Kopern" badge (removable on Pro+)
- CORS whitelist per widget
- Custom welcome message, position, branding

### Webhooks
**Inbound**: External services send JSON to your agent
```
POST /api/webhook/{agentId}?key=kpn_xxx
Content-Type: application/json

{"message": "New order received", "data": {...}}
→ {"response": "Order processed...", "metrics": {...}}
```

**Outbound**: Agent fires webhooks on events
- Events: `message_sent`, `tool_call_completed`, `session_ended`, `error`
- HMAC-SHA256 signing via `X-Webhook-Signature` header
- Compatible with n8n, Zapier, Make (step-by-step integration guides included)

**Anti-loop protection**: Inbound webhooks never trigger outbound webhooks.

### Slack Bot
- OAuth install flow via dashboard
- Responds to @mentions and DMs
- Thread support (maintains conversation context)
- Conversational tool approval (agent asks permission before destructive actions)
- Events API (serverless-compatible, uses `after()` from next/server)

### Telegram Bot
- Bot API via webhook
- Setup: enter bot token in dashboard → automatic webhook registration
- Markdown → HTML conversion for rich formatting (tables, code, bold, links)
- Conversational tool approval
- Async processing via `after()`

### WhatsApp
- Meta Cloud API (Business)
- Phone number + access token setup in dashboard
- Webhook verification (hub.verify)
- Conversational tool approval

### MCP Protocol (Model Context Protocol)
Any Kopern agent works as an MCP server:
```json
{
  "mcpServers": {
    "my-agent": {
      "type": "http",
      "url": "https://kopern.ai/api/mcp/server",
      "headers": { "Authorization": "Bearer kpn_..." }
    }
  }
}
```
- Streamable HTTP transport (MCP spec 2024-11-05)
- Compatible with Claude Code, Cursor, Windsurf, and any MCP client
- **32 tools** covering the full agent lifecycle:
  - **Agent CRUD**: `kopern_create_agent`, `kopern_get_agent`, `kopern_update_agent`, `kopern_delete_agent`, `kopern_list_agents`
  - **Templates**: `kopern_list_templates`, `kopern_deploy_template` (1-click deploy with skills, tools, grading)
  - **Chat**: `kopern_chat` (agent-bound key), `kopern_agent_info` (agent-bound key)
  - **Grading**: `kopern_grade_prompt` (inline), `kopern_create_grading_suite`, `kopern_run_grading`, `kopern_get_grading_results`, `kopern_list_grading_runs`
  - **Optimization**: `kopern_run_autoresearch` (AutoTune iterative prompt optimization)
  - **Teams & Pipelines**: `kopern_create_team`, `kopern_run_team`, `kopern_create_pipeline`, `kopern_run_pipeline`
  - **Connectors**: `kopern_connect_widget`, `kopern_connect_telegram`, `kopern_connect_whatsapp`, `kopern_connect_slack`, `kopern_connect_webhook`, `kopern_connect_email`, `kopern_connect_calendar`
  - **Monitoring**: `kopern_list_sessions`, `kopern_get_session`, `kopern_manage_memory`, `kopern_compliance_report`, `kopern_get_usage`
  - **Portability**: `kopern_export_agent`, `kopern_import_agent`
- Two key types: **user-level** (30 platform tools, no agent needed) and **agent-bound** (all 32, includes chat)
- Self-hosted deployment via Docker (docker-compose + Ollama + Firebase emulator)
- API key authentication (`kpn_` prefix, SHA-256 hashed, expiry support, rotation)

## Service Connectors (OAuth)

### Google
- Gmail: read, send, reply emails
- Google Calendar: list events, check availability, create/update/cancel

### Microsoft
- Outlook: read, send, reply emails
- Microsoft Graph Calendar: list events, check availability, create/update/cancel

Tokens encrypted with AES-256-GCM. Auto-refresh on expiry. Daily limits enforced.
GDPR cleanup endpoint for token revocation.

## Operator Dashboard

Simplified view for non-technical users:
- **KPI Cards**: Messages, resolution rate, satisfaction, cost at a glance
- **One-click AutoFix**: Improve agent without technical knowledge
- **Simplified Edit Form**: Re-answer onboarding questions to update behavior
- **Memory Panel**: View, add, delete agent memories with usage indicator
- **Connector Status**: See which channels are active
- **Service Connector Panel**: Connect/disconnect Google and Microsoft OAuth
- **Expert Mode Toggle**: Switch to full technical view

## Agent Memory & Context Compaction

### Persistent Memory
- Stored in Firestore: `users/{userId}/agents/{agentId}/memory/{key}`
- LRU eviction when maxEntries reached (default 100)
- Keyword search with temporal decay scoring
- Top 20 memories auto-injected into system prompt

### Context Compaction
- Detects when messages exceed token threshold
- Haiku-based summarization of older messages
- Preserves last 4 conversation turns
- Transparent to all routes (chat, widget, webhook, connectors, MCP)

## Onboarding

### Template Path (10 seconds)
1. Choose from 37 templates (gallery with category filters)
2. Answer 3-5 guided questions (industry-specific)
3. 1-click deploy → agent ready with grading suite

### Custom Path (60 seconds)
1. Describe your agent in plain text
2. AI generates complete agent specification (JSON)
3. Review and deploy

Both paths redirect to Operator Dashboard after creation.

## Security & Compliance

- **Rate Limiting**: 8 Upstash Redis sliding window limiters (chat, webhook, widget, MCP, GDPR, connector, bug report)
- **Input Validation**: Zod v4 schemas on all API routes
- **Tool Approval**: EU AI Act Art. 14 human oversight. Interactive SSE dialog in Playground/Widget, conversational on Telegram/WhatsApp/Slack
- **Encrypted Tokens**: AES-256-GCM for OAuth tokens
- **CSP Headers**: Content Security Policy on all routes
- **MCP Key Security**: SHA-256 hashing, expiry, rotation with audit trail
- **EU AI Act Compliance**: Automated reports (Art. 6 risk, Art. 12 audit, Art. 14 oversight, Art. 52 transparency)
- **Sandbox**: Custom tool code runs in Node.js vm module, no network access

## Billing & Plans

| Feature | Starter (Free) | Pro ($79/mo) | Usage (PAYG) | Enterprise ($499/mo) |
|---------|----------------|--------------|--------------|---------------------|
| Agents | 2 | 25 | Unlimited | Unlimited |
| Tokens/month | 10K | 1M | Pay per use | 10M |
| Grading runs | 5/mo | 100/mo | $0.10/run | Unlimited |
| Teams | 0 | 5 | Unlimited | Unlimited |
| Connectors | 1 | 3 | Unlimited | Unlimited |
| MCP endpoints | 1 | 10 | Unlimited | Unlimited |
| Optimization Lab | No | 6 modes | 6 modes | 6 modes + priority |
| Models | Sonnet + Haiku | All | All | All |

Usage-based billing via Stripe Billing Meters. 17% platform commission on token costs (covers agentic execution, grading, observability, security, connectors).

## Technical Architecture

- **Framework**: Next.js 16 (App Router), React 19, TypeScript strict
- **UI**: shadcn/ui + Radix UI + Tailwind CSS 4 + Framer Motion 12
- **Visual Editor**: React Flow v12
- **Database**: Firebase Firestore (real-time subscriptions via onSnapshot)
- **Auth**: Firebase Auth (Google, GitHub, Email/Password)
- **Payments**: Stripe (subscriptions, usage meters, customer portal, 9 webhook events)
- **Code Execution**: GCP Cloud Run (Python/Node/Bash sandbox, auto-scale 0→10)
- **Streaming**: Server-Sent Events for all agent interactions
- **Rate Limiting**: Upstash Redis (8 limiters)
- **Validation**: Zod v4
- **Encryption**: AES-256-GCM (OAuth tokens)
- **i18n**: English and French (800+ keys each)

## Full API Reference

| Method | Endpoint | Auth | Response |
|--------|----------|------|----------|
| POST | /api/agents/{id}/chat | Session | SSE stream |
| POST | /api/agents/{id}/grading/{suiteId}/run | Session | SSE stream |
| POST | /api/agents/{id}/autoresearch/autofix | Session | SSE stream |
| POST | /api/agents/{id}/autoresearch/stress-lab | Session | SSE stream |
| POST | /api/agents/{id}/autoresearch/tournament | Session | SSE stream |
| POST | /api/agents/{id}/autoresearch/distillation | Session | SSE stream |
| POST | /api/agents/{id}/autoresearch/evolution | Session | SSE stream |
| POST | /api/agents/{id}/autoresearch/{suiteId}/run | Session | SSE stream |
| POST | /api/agents/{id}/pipelines/{pid}/execute | Session | SSE stream |
| POST | /api/teams/{id}/execute | Session | SSE stream |
| POST | /api/agents/{id}/approve | Session | JSON |
| POST | /api/agents/meta-create | Session | SSE stream |
| POST | /api/mcp/server | API Key | JSON-RPC |
| POST | /api/mcp (legacy) | API Key | JSON-RPC |
| POST/PUT/DELETE | /api/mcp/keys | Session | JSON |
| POST | /api/widget/chat | API Key | SSE stream |
| GET | /api/widget/config | API Key | JSON |
| GET | /api/widget/script | None | JS |
| POST | /api/webhook/{agentId} | API Key | JSON |
| POST | /api/slack/events | Slack signature | JSON |
| GET | /api/slack/install | Session | Redirect |
| GET | /api/slack/oauth | Query params | Redirect |
| POST | /api/telegram/webhook | Secret token | JSON |
| POST | /api/telegram/setup | Session | JSON |
| GET/POST | /api/whatsapp/webhook | Signature | JSON |
| POST | /api/whatsapp/setup | Session | JSON |
| GET | /api/oauth/google | Session | Redirect |
| GET | /api/oauth/microsoft | Session | Redirect |
| POST | /api/oauth/disconnect | Session | JSON |
| POST | /api/stripe/checkout | Session | JSON |
| POST | /api/stripe/webhook | Stripe signature | JSON |
| GET | /api/stripe/subscription | Session | JSON |
| POST | /api/stripe/portal | Session | JSON |
| GET/POST | /api/github/content | Session | JSON |
| GET | /api/github/repos | Session | JSON |
| POST | /api/bug-report | Session/IP | JSON |
| GET | /api/agents/{id}/compliance-report | Session | JSON |
| GET | /api/cron/grading | Cron secret | JSON |
| GET | /api/cron/routines | Cron secret | JSON |
| POST | /api/monitor/run | IP rate limit | SSE stream |
| GET | /api/monitor/{runId} | None | JSON |
| POST | /api/monitor/setup-team | Session | JSON |
| POST | /api/grader/run | IP rate limit | SSE stream |
| POST | /api/grader/probe | IP rate limit | JSON |
| GET | /api/grader/{runId}/og | None | Image |
| GET | /api/health | None | JSON |

## Firestore Schema

```
users/{userId}
  /agents/{agentId}
    /skills, /tools, /extensions, /versions
    /memory/{key}                    # Agent memory (LRU eviction, keyword search)
    /gradingSuites/{suiteId}/cases, /runs/{runId}/results
    /autoresearchRuns/{runId}/iterations
    /pipelines/{pipelineId}, /sessions/{sessionId}
    /connectors/widget, /connectors/slackConnection
    /webhooks/{webhookId}, /webhookLogs/{logId}
    /mcpServers/{serverId}/usage/{yearMonth}
  /serviceConnectors/{provider}     # Encrypted OAuth tokens (AES-256-GCM)
  /agentTeams/{teamId}
    /activity/{activityId}          # 8-action audit trail
    /tasks/{taskId}                 # Kanban task board
    /routines/{routineId}           # CRON scheduled routines
  /goals/{goalId}
  /usage/{yearMonth}               # Token + cost tracking with agent breakdown
  /bugs/{bugId}
apiKeys/{sha256Hash}                # MCP API keys (O(1) lookup)
slackTeams/{teamId}                 # Slack workspace index
telegramBots/{hash}                 # Telegram bot routing
whatsappPhones/{phoneId}            # WhatsApp phone routing
```

## Workflow Quality Monitor

Public diagnostic tool at kopern.ai/monitor — tests any LLM model or API endpoint for production readiness.

### 6 Quality Criteria
| Criterion | Weight | Description |
|-----------|--------|-------------|
| Reasoning Depth | 20% | Logical deduction, multi-step problem solving, inference quality |
| Instruction Following | 20% | Adherence to constraints, format compliance, role consistency |
| Consistency | 15% | Stable output across similar prompts, no contradictions |
| Latency Benchmark | 15% | Response time measurement against provider baselines |
| Edge Case Handling | 15% | Graceful behavior on ambiguous inputs, missing data, adversarial prompts |
| Output Quality | 15% | Clarity, accuracy, completeness, appropriate tone |

### How It Works
1. 18 standardized prompts (3 per criterion) are sent to the target model/endpoint
2. Each response is evaluated by a Claude Sonnet judge with criterion-specific rubrics
3. Scores (0.0-1.0) are compared against hardcoded baselines for 29 models across 4 providers
4. Actionable insights are generated (CRITICAL/SUGGESTION badges)
5. Results stored in Firestore `monitorRuns` collection for sharing via `/monitor/{runId}`

Rate limit: 3 diagnostics/day/IP. No authentication required.

## Public Agent Grader

Free grading tool at kopern.ai/grader — test any AI endpoint or system prompt without creating an account.

### Two Modes
- **Prompt Mode**: Paste a system prompt and test cases — Kopern runs the agent and evaluates responses
- **Endpoint Mode**: Connect any HTTP endpoint (OpenAI, Anthropic, n8n, custom API) — Kopern sends test prompts and grades the responses

### Evaluation
Uses the same 6 criterion types as the full grading system (output_match, schema_validation, tool_usage, safety_check, custom_script, llm_judge). Results include a radar chart, per-case scores, and shareable OG image at `/api/grader/{runId}/og`.

Rate limit: 5 gradings/day/IP.

## Blog

Technical blog at kopern.ai/blog covering AI agent development, grading systems, MCP protocol, and monitoring. Markdown-based with gray-matter frontmatter, reading time estimation, i18n locale fallback (EN/FR). SEO: ArticleJsonLd + BreadcrumbJsonLd per post.

## Links

- Website: https://kopern.ai
- GitHub: https://github.com/berch-t/kopern
- npm: https://www.npmjs.com/package/@kopern/mcp-server
- License: MIT