# config.cuelo (/reference/config) `config.cuelo` is YAML, validated against a JSON Schema (`schema/config.cuelo.schema.json`) that the CLI and the engine share. Editors with YAML language support can use it for completion: ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/thoughtsinc/cues-harness/main/schema/config.cuelo.schema.json ``` Never put credentials in `config.cuelo`. Reference them as `${VAR}`, and set the variable in `.env`. ## A complete example [#a-complete-example] ```yaml title="config.cuelo" name: support-agent stt: provider: smallest language: en vocab: [Cuelo, Acme, SKU] llm: provider: cerebras model: qwen-3.8-27b prompt: ./config/prompts/system.md # or: instructions: "You are ..." greeting: "Hi, this is Acme support. How can I help?" thinker: provider: anthropic model: claude-opus-5-5 when: refunds, anything that needs several steps tts: provider: smallest voice: ./config/voices/default.yaml turns: controller: turn-1-mini barge_in: true barge_in_detector: maai backchannel: true backchannel_model: maai backchannel_hold: 1200 tools: - type: function name: lookup_order description: Look up an order by its number. Use it before answering about an order. parameters: type: object properties: { order_id: { type: string } } required: [order_id] summary: true store: url: sqlite://cuelo.db audio: ./recordings serve: host: 127.0.0.1 port: 4141 workers: 1 ``` ## Top level [#top-level] | Field | Type | Default | Description | | ----------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- | | `name` (required) | string | — | Agent name, shown in the dashboard and used as the Python project name. | | `stt` (required) | object | — | Speech-to-text. Streaming only. | | `llm` (required) | llm | — | — | | `thinker` | thinker | — | — | | `tts` (required) | object | — | Text-to-speech. | | `turns` | object | — | Turn-taking: when the agent speaks, yields and backchannels. | | `actions` | string[] | — | Deprecated: use `tools`. Python tools in src/actions/<name>.py whose schema comes from @function_tool. | | `summary` | boolean | `true` | Write a call summary with the LLM when each call ends. | | `store` | object | — | — | | `serve` | object | — | — | | `tools` | tool[] | — | Functions the model can call (OpenAI function tool format). | ## `stt` [#stt] Speech-to-text. Providers are listed in [Providers](/reference/providers#speech-to-text). | Field | Type | Default | Description | | --------------------- | ----------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------- | | `provider` (required) | `smallest` \| `elevenlabs` \| `deepgram` \| `cartesia` \| `inworld` \| `assemblyai` \| `soniox` | — | — | | `model` | string | — | Provider model ID. Omit for the provider default. | | `language` | string | — | BCP-47 tag, e.g. en or en-US. Omit to auto-detect. | | `vocab` | string[] | — | Terms to recognize more reliably: names, products, jargon. | | `api_key_env` | envName | — | — | | `base_url` | string | — | — | `api_key_env` reads the key from a different variable than the provider's default. `base_url` points at a self-hosted or regional endpoint. ## `llm` [#llm] The talker: the model that writes every spoken reply. | Field | Type | Default | Description | | --------------------- | ---------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` (required) | `anthropic` \| `openai` \| `openrouter` \| `cerebras` \| `openai-compatible` | — | — | | `model` (required) | string | — | — | | `prompt` | string | `"./config/prompts/system.md"` | Path to the system prompt file. Read at the start of every call, so edits apply without regenerating. Use `instructions` instead to write it inline. | | `temperature` | number | — | — | | `max_tokens` | integer | `1024` | — | | `api_key_env` | envName | — | — | | `base_url` | string | — | — | | `instructions` | string | — | The system prompt, inline (instead of a `prompt` file). | | `greeting` | string | — | What the agent says as soon as the call connects (spoken as written, no LLM). Omit to let the caller speak first. | `openai-compatible` takes any endpoint that speaks the OpenAI Chat Completions API, such as vLLM, Ollama, Groq or Together. Set `base_url` and `api_key_env`: ```yaml llm: provider: openai-compatible base_url: http://localhost:8000/v1 model: meta-llama/Llama-4-Scout api_key_env: VLLM_KEY ``` ## `thinker` [#thinker] Optional reasoning model the talker consults through a `think` tool. See [Thinker](/build/thinker). | Field | Type | Default | Description | | --------------------- | ---------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `provider` (required) | `anthropic` \| `openai` \| `openrouter` \| `cerebras` \| `openai-compatible` | — | — | | `model` (required) | string | — | — | | `temperature` | number | — | — | | `max_tokens` | integer | — | — | | `api_key_env` | envName | — | — | | `base_url` | string | — | — | | `prompt` | string | — | Path to the thinker's system prompt file. | | `instructions` | string | — | The thinker's system prompt, inline. | | `when` | string | — | When the talker should call `think`, in plain words (added to the tool description), e.g. "math, refunds over $100, anything multi-step". | | `filler` | boolean | `true` | The talker says a short filler ("let me think") before calling `think`, so the caller isn't left in silence. | | `context_turns` | integer | `6` | Recent conversation messages the thinker sees along with the question. | ## `tts` [#tts] Text-to-speech. | Field | Type | Default | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- | | `provider` (required) | `smallest` \| `elevenlabs` \| `elevenlabs-streaming` \| `elevenlabs-dialogue` \| `cartesia` \| `cartesia-streaming` \| `deepgram` \| `deepgram-streaming` \| `inworld` \| `inworld-streaming` | — | — | | `voice` (required) | string | — | A provider voice ID, or a path to a voice profile (voices/\*.yaml). | | `model` | string | — | — | | `speed` | number | — | — | | `language` | string | — | — | | `api_key_env` | envName | — | — | | `base_url` | string | — | — | ### Voice profiles [#voice-profiles] When `tts.voice` is a path (`./config/voices/default.yaml`), the file holds: | Field | Type | Default | Description | | ---------------- | ------ | ------- | ------------------------------------------------------------------- | | `id` (required) | string | — | Provider voice ID. | | `provider` | string | — | Which TTS provider the ID belongs to. Checked against tts.provider. | | `model` | string | — | — | | `speed` | number | — | — | | `language` | string | — | — | | `pronunciations` | object | — | word -> how to say it, e.g. Cuelo: kway-low | ## `turns` [#turns] Turn-taking. See [Turn-taking](/conversation). | Field | Type | Default | Description | | ------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `controller` | `vad` \| `smart-turn` \| `turn-1-mini` \| `maai` | `"turn-1-mini"` | How the end of the user's turn is detected. vad: fixed silence. smart-turn: Smart Turn v3 judges at each pause whether the speaker sounds done (multilingual). turn-1-mini: streaming end-of-turn model (English). maai: MaAI voice activity projection from user + agent audio; also decides interruptions (needs cuelo[maai], PyTorch). Model weights download on first use. | | `min_silence` | integer | — | Milliseconds of silence before deciding. vad: the silence that ends the turn (default 500). smart-turn: the pause that triggers a check (default 200). turn-1-mini: quiet required before the model may end the turn (default 60). | | `barge_in` | boolean | `true` | Let the user interrupt the agent. | | `interrupt_after` | integer | `300` | Milliseconds of user speech over the agent that count as an interruption. | | `backchannel` | string \| object | `true` | Agent backchannels ("mhm") while the user talks. true for defaults. | | `max_silence` | integer | `1500` | smart-turn / turn-1-mini: end the turn after this much silence even if the model is unsure. | | `threshold` | number | — | smart-turn / turn-1-mini: end-of-turn probability needed (defaults 0.5 / 0.36). | | `barge_in_detector` | `vad` \| `backchannel-detector` \| `maai` | `"maai"` | What decides that the user is interrupting. vad: any speech for interrupt_after ms. backchannel-detector: a small model that lets "yeah"/"mhm" through. maai: MaAI decides from both voices (default; needs cuelo[maai], PyTorch). | | `backchannel_model` | `vad` \| `maai` | `"maai"` | What times the agent's backchannels. vad: a short pause after a few new words. maai: MaAI VAP-BC predicts when a listener would say "mhm" (needs cuelo[maai], PyTorch). | | `backchannel_hold` | integer | `1200` | After the agent backchannels, wait this many ms before taking the turn, so a pause mid-story gets a "mhm" instead of a reply. 0 turns it off (faster replies, fewer backchannels). | ## `tools` [#tools] A list of functions the model can call, in OpenAI's function tool format. See [Tools](/build/tools). | Field | Type | Default | Description | | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (required) | any | — | — | | `name` (required) | string | — | — | | `description` | string | — | Tell the model what it does and when to use it. | | `parameters` | object | — | JSON Schema for the arguments (type: object, properties, required). | | `http` | httpCall | — | — | | `client` | boolean | `false` | Run it in the connected app: the call goes to the realtime client as an OpenAI function_call and the app answers with function_call_output. | | `handler` | string | — | Python function as module:function (default: src.actions.<name>:<name>). | ### `http` [#http] | Field | Type | Default | Description | | ---------------- | ----------------------------------------------- | -------- | -------------------------------------------------------------------------- | | `url` (required) | string | — | Endpoint URL. ${VAR} reads an environment variable at call time. | | `method` | `GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE` | `"POST"` | GET/DELETE send the arguments as query parameters; others as a JSON body. | | `headers` | object | — | Request headers; use ${VAR} for secrets (kept in .env). | | `timeout_s` | number | `10` | — | ## `store` [#store] | Field | Type | Default | Description | | ------- | ------ | --------------------- | --------------------------------------------------------------------------------------- | | `url` | string | `"sqlite://cuelo.db"` | sqlite://, postgres:// or mysql:// URL. Put passwords in .env and use ${VAR}. | | `audio` | string | `"./recordings"` | Where call recordings are written. | ## `serve` [#serve] | Field | Type | Default | Description | | ---------- | --------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api` | `openai-realtime` \| `none` | `"openai-realtime"` | openai-realtime: serve the OpenAI Realtime API at /v1/realtime. none: only your own routes from src/api.py. | | `host` | string | `"127.0.0.1"` | — | | `port` | integer | `4141` | — | | `workers` | integer | `1` | Server processes for `cuelo serve`. Each holds its own calls and models; `cuelo machine check` recommends a number. | | `api_keys` | string[] | — | Keys every request must carry (Bearer, x-api-key, or the openai-insecure-api-key.<key> WebSocket subprotocol), as ${VAR} references to .env. Required to serve on a non-loopback host. | | `cors` | string[] | — | Browser origins allowed to call the API, e.g. https://app.example.com. Empty: same origin only. | ## Environment variables in config [#environment-variables-in-config] `${VAR}` is expanded from the environment in `store.url`, `serve.api_keys`, and tool `http.url` and `http.headers`. `cuelo generate` adds every referenced variable to the project's required environment, and `cuelo doctor` checks they are set.