Dialog engine

Sellable product

This capability is granted by an API key scoped to the ai-suite product (product face). See the product reference below.

Conversation orchestration as a shared capability — turn management, intent detection, tool-calling, safety-gating, barge-in/cancel, streaming assembly. It CONSUMES other capabilities (provider-gateway for the LLM, retrieval for RAG context, stt/tts for the audio legs) and owns only the dialogue control flow. D-2: retrieval is a SEPARATE capability (C9) — dialog-core calls it, never embeds it.

• Group: Voice & AI
• Contract: contracts/dialog-core/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/dialog/turns
• Capability face (internal first-party — NOT customer-keyed):
  • https://api.vagarylabs.com/v1/turn

Endpoints

Method	Path	Summary
POST	/v1/turn	Process one conversational turn (intent → optional tools + retrieval → LLM → safety → stream)
POST	/v1/turn/{session_id}/cancel	barge-in — cancel the in-flight turn
GET	/health	liveness
GET	/metrics	Prometheus

Product face

The external, paying-customer surface served by the edge at /product/v1/* (contracts/dialog-core/product/v1/openapi.yaml).

Method	Path	Summary
POST	/turns	Process one conversational turn (managed, metered) — wraps the capability's orchestration

Schemas

TurnRequest

Field	Type	Description
organization_id	string
session_id	string
input	string
stream	boolean
model	string	LLM model hint forwarded to provider-gateway (which owns provider selection)
system	string	item 6 — per-caller system-prompt override; default is the service preamble
history	boolean	item 1 — enable/disable multi-turn conversation history for this turn (overrides the DIALOG_HISTORY_ENABLED default)
messages	array	item 1 — OPTIONAL client-supplied PRIOR conversation window ({role,content} list, EXCLUDING the current input). When present it is used as the history for this turn (durable/cross-replica product-face state), taking precedence over the in-process store. Absent => backward-compatible (in-process store when history is on, else stateless).
retrieval	object	opt-in RAG params — dialog-core calls the retrieval capability (C9), never embeds it
tools	array	function-calling tool definitions passed through to provider-gateway; returned tool_calls are surfaced (guarded) — or EXECUTED when execute_tools=true (T5-3)
execute_tools	boolean	T5-3 — OPT-IN: run the agentic execute-then-continue loop (execute each tool_call, feed the result back, re-call, until a final answer). Requires tools. Absent/false => tool_calls are only surfaced (byte-identical to the pre-loop turn).
tool_dispatch	object	T5-3 — how the executor DISPATCHES each tool by name to the caller's own HTTP endpoint (I5: core hosts no business tool). name -> {url, method?, headers?}. A tool with no entry yields a fail-open tool_not_dispatchable result the model can recover from.

TurnResponse

Field	Type	Description
session_id	string
content	string
intent	string
tool_calls	array
tool_trace	array	T5-3 — present only when execute_tools ran: the ordered trace of executed tool_calls (args + result + latency), never silent.
tool_stop_reason	string	T5-3 — why the execute-then-continue loop stopped (present only when it ran)
safety	object

Error

Field	Type	Description
error	string

LlmTokensEmit

Field	Type	Description
type	string	chunk = streamed word-buffer content; clear = flush-buffer control (no text); filler/fallback retained for voice parity (dialog-core emits chunk/clear — provider-gateway owns failover)
text	string	REQUIRED for chunk/filler/fallback; OMITTED for clear (control message)
timestamp	number	unix float seconds at emit; present on every message
org_id	string	ADDITIVE tenant org_id threaded from the transcript envelope; absent on clear; nullable for API-key (no-org) sessions
consent_ref	string	ADDITIVE D22 consent lineage threaded from the transcript envelope; present on text-bearing kinds, absent on clear

BotResponseEmit

Field	Type	Description
type	string	always the literal "bot_response" — the gateway pattern-matches this exact value
text	string	assistant display text (the same word-buffer chunk sent to the TTS leg); REQUIRED on every message
timestamp	number	unix float seconds at emit; present on every message (gateway ignores it, reads only type+text)

---

Generated by scripts/gen-capability-docs.py from contracts/dialog-core/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.