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

# Agents

# Agents

Manage AI voice agents. Agents define how your AI sounds, behaves, and responds on calls. They are the core entity in Truedy — assigned phone numbers, equipped with tools and knowledge bases, and deployed on outbound or inbound calls.

For UUID / phone / datetime formats used below, see [Data formats](/api-reference/introduction#data-formats).

## List Agents

List all agents for your organization.

<Endpoint method="GET" path="/api/public/v1/agents" />

### Parameters

**Query parameters:**

| Parameter | Type    | Description                                               |
| --------- | ------- | --------------------------------------------------------- |
| `status`  | string  | Filter by status: `active`, `draft`, `creating`, `failed` |
| `name`    | string  | Filter by name (substring match)                          |
| `limit`   | integer | 1–100. Default `50`                                       |
| `offset`  | integer | Pagination offset. Default `0`                            |

Each agent in the response includes `inbound_phone_numbers` and `outbound_phone_numbers` (arrays of `{ id, phone_number }`) matching the dashboard view.

### Response

```json theme={null}
{
  "data": [
    {
      "id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
      "name": "Customer Support Agent",
      "description": "Handles customer support calls",
      "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
      "system_prompt": "You are a helpful support agent...",
      "model": "ultravox-v0.7",
      "status": "active",
      "inbound_phone_numbers": [{"id": "d0845d54-d96d-4cb8-8cc3-eac55f94c2c0", "phone_number": "+14155550123"}],
      "outbound_phone_numbers": [],
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false },
  "meta": { "request_id": "f98eb11f-9f34-4d13-9075-0e29f106f37d", "ts": "2024-01-01T00:00:00Z" }
}
```

### cURL

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get Agent

Get details for a specific agent including assigned phone numbers.

<Endpoint method="GET" path="/api/public/v1/agents/{agent_id}" />

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Create Agent

Create a new voice agent. The agent is automatically synced to Ultravox on creation. Only `name`, `voice_id`, and `system_prompt` are required; all other fields are optional.

<Endpoint method="POST" path="/api/public/v1/agents" />

### Request Body

**Core fields:**

| Field               | Type    | Required | Default         | Description                                               |
| ------------------- | ------- | -------- | --------------- | --------------------------------------------------------- |
| `name`              | string  | **Yes**  | —               | Agent display name (1–100 characters)                     |
| `voice_id`          | UUID    | **Yes**  | —               | Voice to use for this agent                               |
| `system_prompt`     | string  | **Yes**  | —               | Instructions that define the agent's behavior and persona |
| `description`       | string  | No       | —               | Internal description (not used during calls)              |
| `model`             | string  | No       | `ultravox-v0.7` | AI model. Use `ultravox-v0.7` for best performance.       |
| `tools`             | UUID\[] | No       | `[]`            | List of tool IDs to enable for this agent                 |
| `knowledge_bases`   | UUID\[] | No       | `[]`            | List of knowledge base IDs (maximum 1)                    |
| `temperature`       | float   | No       | `0.3`           | Response creativity, 0–1. Lower = more consistent.        |
| `recording_enabled` | boolean | No       | `false`         | Enable call recording by default                          |
| `language_hint`     | string  | No       | —               | BCP-47 language code hint, e.g. `en-US`, `es-MX`          |

**Call timing:**

| Field                   | Type   | Default | Description                                          |
| ----------------------- | ------ | ------- | ---------------------------------------------------- |
| `join_timeout`          | string | —       | Time to wait for callee to answer, e.g. `"30s"`      |
| `max_duration`          | string | —       | Maximum call length, e.g. `"3600s"` (1 hour)         |
| `time_exceeded_message` | string | —       | Text the agent speaks when `max_duration` is reached |

**Greeting & inactivity:**

| Field                 | Type      | Description                                                                                                                                                                                        |
| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `greeting_settings`   | object    | Configure the first speaker and greeting behavior. Fields: `first_speaker` (`FIRST_SPEAKER_AGENT` or `FIRST_SPEAKER_USER`), `text` (greeting text), `delay` (seconds), `uninterruptible` (boolean) |
| `inactivity_messages` | object\[] | Messages spoken after user silence. Each item: `{ duration: "10s", message: "Are you still there?", endBehavior: "END_BEHAVIOR_HANG_UP" }`                                                         |

**Advanced audio:**

| Field          | Type   | Description                                                                                                                                            |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vad_settings` | object | Voice activity detection tuning. Fields: `turn_endpoint_delay`, `minimum_turn_duration`, `minimum_interruption_duration`, `frame_activation_threshold` |

**Built-in capabilities:**

| Field             | Type   | Description                                                                                                                                                             |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `built_in_config` | object | Enable built-in tools like call transfer, hang up, and voicemail detection. Structure: `{ transfer: { cold: bool, warm: bool }, hang_up: bool, leave_voicemail: bool }` |

**Post-call analysis:**

| Field                | Type   | Description                                                                                                         |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `success_criteria`   | string | Prompt describing what makes a call successful. Used for outcome analysis.                                          |
| `extraction_schema`  | object | JSON Schema for structured data extraction from the call transcript (e.g. extract appointment date, customer name). |
| `crm_webhook_url`    | string | URL to receive a POST with call results and extracted data after each call ends.                                    |
| `crm_webhook_secret` | string | HMAC secret used to sign `crm_webhook_url` requests.                                                                |

### Example Request

```json theme={null}
{
  "name": "Customer Support Agent",
  "description": "Handles customer support calls",
  "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
  "system_prompt": "You are a helpful customer support agent. Be friendly and professional. The customer's name is {{first_name}}.",
  "model": "ultravox-v0.7",
  "tools": ["4ee4db9b-d099-4dba-b4a8-8272a55fe25a"],
  "knowledge_bases": ["6f4af8be-0a96-49b0-ac2a-a359f46cc966"],
  "temperature": 0.3,
  "recording_enabled": true,
  "language_hint": "en-US",
  "max_duration": "900s",
  "greeting_settings": {
    "first_speaker": "FIRST_SPEAKER_AGENT",
    "text": "Hello! How can I help you today?"
  }
}
```

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 9268623c-f7ff-4871-bf80-cbaac7aa59b9" \
  -d '{
    "name": "Customer Support Agent",
    "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
    "system_prompt": "You are a helpful customer support agent.",
    "model": "ultravox-v0.7"
  }'
```

**Response:** 201 Created with `data` (agent object: `id`, `name`, `status`, `voice_id`, etc.) and `meta`. Send `X-Idempotency-Key` for safe retries.

**Agent status after creation:** The agent starts as `draft` and becomes `active` once synced to Ultravox. Sync happens automatically on creation. If Ultravox sync fails, the agent status remains `draft` and can be retried.

## Update Agent (Full)

Replace an existing agent with the provided fields. All fields from Create Agent are accepted.

<Endpoint method="PUT" path="/api/public/v1/agents/{agent_id}" />

The agent is re-synced to Ultravox immediately after update. Returns **422** if `voice_id` is invalid or missing.

```bash theme={null}
curl -X PUT "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent V2",
    "voice_id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
    "system_prompt": "You are a concise, helpful support agent.",
    "model": "ultravox-v0.7"
  }'
```

## Partial Update Agent

Update only the fields you send. All other fields remain unchanged.

<Endpoint method="PATCH" path="/api/public/v1/agents/{agent_id}" />

### Patchable Fields

Any field from the Create Agent table can be partially updated. Common examples:

| Field                   | Type      | Description                        |
| ----------------------- | --------- | ---------------------------------- |
| `name`                  | string    | Rename the agent                   |
| `system_prompt`         | string    | Update behavior instructions       |
| `voice_id`              | UUID      | Change the voice                   |
| `model`                 | string    | Change the AI model                |
| `tools`                 | UUID\[]   | Replace tool list                  |
| `knowledge_bases`       | UUID\[]   | Replace knowledge base list        |
| `temperature`           | float     | Adjust response creativity         |
| `recording_enabled`     | boolean   | Enable or disable recording        |
| `language_hint`         | string    | Change language hint               |
| `join_timeout`          | string    | Change answer timeout              |
| `max_duration`          | string    | Change max call length             |
| `time_exceeded_message` | string    | Change timeout message             |
| `greeting_settings`     | object    | Update greeting config             |
| `inactivity_messages`   | object\[] | Update silence handling            |
| `vad_settings`          | object    | Tune voice activity detection      |
| `built_in_config`       | object    | Enable/disable built-in tools      |
| `success_criteria`      | string    | Update success evaluation prompt   |
| `extraction_schema`     | object    | Update post-call extraction schema |
| `crm_webhook_url`       | string    | Change CRM webhook destination     |
| `crm_webhook_secret`    | string    | Rotate CRM webhook secret          |

```bash theme={null}
curl -X PATCH "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_enabled": true,
    "temperature": 0.2,
    "max_duration": "600s"
  }'
```

## Delete Agent

<Endpoint method="DELETE" path="/api/public/v1/agents/{agent_id}" />

Deletes the agent from Truedy and removes it from Ultravox. Phone numbers assigned to this agent will be unassigned.

```bash theme={null}
curl -X DELETE "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Test Call

Initiate a test call with an agent using WebRTC (browser-based, no phone number needed). Returns a `join_url` to connect to the call. Intended for testing agent behavior during development.

<Endpoint method="POST" path="/api/public/v1/agents/{agent_id}/test-call" />

### Response

```json theme={null}
{
  "data": {
    "call_id": "44ec8f61-6d9a-4553-a6ca-777f5f5ef95b",
    "join_url": "https://app.ultravox.ai/calls/...",
    "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/agents/1f4baf16-1540-4d91-9696-7f34b2f2cb77/test-call" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns **422** or **502** if the test call cannot be started (e.g. agent not synced, Ultravox error).