How to Deploy Your First AI Agent with Klawty OS

Building and deploying an AI agent that actually works in production is harder than it looks. Most tutorials show you how to get a chatbot running in 10 minutes. What they don’t show you is the architecture that makes it reliable, governable, and safe to run autonomously — 24 hours a day, handling real business operations.

This guide walks you through deploying your first production-grade AI agent using Klawty OS: the same system powering the Inscape 8-agent MAS that has been running continuously in Luxembourg since 2025.

What Klawty OS Is

Klawty OS is dcode’s production-grade agentic operating system. It is not a demo framework or a toy playground. It is the software stack we built to run real AI agents for a real interior design company — agents that handle client communications, financial operations, marketing, sales pipelines, and developer tasks, autonomously, every day.

The key differentiators from other agent platforms:

• Governance by design — tiered autonomy model baked into every action, not bolted on
• EU AI Act ready — audit trails, human oversight mechanisms, and documentation aligned with compliance requirements
• MCP-native — 40+ pre-built MCP server integrations, plus custom server generator
• Multi-LLM — run different agents on different models based on task requirements
• Multi-channel — agents operate via WhatsApp, Telegram, Discord, Slack, email, or web
• Production-hardened — circuit breakers, health monitoring, automatic recovery, Telegram alerting

The Architecture at a Glance

A Klawty deployment has three main components:

1. Agents — the AI workers, each with a defined role, tool access, and autonomy constraints
2. Task Executor — the central engine that runs agent think cycles, routes tool calls, and manages the task queue
3. Agent Brain — the orchestration layer that handles proposals, approval workflows, and inter-agent coordination

Supporting infrastructure:

• SQLite databases — tasks, proposals, memory, and CRM data (WAL mode, backed up daily)
• Qdrant vector store — semantic memory for agents (250+ memories, searchable by meaning)
• Health Monitor — 60-second check loop with Telegram alerting for downtime
• Sentinel — the governance watchdog that monitors all other agents and validates high-risk actions

Step 1: Define Your Agent’s SOUL

Every Klawty agent starts with a SOUL.md file — a structured natural language document that serves as the agent’s governing identity. This is not just documentation; it is injected into every LLM context, shaping how the agent reasons, what it prioritises, and what it refuses to do.

A SOUL.md has these sections:

# [Agent Name] — SOUL

## Identity
Name: [Name]
Role: [One-line role description]
Model: [claude-sonnet-4-6 / kimi-k2.5 / gemini-flash / etc.]
Think Cycle: [Frequency — 15 min / 30 min / 60 min / event-driven]
Channel: [Discord channel or messaging platform]

## Mission
[2-3 sentences describing what this agent exists to do —
written as purpose, not as a task list]

## Core Responsibilities
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Tertiary responsibility]

## Available Tools
[List of tool names and brief descriptions]
Tool autonomy tiers:
- AUTO: [list read/research tools]
- AUTO+: [list low-risk execution tools]
- PROPOSE: [list medium-risk tools requiring rollback window]
- CONFIRM: [list high-risk tools requiring explicit approval]
- BLOCK: [list absolutely prohibited actions]

## Behavioural Constraints
- NEVER [hard constraint 1]
- NEVER [hard constraint 2]
- ALWAYS [positive requirement 1]
- ALWAYS [positive requirement 2]

## Output Format
[How the agent communicates results — format, verbosity, emoji usage, etc.]

The SOUL is the most important document you will write. A vague SOUL produces unpredictable behaviour. A precise SOUL produces reliable, auditable agents.

A practical example — a sales agent SOUL excerpt:

## Mission
Sami manages the sales pipeline for Inscape Interiors — identifying leads,
scoring them by conversion probability, drafting follow-up sequences, and
ensuring no opportunity is left without appropriate next action. Sami never
sends emails autonomously; he always proposes drafts for Islem to review.

## Behavioural Constraints
- NEVER send an email autonomously — all outbound communications require PROPOSE approval
- NEVER promise delivery dates — always defer to Pawel for timeline confirmation
- NEVER score a lead above 8/10 without documenting the reasoning
- ALWAYS flag leads from regulated industries (financial services, healthcare) to Islem
- ALWAYS include competitor mentions in lead notes when detected

Note how specific the constraints are. “Don’t do bad things” is not a constraint. “NEVER promise delivery dates” is.

Step 2: Configure Tool Access via MCP Servers

Tools are what give agents the ability to act on the world. In Klawty OS, every tool is exposed via an MCP server — a lightweight process that wraps an external service and exposes its capabilities through the standardised Model Context Protocol.

