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-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

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

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`

Speech-to-text. Providers are listed in Providers.

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`

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:

llm:
  provider: openai-compatible
  base_url: http://localhost:8000/v1
  model: meta-llama/Llama-4-Scout
  api_key_env: VLLM_KEY

`thinker`

Optional reasoning model the talker consults through a think tool. See 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`

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

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`

Turn-taking. See Turn-taking.

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`

A list of functions the model can call, in OpenAI's function tool format. See 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`

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`

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`

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

${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.

config.cuelo

A complete exampleCopy Anchor Link

Top levelCopy Anchor Link

sttCopy Anchor Link

llmCopy Anchor Link

thinkerCopy Anchor Link

ttsCopy Anchor Link

Voice profilesCopy Anchor Link

turnsCopy Anchor Link

toolsCopy Anchor Link

httpCopy Anchor Link

storeCopy Anchor Link

serveCopy Anchor Link

Environment variables in configCopy Anchor Link

On this page