Key Concepts

Komand is built around a few core primitives. Understanding these will help you get the most out of the platform.

Agents

An Agent is an AI personality configured with a name, system prompt, model, and set of enabled skills. Agents process messages, maintain conversation history, and store persistent memories.

Agent "sales-bot"
├── Model: claude-sonnet-4-20250514
├── System Prompt: "You are a friendly sales assistant..."
├── Skills: [crm-lookup, quote-builder, calendar-book]
└── Memory: { "company_name": "Acme Corp", ... }

Each agent is an isolated Orleans grain with its own state. Multiple agents can run simultaneously, each handling different business functions.

Sessions

A Session is a conversation thread between a user and an agent, scoped to a specific channel. Sessions are identified by a compound key:

{Channel}:{ChannelAccountId}:{SenderId}

For example: Telegram:bot-123:user-456

Sessions track:

• Which agent is bound to the conversation
• Message count and timestamps
• Channel-specific metadata

Skills

A Skill is a discrete capability that an agent can use — like looking up a contact, generating a quote, or booking an appointment. Skills are:

• Sandboxed — executed in isolated containers or WASM runtimes
• Permissioned — declare required permissions (e.g., crm:read, calendar:write)
• Verified — marketplace skills are code-reviewed and signed
• Composable — agents can combine multiple skills in a single conversation

{
  "skillId": "crm-contact-lookup",
  "name": "CRM Contact Lookup",
  "publisher": "komand-official",
  "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } } },
  "requiredPermissions": ["crm:read"],
  "isVerified": true
}

Channels

A Channel is a messaging platform adapter that normalizes inbound messages into Komand’s internal format. Supported channels:

Channel	Status
WebChat	Available
Telegram	Planned
Slack	Planned
Discord	Planned
WhatsApp	Planned
Microsoft Teams	Planned
Signal	Planned
SMS	Planned

All channels produce the same InboundMessage format, so agents work identically regardless of the source channel.

Tools

A Tool is a runtime execution unit. When an agent decides to use a skill, a ToolGrain is created to execute the action. Tools have:

• An execution ID for tracking
• Input parameters from the agent
• A timeout (default: 30 minutes)
• Status tracking (Pending → Running → Completed/Failed/Cancelled)

Memory

Agents have a key-value memory store for persisting information across conversations. Memories are scoped to the agent — not the session — so information stored during one conversation is available in all future conversations.

Store: agent.StoreMemory("client_timezone", "Australia/Brisbane")
Recall: agent.RecallMemory("client_timezone") → "Australia/Brisbane"

Grains

Under the hood, every Komand entity is an Orleans grain — a virtual actor with:

• Isolated state — no shared mutable state between grains
• Single-threaded execution — no concurrency bugs within a grain
• Automatic lifecycle — activated on demand, deactivated when idle
• Persistent storage — state survives restarts via PostgreSQL

See Grain Model for the full grain taxonomy.