create and update also accept --input-json (inline JSON, @file, or - for stdin); explicit flags override fields from the JSON. See Input JSON.
List Agents
coval agents list [OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
--filter | string | — | Filter expression (e.g., model_type="voice") |
--page-size | number | 50 | Results per page |
--order-by | string | — | Sort order (e.g., -create_time) |
# List all agents
coval agents list
# Filter by type
coval agents list --filter 'model_type="voice"'
# JSON output
coval agents list --format json
Get Agent
coval agents get <agent_id>
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | The agent ID |
coval agents get ag_abc123
Create Agent
coval agents create [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
--name | string | Yes | Human-readable agent name |
--type | string | Yes | Agent type (see below) |
--phone-number | string | Conditional | Phone number in E.164 format, or a SIP address (required for voice, sms) |
--endpoint | string | Conditional | Webhook URL (required for outbound-voice) |
--metadata | JSON | Conditional | JSON string for type-specific configuration (see the required keys below) |
--customer-agent-id | string | No | Your own stable identifier for the agent |
--prompt | string | No | Agent instructions / system prompt |
--language | string | No | Primary agent language |
--attributes | JSON | No | JSON object of free-form agent attributes |
--metric-ids | string | No | Comma-separated metric IDs to attach |
--test-set-ids | string | No | Comma-separated test set IDs to attach |
--workflows | JSON | No | JSON object containing workflow configuration |
--tags | string | No | Comma-separated tag names |
Agent Types
| Type | Description | Required fields |
|---|---|---|
voice | Inbound voice agent Coval calls | --phone-number (E.164 or SIP) |
outbound-voice | Outbound voice agent that calls Coval | --endpoint (webhook URL) |
chat | Chat agent behind an HTTP endpoint | --metadata '{"chat_endpoint":"https://..."}' |
chat-a2a | Chat agent using the A2A protocol | --metadata '{"chat_endpoint":"https://..."}' |
chat-websocket | Chat agent over a WebSocket | --metadata '{"endpoint":"wss://..."}' |
sms | SMS messaging agent | --phone-number (E.164) |
websocket | Voice agent over a WebSocket | --metadata '{"endpoint":"wss://..."}' |
livekit | LiveKit agent | --metadata '{"generate_token_endpoint":"https://...","livekit_url":"wss://..."}' |
pipecat | Pipecat Cloud agent | --metadata '{"pipecat_api_key":"...","agent_name":"..."}' |
openai-realtime | OpenAI Realtime agent | --metadata '{"openai_realtime_api_key":"..."}' |
gemini-realtime | Gemini Live agent | --metadata '{"gemini_realtime_api_key":"..."}' |
grok-realtime | Grok Realtime agent | --metadata '{"grok_realtime_api_key":"..."}' |
Type-specific connection settings are passed through
--metadata as a JSON string. Optional keys for a connection type (for example input_template on a chat agent) go in the same object. See Agent connections for what each type supports.# Create a voice agent
coval agents create \
--name "Support Agent" \
--type voice \
--phone-number "+15551234567"
# Create a chat agent with metadata
coval agents create \
--name "Chat Bot" \
--type chat \
--metadata '{"chat_endpoint":"https://api.example.com/chat"}'
# Create a LiveKit agent
coval agents create \
--name "LiveKit Agent" \
--type livekit \
--metadata '{"generate_token_endpoint":"https://api.example.com/token","livekit_url":"wss://example.livekit.cloud"}'
# Create with associated metrics, test sets, and tags
coval agents create \
--name "Support Agent" \
--type voice \
--phone-number "+15551234567" \
--metric-ids "met_abc,met_def" \
--test-set-ids "ts_123" \
--tags "prod,billing"
Update Agent
coval agents update <agent_id> [OPTIONS]
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | The agent ID to update |
| Option | Type | Description |
|---|---|---|
--name | string | New display name |
--type | string | New agent type (same values as create) |
--phone-number | string | New phone number |
--endpoint | string | New endpoint URL |
--metadata | JSON | JSON string for type-specific configuration |
--customer-agent-id | string | Your own stable identifier for the agent |
--prompt | string | New system prompt |
--language | string | Primary agent language |
--attributes | JSON | JSON object of free-form agent attributes |
--metric-ids | string | Comma-separated metric IDs |
--test-set-ids | string | Comma-separated test set IDs |
--workflows | JSON | JSON object containing workflow configuration |
--tags | string | Comma-separated tag names |
# Update agent name
coval agents update ag_abc123 --name "Updated Agent Name"
# Update agent metadata (e.g., chat endpoint and input template)
coval agents update ag_abc123 \
--metadata '{"chat_endpoint":"https://proxy.example.com/chat","input_template":"{\"user_id\":\"{{user_id}}\"}"}'
Delete Agent
coval agents delete <agent_id>
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | The agent ID to delete |
coval agents delete ag_abc123