Connect an agent

Free-form agent attributes; referenceable in metric prompts as {{agent.<key>}}.

Simulator-specific configuration (JSONB, max 10MB).

For CHAT agents:

Required:

• chat_endpoint - Chat endpoint URL (validated, no private IPs/localhost)

Authentication:

• authorization_header - Auth header (Bearer, X-API-Key, etc.)

Initialization:

• initialization_endpoint - Init endpoint called before chat (validated URL)
• initialization_payload - JSON payload for init request (max 16KB)

Custom Data:

• custom_data - Organization/agent-level data (max 32KB JSON string)
• custom_persona_data - Persona-specific data (max 16KB JSON string)

Headers & Format:

• custom_headers - Additional headers with template variables, as a JSON object or JSON-encoded object string (max 16KB when encoded)
• response_format - "chat_completions" (default) or "responses"

Request/Response Processing:

• input_template - Custom JSON template for requests (validated JSON)
• payload_wrapper - Wrapper field name (e.g., "data", "request")
• response_message_path - Dot notation path to extract message
• strip_message_timestamps - Remove timestamp fields (boolean, default: false)

Tool Calls:

• tool_call_extraction_config - Configuration for extracting tool calls from custom responses

Dynamic Configuration:

• persona_id - Reference persona for parameter substitution (22-char ShortUUID)

Template Variables: {{sessionId}}, {{simulation_output_id}}, {{init_response.path}}, {{persona.field}}, {{messages}}, {{latest_message}}, {{custom_data.field}}

For OUTBOUND_VOICE agents:

• trigger_call_headers - JSON string with HTTP headers
• trigger_call_payload - JSON string with base payload
• phone_number_key - Field name for phone number (default: "phone_number")

For LIVEKIT agents:

Required:

• generate_token_endpoint - HTTP/HTTPS endpoint Coval calls to create a participant token
• livekit_url - LiveKit server URL using ws, wss, http, or https

Optional:

• generate_token_headers - Token-request headers as a JSON object or encoded object string
• token_request_payload - Fields merged into the token request as a JSON object or encoded object string
• content_type - Convenience value for the token-request Content-Type header
• livekit_agent_name - Agent dispatch name

For DAILY (Pipecat Cloud) agents:

Required:

• pipecat_api_key - Pipecat Cloud API key
• agent_name - Pipecat Cloud agent name

Optional:

• custom_data - JSON-encoded object with string keys and string values (max 16KB)

For WEBSOCKET agents:

Required:

• endpoint - WebSocket endpoint URL (must be wss://, validated). Required in direct connection mode.

Connection mode:

• connection_mode - direct (default), http_first, or twiml_webhook.
• http_url, http_method, http_request_body, http_headers, websocket_url_response_path - HTTP-first setup fields when connection_mode=http_first.
• voice_url, voice_http_method, voice_http_headers, voice_form_fields, twilio_account_sid, twilio_from_number, twilio_to_number - TwiML voice-webhook fields when connection_mode=twiml_webhook.

Authentication (optional):

• authorization_header - Auth header sent during the WebSocket handshake. Supports:
  • "Bearer <token>" → sent as Authorization: Bearer <token>
  • "Basic <base64-credentials>" → sent as Authorization: Basic <base64-credentials>
  • "X-API-Key <key>" → sent as X-API-Key: <key>
• custom_headers - JSON object or JSON-encoded object string of additional HTTP headers for the WebSocket handshake.

Initialization & handshake (optional):

• initialization_json - JSON object or JSON string payload sent after the WebSocket upgrade and before any ready-message wait.
• handshake_ready_message_type - Message type to wait for before streaming audio (default session_ready in direct mode and empty in http_first and twiml_webhook; empty string skips the ready-message wait).
• handshake_requires_session_id - Whether the ready message must include session_id (default true in direct mode and false in http_first and twiml_webhook).
• handshake_timeout_seconds - Seconds Coval waits for the ready message (default 30).

Audio format (optional):

• send_audio_template - JSON template for outbound audio. Must contain {{audio_data}}. Setting it exactly to {{audio_data}} sends raw PCM bytes (default {"type":"audio_chunk","data":"{{audio_data}}"}).
• message_type_path - Dot-notation path to the field naming the inbound message kind (default type).
• audio_message_type_value - Value identifying an audio frame; use * to treat every JSON message as audio (default audio_chunk).
• audio_data_path - Dot-notation path to the inbound base64 audio payload (default data).
• audio_encoding - JSON audio payload encoding: pcm (default), mp3, or ulaw. MP3 is inbound-only; ulaw sends and receives G.711 mu-law audio.
• receive_audio_channels - 1 for mono inbound JSON PCM or 2 for legacy stereo-to-mono averaging (default 2).
• send_sample_rate_hertz - Outbound sample rate. One of 8000, 16000, 24000, 48000 (default 16000).
• receive_sample_rate_hertz - Inbound sample rate. One of 8000, 16000, 24000, 48000 (default 48000).
• pipeline_sample_rate_hertz - Pipeline-internal rate; must remain 16000.
• pace_inbound_binary_audio - Boolean, paces inbound binary PCM at real-time. Defaults on when outbound audio is configured for raw PCM bytes, off for JSON templates.
• send_media_template - Outbound template for image attachments. Must contain {{media_data}}; may also include {{media_name}} and {{mime_type}}. Set exactly to {{media_data}} to send raw bytes, otherwise Coval base64-encodes the image into the JSON template.
• send_dtmf_template - Outbound template for keypad digits. Must contain {{digit}}.

Per-simulation placeholders:

• Connection setup fields support {{run_id}}, {{simulation_output_id}} (legacy alias {{simulation_id}}), {{stream_sid}}, {{call_sid}}, {{agent.*}}, {{test_case.*}}, {{sim_wrapper.*}}, and {{run_metadata.*}}.
• Connection setup fields are initialization_json in direct and HTTP-first modes; custom_headers in every mode; http_request_body and http_headers in HTTP-first mode; and voice_form_fields and voice_http_headers in TwiML webhook mode.
• {{stream_sid}} and {{call_sid}} also resolve in send_audio_template, send_media_template, and send_dtmf_template. Coval generates fresh Twilio-shaped values for every simulation.

Non-audio event capture (optional):

• non_audio_event_message_types - List of message-type values to emit as WebsocketEventFrames instead of dropping. Each match carries the message type, optional event name, and original payload. Useful for cart updates, transcript fragments, or session telemetry.

Compatibility profile (optional):

• websocket_compat_profile - One of generic or json_audio. Forces the simulator routing decision. Use json_audio for the JSON audio preset shape.

Workflow configuration (JSONB, max 10MB)

Agent configuration resource.

Note: The active field (soft delete status) is managed internally and not exposed in API responses.