Skip to content
K-AgentK-Agent Docs

Introduction

View as Markdown

K-Agent is an AI agent platform by Kerneltics. You configure an agent once — its identity and dialect, instructions, knowledge, tools, guardrails, business hours and handoff rules — and then use that same agent everywhere: from your backend, in chat sessions, through OpenAI SDKs, in a chat widget on your website, and with your team taking over when a human is needed.

It is built Arabic-first for Saudi Arabia and the GCC. Every setting, message and error is available in Arabic and English, and replies follow the dialect you choose.

Ways to use your agent

Section titled “Ways to use your agent”
Entry point What it is for How
One-shot ask One question in, one answer out. No conversation state. POST /v1/agents/{agent}/ask
Chat sessions Ongoing conversations with history, with our sess_… ID or your own external_id. POST /v1/sessions, then POST /v1/sessions/{session}/messages
Streaming Show the reply as it is written, over Server-Sent Events. "stream": true on ask, sessions and messages
OpenAI-compatible endpoint Keep your OpenAI SDK code; point it at K-Agent and use the agent slug as the model. /openai/v1/chat/completions
Web widget A chat bubble for your website, for anonymous or signed-in visitors. One <script> tag
Handoff Desk A small inbox where your team picks up conversations the agent hands over. Dashboard, or the handoff API

Everything the dashboard does goes through the same public API, so anything you can click you can also automate.

The building blocks

Section titled “The building blocks”
Term Meaning
Organization (org_) Your company. It owns projects, members and a plan.
Project (proj_) The isolation unit: keys, agents, sessions and data. Use separate projects for staging and production.
Agent (agt_) A configured assistant. It has an editable draft and immutable numbered versions. You address it by ID or by its slug, such as store-assistant.
Session (sess_) A durable conversation between one end user and one agent. It can also carry your own external_id.
Run (run_) One agent turn: input in, model and tool steps, output out. A one-shot ask is a run with no session.
Message (msg_) One item in a transcript, with the role user, assistant, human_agent or system.
End user (eu_) The person talking to the agent. Verified only when your server vouches for them.
Handoff (ho_) A typed transfer of a conversation to your team. While it is open, the agent stays quiet.
Tool An action the model can call: built-in, an HTTP tool that calls your API, or a client tool that your app runs.
Knowledge source (ks_) Text, a catalog or an API feed the agent answers from.
AI conversation The billable unit. See Usage and billing.

IDs are a prefix plus 26 lowercase characters (sess_01k6rz4p7h2c9m5x8w3t6v1qbg). They are unguessable and sort by creation time.

What happens in one turn

Section titled “What happens in one turn”

When you send a message, K-Agent:

  1. Resolves the agent version, the session and the end user, and checks that your key may touch them.
  2. Replays a stored result if you repeat an Idempotency-Key.
  3. Stays quiet in human mode: if your team has the conversation, the message is stored and no AI runs.
  4. Admits the run under the session’s concurrency policy, so two messages never race each other.
  5. Checks quota and readiness — for example that a model key is connected.
  6. Builds the prompt from your settings: identity, instructions, knowledge, then the guardrails last; the history window; and a short live block with the clock and business hours.
  7. Runs the model and tools for up to max_tool_rounds rounds. Every tool call passes a policy check before it executes.
  8. Ends with exactly one outcome — usually answered or handed_off — or pauses in requires_action while your app runs a client tool. A run is never silent.

Safety you can rely on

Section titled “Safety you can rely on”

Escalation is enforced in code, not left to the prompt:

  • Never-handle list. Topics the agent must never answer itself (damage claims, legal threats, refund amounts, complaints about staff, other customers’ data). It is on by default and is placed last in the prompt.
  • Verbatim escalation reply. When the agent hands over a liability case, the customer sees exactly the reply you wrote, word for word.
  • Never silent. Provider errors are retried, then tried on fallback models, then answered with your fallback message and a handoff.
  • Truthful handoffs. The agent only says a person will follow up when a handoff was really recorded.
  • Quota never shows as an error to customers. When a Free plan runs out, sessions hand off with a notice instead.

Read more in Handoff and safety.

Hosts and authentication

Section titled “Hosts and authentication”
What URL
API https://api.k-agent.kerneltics.com/v1
OpenAI-compatible API https://api.k-agent.kerneltics.com/openai/v1
Dashboard https://app.k-agent.kerneltics.com
Widget script https://api.k-agent.kerneltics.com/widget/v1.js

Every request carries Authorization: Bearer <credential>:

Credential Prefix Where it lives
Secret key kt_sk_live_… or kt_sk_test_… Your servers only. Full API access, optionally limited by scopes or agents.
Publishable key kt_pk_live_… Your web pages. Only starts widget sessions, and only from the origins you allow.
Client token ct_… A browser or app, for one end user and one agent. Minted by your server, valid up to 60 minutes.

_live_ and _test_ are labels that help you and secret scanners tell keys apart; the project is what isolates data.

API conventions in one minute

Section titled “API conventions in one minute”
  • JSON everywhere. Objects carry id, object and created_at (Unix seconds).
  • Lists use cursors: ?limit=20&after=<id> returns {object: "list", data, first_id, last_id, has_more} (at most 100 per page).
  • Errors use one envelope with a stable code and a message in Arabic or English, chosen by Accept-Language. See Errors.
  • Retries are safe with an Idempotency-Key header on POST and DELETE. See Idempotency.
  • Request IDs: every response has a Request-Id header. Quote it when you contact support.
  • Versioning: /v1 only changes additively. See Versioning policy.

Next steps

Section titled “Next steps”