> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# 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: '+15551234567'
    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](/documentation/config-as-code/simulation-plans) `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 (`+12345678900`) 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:

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
endpoints:
  - value: '+15551234567'
    direction: INCOMING
  - value: '+15551234567'
    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:

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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.

<Note>
  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.
</Note>

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

<Note>
  For the full field reference of every kind, see the [Config DSL reference](https://roark.ai/roark-config.schema.json) schema.
</Note>