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

# Agent

> The Agent object represents a voice agent in the Voicy platform

An Agent defines how a voice agent behaves. The API exposes an agent's
**interface** — its identity, voice, and variable contract — but not its
internal configuration.

<Note>
  There are two agent types. **Prompt-based** agents (`singlePrompt`) are fully
  manageable via the API. **Flow** agents (`conversationalFlow`) are built in the
  [dashboard](https://app.voicy.co); they appear in [List](/api-reference/agent-list)
  and [Get](/api-reference/agent-get) but cannot be created or modified through
  the API, and their internal flow configuration is never returned.
</Note>

## Properties

<ResponseField name="agent_id" type="string" required>
  Unique identifier (UUID). Pass this as `override_agent_id` on [Dial](/api-reference/call-dial).
</ResponseField>

<ResponseField name="name" type="string">Agent display name.</ResponseField>

<ResponseField name="language" type="string">Language code, e.g. `he` or `en`.</ResponseField>

<ResponseField name="voice" type="string">
  Voice display name. One of `Keren`, `Karmit`, `Kobi`, `Kfir`, `Dana`, `Dafna`, `Dorin`, `Dan`, `Dor`, `David`, `Sapir`, `Steve`.
</ResponseField>

<ResponseField name="agent_type" type="string">
  `singlePrompt` (prompt-based, API-manageable) or `conversationalFlow` (dashboard-only, read-only here).
</ResponseField>

<ResponseField name="active" type="boolean">Whether the agent is enabled.</ResponseField>

<ResponseField name="prompt" type="string">
  System prompt. Present for prompt-based agents only.
</ResponseField>

<ResponseField name="welcome_message" type="string">
  Message spoken first when the agent answers. Present for prompt-based agents only.
</ResponseField>

<ResponseField name="variables_provided" type="array">
  Variables the agent accepts at call time — supply them via `vars_provided` on Dial.

  <Expandable title="Variable properties">
    <ResponseField name="name" type="string">Variable name.</ResponseField>
    <ResponseField name="description" type="string">Human-readable description.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="variables_extracted" type="array">
  Variables the agent extracts from the conversation after the call.

  <Expandable title="Variable properties">
    <ResponseField name="name" type="string">Variable name.</ResponseField>
    <ResponseField name="description" type="string">Human-readable description.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp.</ResponseField>

## Example

```json theme={null}
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Appointment Booker",
  "language": "he",
  "voice": "Keren",
  "agent_type": "singlePrompt",
  "active": true,
  "prompt": "You are a friendly receptionist that books appointments.",
  "welcome_message": "שלום, איך אפשר לעזור?",
  "variables_provided": [
    { "name": "customer_name", "description": "The caller's name" }
  ],
  "variables_extracted": [
    { "name": "appointment_date", "description": "The date the caller chose" }
  ],
  "created_at": "2026-06-06T10:00:00Z",
  "updated_at": "2026-06-06T10:00:00Z"
}
```