Agents

Define voice agents as config

A voice agent: its prompt and the lines it can be reached on. Thin by design; endpoints are nested and reconciled with the agent. References nothing.

# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json
kind: agent
name: frontdesk
description: Bright Smiles front desk booking agent
customId: bright-smiles-frontdesk
prompt: file://prompts/frontdesk.md
endpoints:
  - value: '[phone]'
    direction: INCOMING_AND_OUTGOING

• name is the local key (^[a-z0-9][a-z0-9-_.]*$) and, with the kind, forms the config identity.
• displayName (optional) is the agent’s name as it appears in Roark, where spaces and capitals are allowed; it defaults to name. Set it to an agent’s exact existing name to bring an agent you created in the app under config (apply takes it over in place instead of creating a duplicate) when that name isn’t slug-shaped, for example displayName: "Dental Clinic" with name: dental-clinic.
• Other resources reference an agent by its name (the slug), not its displayName (e.g. a flow’s agents: list, a collector’s AGENT filter, or a simulation plan’s agentEndpoints).

Endpoints

An endpoint is identified by its value: the E.164 number for a phone line, the URL otherwise. That is the only field you always have to give.

Field	Default	Notes
value	—	E.164 ([phone]) for PHONE, the ws:// or wss:// URL for WEBSOCKET
type	PHONE	PHONE or WEBSOCKET
direction	INCOMING	INCOMING or OUTGOING
environment	production

An endpoint is identified by its value and its direction together, so one number can carry an inbound endpoint and an outbound one:

endpoints:
  - value: '[phone]'
    direction: INCOMING
  - value: '[phone]'
    direction: OUTGOING

That is how a number that both takes and places calls is set up: an endpoint is INCOMING or OUTGOING, never both.

Endpoints reconcile with the agent on that pair: one you add is created, one you change is updated, and one you remove is detached. Changing a direction is therefore a new endpoint and the retirement of the old one rather than an edit, which matches what it does to your call routing.

Prompt

prompt is the agent’s system prompt, kept in your repo and versioned in Roark. Like every prompt field it takes an inline string or a file:// reference resolved from your config root:

prompt: file://prompts/frontdesk.md

Each apply versions it: a change appends a new version, identical content is a no-op. It lands in its own history on the agent’s Prompts tab, shown as a read-only Config as code lineage, separate from prompts you edit in the app or that arrive on calls. Omitting prompt leaves any existing prompt alone: config sets a prompt, it never clears one you did not declare.

The prompt is kept for your reference and versioning only. Roark does not run your agent, and no metric evaluates against this prompt, so setting it does not change how your agent behaves or how it is scored.

Other endpoint types (LiveKit, SmallWebRTC, ElevenLabs, Kore, Google CES, Daily) are not configurable here. They are bidirectional, so they carry no direction, and each needs provider configuration the config format has no place for. Their endpoints are created by the integration that owns them.

Omitting the endpoints block leaves the agent’s existing lines alone. Writing endpoints: [] removes all of them. The difference matters, because it is the difference between saying nothing about your phone numbers and saying you want none.

Outbound dialling is not expressible in config: an endpoint applied from a bundle is always created with it set to none. The alternative needs an HTTP request definition that config cannot yet declare, so configure that in the dashboard.

For the full field reference of every kind, see the Config DSL reference schema.