Agents

Agents are the core of Komand. Each agent is an AI personality with its own model, system prompt, enabled skills, memory, and conversation history. A single Komand instance can run multiple agents — a sales bot, a support agent, an internal assistant — each with separate configuration and isolated state.

Creating an Agent

curl -X POST http://localhost:5000/api/agents/ \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "sales-bot",
    "name": "Sales Assistant",
    "description": "Handles inbound leads and product inquiries",
    "systemPrompt": "You are a friendly sales assistant for Acme Corp. Help customers with product inquiries, pricing, and scheduling demos.",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-20250514",
    "maxContextTokens": 100000,
    "enabledSkillIds": ["crm-contact-lookup", "quote-builder", "calendar-book"],
    "allowedChannels": ["WebChat", "Slack", "Telegram"]
  }'

Agent Configuration

Field	Type	Default	Description
`agentId`	string	—	Unique identifier (required)
`name`	string	—	Display name (required)
`description`	string	`null`	Human-readable description
`systemPrompt`	string	`"You are a helpful enterprise AI assistant."`	Instructions that shape the agent’s behaviour
`modelProvider`	string	`"anthropic"`	AI provider to use
`modelId`	string	`"claude-sonnet-4-20250514"`	Specific model within the provider
`maxContextTokens`	int	`100,000`	Maximum context window for LLM calls
`enabledSkillIds`	string[]	`[]`	Skill IDs the agent can invoke
`allowedChannels`	string[]	`[]`	Channels the agent can operate on
`createdAt`	datetime	(auto)	When the agent was created
`updatedAt`	datetime	(auto)	When the agent was last modified

The systemPrompt is prepended to every LLM call. It defines the agent’s personality, knowledge boundaries, and behavioral guidelines.

Retrieving an Agent

curl http://localhost:5000/api/agents/sales-bot

Response:

{
  "success": true,
  "data": {
    "agentId": "sales-bot",
    "name": "Sales Assistant",
    "description": "Handles inbound leads and product inquiries",
    "systemPrompt": "You are a friendly sales assistant...",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-20250514",
    "maxContextTokens": 100000,
    "enabledSkillIds": ["crm-contact-lookup", "quote-builder", "calendar-book"],
    "allowedChannels": ["WebChat", "Slack", "Telegram"]
  }
}

Conversation History

Each agent maintains separate conversation histories per session. A session is identified by the channel, account, and sender — see Sessions for details.

Get the last 50 turns from a session:

curl "http://localhost:5000/api/agents/sales-bot/history/session-123?maxTurns=50"

Response:

{
  "success": true,
  "data": [
    {
      "role": "user",
      "content": "What's the pricing for your Pro plan?",
      "timestamp": "2026-02-23T10:30:00Z",
      "toolCallIds": null
    },
    {
      "role": "assistant",
      "content": "The Pro plan is $49/month per user...",
      "timestamp": "2026-02-23T10:30:02Z",
      "toolCallIds": null
    }
  ]
}

Clear a session’s history:

curl -X DELETE http://localhost:5000/api/agents/sales-bot/history/session-123

History Management

When a session exceeds MaxTurnsPerSession (default 100), the oldest turns are trimmed before adding new ones
When the agent exceeds MaxSessionsPerAgent (default 100), the oldest session (by last activity) is automatically evicted
Clearing a session’s history does not end the session — new messages continue to accumulate

Agent Memory

Agents have a persistent key-value memory store that persists across sessions and channels. This is for long-term facts — preferences, learned context, user information — not conversation history.

Store a memory:

curl -X POST http://localhost:5000/api/agents/sales-bot/memory \
  -H "Content-Type: application/json" \
  -d '{ "key": "company_timezone", "value": "Australia/Brisbane" }'

Recall a memory:

curl http://localhost:5000/api/agents/sales-bot/memory/company_timezone

Memory is scoped to the agent, not the session. Information stored during a Telegram conversation is available when the same agent handles a Slack conversation. This enables cross-channel continuity:

[Telegram] You:   "Our office is in Brisbane"
[Telegram] Agent: "Got it — I'll use Australia/Brisbane for scheduling."

... later ...

[Slack]    You:   "Book a meeting for 2pm tomorrow"
[Slack]    Agent: "Booked for 2:00 PM AEST (Australia/Brisbane)."

Memory Limits

Setting	Default
Max entries per agent	1,000
Max value length	100,000 characters

When the entry limit is reached, you must delete existing entries before storing new ones.

Multi-Agent Setup

You can run multiple agents for different purposes:

Agent	Purpose	Channels
`default`	General assistant	All
`sales-bot`	Lead qualification, demos	WebChat, Slack
`support-bot`	Customer support, troubleshooting	Telegram, WhatsApp
`internal-bot`	Team operations, status checks	Teams, Discord

Sessions are bound to a specific agent. By default, new sessions bind to the "default" agent. You can rebind sessions to different agents — see Sessions.

AI Model Integration

Phase 1: BYO API Key

In V1, users provide their own API key for AI providers. Komand supports any provider with an OpenAI-compatible API, with first-class support for Anthropic Claude models.

Configure the model per agent:

{
  "modelProvider": "anthropic",
  "modelId": "claude-sonnet-4-20250514",
  "maxContextTokens": 100000
}

API keys will be stored in the platform’s credential vault and never exposed in agent configuration or logs.

Phase 2: Komand Gateway

In V2, Komand will offer a managed AI gateway that handles model routing, rate limiting, and usage tracking — no API key required.

Limits

All limits are configurable via the GrainLimits configuration section:

Setting	Default	Description
`MaxTurnsPerSession`	100	Oldest turns trimmed when exceeded
`MaxSessionsPerAgent`	100	Oldest session evicted when exceeded
`MaxMemoryEntries`	1,000	Per-agent memory capacity
`MaxMemoryValueLength`	100,000	Characters per memory value