Copy page

Guides

Agent Lifecycle

Agents in Neuratel are versioned resources. Every configuration change increments the version number, giving you a full history of every state the agent has ever been in. This guide covers the complete lifecycle from creation through deletion.

Prerequisites: Neuratel account, API key

---

Create an Agent

POST /v1/agents returns the agent object with version: 1.

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": "Sales Agent",
    "brain": {
      "provider": "groq",
      "model": "meta-llama/llama-4-scout-17b-16e-instruct",
      "instructions": "You are a friendly sales agent for Acme Corp. Qualify leads and book demos.",
      "temperature": 0.6
    },
    "voice": {
      "provider": "cartesia",
      "model": "sonic-3",
      "voice_id": "your-cartesia-voice-id"
    },
    "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"},
)

agent = client.post("/v1/agents", json={
    "name": "Sales Agent",
    "brain": {
        "provider": "openai",
        "model": "gpt-4.1-mini",
        "instructions": "You are a friendly sales agent for Acme Corp. Qualify leads and book demos.",
        "temperature": 0.6,
    },
    "voice": {
        "provider": "cartesia",
        "model": "sonic-3",
        "voice_id": "your-cartesia-voice-id",
    },
    "transcriber": {
        "provider": "deepgram",
        "model": "nova-3",
        "language": "en-US",
    },
}).json()

print(agent["id"], agent["version"])  # agent_abc123 1

Code
const res = 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: "Sales Agent",
    brain: {
      provider: "groq",
      model: "meta-llama/llama-4-scout-17b-16e-instruct",
      instructions:
        "You are a friendly sales agent for Acme Corp. Qualify leads and book demos.",
      temperature: 0.6,
    },
    voice: {
      provider: "cartesia",
      model: "sonic-3",
      voice_id: "your-cartesia-voice-id",
    },
    transcriber: {
      provider: "deepgram",
      model: "nova-3",
      language: "en-US",
    },
  }),
});

const agent = await res.json();
console.log(agent.id, agent.version); // agent_abc123 1

---

Update an Agent

PATCH /v1/agents/{id} performs a partial update. Only the fields you send are changed.

Code
curl -X PATCH https://api.neuratel.ai/v1/agents/agent_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brain": {
      "instructions": "You are a friendly sales agent for Acme Corp. Qualify leads and book demos. Always offer a 14-day free trial.",
      "temperature": 0.5
    }
  }'

Code
updated = client.patch("/v1/agents/agent_abc123", json={
    "brain": {
        "instructions": (
            "You are a friendly sales agent for Acme Corp. "
            "Qualify leads and book demos. Always offer a 14-day free trial."
        ),
        "temperature": 0.5,
    },
}).json()

print(updated["version"])  # 2

Code
const updated = await fetch("https://api.neuratel.ai/v1/agents/agent_abc123", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    brain: {
      instructions:
        "You are a friendly sales agent for Acme Corp. " +
        "Qualify leads and book demos. Always offer a 14-day free trial.",
      temperature: 0.5,
    },
  }),
}).then((r) => r.json());

console.log(updated.version); // 2

Each successful update increments version by one. In-progress calls always run on the version that was active when the call connected — updates only affect new calls.

---

Optimistic Concurrency

When multiple team members or automated systems update the same agent simultaneously, one write can silently overwrite another. Neuratel prevents this with the expected_version field.

Pass the version number you read before making changes. If someone else has updated the agent in the meantime, the API returns 409 Conflict instead of silently overwriting their work.

Code
curl -X PATCH https://api.neuratel.ai/v1/agents/agent_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 2,
    "brain": {
      "temperature": 0.4
    }
  }'

Conflict response (409):

Code
{
  "error": "version_conflict",
  "message": "Agent is at version 3, expected 2. Fetch the latest version and retry.",
  "current_version": 3
}

Always use expected_version in production integrations that run concurrently.

---

View Version History

Retrieve the full list of past configurations for an agent.

Code
curl "https://api.neuratel.ai/v1/agents/agent_abc123/versions" \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
versions = client.get("/v1/agents/agent_abc123/versions").json()
for v in versions["items"]:
    print(v["version"], v["created_at"])

Code
const { items } = await fetch(
  "https://api.neuratel.ai/v1/agents/agent_abc123/versions",
  { headers: { "Authorization": "Bearer nk_live_your_api_key" } }
).then((r) => r.json());

items.forEach((v) => console.log(v.version, v.created_at));

Response:

Code
{
  "items": [
    {
      "version": 2,
      "created_at": "2026-04-07T10:15:00Z",
      "changed_by": "user_bilal",
      "snapshot": { "brain": { "temperature": 0.5 }, "..." : "..." }
    },
    {
      "version": 1,
      "created_at": "2026-04-07T09:00:00Z",
      "changed_by": "user_bilal",
      "snapshot": { "brain": { "temperature": 0.6 }, "..." : "..." }
    }
  ]
}

---

Restore a Version

Roll back to any previous version. This creates a new version (not a destructive revert), so the history remains intact.

Code
curl -X POST https://api.neuratel.ai/v1/agents/agent_abc123/versions/1/restore \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
restored = client.post(
    "/v1/agents/agent_abc123/versions/1/restore"
).json()
print(restored["version"])  # 3 — a new version containing v1's config

Code
const restored = await fetch(
  "https://api.neuratel.ai/v1/agents/agent_abc123/versions/1/restore",
  {
    method: "POST",
    headers: { "Authorization": "Bearer nk_live_your_api_key" },
  }
).then((r) => r.json());

console.log(restored.version); // 3

---

Duplicate an Agent

Creates a full copy of an agent including all configuration. The duplicate starts at version: 1 and is independent of the original.

Code
curl -X POST https://api.neuratel.ai/v1/agents/agent_abc123/duplicate \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Agent — FR"}'

Code
copy = client.post("/v1/agents/agent_abc123/duplicate", json={
    "name": "Sales Agent — FR",
}).json()
print(copy["id"])  # agent_def456

Code
const copy = await fetch(
  "https://api.neuratel.ai/v1/agents/agent_abc123/duplicate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer nk_live_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Sales Agent — FR" }),
  }
).then((r) => r.json());

console.log(copy.id);

Duplication is the recommended way to create language or region variants of an existing agent without starting from scratch.

---

Delete an Agent

Deleting an agent is a soft delete. Historical call data, transcripts, and analytics are preserved. The agent is removed from all active lists and can no longer receive calls.

Code
curl -X DELETE https://api.neuratel.ai/v1/agents/agent_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
client.delete("/v1/agents/agent_abc123")

Code
await fetch("https://api.neuratel.ai/v1/agents/agent_abc123", {
  method: "DELETE",
  headers: { "Authorization": "Bearer nk_live_your_api_key" },
});

A 204 No Content response confirms deletion. To restore a deleted agent, contact support within 30 days.

---

Best Practices

Practice	Reason
Always pass expected_version in concurrent systems	Prevents silent overwrites
Duplicate before major rewrites	Keep the original as a fallback
Use descriptive names for duplicates	Support Agent — ES is clearer than Copy of Agent
Restore rather than rewrite when reverting	Keeps version history clean
Soft-delete instead of permanently removing	Preserves call data and analytics

---

Related

• Building Your First Agent
• Agent Studio
• Events and Webhooks