Selecting Pre-Built MCP Servers

Klawty ships with pre-built MCP servers for the most common enterprise integrations:

Communication:

• Gmail / Google Workspace (read, draft, send — with tier controls)
• Outlook / Microsoft 365
• Slack (post, search, channel management)
• Discord (messaging, reactions, thread management)

Productivity:

• Google Calendar (read, create, modify events)
• Notion (read/write pages and databases)
• Linear (issues, projects, cycles)

Development:

• GitHub (repos, PRs, issues, actions)
• GitLab (full pipeline integration)

Business:

• Salesforce (contacts, opportunities, cases)
• HubSpot (contacts, deals, timelines)
• Stripe (payment and subscription data — read-only recommended)

Data:

• PostgreSQL (scoped read-only or read-write based on agent role)
• Google Sheets / Excel (data synchronisation)

Configuring Tool Risk Tiers

For each tool your agent has access to, you assign an autonomy tier. This is not a capability question — it’s a risk question:

// In agents/tools/sami-tools.js
const SAMI_TOOLS = {
  // AUTO — pure reads, zero risk
  'search_crm_contacts': { tier: 'AUTO', description: 'Search CRM for contacts' },
  'get_lead_score': { tier: 'AUTO', description: 'Calculate lead score' },
  'search_web': { tier: 'AUTO', description: 'Research prospect online' },

  // AUTO+ — writes that are logged but low-risk
  'update_lead_stage': { tier: 'AUTO_PLUS', description: 'Update pipeline stage in CRM' },
  'add_crm_note': { tier: 'AUTO_PLUS', description: 'Add note to contact record' },
  'create_task': { tier: 'AUTO_PLUS', description: 'Create follow-up task' },

  // PROPOSE — visible to prospect or costly to undo
  'draft_email': { tier: 'PROPOSE', description: 'Draft follow-up email for review' },
  'schedule_meeting': { tier: 'PROPOSE', description: 'Propose calendar invite' },

  // CONFIRM — explicit Islem approval required
  'send_proposal_doc': { tier: 'CONFIRM', description: 'Send formal proposal document' },
  'create_deal': { tier: 'CONFIRM', description: 'Create deal in CRM above €10K' },

  // BLOCK — hardcoded no-op
  'delete_contact': { tier: 'BLOCK', description: 'Deleting contacts is never permitted' },
  'modify_pricing': { tier: 'BLOCK', description: 'Pricing changes require Islem directly' },
};

This configuration is the security architecture of your agent. Take your time with it.

Step 3: Set Up the Task Queue

Klawty agents operate on a task queue — rather than having continuous unconstrained access to LLM calls, each agent run processes tasks from a queue. This has several benefits:

• Auditability — every agent action corresponds to a task with full history
• Rate limiting — prevents runaway agent loops
• Human visibility — the Task Manager UI shows exactly what every agent is doing
• Prioritisation — urgent tasks jump the queue

A task in Klawty looks like:

{
  "id": "task_abc123",
  "agent": "sami",
  "type": "lead_follow_up",
  "title": "Follow up with Marie Laurent — Inscape consultation inquiry",
  "priority": "high",
  "status": "executing",
  "metadata": {
    "contact_id": "sf_00Q1234",
    "last_contact": "2026-03-18",
    "inquiry_type": "office_renovation"
  },
  "created_at": "2026-03-21T09:00:00Z"
}

The Task Executor picks this up, runs the agent’s think cycle against it, captures tool calls, and records the outcome — all without human intervention, unless a tool call requires PROPOSE or CONFIRM tier approval.

Step 4: Configure the Think Cycle

The think cycle defines how frequently your agent runs and what it looks for. In Klawty, cycles are driven by LaunchAgent scheduled processes (macOS) or systemd services (Linux/VPS):

# /Library/LaunchAgents/com.klawty.sami.plist
# Runs Sami's think cycle every 20 minutes
StartCalendarInterval:
  - Minute: 0
  - Minute: 20
  - Minute: 40

Within each cycle, the agent:

1. Fetches context — reads recent messages in its channel, pulls relevant tasks from queue, queries memory
2. Plans — the LLM reasons about what to do given current context
3. Executes — calls tools in sequence, handling the results of each call
4. Reports — posts a summary to its Discord channel
5. Commits — completed tasks are marked done; new tasks created for follow-up work

The cycle length depends on task urgency. Customer service agents might run every 5 minutes. Analytics agents might run every 60 minutes. The right cadence balances responsiveness against API costs.

Step 5: Enable Sentinel Monitoring

