Voice Agents

Build real-time conversational AI agents with natural voice interaction.

Overview

Voice Agents enable you to build interactive, voice-driven AI experiences. Each agent maintains conversational context, supports tool calling, and streams audio in real time over WebSockets.

Real-time conversation

Tool / function calling

Multi-language support

Custom system prompts

Session management

WebSocket streaming

Quickstart

Create an agent and start a voice session in just a few lines of code.

from nur import NurClient
client = NurClient()
# Create a voice agent
agent = client.agents.create(
    name="Customer Support",
    voice_id="rachel_v2",
    system_prompt="You are a friendly customer support agent for an e-commerce store.",
    language="en",
    tools=[{
        "name": "lookup_order",
        "description": "Look up order status by ID",
        "parameters": {
            "order_id": {"type": "string", "required": True}
        }
    }]
)
# Start a session
session = client.agents.sessions.create(
    agent_id=agent.id,
    initial_message="Hello! How can I help you today?"
)
print(f"Agent: {agent.id}")
print(f"WebSocket: {session.websocket_url}")

Create Agent

POST/v1/agents/create

Create a new voice agent with a custom persona, voice, and optional tool definitions. Agents persist across sessions and can be reused.

Parameter	Type	Description
nameREQUIRED	string	Display name for the agent
voice_idREQUIRED	string	Voice to use for speech synthesis
system_promptREQUIRED	string	System instructions defining agent behavior
language	string	Language code (e.g. en, es, fr). Defaults to en
tools	object[]	Array of tool/function definitions the agent can call
max_turns	integer	Maximum conversation turns per session. Defaults to 50

curl -X POST https://api.nur.ai/v1/agents/create \
  -H "Authorization: Bearer $NUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "voice_id": "rachel_v2",
    "system_prompt": "You are a helpful support agent.",
    "language": "en",
    "tools": [{
      "name": "lookup_order",
      "description": "Look up order status",
      "parameters": {
        "order_id": {"type": "string", "required": true}
      }
    }],
    "max_turns": 30
  }'

Response

{
  "id": "agt_abc123",
  "name": "Customer Support",
  "voice_id": "rachel_v2",
  "system_prompt": "You are a helpful support agent.",
  "language": "en",
  "tools": [
    {
      "name": "lookup_order",
      "description": "Look up order status",
      "parameters": {
        "order_id": {"type": "string", "required": true}
      }
    }
  ],
  "max_turns": 30,
  "created_at": "2025-01-15T10:30:00Z",
  "status": "active"
}

Create Session

POST/v1/agents/{agent_id}/sessions

Start a new conversational session with an agent. Returns a WebSocket URL for real-time audio streaming.

Parameter	Type	Description
agent_idREQUIRED	string	ID of the agent to start a session with
metadata	object	Custom key-value metadata to attach to the session
initial_message	string	Optional greeting message the agent speaks first

curl -X POST https://api.nur.ai/v1/agents/agt_abc123/sessions \
  -H "Authorization: Bearer $NUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"user_id": "usr_456", "channel": "web"},
    "initial_message": "Hello! How can I help you today?"
  }'

Response

{
  "session_id": "ses_xyz789",
  "agent_id": "agt_abc123",
  "websocket_url": "wss://ws.nur.ai/v1/sessions/ses_xyz789",
  "created_at": "2025-01-15T10:35:00Z",
  "expires_at": "2025-01-15T11:35:00Z",
  "status": "active"
}

List Agents

GET/v1/agents

Retrieve a paginated list of all agents in your account.

Parameter	Type	Description
limit	integer	Number of agents to return. Defaults to 20, max 100
offset	integer	Number of agents to skip for pagination

curl -X GET "https://api.nur.ai/v1/agents?limit=10&offset=0" \
  -H "Authorization: Bearer $NUR_API_KEY"

Delete Agent

DELETE/v1/agents/{agent_id}

Permanently delete an agent and terminate all its active sessions. This action cannot be undone.

Parameter	Type	Description
agent_idREQUIRED	string	ID of the agent to delete

curl -X DELETE https://api.nur.ai/v1/agents/agt_abc123 \
  -H "Authorization: Bearer $NUR_API_KEY"

Response Objects

Reference for the objects returned by Voice Agent endpoints.

Agent Object

Field	Type	Description
id	string	Unique agent identifier (prefixed with agt_)
name	string	Display name of the agent
voice_id	string	Voice used for synthesis
system_prompt	string	System instructions for agent behavior
created_at	string	ISO 8601 creation timestamp
status	string	Agent status: active, paused, or deleted

Session Object

Field	Type	Description
session_id	string	Unique session identifier (prefixed with ses_)
agent_id	string	ID of the agent this session belongs to
websocket_url	string	WebSocket URL for real-time audio streaming
created_at	string	ISO 8601 creation timestamp
expires_at	string	ISO 8601 session expiry timestamp
status	string	Session status: active, ended, or expired

Best Practices

Keep system prompts focused

Write clear, concise system prompts that define a single persona. Avoid overloading agents with too many responsibilities -- create separate agents for distinct use cases instead.

Handle WebSocket reconnections

Network interruptions are inevitable. Implement automatic reconnection logic with exponential backoff, and use the session metadata to restore conversation context.

Set appropriate max_turns limits

Configure max_turns to prevent runaway sessions and control costs. For simple Q&A agents, 10-20 turns is typically sufficient. For complex workflows, consider 30-50.

Use tool calling for dynamic data

Instead of hardcoding information in prompts, define tools that fetch live data such as order status, account details, or inventory. This keeps responses accurate and up to date.