# Agents: Get an agent (https://docs.envocal.ai/api-reference/agents/get-an-agent/)

> The agent's settings. Use GET /v1/agents/{id}/full to also get its knowledge bases and tools expanded.

## GET `/v1/tenants/{tenantId}/agents/{id}`

The agent's settings. Use `GET /v1/agents/{id}/full` to also get its knowledge bases and tools expanded.

**Required permission:** `agents:read`

### Parameters

| Name | In | | Type | Description |
| --- | --- | --- | --- | --- |
| `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. |
| `id` | path | required | string | Agent id. |

### Responses

**200** — AgentDto: The agent.

| Field | Type | | Description |
| --- | --- | --- | --- |
| `id` | string | required | Agent id. |
| `version` | integer |  | Concurrency version. Send it back when updating; it increases on every update. |
| `name` | string | required | Display name. |
| `description` | string | nullable | Internal description for people; not given to the AI. |
| `instructions` | string | nullable | System prompt for the AI. May reference prompt variables as `{{name}}` (see `variableDefinitionsJson`) and system variables such as `{{system_caller_number}}`. |
| `variableDefinitionsJson` | string | nullable | Prompt variables as a JSON-encoded string: an array of `{"name", "jsonType", "placeholder", "description", "required"}`. Referenced as `{{name}}` in the instructions and filled at conversation time (e.g. from tool output); `placeholder` is used when no value is available. |
| `status` | `draft` \| `active` \| `archived` | nullable | Lifecycle status. |
| `model` | string | nullable | Realtime model, e.g. `gpt-realtime` or `gpt-realtime-1.5`. Empty means the platform default. |
| `voice` | `alloy` \| `ash` \| `ballad` \| `coral` \| `echo` \| `sage` \| `shimmer` \| `verse` \| `marin` \| `cedar` | nullable | Voice used for speech output. |
| `knowledgeBaseIds` | string[] | nullable | Ids of linked knowledge bases. |
| `phoneNumberId` | string | nullable | Id of the assigned phone number, if any. Change it with the agent phone-number endpoints. |
| `phoneNumber` | string | nullable | The assigned phone number in E.164 format (read only). |
| `allowFollowUpEmail` | boolean |  | Give the AI a `send_email` tool that emails conversation details to `followUpEmailAddress`. |
| `followUpEmailAddress` | string | nullable | Recipient of follow-up emails (e.g. a team inbox). Required when `allowFollowUpEmail` is true. |
| `allowCallTransfer` | boolean |  | Give the AI a `transfer_call` tool on phone calls. |
| `callTransferType` | CallTransferType |  | How phone calls are transferred. |
| `isTemplate` | boolean |  | When true the agent is a template that this tenant and its sub-tenants can create agents from. |
| `type` | string | nullable | Optional free-text label for your own classification; not used by the platform. |
| `allowEndCall` | boolean |  | Give the AI an `end_call` tool to end the conversation after saying goodbye. |
| `tenantId` | string | required | Tenant the agent belongs to (cannot be changed). |
| `turnDetectionType` | `server_vad` \| `semantic_vad` \| `none` | nullable | How the AI decides the user finished speaking: `server_vad` (silence based), `semantic_vad` (meaning based) or `none` (no automatic turn taking). |
| `turnDetectionEagerness` | `auto` \| `low` \| `medium` \| `high` | nullable | `semantic_vad` only: how quickly the AI responds. |
| `turnDetectionThreshold` | number (double) | nullable | `server_vad` only: speech detection sensitivity, 0.0–1.0 (higher needs louder speech). Default 0.5. |
| `turnDetectionPrefixPadding` | integer | nullable | `server_vad` only: milliseconds of audio kept before detected speech. Default 300. |
| `turnDetectionSilenceDuration` | integer | nullable | `server_vad` only: milliseconds of silence that end the user's turn. Default 500. |
| `turnDetectionTimeout` | boolean | nullable | `server_vad` only: when true, the AI speaks up after `turnDetectionTimeoutTime` of user silence. |
| `turnDetectionTimeoutTime` | integer | nullable | Idle timeout in milliseconds; required when `turnDetectionTimeout` is true. |
| `turnDetectionInterruptResponse` | boolean | nullable | Whether the user can interrupt the AI while it is speaking. Default true. |
| `transcriptionModel` | string | nullable | Speech-to-text model for transcripts: `gpt-4o-transcribe` (precision) or `gpt-4o-mini-transcribe` (speed). `off` disables transcription. |
| `transcriptionLanguage` | string | nullable | Expected language as an ISO 639-1 code (e.g. `sv`, `en`), or `auto` to detect. |
| `transcriptionInstructions` | string | nullable | Optional hints for the transcriber, e.g. product names or spelling. |
| `noiseReductionType` | `none` \| `near_field` \| `far_field` | nullable | Input noise reduction: `near_field` (headsets, phones), `far_field` (laptops, rooms) or `none`. |
| `toolAssignments` | AgentToolsConfigDto | nullable | Not filled here; use `GET /v1/tenants/{tenantId}/agents/{id}/tools`. |

**401**: Missing, invalid, revoked or expired API key.

**403**: The key lacks the required permission, or the tenant/resource is outside its reach.

**404**: Not found in this tenant.

**429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

### Example

```bash
curl -X GET "https://api.envocal.ai/v1/tenants/current/agents/{id}" \
  -H "Authorization: Bearer evk_eu_..."
```