Sentinel is Klawty’s governance watchdog — an agent dedicated to monitoring all other agents. Before any PROPOSE or CONFIRM tier action executes, Sentinel validates it against your business rules:

// Sentinel business rules (excerpt)
const SENTINEL_RULES = [
  {
    rule: 'no_ceka_invoice_forwarding',
    check: (action) => !action.includes('CEKA PRO'),
    message: 'CEKA PRO invoices require Islem personally — not auto-forwarding'
  },
  {
    rule: 'no_delivery_promises',
    check: (action) => !action.match(/deliver|deadline|by (Monday|Tuesday|Wednesday|Thursday|Friday)/i),
    message: 'Delivery commitments require Pawel confirmation first'
  },
  {
    rule: 'email_requires_review',
    check: (action, tier) => action.type !== 'send_email' || tier === 'PROPOSE' || tier === 'CONFIRM',
    message: 'Autonomous email sending is not permitted — must be PROPOSE or CONFIRM'
  }
];

If a proposed action fails any Sentinel rule, it is blocked before execution. The agent receives the block reason and can either revise the action or escalate to the human.

Step 6: Production Deployment

With SOUL, tools, tasks, cycle, and Sentinel configured, deployment looks like:

# 1. Syntax check before any service start
node --check agents/sami/sami-runner.js

# 2. Load the LaunchAgent
launchctl load ~/Library/LaunchAgents/com.klawty.sami.plist

# 3. Verify it started
launchctl list | grep com.klawty.sami

# 4. Monitor the first cycle
tail -f /var/log/klawty/sami.log

# 5. Check the Task Manager UI
open http://localhost:3000

The Task Manager UI shows real-time status for all agents, their current tasks, tool call history, and pending proposals waiting for approval.

What a Production Day Looks Like

Once deployed, a Klawty agent runs autonomously. For Sami (sales agent) on a typical day:

• 09:00 — Sami runs, reviews overnight inquiries from the website contact form
• 09:05 — Scores 3 new leads (AUTO tier — no approval needed)
• 09:06 — Proposes a follow-up email draft for the highest-scoring lead (PROPOSE — 15-min window)
• 09:08 — Islem reviews, clicks ✅ on Discord — email sends
• 09:15 — Next cycle runs, Sami checks pipeline for stalled deals
• 09:20 — Updates 2 deal stages in CRM (AUTO+ tier — executes and logs)
• 11:20 — Flags high-value enterprise inquiry for CONFIRM-tier response (requires explicit approval)
• 17:00 — Posts daily pipeline summary to #leads-pipeline channel

All of this happens without Islem opening a CRM, writing an email from scratch, or managing a pipeline manually. The agent handles the routine; Islem handles the judgment calls.

Common First-Deployment Mistakes

1. Making the SOUL too vague “Help the sales team” is not a mission. “Score leads daily, draft follow-up sequences for the top 3 priority leads, and flag all enterprise inquiries for Islem’s personal response” is a mission.

2. Setting everything to AUTO The temptation to make the agent fully autonomous is real — but premature. Start with PROPOSE for anything involving external communication or data modification. Move to AUTO+ only after you have watched the agent make good decisions 50+ times.

3. Not reading the first 10 cycles manually The first cycles will reveal misunderstandings in your SOUL or tool configuration. Read every log line for the first day. You will catch problems before they affect real business operations.

4. Skipping Sentinel Sentinel feels like overhead until the agent tries to send a client an email with wrong pricing. Configure your business rules before deployment, not after.

5. Not configuring memory Agents without memory repeat themselves — they rediscover the same information every cycle, they send the same follow-up twice, they lose context on ongoing conversations. Configure the Memory Distiller to extract insights from completed tasks and store them in Qdrant.

Getting Started with Klawty

Klawty OS is available for self-hosted deployment or as a fully managed service:

Self-hosted — Download Klawty OS and deploy on your own infrastructure. Best for businesses with technical teams and data sovereignty requirements.

Managed by dcode — We deploy, configure, and operate Klawty agents on your behalf. Includes monitoring, incident response, and ongoing optimisation. Starting from 1 agent, scaling to full multi-agent teams.

Agent-as-a-Service — Pre-built agents (Sales Sami, Finance Falco, Marketing Zara, Operations Nour) available as monthly subscriptions. Fastest path to production. Learn about AaaS.

Islem Binous is the founder of dcode Technologies and the architect of the Inscape 8-agent production system — one of the most advanced real-world MAS deployments in Europe. Every pattern in this guide was learned from running production agents for real business operations.