Copy page

Guides

Building Your First Agent

This guide walks you through the complete process of creating a voice AI agent — from the first API call to reviewing live call transcripts. By the end you will have a working agent capable of handling phone calls.

Time: ~20 minutes
Prerequisites: Neuratel account, API key (nk_live_...)

---

Step 1: Create the Agent

Create the agent with a full V3 configuration in one request. The three required sections are brain (the LLM), voice (text-to-speech), and transcriber (speech-to-text).

Code
curl -X POST https://api.neuratel.ai/v1/agents \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "brain": {
      "provider": "groq",
      "model": "meta-llama/llama-4-scout-17b-16e-instruct",
      "instructions": "You are a helpful customer support agent for Acme Corp. Answer questions about orders, returns, and account issues. Be concise and empathetic.",
      "temperature": 0.7
    },
    "voice": {
      "provider": "cartesia",
      "model": "sonic-3",
      "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853"
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-3",
      "language": "en-US"
    }
  }'

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
)

response = client.post("/v1/agents", json={
    "name": "Customer Support Agent",
    "brain": {
        "provider": "openai",
        "model": "gpt-4.1",
        "instructions": (
            "You are a helpful customer support agent for Acme Corp. "
            "Answer questions about orders, returns, and account issues. "
            "Be concise and empathetic."
        ),
        "temperature": 0.7,
    },
    "voice": {
        "provider": "cartesia",
        "model": "sonic-3",
        "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
    },
    "transcriber": {
        "provider": "deepgram",
        "model": "nova-3",
        "language": "en-US",
    },
})

agent = response.json()
print(agent["id"])  # agent_abc123

Code
const response = await fetch("https://api.neuratel.ai/v1/agents", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Support Agent",
    brain: {
      provider: "openai",
      model: "gpt-4.1",
      instructions:
        "You are a helpful customer support agent for Acme Corp. " +
        "Answer questions about orders, returns, and account issues. " +
        "Be concise and empathetic.",
      temperature: 0.7,
    },
    voice: {
      provider: "cartesia",
      model: "sonic-3",
      voice_id: "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
    },
    transcriber: {
      provider: "deepgram",
      model: "nova-3",
      language: "en-US",
    },
  }),
});

const agent = await response.json();
console.log(agent.id); // agent_abc123

Response:

Code
{
  "id": "agent_abc123",
  "name": "Customer Support Agent",
  "version": 1,
  "created_at": "2026-04-07T09:00:00Z"
}

Save the id — you will use it in every subsequent step.

Model reference

Provider	Model	Latency profile
OpenAI	gpt-4.1	Balanced quality and speed
OpenAI	gpt-4.1-mini	Faster, lower cost
OpenAI	gpt-5.4	Highest capability
Groq	llama-3.1-8b-instant	Lowest latency
Neuratel	phantom	~187 ms avg, no external dependency

---

Step 2: Test in the Dashboard

Before assigning a phone number, run a live voice test directly from the dashboard using WebRTC — no phone required.

1. Open Agents in the sidebar and select your new agent.
2. Click the Talk button in the top-right corner.
3. Allow microphone access when prompted.
4. Speak naturally and listen to the agent's responses.
5. End the session and open the Transcript panel to review what was captured.

Use this to verify the system prompt produces the right tone, the voice sounds correct, and the transcriber is recognising speech accurately before any traffic reaches the agent.

---

Step 3: Assign a Phone Number

To receive inbound calls you need to link the agent to a phone number in your account.

Code
curl -X POST https://api.neuratel.ai/v1/numbers/num_xyz789/assign \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_abc123"}'

Code
response = client.post("/v1/numbers/num_xyz789/assign", json={
    "agent_id": "agent_abc123",
})
print(response.json())

Code
const response = await fetch("https://api.neuratel.ai/v1/numbers/num_xyz789/assign", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agent_id: "agent_abc123" }),
});

If you need a phone number, contact your account team — numbers are provisioned by the Neuratel team.

---

Step 4: Make an Outbound Test Call

Trigger a single outbound call to verify the full telephony path — the agent dials out and you pick up on your own phone.

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/outbound \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "to": "+14155550100",
    "from": "+14155550199"
  }'

Code
response = client.post("/v1/voice-sessions/outbound", json={
    "agent_id": "agent_abc123",
    "to": "+14155550100",
    "from": "+14155550199",
})
call = response.json()
print(call["id"])  # call_def456uvw

Code
const response = await fetch("https://api.neuratel.ai/v1/voice-sessions/outbound", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    to: "+14155550100",
    from: "+14155550199",
  }),
});

const call = await response.json();
console.log(call.id); // call_def456uvw

Response:

Code
{
  "id": "call_def456uvw",
  "status": "dialing",
  "agent_id": "agent_abc123",
  "to": "+14155550100",
  "from": "+14155550199"
}

Your phone will ring within a few seconds. When you answer, the agent starts speaking.

---

Step 5: Review Call Logs and Transcript

After the call ends, retrieve the full record including the transcript, duration, and any tool calls made.

Code
curl https://api.neuratel.ai/v1/voice-sessions/call_def456uvw \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
response = client.get("/v1/voice-sessions/call_def456uvw")
call = response.json()

for turn in call["transcript"]:
    speaker = "Agent" if turn["role"] == "assistant" else "Caller"
    print(f"{speaker}: {turn['text']}")

Code
const response = await fetch(
  "https://api.neuratel.ai/v1/voice-sessions/call_def456uvw",
  {
    headers: { "Authorization": "Bearer nk_live_your_api_key" },
  }
);

const call = await response.json();
call.transcript.forEach((turn) => {
  const speaker = turn.role === "assistant" ? "Agent" : "Caller";
  console.log(`${speaker}: ${turn.text}`);
});

Response:

Code
{
  "id": "call_def456uvw",
  "status": "completed",
  "duration_seconds": 94,
  "transcript": [
    {
      "role": "assistant",
      "text": "Thanks for calling Acme Corp, how can I help you today?",
      "start_ms": 820
    },
    {
      "role": "user",
      "text": "I'd like to check on my order.",
      "start_ms": 3100
    }
  ],
  "recording_url": "https://recordings.neuratel.ai/call_def456uvw.mp3",
  "analysis": null
}

Use the transcript to identify gaps in the system prompt, unexpected responses, or transcription errors. Iterate on brain.instructions via PATCH /v1/agents/{id} and test again.

---

Complete agent configuration reference

Code
{
  "name": "Customer Support Agent",
  "brain": {
    "provider": "openai",
    "model": "gpt-4.1",
    "instructions": "You are a helpful customer support agent for Acme Corp. Answer questions about orders, returns, and account issues. Be concise and empathetic.",
    "temperature": 0.7
  },
  "voice": {
    "provider": "cartesia",
    "model": "sonic-3",
    "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
    "language": "en",
    "speed": 1.0
  },
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-3",
    "language": "en-US"
  },
  "conversation": {
    "first_message": "Thanks for calling Acme Corp. How can I help you today?",
    "silence_timeout_seconds": 20,
    "max_duration_seconds": 600
  }
}

---

What's next

• Agent Lifecycle — versioning, updates, and rollbacks
• Configuring Agent Voice — ElevenLabs, Cartesia, and Phantom Speech options
• Tools and Actions — give the agent real capabilities like order lookups
• Events and Webhooks — receive call.summary.ready events after every call