# Get an agent

Return an agent using its active, requested branch, or requested version configuration.

## Endpoint

`GET /api/v1/workspaces/{workspace_id}/agents/{agent_id}`

## Authentication

| Class | Authentication | Minimum role | API key |
| --- | --- | --- | --- |
| customer-api | Bearer API key or dashboard session cookie; dashboard mutations also require X-CX-Request: 1. | member | Allowed |

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspace_id` | path | `string` | Yes | — |
| `agent_id` | path | `string` | Yes | — |
| `version_id` | query | `string or null` | No | — |
| `branch_id` | query | `string or null` | No | — |

## Request body

This operation has no request body.

## Example

```bash
curl --request GET 'https://operade.ai/api/v1/workspaces/ws_demo/agents/agt_demo' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Responses

| Status | Description | Content |
| --- | --- | --- |
| 4XX | Handled client error | application/json: `ErrorResponse` |
| 200 | Successful Response | application/json: `AgentDetailResponse` |

### 4XX application/json response schema

| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `$` | `object` | ErrorResponse | — | No | Yes | — | — |
| `error` | `object` | ErrorItem | — | No | Yes | — | — |
| `error.code` | `string` | — | — | No | Yes | — | — |
| `error.details` | `object` | — | — | No | No | — | — |
| `error.message` | `string` | — | — | No | Yes | — | — |

### 200 application/json response schema

| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `$` | `object` | AgentDetailResponse | — | No | Yes | — | — |
| `active_version_id` | `string` | — | — | No | Yes | — | — |
| `archived_at` | `string or null` | — | date-time | Yes | Yes | — | — |
| `branch` | `object` | AgentDetailBranch | — | No | Yes | — | — |
| `branch.id` | `string` | — | — | No | Yes | — | — |
| `branch.is_main` | `boolean` | — | — | No | Yes | — | — |
| `branch.live_percentage` | `number` | — | — | No | Yes | — | — |
| `branch.name` | `string` | — | — | No | Yes | — | — |
| `branch.updated_at` | `string` | — | date-time | No | Yes | — | — |
| `config` | `object` | ConfigAgen | — | No | Yes | — | — |
| `config.agent` | `object` | AgentConfig | — | No | No | — | — |
| `config.agent.first_message` | `string` | — | — | No | No | — | — |
| `config.agent.language` | `string` | — | — | No | No | "id", "en" | — |
| `config.agent.prompt` | `object` | PromptConfig | — | No | No | — | — |
| `config.agent.prompt.built_in_tools` | `object` | BuiltInTools | — | No | No | — | `None` berarti mati. Bentuk ini ikut ElevenLabs, dan ia bertetangga dengan `tool_ids` di dalam `agent.prompt` — bukan di `agent` — sesuai kontrak resminya. Cuma `end_call` yang ada. Sisanya (`transfer_to_number`, `play_keypad_touch_tone`, `voicemail_detection`) semuanya soal telepon, `transfer_to_agent` butuh F6, dan `language_detection` butuh multi-bahasa yang sengaja ditunda. |
| `config.agent.prompt.built_in_tools.end_call` | `object or null` | SystemTool | — | Yes | No | — | Tool bawaan platform: tidak punya URL, tidak punya rahasia, dan tidak bisa dibuat pelanggan. `description` kosong berarti pakai kalimat bawaan kita — bentuk yang sama dengan ElevenLabs (docs/03 `SystemToolConfig`). |
| `config.agent.prompt.built_in_tools.end_call.description` | `string` | — | — | No | No | — | — |
| `config.agent.prompt.ignore_default_personality` | `boolean` | — | — | No | No | — | — |
| `config.agent.prompt.knowledge_base` | `array<DokumenTerpasang>` | — | — | No | No | — | — |
| `config.agent.prompt.knowledge_base[]` | `object` | DokumenTerpasang | — | No | Yes | — | Satu dokumen knowledge base yang dipasang ke agen ini. Nama field mengikuti `KnowledgeBaseLocator` ElevenLabs (docs/03), termasuk menyimpan `name` di sini walau bisa dibaca dari tabel dokumen. Itu disengaja: versi agen harus tetap terbaca enam bulan kemudian, bahkan kalau dokumennya sudah dihapus — tanpa nama, riwayat versinya cuma memuat id yang tidak berarti apa-apa bagi siapa pun. |
| `config.agent.prompt.knowledge_base[].id` | `string` | — | — | No | Yes | — | — |
| `config.agent.prompt.knowledge_base[].name` | `string` | — | — | No | No | — | — |
| `config.agent.prompt.knowledge_base[].type` | `string` | — | — | No | No | "text", "file", "url" | — |
| `config.agent.prompt.knowledge_base[].usage_mode` | `string` | — | — | No | No | "auto", "prompt" | — |
| `config.agent.prompt.llm` | `string` | — | — | No | No | "gpt-5-mini", "gpt-5", "deepseek-v4-flash", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-flash" | — |
| `config.agent.prompt.max_tokens` | `integer` | — | — | No | No | — | — |
| `config.agent.prompt.prompt` | `string` | — | — | No | No | — | — |
| `config.agent.prompt.rag` | `object` | RagConfig | — | No | No | — | Angka bawaannya sama persis dengan ElevenLabs (docs/03 `RagConfig`), kecuali jumlah potongan yang mereka biarkan sampai 20. Lima cukup untuk pertanyaan CS, dan tiap potongan tambahan dibayar tiap giliran. |
| `config.agent.prompt.rag.enabled` | `boolean` | — | — | No | No | — | — |
| `config.agent.prompt.rag.max_documents_length` | `integer` | — | — | No | No | — | — |
| `config.agent.prompt.rag.max_retrieved_rag_chunks_count` | `integer` | — | — | No | No | — | — |
| `config.agent.prompt.rag.max_vector_distance` | `number` | — | — | No | No | — | — |
| `config.agent.prompt.temperature` | `number` | — | — | No | No | — | — |
| `config.agent.prompt.tool_ids` | `array<string>` | — | — | No | No | — | — |
| `config.agent.prompt.tool_ids[]` | `string` | — | — | No | Yes | — | — |
| `config.conversation` | `object` | ConversationConfig | — | No | No | — | — |
| `config.conversation.max_duration_seconds` | `integer` | — | — | No | No | — | — |
| `config.conversation.text_only` | `boolean` | — | — | No | No | — | — |
| `config.guardrails` | `object` | GuardrailsConfig | — | No | No | — | — |
| `config.guardrails.content` | `object` | ContentGuardrails | — | No | No | — | — |
| `config.guardrails.content.categories` | `object` | ContentCategories | — | No | No | — | — |
| `config.guardrails.content.categories.harassment` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.harassment.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.harassment.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.categories.medical_and_legal_information` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.medical_and_legal_information.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.medical_and_legal_information.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.categories.profanity` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.profanity.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.profanity.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.categories.religion_or_politics` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.religion_or_politics.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.religion_or_politics.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.categories.self_harm` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.self_harm.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.self_harm.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.categories.sexual` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.sexual.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.sexual.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.categories.violence` | `object` | ContentCategory | — | No | No | — | — |
| `config.guardrails.content.categories.violence.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.content.categories.violence.threshold` | `string` | — | — | No | No | "low", "medium", "high" | — |
| `config.guardrails.content.execution_mode` | `string` | — | — | No | No | "streaming", "blocking" | — |
| `config.guardrails.content.trigger_action` | `object` | TriggerAction | — | No | No | — | — |
| `config.guardrails.content.trigger_action.feedback` | `string` | — | — | No | No | — | — |
| `config.guardrails.content.trigger_action.type` | `string` | — | — | No | No | "end_call", "retry" | — |
| `config.guardrails.custom` | `object` | CustomGuardrails | — | No | No | — | — |
| `config.guardrails.custom.configs` | `array<CustomGuardrail>` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[]` | `object` | CustomGuardrail | — | No | Yes | — | — |
| `config.guardrails.custom.configs[].execution_mode` | `string` | — | — | No | No | "streaming", "blocking" | — |
| `config.guardrails.custom.configs[].history_message_count` | `integer` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[].id` | `string` | — | — | No | Yes | — | — |
| `config.guardrails.custom.configs[].is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[].model` | `string` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[].name` | `string` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[].prompt` | `string` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[].trigger_action` | `object` | TriggerAction | — | No | No | — | — |
| `config.guardrails.custom.configs[].trigger_action.feedback` | `string` | — | — | No | No | — | — |
| `config.guardrails.custom.configs[].trigger_action.type` | `string` | — | — | No | No | "end_call", "retry" | — |
| `config.guardrails.focus` | `object` | ToggleGuardrail | — | No | No | — | — |
| `config.guardrails.focus.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.prompt_injection` | `object` | ToggleGuardrail | — | No | No | — | — |
| `config.guardrails.prompt_injection.is_enabled` | `boolean` | — | — | No | No | — | — |
| `config.guardrails.version` | `string` | — | — | No | No | "1" | — |
| `config.platform_settings` | `object` | PlatformSettings | — | No | No | — | — |
| `config.platform_settings.analysis_llm` | `string` | — | — | No | No | "gpt-5-mini", "gpt-5" | — |
| `config.platform_settings.data_collection` | `object` | — | — | No | No | — | — |
| `config.platform_settings.evaluation` | `object` | EvaluationSettings | — | No | No | — | — |
| `config.platform_settings.evaluation.criteria` | `array<EvaluationCriterion>` | — | — | No | No | — | — |
| `config.platform_settings.evaluation.criteria[]` | `object` | EvaluationCriterion | — | No | Yes | — | — |
| `config.platform_settings.evaluation.criteria[].conversation_goal_prompt` | `string` | — | — | No | Yes | — | — |
| `config.platform_settings.evaluation.criteria[].id` | `string` | — | — | No | Yes | — | — |
| `config.platform_settings.evaluation.criteria[].name` | `string` | — | — | No | Yes | — | — |
| `config.platform_settings.sentiment_analysis` | `object` | SentimentAnalysisSettings | — | No | No | — | — |
| `config.platform_settings.sentiment_analysis.enabled` | `boolean` | — | — | No | No | — | — |
| `config.platform_settings.testing` | `object` | TestingSettings | — | No | No | — | — |
| `config.platform_settings.testing.attached_tests` | `array<AttachedTest>` | — | — | No | No | — | — |
| `config.platform_settings.testing.attached_tests[]` | `object` | AttachedTest | — | No | Yes | — | — |
| `config.platform_settings.testing.attached_tests[].test_id` | `string` | — | — | No | Yes | — | — |
| `config.platform_settings.testing.attached_tests[].workflow_node_id` | `string or null` | — | — | Yes | No | — | — |
| `config.platform_settings.topic_discovery` | `object` | TopicDiscoverySettings | — | No | No | — | — |
| `config.platform_settings.topic_discovery.enabled` | `boolean` | — | — | No | No | — | — |
| `config.procedures` | `array<object>` | — | — | No | No | — | — |
| `config.procedures[]` | `object` | — | — | No | Yes | — | — |
| `config.workflow` | `object or null` | — | — | Yes | No | — | — |
| `created_at` | `string` | — | date-time | No | Yes | — | — |
| `guardrail_errors` | `array<JsonValue>` | — | — | No | Yes | — | — |
| `guardrail_errors[]` | `reference` | JsonValue | — | No | Yes | — | — |
| `id` | `string` | — | — | No | Yes | — | — |
| `name` | `string` | — | — | No | Yes | — | — |
| `procedure_errors` | `array<JsonValue>` | — | — | No | Yes | — | — |
| `procedure_errors[]` | `reference` | JsonValue | — | No | Yes | — | — |
| `tags` | `array<string>` | — | — | No | Yes | — | — |
| `tags[]` | `string` | — | — | No | Yes | — | — |
| `version` | `object` | BranchVersion | — | No | Yes | — | — |
| `version.branch_id` | `string` | — | — | No | Yes | — | — |
| `version.created_at` | `string` | — | date-time | No | Yes | — | — |
| `version.created_by` | `object` | NamedActor | — | No | Yes | — | — |
| `version.created_by.email` | `string` | — | — | No | Yes | — | — |
| `version.created_by.id` | `string` | — | — | No | Yes | — | — |
| `version.created_by.name` | `string` | — | — | No | Yes | — | — |
| `version.description` | `string` | — | — | No | Yes | — | — |
| `version.id` | `string` | — | — | No | Yes | — | — |
| `version.label` | `string` | — | — | No | Yes | — | — |
| `version.merged_from_version_id` | `string or null` | — | — | Yes | Yes | — | — |
| `version.out_of_branch_parent_id` | `string or null` | — | — | Yes | Yes | — | — |
| `version.parent_version_id` | `string or null` | — | — | Yes | Yes | — | — |
| `version.rebased_from_version_id` | `string or null` | — | — | Yes | Yes | — | — |
| `version.reverted_from_version_id` | `string or null` | — | — | Yes | Yes | — | — |
| `version_id` | `string` | — | — | No | Yes | — | — |
| `workflow_errors` | `array<JsonValue>` | — | — | No | Yes | — | — |
| `workflow_errors[]` | `reference` | JsonValue | — | No | Yes | — | — |

### Response example

```json
{
  "id": "string",
  "name": "string",
  "tags": [],
  "active_version_id": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "archived_at": "2026-01-01T00:00:00Z",
  "version_id": "string",
  "config": {},
  "workflow_errors": [],
  "procedure_errors": [],
  "guardrail_errors": [],
  "version": {
    "id": "string",
    "branch_id": "string",
    "parent_version_id": "string",
    "out_of_branch_parent_id": "string",
    "merged_from_version_id": "string",
    "rebased_from_version_id": "string",
    "reverted_from_version_id": "string",
    "description": "string",
    "label": "string",
    "created_at": "2026-01-01T00:00:00Z",
    "created_by": {
      "id": "string",
      "name": "string",
      "email": "string"
    }
  },
  "branch": {
    "id": "string",
    "name": "string",
    "is_main": false,
    "live_percentage": 0,
    "updated_at": "2026-01-01T00:00:00Z"
  }
}
```

## Errors

Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the [distributed error index](/docs/reference/api/errors) to find each code's canonical domain page.

| Status | Code | Description |
| --- | --- | --- |
| 401 | `unauthenticated` | Authentication is missing, invalid, or revoked. |
| 403 | `forbidden` | The authenticated caller does not have access to this operation. |
| 404 | `not_found` | The requested workspace resource was not found. |

## Related operations

- [Archive an agent](/docs/api-reference/agents/archive-agent) — `DELETE /api/v1/workspaces/{workspace_id}/agents/{agent_id}`
- [Create an agent](/docs/api-reference/agents/create-agent) — `POST /api/v1/workspaces/{workspace_id}/agents`
- [List agents](/docs/api-reference/agents/list-agents) — `GET /api/v1/workspaces/{workspace_id}/agents`