> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md).

# Services

Bind agents and context graphs into deployable services, manage version sets, and configure voice behavior for conversations across supported channels.

A service binds an **agent**, a **context graph**, and **version sets** into a deployable unit. Services are the entry point for conversations: when a user calls a phone number or starts a chat, the platform resolves the service to determine which agent persona, conversation flow, and model configuration to use. A service that runs only [direct programs](https://docs.concurrence.com/developer-guide/platform-api/workspaces/direct-programs.md) binds no context graph.

{% hint style="info" %}
**Classic API vs Platform API**: These APIs expose separate service resources. Platform services are workspace-scoped and their IDs are used with Platform conversation and call routes. Classic service IDs are organization-scoped and used with Classic conversation routes.
{% endhint %}

## Key Concepts

* **Agent and context graph binding**: every service links to one agent. It also links to one context graph, which is optional when each of its version sets runs a [direct program](https://docs.concurrence.com/developer-guide/platform-api/workspaces/direct-programs.md): a service that binds none has `context_graph_id: null`.
* **Version sets**: named configurations that pin specific agent and context graph versions, dynamic behavior versions, and LLM model preferences.
* **Tags**: key-value metadata stored with the service.
* **Channel type**: the separate `channel_type` field declares whether the service is for `voice` or `text` conversations.
* **Tool capacity**: maximum concurrent tool executions per conversation (1-10, default 3).
* **Declared languages**: the optional `declared_languages` field lists the languages the service serves, as ISO 639-1 codes. It accepts a non-empty list of distinct values from `en`, `es`, `ar`, `fr`, `de`, `pt`, `zh`, `ja`, and `ko`, so at most 9 entries. A code outside that set, a duplicate, or an empty list returns `422`. Omit it or send `null` on create for none declared. On update, omit it to keep the list and send `null` to clear it. An update that sends a list replaces the whole list. In the Developer Console, open the service under **Build > Agents**, choose **Edit details** from the **More actions** menu, and check its **Languages**. Clearing every box clears the field. A service serves its declared languages, or only its agent's default language when it declares none. A voice call starts in the agent's default language, and a caller's language replaces it only when the service serves that language. The agent's default language must be one of the declared languages: a save that leaves it out returns `422` with `detail.code` `declared_languages_exclude_agent_default`. See [Languages a Service Serves](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#languages-a-service-serves).
* **Accepted conversation context**: the `accepted_context` schema declares which string and number values callers may supply when starting a conversation.
* **Platform caller verification**: `platform_caller_verification` (default `true`) decides whether the platform verifies a caller who may match a patient record. With `false`, the platform never asks the service's callers to verify, and the built-in tools that read a patient record refuse. See [Caller Verification](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#caller-verification).
* **Unverified integration results**: `allow_unverified_integration_results` (default `false`) lets the agent read integration results back to an unverified caller. Only a Concurrence platform administrator (`platform:admin`) can turn it on, and it cannot be combined with `caller_verification_endpoint_id`. See [Caller Verification](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#unverified-integration-results).
* **Medical emergency ending**: `medical_emergency_ending` (default `stay_on_line`) decides whether a `gpt_realtime` call ends after its emergency script for a medical emergency described in English. `end_after_script` plays a closing line after the script and ends the call. Self-harm keeps the call open in every setting, and the setting doesn't change platform-managed calls. Choose it with the service's clinical owner. See [Realtime Emergency Script](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#realtime-emergency-script).

### Services in the Developer Console

Services are listed under **Build > Agents**. A service's page has **Configuration**, **JSON**, and **History** tabs.

* **Saving.** Before an edit is written, the Console checks the draft with the [service plan](#plan-a-service-save) and lists every problem it finds. **Save changes** is enabled once the check reports none.
* **Settings.** The Configuration tab has a **Settings** section that lists the tunable settings each harness the service runs declares, grouped by area. Each setting shows its description, the value in effect, and whether that value is set on the service or comes from the harness default. The limits, choices, and defaults shown come from the [harness settings schema](#read-and-save-harness-settings). A setting that is not writable at the service scope is shown read-only. Editing a value, or resetting it to the harness default, is a save that is separate from the rest of the service edit. Values are checked against the schema's bounds before the save is offered, and a save replaces the service's stored settings on the revision they were read from, so a refusal leaves the stored settings unchanged. Changing settings needs an admin or owner role.
* **Version sets.** Each version set picks its engage model from the workspace's [model list](#list-models-the-workspace-may-pin), or the platform default, and a reasoning effort from the efforts that model accepts. A refused model or effort shows the API's message on its version set.
* **History** lists the audit events recorded for the service, newest first: the action, its time, the actor, and the recorded changes. It shows the latest 50 changes.

## Endpoints

### Create a Service

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

Leave out `context_graph_id`, or send `null`, to create a service that binds no Context Graph. Each of its version sets must run an agent version whose program is direct and pin no Context Graph version, or the request returns `422` with `detail.code` `context_graph_required`. See [Direct Programs](https://docs.concurrence.com/developer-guide/platform-api/workspaces/direct-programs.md#save-refusals).

### List Services

Filter by `agent_id` or `context_graph_id` to find the services that run a given agent or Context Graph. Filters apply before pagination.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get a Service

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update a Service

Omitted top-level fields and fields sent as `null` leave their stored values unchanged. Explicit non-null values, including an empty description, `is_active: false`, or empty `keyterms` and `tags` lists, are applied when valid for the field.

A supplied `voice_config` object replaces the stored voice configuration. Nested nulls accepted by its schema are preserved, including `forwarding.forward_to: null` for dynamic forwarding. Sending `voice_config: null` leaves the existing configuration unchanged. Read the current configuration first and resend the complete object when changing it.

Omitting `context_graph_id` or sending `null` keeps the stored binding. An update can bind a Context Graph to a service that has none, and cannot remove one.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

Updates to a service, and upserts and deletes of its version sets, are recorded in the [audit log](https://docs.concurrence.com/developer-guide/platform-api/safety.md#audit-trail) with the actor and the field diff.

### Delete a Service

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}" method="delete" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Plan a Service Save

Plan a create or an update before you send it. A plan runs the save's own checks and writes nothing. `problems` lists each refusal the save would answer with, in the order the save meets them, `changes` is the field diff against the stored service, `families` lists each version set's voice family, and `readiness` is the [readiness](#read-service-readiness) readback for the configuration the save would store. A plan needs the same permission and scope as the save it previews, and a permission the save would need for a field you set is reported as a problem rather than a `403`. The save can still be refused, for example when a pinned version set has been archived since the plan.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/plan" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/plan" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Read Service Readiness

Read the service's current configuration and whether each destination passes the dial check, without placing a call. The response lists the voice use cases bound to the service, its lines, the voice family each version set runs, the configured call policies, and launch settings such as whether a human line is configured. Each family entry lists any `voice_config` fields that family ignores. See [Voice Setting Warnings](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#voice-setting-warnings). Phone numbers, identifiers and authored speech are not returned, and labels have digits redacted. Readiness does not verify that anyone picks up, and family capabilities are the catalog's declarations, not evidence from a call. A service with no bound use case has empty use-case results.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/readiness" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Read Configuration Identity

Read the identity of the version set you intend to run when reviewing a configuration or comparing execution evidence. This requires service-view access and does not start a conversation or return the configuration's contents.

The `service_config_digest` identifies the resolved configuration, including the selected versions, harness releases and settings. The accompanying `updated_at` is the service revision used for that resolution. Use the digest when comparing configuration evidence and the revision when making a [conditional configuration write](#conditional-configuration-writes).

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/configuration-identity" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Read and Save Harness Settings

Read the declared settings and the service's current values before changing them. A save replaces the service's overrides, and a key left out follows its harness default. Setting values must satisfy every selected harness that declares the key. Reading requires service-view access, and saving requires service-update access.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/settings/schema" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/settings" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/settings" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Set Harness Pins

A pin selects a registered harness release for the service. Saving replaces the service's pins, and a harness left out follows its default. The release must be compatible with the service and available to run. Saving requires service-update access. Review settings affected by a pin change before choosing whether to discard overrides that the selected harnesses do not declare.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/harness-pins" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Conditional Configuration Writes

When saving harness settings, harness pins or a version set, first read the configuration identity or service and retain its `updated_at`. Then read the settings, pins or version set you intend to edit, review those values and submit your change with that retained revision as `expected_updated_at`. Do not fetch a newer revision after reviewing the values and attach it to an older edit. Preserve the returned timestamp string exactly, including fractional-second precision; converting it through a millisecond-only date type can cause a conflict. [Get a Service](#get-a-service) also supplies this revision for configuration edits. A revision mismatch returns `409` without changing configuration. Settings and pin writes check the revision before configuration-specific validation, including whether to discard unsupported settings. Permission and request-schema checks still apply.

After a conflict or a timeout with an uncertain result, repeat that read order and compare the current configuration with the intended change before deciding whether to retry. A conditional write that changes the service advances the revision, so repeating it with the old revision returns `409`. Saving the same harness settings or pins using the current revision makes no additional change or change-audit event. Omitting `expected_updated_at` makes no comparison to a revision the caller reviewed.

Revision protection applies to the saved service definition. An agent or Context Graph version, a workspace default or a harness default can change the effective configuration digest independently. Reading identity after a save observes the resulting configuration; it does not make that save atomic with a comparison of the full digest. Compare execution evidence with the digest you intend to qualify; a configuration identity alone is not proof of execution. When a write must apply only to the digests you reviewed, [promote the reviewed configuration](#promote-a-reviewed-configuration).

### Promote a Reviewed Configuration

A promotion stores a candidate version set as `target_version_set`, together with the service's harness pins and settings when the request includes them, in one write. The write applies only while the service is at `expected_updated_at` and every version set in `reviewed_base` still has the `service_config_digest` you reviewed through [Read Configuration Identity](#read-configuration-identity). A change that alters a reviewed digest - whether it comes from the service, an agent, a Context Graph, a dynamic behavior set, a workspace default or a harness default - returns `409` with `detail.code` `promotion_base_changed`, and nothing is stored.

Name the target in `reviewed_base` when the service already has it. A request that includes `harness_pins` or `settings` changes what every version set loads, so it names every version set of the service. A target the service does not have is created and is not named in `reviewed_base`. The candidate names its agent version, and its Context Graph version when the service binds a Context Graph. A candidate that follows the latest version of either returns `422`. A service that binds no Context Graph pins no graph version, and a candidate that pins one returns `422` with `detail.code` `context_graph_required`. The candidate also gets the checks of a version set, harness pin or harness settings save. Leaving out `harness_pins` or `settings` keeps the stored values.

The `201` response is the promotion receipt, recorded with the write. Its `service_config_digest` identifies the configuration a session of the target version set loads from what the promotion stored, and its `updated_at` is the revision for your next conditional write. A receipt records what one promotion stored and stays the same when the service is edited later. It is not evidence of the service's current configuration or of what a session ran. Compare the digest in [simulation execution evidence](https://docs.concurrence.com/developer-guide/platform-api/safety/simulation-coverage.md#configuration-lock-and-execution-evidence) with the receipt's digest to relate a run to a promotion.

Use a new `request_id` for each promotion and repeat it only to retry the same request. The same request with the same `request_id` from the same credential returns the stored receipt with `200` and writes nothing, which is how to learn the result after a timeout or a lost response. The same `request_id` with a different request returns `409` with `promotion_request_mismatch`. A `503` stores nothing, except `promotion_transaction_timeout` with `detail.outcome` `unknown`, where the write can have been stored. Retry with the same `request_id`. Promotion requires service-update access.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/promotions" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Upsert a Version Set

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/version-sets/{name}" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Process a Voice-Note Turn

Send one recorded voice note with the caller's E.164 `phone_number`, and the operation returns the agent's spoken reply. The note can be OGG Opus, WebM, WAV, MP4, or MP3 audio, up to 20 MB, sent with a matching audio content type. Turns are keyed on the workspace, service, and phone number, so a second note from the same number while one is still running returns `409`. See [WhatsApp Voice Notes](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#whatsapp-voice-notes) for the reply formats and session behavior.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/voice-turn" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The note is transcribed in the caller's language when the matched caller record has one, or in the workspace voice language when that is neither English nor `multilingual`. Otherwise, including for a caller or workspace set to `multilingual`, the language the note was spoken in is detected, so a Spanish note on an English workspace is transcribed in Spanish. A `language_providers` entry for that language can pick the reply voice. See [Default TTS Model](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#default-tts-model) for how voice notes choose a voice.

| Status | Detail                                       | What it means                                                                                               |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `413`  | Starts with `Audio too large`                | The file is over 20 MB. Send a smaller file.                                                                |
| `415`  | Starts with `Unsupported audio content type` | Send OGG Opus, WebM, WAV, MP4, or MP3 audio with its audio content type.                                    |
| `422`  | `Empty audio file`                           | The upload had no audio. Fix the upload rather than resending it.                                           |
| `422`  | `Audio could not be decoded`                 | The recognizer could not read the audio. Fix the recording or its encoding, and don't resend the same file. |
| `422`  | `No speech detected in audio`                | The audio has no speech to answer. Don't resend the same file.                                              |
| `502`  | `Speech-to-text failed`                      | Recognition failed and the turn did not run, so resending the note is safe.                                 |
| `502`  | `Text-to-speech failed`                      | The turn ran, but its reply could not be spoken. Resending the note runs the turn again.                    |
| `504`  | A timeout                                    | The turn may have run. Resending the note can run it again.                                                 |

### Text Conversations

Use [Conversations](https://docs.concurrence.com/developer-guide/platform-api/conversations.md) for application-hosted text and the managed channel integrations for SMS and WhatsApp.

### Preview Rendered Service Instructions

Returns configuration-only instructions for explicit call context. The request supplies tool and transfer availability, language, and the crisis resource. It does not include caller history or decide which dynamic behavior is in force, creates no run, and changes no saved configuration.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/prompt-preview" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Accepted Conversation Context

Declare `accepted_context` on the service's create or update request. Each entry specifies a unique `key`, a `type` of `string` or `number`, a `description`, and a `required` flag. Conversation creation validates its parsed `context` map against this schema. Unknown keys, missing required keys, and values that fail this validation return `422`. The guide below also covers a boolean-coercion edge case in request parsing.

Update the service with `PUT /v1/{workspace_id}/services/{service_id}`. A supplied `accepted_context` list replaces the entire previous list. Omission or `null` preserves it, and `[]` accepts no caller-supplied context keys. Coordinate newly required keys with callers before changing a shared service.

The service declares the schema, and the active Context Graph's state-to-tool specification declares `context_bindings`. Follow [Pass Context to Tool Parameters](https://docs.concurrence.com/developer-guide/guides/conversation-context.md) for a complete setup, supported tool paths, and mapped parameter names and automatic `channel-id` prerequisites.

The same declaration governs values a trusted backend sets on a live voice call. Declare such a key with `required: false`. On voice, a tool bound to it refuses to run until it is set. See [Set Context on a Live Voice Call](https://docs.concurrence.com/developer-guide/guides/live-call-context.md).

## Version Sets

Creating a service, updating it, and upserting a version set all check the version sets they write. A version set name must match `[A-Za-z0-9_-]{1,40}`, or the request returns `422`. Each pinned agent and Context Graph version must exist for the service's agent and graph, or the request returns `404`. Changing a service's `agent_id` or `context_graph_id` checks its stored pins against the new target.

{% hint style="warning" %}
**Model ID validation.** Creating or updating a service and upserting a version set check every `llm_name` in `version_sets.llm_model_preferences`. A model id the platform cannot route returns `422` naming the version set, role, and id. A retired Claude id returns `422` naming the version set, role, and the current model of the same tier to use instead, such as `claude-sonnet-5-5` for `claude-sonnet-4-6`. [Skills](https://docs.concurrence.com/developer-guide/platform-api/workspaces/skills.md#execution-configuration) lists each replacement. The check runs only on writes, and reading a stored configuration does not re-validate it.
{% endhint %}

Version sets support an optional `llm_model_preferences` map that overrides the default models used for context graph navigation and conversational engagement. Each key identifies a model role: use `nav` for navigation and `engage` for response generation. Each value specifies the preferred model and optional parameters for that role. When omitted, sessions use the platform defaults.

This lets you pin specific agent versions to specific models for controlled rollouts, A/B testing, or compliance requirements that mandate a fixed model version.

### Model preference resolution order

1. **Version set override** - If the active version set has an `llm_model_preferences` entry for the relevant role, that model is used.
2. **Platform default** - If no override is configured, the platform default model is used.

The resolved model is applied consistently across voice sessions, text sessions, and simulation runs.

### Tool Turns and Reasoning Effort <a href="#tool-turns-and-reasoning-effort" id="tool-turns-and-reasoning-effort"></a>

An engage preference can set `reasoning_effort` in `experience_controls` (or in `params`, which `experience_controls` overrides). The effort applies to text conversation turns that offer the model tools, which is where the agent decides whether to call a tool or answer. When unset, the model follows the default behavior listed below.

Each model family accepts its own efforts:

| Engage model                             | Efforts a version set can set    | When unset                                   |
| ---------------------------------------- | -------------------------------- | -------------------------------------------- |
| `gpt-5.4`, `gpt-5.5`, `gpt-5.6`, `gpt-6` | `none`, `low`, `medium`, `high`  | Tool turns run at `none`                     |
| `gpt-6-astra`, `gpt-6.1-sol`             | `low`, `medium`, `high`          | Tool turns run at the model's default effort |
| `grok-4.7`, `grok-4.6`                   | `low`, `medium`, `high`, `xhigh` | `low`                                        |
| Claude and Gemini models                 | Set by the model's provider      | An effort the version set names is not sent  |

On `gpt-5.4`, `gpt-5.5`, `gpt-5.6`, and `gpt-6`, voice calls and voice notes run at `none`. For text turns without tools, an explicitly configured effort runs at `none`. When effort is unset, the model's default applies. A simulation of a text service uses the effort. A simulation of a voice service runs as its voice calls do.

**Latency.** A higher effort lets the model reason before it answers, which can make tool choices more reliable, and makes each turn slower. A turn that calls a lookup tool first reasons again once the result returns, so the turn grows by more than one step. Start at `low`, measure reply time and behavior on your own conversations in a separate workspace, and raise the effort only when the behavior needs it.

**What a save accepts.** Creating or updating a service, or upserting a version set, returns `422` when an engage preference sets an effort its model does not accept, such as `none` on `gpt-6-astra` or `xhigh` on `gpt-5.5`. The message names the version set, the preference, the model, and the efforts it accepts. A stored version set with an unaccepted effort still loads, and its next save returns `422` until the effort is changed.

**Region.** The efforts a model accepts can depend on the region your workspace runs in. [List Models the Workspace May Pin](#list-models-the-workspace-may-pin) returns each model's `reasoning_efforts` for your workspace's region, the same list the save checks. An effort outside that list returns `422` naming the region and the efforts it accepts. An empty list means the model cannot run engage tool turns in that region, and pinning it as an engage model returns `422`. Pin another model.

`gpt-5.5`, `gpt-5.6`, and `gpt-6` reason above `none` by default. A request to one of them that runs above `none`, such as a text turn without tools that leaves the effort unset, does not send the preference's `temperature`, `top_p`, `logprobs`, or `top_logprobs`. Set `reasoning_effort` to `none` when those parameters must apply.

Version sets enable safe iteration, like Git branches for your service configuration:

* **`release`**: the required default version set used when clients do not specify one. Service creation adds an unpinned `release` set when `version_sets` is omitted or empty.
* **Custom sets**: create named sets (for example, `personal-dev`, `test`, or `preview`) for your promotion workflow. Leaving a version number unset resolves the latest available version at runtime.

```mermaid
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, sans-serif","fontSize":"16px","background":"#FAF8F6","primaryColor":"#F1EAE7","primaryTextColor":"#1A1817","primaryBorderColor":"#D7D2D0","secondaryColor":"#FDFCFB","tertiaryColor":"#F6F2F0","lineColor":"#575452","textColor":"#3D3937","clusterBkg":"#FDFCFB","clusterBorder":"#E8E2DF","edgeLabelBackground":"#FAF8F6","actorBkg":"#F1EAE7","actorTextColor":"#1A1817","actorBorder":"#D7D2D0","actorLineColor":"#575452","signalColor":"#575452","signalTextColor":"#3D3937","labelBoxBkgColor":"#F1EAE7","labelBoxBorderColor":"#D7D2D0","labelTextColor":"#3D3937","loopTextColor":"#3D3937","noteBkgColor":"#F6F2F0","noteBorderColor":"#D7D2D0","noteTextColor":"#3D3937","activationBkgColor":"#F1EAE7","activationBorderColor":"#D7D2D0","altSectionBkgColor":"#FAF8F6","altSectionColor":"#3D3937"},"fontFamily":"Inter, sans-serif"}}%%
flowchart TB
    A[personal-dev] -->|validate| B[test]
    B -->|run simulations| C[preview]
    C -->|UAT + promote| D[release]
```

The recommended promotion path: `personal-dev → test → preview → release`

A version set also pins [dynamic behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors.md): its `dynamic_behavior_sets` list names a set and an exact version for each, and the upsert replaces the whole named version set except for that list, which keeps its stored pins when you leave it out. See [Pin a Version on a Service](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors.md#pin-a-version-on-a-service).

Manage Platform version sets through service updates or the single-version upsert endpoint. Agent Forge also provides `forge platform version-set` commands for listing, inspecting, upserting, comparing, promoting, and rolling back sets. Mutating commands are dry-run by default and require `--apply` to execute.

{% hint style="warning" %}
When creating a service with a non-empty `version_sets` map, or replacing that map during an update, include `release`. The single-version upsert can create or replace `release` or a custom set. It validates pinned agent and context graph versions. Names must match `^[A-Za-z0-9_-]+$` (max 40 characters).
{% endhint %}

## Structured Actions

Context Graph action states use a **structured Action model**. Each action and exit condition can carry a `filler_hint`, a semantic direction that guides the voice pipeline's filler generation alongside the turn's empathy tier and latency state.

```json
{
  "actions": [
    { "description": "Look up available appointment slots", "filler_hint": "Let me check what's available..." },
    { "description": "Confirm the appointment with the user", "filler_hint": null }
  ],
  "exit_conditions": [
    { "description": "Appointment confirmed", "next_state": "wrap_up", "filler_hint": "Great, I've got that booked." }
  ]
}
```

{% hint style="info" %}
**Filler hints** are not literal audio fillers. They are semantic directions that the voice pipeline uses alongside the turn's empathy tier and latency context to produce natural-sounding filler speech.
{% endhint %}

## Voice Configuration

### Session Provider

The `voice_config.session_provider` field controls which voice session runtime drives calls for a service. Supported values:

| Value             | Description                                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `concurrence`     | Concurrence's own voice pipeline (STT, reasoning, TTS). The default.                                                                 |
| `gpt_realtime`    | GPT realtime speech-to-speech model family                                                                                           |
| `eleven_realtime` | Eleven Realtime speech-to-speech family for app voice sessions, inbound phone calls, Playground, and test calls                      |
| `gpt_live`        | GPT-Live realtime speech with Concurrence reasoning and multi-state Context Graph navigation                                         |
| `grok_voice`      | Grok Voice speech-to-speech family in a built-in Grok voice, for app voice sessions, inbound phone calls, Playground, and test calls |

When the service field is unset, it inherits the agent-level provider, and with neither set the call runs on `concurrence`. The session provider can also be set to `concurrence` or `gpt_realtime` on the service's page (**Agents** in the Console).

The platform resolves the session provider with the following precedence: service > agent > `concurrence`.

Compare channels, graph support, and call controls in [Choosing a Realtime Voice Family](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#choosing-a-realtime-voice-family). Read the families a workspace can use, with their models, voices, and settings, from [voice family discovery](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#discover-voice-families).

`gpt_realtime`, `eleven_realtime`, and `grok_voice` are the speech-to-speech families. Select `eleven_realtime` on the service with both `voice_config.session_provider` and `voice_config.eleven_realtime`. An agent version cannot select it. The block requires `voice` and accepts an optional `model`. See [Eleven Realtime configuration](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#eleven-realtime) for the fields, opening notice, and billing. It serves app voice sessions, inbound phone calls, the Playground, and test calls. Outbound calls are not available.

Select `gpt_live` on the service with `voice_config.session_provider`. Its optional `voice_config.gpt_live` block selects the model and voice. Omitting it uses `gpt-live-1` and `marin`. It serves app voice sessions, inbound phone calls, Playground, and test calls in US workspaces without regional data residency. Concurrence reasoning navigates multi-state Context Graphs on delegated requests. Phone calls support end call and cold transfer. Outbound calls, warm transfer, and operator takeover are not available. See [GPT-Live](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#gpt-live) for configuration, voices, prerecorded lines, billing, and exact save refusal codes.

Select `grok_voice` on the service with `voice_config.session_provider`. An agent version cannot select it. Its optional `voice_config.grok_voice` block sets the model, voice, speed, reasoning effort, transcription keyterms, and language hint. It serves app voice sessions, inbound phone calls, Playground, and test calls in workspaces without regional data residency, on a Context Graph of exactly one action state with no enabled dynamic behaviors. Phone calls support end call and cold transfer. Outbound calls, warm transfer, and operator takeover are not available. See [Grok Voice](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#grok-voice) for configuration, voices, prerecorded lines, billing, and exact save refusal codes.

A `gpt_realtime` or `eleven_realtime` service needs all of these:

* For `gpt_realtime`, one action state or 2 to 12 action states with unique names and valid exit targets. Both initial-state fields on a multi-state graph must name its first state. For `eleven_realtime`, exactly one action state.
* No typed `guardrails` on any action state.
* For `eleven_realtime`, no enabled dynamic behaviors and no tool call spec that sets `navigate_on_completion`.
* For `eleven_realtime`, a workspace without regional data residency (its `data_residency` setting is `any`). A workspace's `data_residency` cannot be set to `regional` while one of its services is on `eleven_realtime`: the request returns `422` with `detail.code` `data_residency_refused`.

A save that breaks one of these returns `422` and changes nothing. Show the response's message to the person who made the save. The graph and behavior messages name the version set, the graph or the behaviors, and what to change:

| Refusal                                                                       | What to do                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The Context Graph does not meet the selected family's requirements            | For `gpt_realtime`, use one action state or 2 to 12 action states with unique names and existing exit targets. For `eleven_realtime`, use exactly one action state. Choose `concurrence` for other graph shapes. |
| A multi-state `gpt_realtime` graph starts anywhere other than its first state | Set `new_user_initial_state` and `returning_user_initial_state` to the first state's name.                                                                                                                       |
| An action state has typed `guardrails`                                        | Move each rule to the state's `boundary_constraints`, bind a graph version without guardrails, or set `voice_config.session_provider` to `concurrence`.                                                          |
| An `eleven_realtime` version set pins an enabled dynamic behavior             | Disable or unpin the behaviors, or set `voice_config.session_provider` to `concurrence`.                                                                                                                         |
| An `eleven_realtime` tool call spec sets `navigate_on_completion`             | Turn off `navigate_on_completion`, or set `voice_config.session_provider` to `concurrence`.                                                                                                                      |
| An agent version selects `eleven_realtime`                                    | Leave the agent version's `voice_config.session_provider` unset and set it on the service.                                                                                                                       |
| The workspace has regional data residency                                     | Use a workspace without regional data residency for `eleven_realtime`, or set the service to `concurrence`.                                                                                                      |

Graph-shape and behavior refusals have a plain string as `detail`. A multi-state initial-state mismatch has `detail.code` `realtime_initial_state_mismatch` and `detail.message` `gpt_realtime multi-state graphs require new_user_initial_state and returning_user_initial_state to both equal the first state 'NAME'.`, where `NAME` is the first state's name. A guardrail refusal has `detail.code` `realtime_guardrails_unsupported` and a `detail.message` that begins `gpt_realtime enforces no guardrails, but` or `eleven_realtime enforces no guardrails, but` and names the version set, the Context Graph, and each guardrail. A completion-navigation refusal has `detail.code` `realtime_completion_navigation_unsupported` and a `detail.message` that begins `eleven_realtime does not support navigate_on_completion, but` and names the action state and the tool. The agent-version refusal has `detail.code` `eleven_realtime_agent_version_unsupported` and the residency refusal `eleven_realtime_not_enabled`, each with a `detail.message`. A body that does not fit the schema has a list of problems as `detail`. Show `detail` when it is a string, `detail.message` when it is an object, and each problem's `msg` when it is a list.

A write that would pair a `gpt_realtime` version set with an unsupported graph returns `422`. Its message begins `gpt_realtime needs a context graph of at most 12 ActionStates with unique names and existing exit targets, but` and names the graph, version set, and required action. An Eleven graph-shape refusal begins `eleven_realtime needs a context graph that is exactly one ActionState, but`. The graph, guardrail, and completion-navigation checks cover service creation and updates, version-set upserts, graph versions followed at latest, and agent versions that change an inheriting service's runtime. Each version set whose runtime or graph the write changes is checked, and an unchanged pairing is not rechecked. Bind a supported graph version, correct its initial states, or select `concurrence`.

For example, saving version set `release` on Context Graph `Intake` v1 with 13 states returns this exact `detail` string:

> gpt\_realtime needs a context graph of at most 12 ActionStates with unique names and existing exit targets, but version set 'release' runs context graph 'Intake' v1, which has 13 states. Bind a graph version that is one to twelve ActionStates with unique names and valid exit targets, or set voice\_config.session\_provider to 'concurrence'.

Saving that version set on `Intake` v2, one action state with a guardrail named `no-diagnosis`, returns `detail.code` `realtime_guardrails_unsupported` with this `detail.message`:

> gpt\_realtime enforces no guardrails, but version set 'release' runs context graph 'Intake' v2, which has 1 guardrail ('no-diagnosis') on its ActionState. Move each rule to the state's boundary\_constraints, bind a graph version without guardrails, or set voice\_config.session\_provider to 'concurrence'.

A multi-state `gpt_realtime` session reasons from its current state only. The model requests moves through `change_state`, and can miss a move and stay put. `preload`, `wait_for`, `surface_spec_template`, `turn_policy`, and `channel_overrides` do not apply. Outbound calls require a single action state. See [GPT Realtime Multi-State Workflows](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#gpt-realtime-multi-state-workflows) for authoring and testing guidance.

`gpt_realtime` runs the enabled dynamic behaviors that the service's version set pins. A behavior chosen on a caller turn takes effect from a later reply, usually the reply to the caller's next turn. `eleven_realtime` runs none: an enabled-behavior refusal begins `eleven_realtime runs no dynamic behaviors, but` and names the version set and what to change. See [Speech-to-Speech Voice Families](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors.md#services-on-gpt-realtime).

`voice_config` is an optional field on the service model that controls how the voice pipeline behaves for that service. It covers latency tuning, filler behavior, response length, barge-in sensitivity, and tool access. If omitted, the service has no service-level overrides. See [Voice Configuration](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md) for field-level inheritance and defaults.

### Fields

**Latency**

| Field                 | Type                 | Default | Description                                                                                                                                                                                                                                                                                   |
| --------------------- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_buffer_delay_ms` | `int` (200 to 1000)  | `500`   | How long the pipeline buffers text before sending to TTS. Lower values feel snappier but may produce choppier speech.                                                                                                                                                                         |
| `eager_eot_threshold` | `float` (0.0 to 1.0) | -       | Confidence at which the recognizer reports an early end of turn. The agent replies at the final end of turn, so this value does not change when it responds. It applies on the platform-managed runtime, on recognizers that accept it. An English call on the default recognizer ignores it. |
| `eot_timeout_ms`      | `int`                | -       | Hard timeout for end-of-turn detection in milliseconds. It applies on the platform-managed runtime, on recognizers that accept it. An English call on the default recognizer ignores it.                                                                                                      |

**Fillers**

| Field                  | Type                                       | Default         | Description                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filler_style`         | `"backchannel"`, `"phrase"`, or `"silent"` | `"backchannel"` | Only `silent` changes runtime behavior: it mutes the agent's autonomous backchannels. `backchannel` and `phrase` are advisory, and Context Graph progress phrases still play under `silent`. See [Voice Configuration](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#fillers). |
| `filler_vocabulary`    | `list[str]`                                | -               | Custom words for the short acknowledgment played when navigation is skipped. Tool-wait phrases come from `progress_vocabulary` or Context Graph progress phrases.                                                                                                                                                            |
| `backchannel_delay_ms` | `int`                                      | `400`           | Delay before emitting a backchannel filler when navigation is skipped. Controls how quickly the agent acknowledges the caller.                                                                                                                                                                                               |

**Response**

| Field                    | Type  | Default | Description                                                                        |
| ------------------------ | ----- | ------- | ---------------------------------------------------------------------------------- |
| `max_response_sentences` | `int` | -       | Streamed-response sentence cap. Counting is approximate across streamed fragments. |
| `max_response_words`     | `int` | -       | Streamed-response word cap, enforced while consuming generated text.               |

**Barge-in**

| Field                   | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `barge_in_min_speech_s` | `float` | `0.5`   | Minimum duration of speech still in progress before it can cut the agent off. On the platform-managed runtime the speech also needs recognized words, and a finished utterance with recognized words needs no minimum. On `gpt_realtime` it applies to all speech the realtime session detects. See [Barge-in](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#barge-in). |
| `barge_in_cooldown_s`   | `float` | `1.5`   | Time after the caller last cut the agent off before speech still in progress can do so again. Prevents rapid back-and-forth interruptions. It applies only on the platform-managed runtime.                                                                                                                                                                                                                           |

**Speed**

| Field           | Type                 | Default | Description                                                                                                                                                                                                                                                                                                                        |
| --------------- | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `min_tts_speed` | `float` (0.5 to 1.0) | -       | Minimum TTS speed multiplier. When empathy pacing reduces speech rate after a distressing turn, it cannot go below this value. The empathy formula produces speeds in the 0.85-0.97 range. Set this somewhere in that band if the agent sounds unnaturally slow after emotional turns. Omit to use the default unclamped behavior. |

### Call Forwarding

Configure forwarding in `voice_config.forwarding`. Omitting that block or setting it to null leaves the forwarding tool unavailable. When present, choose warm or cold transfer explicitly and configure either a fixed destination or dynamic destination mode. There is no workspace-number fallback. A save that adds a destination, including a `fallback_to`, an approved destination or a test line, is refused with `422` unless each number is on the `allowed_forwarding_numbers` list of the voice use cases bound to the service in Channel Manager. The response names the use case and labels, not numbers. Public emergency and N11 short codes (211 through 911, and 988) are refused in every destination field, and `forward_call` does not dial them.

In dynamic mode (`forward_to: null`), `forward_call` dials only the numbers listed in `approved_destinations`, a map of E.164 number to label with up to 50 entries. A dynamic block with no approved destinations offers no `forward_call` tool, and `approved_destinations` with a fixed `forward_to` returns `422`. A `forward_call` transfer that can't connect returns the caller to the agent. The optional `fallback_to` is the line the [safe exit](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#graceful-degradation) dials in either mode, and `forward_call` doesn't use it. See [Call Forwarding](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#call-forwarding) for an example and the full flow.

The `forwarding` block is the enablement control, and there is no separate `forward_call_enabled` flag. Staffed hours, transfer reasons and the default line on a dynamic service are set in the same block. See [Transfer Hours](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#transfer-hours) and [Transfer Reasons and Default Line](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#transfer-reasons-and-default-line). The embedded service schema is authoritative for the forwarding object. On the platform-managed runtime, active turn policy can further restrict forwarding. See [Call Forwarding](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#call-forwarding) for the hold and answer-handling sequence.

### Presets

Agent Forge provides four named presets:

| Preset              | Buffer | Filler Style  | Backchannel Delay | Response Cap |
| ------------------- | ------ | ------------- | ----------------- | ------------ |
| `ultra_low_latency` | 200ms  | `backchannel` | 400ms             | 1 sentence   |
| `balanced`          | 500ms  | defaults      | defaults          | -            |
| `quality`           | 500ms  | `phrase`      | defaults          | -            |
| `gpt_realtime`      | n/a    | n/a           | n/a               | n/a          |

Presets do not select a Cartesia model, and a sent service `tts_model` value is ignored. Pin a model in `tts_config.model`. See [Default TTS Model](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#default-tts-model).

### Example

Include `voice_config` when creating or updating a service:

```json
{
  "name": "Intake Line",
  "agent_id": "abc123",
  "context_graph_id": "def456",
  "voice_config": {
    "max_buffer_delay_ms": 200,
    "filler_style": "backchannel",
    "backchannel_delay_ms": 400,
    "max_response_sentences": 1,
    "barge_in_min_speech_s": 0.25,
    "min_tts_speed": 0.92,
    "forwarding": null
  }
}
```

### CLI

Apply a preset:

```bash
forge platform service voice-config <service_id> --preset ultra_low_latency
```

Set config fields (the body replaces the stored voice config as a whole - read the current config first and include every field you want to keep):

```bash
forge platform service voice-config <service_id> --body '{"filler_style": "silent", "max_response_sentences": 1}'
```

Read current config:

```bash
forge platform service voice-config <service_id> --get
```

### API

Use [Update a Service](#update-a-service) with the `voice_config` field in the request body. The field replaces the stored voice config as a whole. Omitted fields resolve through their field-specific defaults or inheritance rules. Read the current config first (`--get` or [Get a Service](#get-a-service)) and resend the full object with your changes.

## Turn-Level Emotion

On each turn, the voice pipeline selects an emotional tone from the conversation alongside the state transition and applies it to the entire utterance - filler and main response share the same tone, so the whole turn has consistent prosody with no mid-sentence shifts. See [Voice Configuration](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md#turn-level-emotion-selection) for the available emotions and how the empathy tier shapes the reply, and [Voice Agent](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#voice-adaptation) for the adaptation behavior.

## Data Residency and Model Choices

### Get Data Residency

Returns where this workspace's model calls may be processed. Any role can read it.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/data-residency" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update Data Residency

Sets where model calls may be processed: `any` or `regional`, which allows only routes that stay in the region's geography. Turning `regional` on answers 422 with code `data_residency_refused` and lists every saved choice the region's policy forbids. An admin or owner can turn it on. Turning it off takes an owner and returns 403 for an admin.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/data-residency" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List Models the Workspace May Pin

Lists every model the workspace's data residency allows in its region. A regional workspace sees only models whose request paths stay in the region's geography. Any role can read it.

Each item's `usable_for` says whether it can be an engage model, a skill model, or both. Its `reasoning_efforts` lists the engage efforts a version set can set on it in this region: `null` for a model whose provider sets its own effort, and an empty list for a model that cannot run engage tool turns here. Build model and effort pickers from this list, so they offer exactly what a save accepts. See [Tool Turns and Reasoning Effort](#tool-turns-and-reasoning-effort).

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/models" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
