> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Manage AI agent configurations with the Coval CLI

## List Agents

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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.

```bash theme={null}
coval agents get ag_abc123
```

## Create Agent

```bash theme={null}
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` |

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

```bash theme={null}
# 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

```bash theme={null}
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   |

```bash theme={null}
# 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

```bash theme={null}
coval agents delete <agent_id>
```

| Argument   | Type   | Required | Description            |
| ---------- | ------ | -------- | ---------------------- |
| `agent_id` | string | **Yes**  | The agent ID to delete |

```bash theme={null}
coval agents delete ag_abc123
```