# Introduction

> What K-Agent is, its building blocks, and how one call flows from your code to an answer.

**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

| 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

| 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](/docs/en/concepts/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

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

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](/docs/en/concepts/handoff-and-safety/).

## 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.

:::caution[Keep secret keys on the server]
Never put a `kt_sk_` key in browser code, a mobile app or a public repository. The API sends no CORS headers for secret keys, so browsers cannot use them anyway. Use a publishable key or a client token in front-end code.
:::

## 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](/docs/en/reference/errors/).
- **Retries are safe** with an `Idempotency-Key` header on POST and DELETE. See [Idempotency](/docs/en/reference/idempotency/).
- **Request IDs:** every response has a `Request-Id` header. Quote it when you contact support.
- **Versioning:** `/v1` only changes additively. See [Versioning policy](/docs/en/reference/versioning/).

## Next steps

- Make your first calls in the [5-minute quickstart](/docs/en/get-started/quickstart/).
- Understand [sessions and session IDs](/docs/en/concepts/sessions/), the part most integrations depend on.
- Browse every endpoint in the [API reference](/docs/en/api/).