Get Agent
Agents
Get Agent
Returns full configuration details for a specific agent. Returns 403 if the agent is private and the caller is not its creator or an org admin/owner.
GET
Get Agent
Overview
Retrieves complete configuration for a single agent by ID. Includes all settings, languages, voice configuration, and related metadata. Authentication: Session-based (Better Auth) Scope: Active organization from sessionRequest
Path Parameters:| Parameter | Type | Required | Description |
|---|---|---|---|
agentId | string | ✅ | Agent ID (ULID format) |
Response
Status:200 OK
Response Fields
| Field | Type | Description |
|---|---|---|
agent | object | Agent configuration object |
agent.id | string | Agent ID (ULID) |
agent.name | string | Display name |
agent.description | string | Internal description (max 200 chars) |
agent.agentArchitecture | string | pipeline, realtime, or text |
agent.mode | string | public, private, or commercial |
agent.model | string | LLM model (pipeline/text only) |
agent.stt | string | STT provider (pipeline only) |
agent.voiceId | string | Voice ID (pipeline/realtime only) |
agent.realtimeProvider | string | openai or gemini (realtime only) |
agent.sysMsg | string | System prompt (max 5000 chars) |
agent.functionCallingEnabled | boolean | Functions enabled flag |
agent.enabledFunctions | array | Built-in function IDs |
agent.enabledCustomFunctions | array | Custom function IDs |
agent.temperature | number | 0.1–1.0 (default: 0.7) |
agent.inactivityTimeout | number | 10–60 seconds (default: 30) |
agent.greetingType | string | agentFirst or userFirst |
agent.greetingMessage | string | Custom greeting message |
agent.lastMessage | string | Farewell message |
agent.languages | array | Language configurations |
agent.VoiceOption | object | Voice configuration details |
agent.user | object | Agent creator information |
agent.organization | object | Organization information |
Access Control
| User Role | Can Access |
|---|---|
| Owner | ✅ Any agent in organization |
| Admin | ✅ Any agent in organization |
| Member (Creator) | ✅ Own agents (any mode) |
| Member (Not Creator) | ✅ Public agents only / ❌ Private agents (403) |
| External User | ❌ Commercial agents only |
Error Responses
401 Unauthorized
403 Forbidden
404 Not Found
500 Server Error
Examples
cURL
JavaScript (Fetch)
Next.js (Server Component)
Use Cases
Display Agent Configuration
Check Agent Permissions
Related Endpoints
- List Agents — List all agents in organization
- Create Agent — Create a new agent
- Update Agent — Update agent configuration
- Delete Agent — Delete an agent