Agents - Coval Documentation

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`)

Output columns: ID, NAME, TYPE, CREATED

# 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

Returns full agent details as JSON including configuration, metadata, and associated resources.

coval agents get ag_abc123

Create Agent

coval agents create [OPTIONS]

Option	Type	Required	Description
`--name`	string	Yes	Display name for the agent
`--type`	string	Yes	Agent type (see below)
`--phone-number`	string	Conditional	Phone number in E.164 format (required for `voice`, `sms`)
`--endpoint`	string	Conditional	Webhook URL (required for `outbound-voice`)
`--prompt`	string	No	System prompt / instructions
`--metadata`	string	No	JSON string for agent metadata (e.g., `chat_endpoint`, `input_template`)
`--metric-ids`	string	No	Comma-separated metric IDs to associate
`--test-set-ids`	string	No	Comma-separated test set IDs to associate

Agent Types

Type	Description	Required Fields
`voice`	Inbound voice agent	`--phone-number`
`outbound-voice`	Outbound voice agent	`--endpoint`
`chat`	Chat/text-based agent	`metadata.chat_endpoint`
`sms`	SMS messaging agent	`--phone-number`
`websocket`	WebSocket-based agent	`metadata.endpoint`, `metadata.initialization_json`

For chat and websocket agents, required fields like chat_endpoint and initialization_json are passed via the --metadata flag as a JSON string.

# 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 with associated metrics and test sets
coval agents create \
  --name "Support Agent" \
  --type voice \
  --phone-number "+15551234567" \
  --metric-ids "met_abc,met_def" \
  --test-set-ids "ts_123"

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
`--phone-number`	string	New phone number
`--endpoint`	string	New endpoint URL
`--prompt`	string	New system prompt
`--metadata`	string	JSON string for agent metadata
`--metric-ids`	string	Comma-separated metric IDs
`--test-set-ids`	string	Comma-separated test set IDs

# 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

⌘I