Services
Bind agents and context graphs into deployable services with version sets and structured actions.
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.
Classic API vs Platform API: The Classic API also exposes service endpoints. The Platform API services are workspace-scoped and include richer configuration (tags, tool capacity). Use the Platform API for service setup; the Classic API for runtime conversation creation with the service ID.
Key Concepts
Agent and context graph binding: every service links to one agent and one context graph.
Version sets: named configurations that pin specific agent and context graph versions and LLM model preferences.
Tags: key-value metadata (e.g.,
channel:phone,preset:voice) used for routing and validation.Tool capacity: maximum concurrent tool executions per conversation (1-10, default 3).
For the authoritative Service request and response schema, see the Services API reference.
Version Sets
Model ID validation. When creating or updating a service, every llm_name in version_sets.llm_model_preferences must belong to a supported provider family. Unroutable model identifiers are rejected with a 422 response listing the offending entries. This validation applies only at write time - existing configurations are not affected on read.
Version sets support an optional llm_model_preferences map that overrides the default model used for context graph navigation and conversational engagement. Each key in the map identifies a model role (e.g., nav for the navigation and engagement model), and each value specifies a preferred model name. When set, the specified model is used for all sessions running under that version set. When omitted, sessions use the platform default.
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
Version set override - If the active version set has an
llm_model_preferencesentry for the relevant role, that model is used.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.
Version sets enable safe iteration, like Git branches for your service configuration:
edge: always resolves to latest versions. Immutable, so it cannot be updated or deleted. Use for smoke tests only.release: the default version set used when clients don't specify one. Can be updated but not deleted.Custom sets: create named sets (e.g.,
personal-dev,test,preview) for your promotion workflow.
The recommended promotion path: personal-dev → test → preview → release
For full details on version set management, CLI commands, and promotion workflows, see Version Sets & Promotion.
When upserting a version set, the API validates that pinned agent and context graph versions actually exist. Version set names must match ^[A-Za-z0-9_-]+$ (max 40 characters).
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 emotional context and latency state.
Filler hints are not literal audio fillers. They are semantic directions; the voice pipeline uses them alongside real-time emotional and latency context to produce natural-sounding filler speech.
Voice Configuration
Session Provider
The voice_config.session_provider field controls which voice session runtime drives calls for a service. Supported values:
amigo
Amigo's own voice pipeline (STT, reasoning, TTS). The default.
gpt_realtime
GPT realtime speech-to-speech model family
gpt_live
GPT-Live full-duplex speech-to-speech model family
When not set, the service defaults to amigo. The session provider can also be set through the Developer Console's service edit page.
The platform resolves the session provider with the following precedence: service > agent > workspace > environment default.
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 uses balanced defaults.
Fields
Latency
tts_model
"sonic-turbo" or "sonic-3"
"sonic-turbo"
TTS model selection. sonic-turbo targets 40ms time-to-first-audio; sonic-3 targets 90ms with higher speech quality.
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)
-
End-of-turn sensitivity. Higher values make the system more aggressive about detecting when the caller has stopped talking.
eot_timeout_ms
int
-
Hard timeout for end-of-turn detection in milliseconds.
Fillers
filler_style
"backchannel", "phrase", or "silent"
"backchannel"
backchannel produces short acknowledgments like "Mm" and "Yeah". phrase produces longer fillers like "Let me check on that". silent disables fillers entirely.
filler_vocabulary
list[str]
-
Custom filler words. Overrides the default vocabulary for the selected filler style.
backchannel_delay_ms
int
400
Delay before emitting a backchannel filler when navigation is skipped. Controls how quickly the agent acknowledges the caller.
Response
max_response_sentences
int
-
Hard cap on response length in sentences. This is mechanically enforced (the pipeline truncates), not just prompted.
max_response_words
int
-
Hard cap on response length in words. Same mechanical enforcement.
Barge-in
barge_in_min_speech_s
float
0.25
Minimum speech duration before the caller can interrupt the agent. Lower values make barge-in more sensitive. Setting this too low causes false interrupts from breath sounds or "um".
barge_in_cooldown_s
float
1.5
Cooldown period after a barge-in before another one can trigger. Prevents rapid-fire interruptions.
Speed
min_tts_speed
float (0.5 to 1.0)
-
Minimum TTS speed multiplier. When the emotion engine reduces speech rate in response to caller distress, 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.
Tools
forward_call_enabled
bool
false
Whether the forward_call tool is available. Opt-in because call forwarding has cost and compliance implications.
Presets
Three named presets cover common configurations:
ultra_low_latency
sonic-turbo
200ms
backchannel
400ms
1 sentence
balanced
defaults
500ms
defaults
defaults
-
quality
sonic-3
500ms
phrase
defaults
-
Example
Include voice_config when creating or updating a service:
CLI
Apply a preset:
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):
Read current config:
API
PUT /v1/{workspace_id}/services/{service_id} with the voice_config field in the request body. The field replaces the stored voice config as a whole - omitted fields revert to their defaults (inheriting from workspace settings). Read the current config first (--get or GET the service) and resend the full object with your changes.
Turn-Level Emotion
On each turn, the voice pipeline selects an emotional tone 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 for the available emotions and how the empathy system can override the selection, and Voice Agent for the emotional adaptation behavior.
API Reference
Last updated
Was this helpful?