Glossary & Terminology

The terms used across this documentation set, defined as they are used on this platform — not generically. Where a term is a public standard, the definition names the standard; where it is VegaDūta-specific, the definition names the code or config that implements it.

Product and tenancy

Term	Definition
Agent	A configured AI worker owned by a tenant: a role (system prompt), a model, an allow-list of tools, optional knowledge collections, and channel bindings. Defined by the agent table in each tenant schema (core/agents, Agent.java). Agents carry per-instance tuning knobs — reasoning_depth, cost routing, collaborator lists — settable after creation via PATCH /api/agents/{id}/….
Tenant	One customer workspace. Registered in control_plane.tenant in the public schema; all of the tenant's data lives in its own Postgres schema. The request's tenant context (TenantContext) is derived from the JWT and selects the schema.
Schema-per-tenant	The isolation model: each tenant gets its own Postgres schema — its own full set of tables — inside one shared database. Isolation is enforced by SET search_path on the pooled connection, which is why PgBouncer must run in session mode: transaction pooling reassigns connections mid-session and a query can land in the wrong tenant's schema. See Data Architecture.
Control plane	The shared, non-tenant state in the public schema — the tenant registry, plans, platform settings — migrated by the db/migration/controlplane/ Flyway directory, once, rather than per schema.
Persona	A role-shaped user of the platform: tenant admin, tenant member (agent-builder / delegated-user), end-customer (embeds), platform admin, API consumer / external agent, and channel end-user. Realm roles in Keycloak map to the authenticated subset.
FREE mode	A platform-wide positioning flag (platform.free-mode.enabled=true, seeded by migration V237; NEXT_PUBLIC_FREE_MODE=1 / WEB_FREE_MODE for the console). Every tenant resolves as the top tier for feature gates while the platform-pool anti-abuse caps stay enforced; the web UI swaps pricing surfaces for open-source copy. Plan/billing surfaces stay hidden unless NEXT_PUBLIC_BILLING_ENABLED=1.

Agents, LLMs and knowledge

