Core Concepts
The /ask flow, request intents, and the Console↔backend vocabulary.
A single mental model explains most of EgoX: one request lifecycle, four intents, and one vocabulary that maps Console terms to backend terms.
The /ask flow
Every call to POST /egox/ask runs the same lifecycle:
- Authenticate & resolve tenant — nothing touches data before EgoX knows whose data path it's on.
- Load tenant context — config, enabled tools, knowledge scope, prompt overrides.
- Load conversation state — prior messages from the thread, if any.
- Classify intent — vanilla / RAG / tools / RAG+tools. Cheap and deterministic; expensive LLM work only happens when the intent justifies it.
- Assemble context — history + retrieved chunks + tool catalog, as the intent requires.
- Call the LLM with the right system prompt for that intent.
- Execute tool calls if requested, with storm protection (dedup, per-tool cap, error classification, transient retry, iteration cap).
- Persist the turn — message, token usage, intent, audit flags.
- Return — the answer plus metadata the caller can act on.
Intents
EgoX classifies each request into exactly one intent, which selects the system prompt and how much context to assemble:
| Intent | The request is… | Prompt tab in Console |
|---|---|---|
vanilla | plain conversation | Base |
rag | grounded in retrieved knowledge | RAG |
tools | calling an external API | Tool |
rag_tools | both | RAG+Tool |
The chosen intent comes back on the response as intent, so callers (and the
Console's thread auditing) can see how each turn
was handled.
The intent selects the system prompt; the project's Personality gives that prompt its voice. Same model, same intent — a different Ego makes it sound like your product.
Vocabulary
The Console speaks product language; the backend speaks domain language:
| Console (user-facing) | Backend (domain) | What it represents |
|---|---|---|
| Project | Tenant | Isolation unit; owns everything below it |
| AI Configuration | Tenant Config | Model, temperature, response format |
| Endpoints | Tools | External APIs the LLM can call |
| Knowledge Base | RAG Documents / Chunks | Embedded content the LLM retrieves |
| Threads | Threads + Messages | Turn history for one user session |
Renaming a Console label is cosmetic; renaming a backend domain term is a migration. Both names are correct — they just live on different sides of the product.
Response envelope
All HTTP responses use one envelope. Programmatic callers branch on the error code (a closed enum), not the message.
// success
{ "status": "OK", "data": { /* ... */ } }
// error
{ "status": "KO", "error": { "code": "ERROR_CODE", "message": "human readable" } }