Skip to main content

​
List Agents

coval agents list [OPTIONS]
OptionTypeDefaultDescription
--filterstring—Filter expression (e.g., model_type="voice")
--page-sizenumber50Results per page
--order-bystring—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>
ArgumentTypeRequiredDescription
agent_idstringYesThe 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]
OptionTypeRequiredDescription
--namestringYesDisplay name for the agent
--typestringYesAgent type (see below)
--phone-numberstringConditionalPhone number in E.164 format (required for voice, sms)
--endpointstringConditionalWebhook URL (required for outbound-voice)
--promptstringNoSystem prompt / instructions
--metadatastringNoJSON string for agent metadata (e.g., chat_endpoint, input_template)
--metric-idsstringNoComma-separated metric IDs to associate
--test-set-idsstringNoComma-separated test set IDs to associate

​
Agent Types

TypeDescriptionRequired Fields
voiceInbound voice agent--phone-number
outbound-voiceOutbound voice agent--endpoint
chatChat/text-based agentmetadata.chat_endpoint
smsSMS messaging agent--phone-number
websocketWebSocket-based agentmetadata.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]
ArgumentTypeRequiredDescription
agent_idstringYesThe agent ID to update
OptionTypeDescription
--namestringNew display name
--typestringNew agent type
--phone-numberstringNew phone number
--endpointstringNew endpoint URL
--promptstringNew system prompt
--metadatastringJSON string for agent metadata
--metric-idsstringComma-separated metric IDs
--test-set-idsstringComma-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>
ArgumentTypeRequiredDescription
agent_idstringYesThe agent ID to delete
coval agents delete ag_abc123