Concepts

A short glossary used throughout these docs. If a term shows up on another page without being re-explained, its meaning is here.

OrganizationCopy Anchor Link

The top-level isolation boundary. Every agent, knowledge base, conversation, end-user, API key, and so on belongs to exactly one organization, and data never crosses between two organizations — even with a mistaken publishable key or an expired token. See Data isolation.

Members & rolesCopy Anchor Link

People in your organization sign in to the admin console (app.harnix.vn) with an invited account. Roles and invites are managed under API keys & Members in the console — see API keys & members.

AgentCopy Anchor Link

A configuration for answering: a provider + model (e.g. OpenAI, or an OpenAI-compatible endpoint), a system prompt, a conversation history window, and an optional daily token budget. An agent can have knowledge bases attached (for lookup) and MCP servers attached (for external tools). A deactivated agent still exists but refuses new messages (agent_inactive). See Build an agent.

Knowledge base & documentCopy Anchor Link

A knowledge base is a set of documents (PDF, Markdown, text) that have been "ingested" — text extracted, chunked, and embedded with the deployment's one fixed embedding model. Each document has its own ingest status (processing, completed, failed). See Knowledge bases.

ToolCopy Anchor Link

Two kinds of tools an agent can call while answering:

• knowledge_search — automatically enabled once the agent has at least one knowledge base attached; no separate toggle.
• MCP server — an external server speaking the Model Context Protocol (MCP), with a URL and authentication headers configured per organization.

See Tools.

Run & traceCopy Anchor Link

Every time an agent answers a message, that's a run: the model thinks, may call one or more tools, then answers. A trace is the full record of that run — every model step, every tool call, every result, every citation — reviewable in the console. A run streams live over SSE while it's in progress; see Streaming and Runs & traces.

Conversation & messageCopy Anchor Link

A conversation belongs to one agent and one end-user; it holds an ordered sequence of messages (role user or assistant). An assistant message can carry citations — the specific knowledge-base sources the agent cited.

End-userCopy Anchor Link

The person chatting with the agent — not a member of your organization, but a user of your product. Three identity levels: anonymous (the widget generates its own anonymous id), identified (you assert an identity, either signed or via an API key), and service (an end-user standing in for the API key itself when /v2/chat is called without an end_user_id). See Authentication.

API key, publishable key, identity secretCopy Anchor Link

Three credentials with different jobs — don't mix them up:

• API key (X-API-Key) — a secret, used only from your backend, never placed in HTML or browser-side JavaScript. It lets you call /v2/chat directly on behalf of your end-users.
• Publishable key (pk_...) — not a secret, safe to sit in public HTML. It only opens POST /v2/token, and only for requests from an origin on your organization's allowed list.
• Identity secret — a secret that lives on your backend, used to sign (HMAC) an end-user identity before handing it to the widget, so the widget can exchange it for a token without your backend having to issue tokens itself. See Token exchange.