Term	Definition
BYOK — bring your own key	A tenant supplies its own API credentials for an LLM provider. Keys are validated at entry and stored encrypted with APP_ENCRYPTION_KEY in the tenant schema; every agent on the account can then use that provider's models. ~14 providers are supported.
Hosted (platform) pool	The operator-provided model option for tenants without a BYOK key; the operator configures which providers and credentials back it (for example the VERTEX_POOL_* slots). Usage is metered into llm_call_log and capped by the anti-abuse limiter — which stays on even under FREE mode.
Jev	TypeSafe's decision model, integrated as a cheap calibrated yes/no call (noul) rather than a chat model. Used today as a second opinion for cost routing: a deterministic heuristic decides if a turn is "simple"; only a heuristic not-simple is offered to Jev, which can rescue it to the agent's economy model above a confidence threshold (default 0.75). Tenants can bring their own TypeSafe key (/api/jev/credential), set a per-tenant policy (jev_policy, V334), or try it in a bounded playground. Implementation: core/agents/.../decision/JevDecisionService.java.
Reasoning depth	A per-agent enum (agent.reasoning_depth, ReasoningDepth.java) controlling how much verification a turn gets — a pipeline knob, not a sampling knob. FAST = no extra pass (default, unchanged legacy behavior). CAREFUL = one self-consistency re-check of the final answer. RIGOROUS = CAREFUL plus Reflexion self-critique plus an independent verifier call before every tool executes — the right default for side-effecting agents. PLANNED = a cheap planning call decomposes the request into an ordered step list before the tool loop; not currently combinable with CAREFUL/RIGOROUS passes in one turn.
Guardrail	A platform-layer check applied outside the model on what goes in and what comes out — profanity, jailbreak/prompt-injection, PII, policy violations, toxicity, custom rules — enforced by core/guardrails (e.g. GuardedToolCallback, ChatGuardrailGate), with flagged content sent to a review queue. Enforced by the system, not requested in the prompt.
Approval gate	Human-in-the-loop control: a workflow node type and a gate in front of sensitive agent tool calls. The run pauses until a person approves or rejects; the decision is written to the audit log (core/approval).
RRF — Reciprocal Rank Fusion	The rank-merge rule used by knowledge search: hybrid retrieval runs a vector (pgvector) list and a keyword list, then fuses them by summing 1/(k + rank) per list with k = 60 (Cormack et al.). A reranker may refine the fused shortlist; if reranking is unavailable the RRF order stands. Implementation: core/knowledge/.../KnowledgeSearchService.java.
llm_call_log	The per-tenant table every LLM call writes (via LlmMetricsAdvisor): provider, model, latency, tokens, estimated cost, success/exception. Parallel to the OTLP span sent to Langfuse.
Kill switch	An emergency off. Exists at tenant scope (suspend one tenant's agents) and platform scope (web-admin); part of the built-in governance layer alongside autonomy tiers.

Integration and protocols

Term	Definition
MCP — outbound (client)	Core acts as an MCP client: tenants register MCP servers in a dynamic connector registry (core/mcp) over STDIO, SSE or streamable HTTP, and their tools become available to agents. STDIO packages (npx …, uvx …) are spawned on mcp-stdio-runner — a separate Node service — because untrusted code never runs inside core.
MCP — inbound (server)	Core also exposes an MCP server (the mcpserver Spring profile): external MCP clients — Claude, an IDE — can list and call a tenant's agents and workflows and search its knowledge base, subject to the same auth.
AG-UI	The Agent–User Interaction protocol: an open, event-based standard for streaming an agent's messages, tool calls and state changes to a front end. Implemented by AgUiRunController / AgUiEventMapper in core/agents/agui; one of the three agent connections alongside MCP (to tools) and A2A (to agents).
A2A	The Agent-to-Agent protocol (v1.0): lets agents on other platforms discover and call agents built here. The platform publishes an agent card at api.example.com/.well-known/agent-card.json.
Channel	A messaging surface an agent answers on — ~10 types: WhatsApp, Telegram, Slack, Discord, Messenger, Instagram, X, Email, Teams, Voice — plus web embeds. Implemented in core/omnichannel; voice-agent is the LiveKit worker.
Sidecar	Ambiguous on this platform; both uses are real: (1) sidecar/ — the Python FastAPI knowledge/ML service on port 8001 (chunking, embeddings, OCR, reranking, transcription); (2) a helper container deployed next to a service (for example a connection pooler). Context disambiguates.

Deployment and operations

Term	Definition
Worktree build rule	Images you deploy should be built from a clean, detached git worktree at the target SHA — git worktree add --detach, build there, git worktree remove --force after. A Docker build context includes whatever is on disk, including uncommitted work and stray .env*.local files. Released images from release.yml are built in CI from the tag.
NEXT_PUBLIC_* bake	Next.js inlines a NEXT_PUBLIC_* value into the browser bundle when it is set at build time. The Dockerfiles leave these build args empty by default so the runtime environment decides; a value you do bake (especially localhost) can only be changed by rebuilding. See ADR-0007.
APP_ENCRYPTION_KEY	The single symmetric key encrypting every stored provider credential and channel secret. It must be identical everywhere core boots — deploy/compose/.env, core/.env.local, your Kubernetes Secret. A mismatch makes all stored credentials undecryptable — a classic failure during host migrations and restores. Rotation requires a decrypt/re-encrypt migration.
Dual issuer	Core validates JWTs against a primary issuer plus KEYCLOAK_ADDITIONAL_ISSUERS. Required because Keycloak pins its hostname: every token carries iss=<PUBLIC_AUTH_URL>/realms/agentic-ai regardless of which URL minted it. If core does not accept that exact issuer, every authenticated call 401s. Add the old issuer here during a domain change.
shape-api / shape-jobs / app-worker	The runtime split of the one core image: shape-api is a Spring profile for interactive-serving pods that skips ~30 scheduled beans/listeners; shape-jobs is the profile for pods that own those sweeps (queue pollers, outbox relays, cron tickers); app-worker is a separate Temporal-worker assembly (no @EnableScheduling). Unset, everything runs in the single JVM as before.
Flyway version namespace	Both migration directories — db/migration/controlplane/ (80 files) and db/migration/tenant/ (139 files) — share one version space. controlplane/V227 and tenant/V227 collide. Reserve numbers by checking maxima in both folders; scripts/ci/flyway-lint.sh gates it in CI. File counts are approximate and grow over time.
Compose profile	A named opt-in group of services in deploy/compose/docker-compose.yml (events, temporal, jobs, observability, tracing, voice, rl, code-intel, builder, sandbox, tools, browser). scripts/vegaduta up --full --profile x also sets the core flags each profile needs.
Verified / unverified	The ops convention carried through this documentation: verified = checked against the repository on the stated date; unverified = believed, not re-checked — a lead, not a fact.