Configure Your AI Agent - Naturalead API

An AI agent is the brain behind every lead conversation in Naturalead. It determines how the AI introduces itself, what questions it asks, when it qualifies a lead, and when it escalates to a human. Each agent is defined by four building blocks:

System Prompt & Instructions

The personality, tone, and context the AI uses in every message. This is the foundation of how your agent sounds and behaves.

Conversation Stages

An ordered flow of stages (introduction, discovery, qualification, etc.) that guide the conversation toward a goal.

Guardrails

Safety limits like max messages, inactivity timeouts, forbidden topics, and escalation triggers that keep conversations on track.

Knowledge Bases

Documents and data the agent can reference via RAG to answer domain-specific questions accurately.

Prerequisites

Before configuring an agent you need:

A Naturalead account with agent_config:edit permission (roles: owner, integrator, or ai_architect)
An API key with agent_config:edit scope
Optionally, uploaded knowledge base documents if you want RAG-powered answers

Step-by-step walkthrough

Start from a template (recommended)

Templates give you a proven starting point. Fetch the available templates and apply one to pre-populate your agent configuration.

curl

# List available templates
curl "${API_URL}/api/agent-config/templates" \
  -H "X-API-Key: ${API_KEY}"

# Apply a template to get a pre-filled config
curl -X POST "${API_URL}/api/agent-config/apply-template" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "sales-qualifier" }'

Python

import requests

headers = {"X-API-Key": API_KEY}

# List templates
templates = requests.get(f"{API_URL}/api/agent-config/templates", headers=headers).json()
print(templates)

# Apply a template
config = requests.post(
    f"{API_URL}/api/agent-config/apply-template",
    headers=headers,
    json={"templateId": "sales-qualifier"},
).json()

Node.js

const headers = { "X-API-Key": API_KEY };

// List templates
const templates = await fetch(`${API_URL}/api/agent-config/templates`, { headers }).then(r => r.json());
console.log(templates);

// Apply a template
const config = await fetch(`${API_URL}/api/agent-config/apply-template`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ templateId: "sales-qualifier" }),
}).then(r => r.json());

The apply-template endpoint returns a configuration object without saving it. You can modify it before creating the agent.

Create the agent

Use the template output (or build from scratch) to create a new agent. At minimum you need a name, systemPrompt, and goal.

curl

curl -X POST "${API_URL}/api/agent-config" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Qualifier",
    "systemPrompt": "You are a friendly sales assistant for Acme Corp. Your job is to understand the prospect'\''s needs, qualify them based on budget and timeline, and schedule a demo if they are a good fit.",
    "goal": "Qualify inbound leads and book demo meetings",
    "language": "English",
    "instructions": "Always greet by name. Ask open-ended questions. Never discuss competitor pricing."
  }'

Python

agent = requests.post(
    f"{API_URL}/api/agent-config",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "name": "Sales Qualifier",
        "systemPrompt": "You are a friendly sales assistant for Acme Corp...",
        "goal": "Qualify inbound leads and book demo meetings",
        "language": "English",
        "instructions": "Always greet by name. Ask open-ended questions.",
    },
).json()

agent_id = agent["_id"]
print(f"Created agent: {agent_id}")

Node.js

const agent = await fetch(`${API_URL}/api/agent-config`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Sales Qualifier",
    systemPrompt: "You are a friendly sales assistant for Acme Corp...",
    goal: "Qualify inbound leads and book demo meetings",
    language: "English",
    instructions: "Always greet by name. Ask open-ended questions.",
  }),
}).then(r => r.json());

const agentId = agent._id;

Customize the system prompt and instructions

The system prompt is sent to the LLM as the system message for every conversation turn. It defines the agent’s persona, context, and behavioral rules. The instructions field provides additional guidance that supplements the system prompt.

Tips for writing effective prompts:

Be specific about the agent’s role and company context

Define the tone (formal, friendly, consultative)

List what the agent should and should not discuss

Include example phrases if you want a particular style

curl

curl -X PUT "${API_URL}/api/agent-config/${AGENT_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are Alex, a senior sales consultant at Acme Corp. You help prospects understand how our AI platform can save them 10+ hours per week on lead qualification. You are warm, knowledgeable, and concise. Never make up features that do not exist.",
    "instructions": "1. Always use the prospect'\''s first name.\n2. Reference their industry when possible.\n3. If they mention a competitor, acknowledge it positively and pivot to our strengths.\n4. End every message with a question to keep the conversation going."
  }'

Python

requests.put(
    f"{API_URL}/api/agent-config/{agent_id}",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "systemPrompt": "You are Alex, a senior sales consultant at Acme Corp...",
        "instructions": "1. Always use the prospect's first name.\n2. Reference their industry when possible.",
    },
)

Node.js

await fetch(`${API_URL}/api/agent-config/${agentId}`, {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    systemPrompt: "You are Alex, a senior sales consultant at Acme Corp...",
    instructions: "1. Always use the prospect's first name.\n2. Reference their industry when possible.",
  }),
});

Add conversation stages

Stages define the flow of the conversation. Each stage has a prompt that guides the LLM, transition criteria that determine when to move on, and optional branching via nextStages.

A typical qualification flow looks like:

Introduction — greet and build rapport

Discovery — understand needs, budget, and timeline

Qualification — evaluate fit against your criteria

Handoff / Close — schedule a meeting or politely disengage

curl

curl -X PUT "${API_URL}/api/agent-config/${AGENT_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "stages": [
      {
        "id": "intro",
        "name": "Introduction",
        "order": 0,
        "prompt": "Greet the lead by name and introduce yourself. Explain briefly why you are reaching out.",
        "transitionCriteria": "Lead has responded and acknowledged the conversation.",
        "maxMessages": 3,
        "nextStages": [{ "id": "discovery" }]
      },
      {
        "id": "discovery",
        "name": "Discovery",
        "order": 1,
        "prompt": "Ask about their current process, pain points, team size, and budget range.",
        "transitionCriteria": "You have gathered budget, timeline, and primary pain point.",
        "maxMessages": 8,
        "nextStages": [
          { "id": "qualified", "condition": "Good fit" },
          { "id": "close", "condition": "Not a fit" }
        ]
      },
      {
        "id": "qualified",
        "name": "Qualification",
        "order": 2,
        "prompt": "Confirm the lead is a good fit. Propose a demo meeting and ask for availability.",
        "transitionCriteria": "Meeting is scheduled or lead declines.",
        "maxMessages": 5,
        "nextStages": [{ "id": "close" }]
      },
      {
        "id": "close",
        "name": "Close",
        "order": 3,
        "prompt": "Thank the lead for their time. If qualified, confirm next steps. If not, leave the door open for future contact.",
        "transitionCriteria": "Conversation is complete.",
        "maxMessages": 2
      }
    ]
  }'

Python

stages = [
    {
        "id": "intro",
        "name": "Introduction",
        "order": 0,
        "prompt": "Greet the lead by name and introduce yourself.",
        "transitionCriteria": "Lead has responded.",
        "maxMessages": 3,
        "nextStages": [{"id": "discovery"}],
    },
    {
        "id": "discovery",
        "name": "Discovery",
        "order": 1,
        "prompt": "Ask about their process, pain points, and budget.",
        "transitionCriteria": "Budget, timeline, and pain point gathered.",
        "maxMessages": 8,
        "nextStages": [
            {"id": "qualified", "condition": "Good fit"},
            {"id": "close", "condition": "Not a fit"},
        ],
    },
    {
        "id": "qualified",
        "name": "Qualification",
        "order": 2,
        "prompt": "Confirm fit and propose a demo meeting.",
        "transitionCriteria": "Meeting scheduled or declined.",
        "maxMessages": 5,
        "nextStages": [{"id": "close"}],
    },
    {
        "id": "close",
        "name": "Close",
        "order": 3,
        "prompt": "Thank the lead and confirm next steps.",
        "transitionCriteria": "Conversation complete.",
        "maxMessages": 2,
    },
]

requests.put(
    f"{API_URL}/api/agent-config/{agent_id}",
    headers={**headers, "Content-Type": "application/json"},
    json={"stages": stages},
)

Node.js

const stages = [
  {
    id: "intro",
    name: "Introduction",
    order: 0,
    prompt: "Greet the lead by name and introduce yourself.",
    transitionCriteria: "Lead has responded.",
    maxMessages: 3,
    nextStages: [{ id: "discovery" }],
  },
  {
    id: "discovery",
    name: "Discovery",
    order: 1,
    prompt: "Ask about their process, pain points, and budget.",
    transitionCriteria: "Budget, timeline, and pain point gathered.",
    maxMessages: 8,
    nextStages: [
      { id: "qualified", condition: "Good fit" },
      { id: "close", condition: "Not a fit" },
    ],
  },
  {
    id: "qualified",
    name: "Qualification",
    order: 2,
    prompt: "Confirm fit and propose a demo meeting.",
    transitionCriteria: "Meeting scheduled or declined.",
    maxMessages: 5,
    nextStages: [{ id: "close" }],
  },
  {
    id: "close",
    name: "Close",
    order: 3,
    prompt: "Thank the lead and confirm next steps.",
    transitionCriteria: "Conversation complete.",
    maxMessages: 2,
  },
];

await fetch(`${API_URL}/api/agent-config/${agentId}`, {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ stages }),
});

Set up guardrails

Guardrails protect your brand and keep conversations safe. Configure them based on your use case:

SettingDescriptionDefaultmaxTotalMessagesHard cap on total messages per conversation40inactivityTimeoutMinutesAuto-close after N minutes of silence1440 (24h)forbiddenTopicsComma-separated topics the agent must refuse to discussemptyescalationTriggersComma-separated phrases that trigger human handoffempty

curl

curl -X PUT "${API_URL}/api/agent-config/${AGENT_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "guardrails": {
      "maxTotalMessages": 30,
      "inactivityTimeoutMinutes": 720,
      "forbiddenTopics": "competitor pricing, internal roadmap, legal advice",
      "escalationTriggers": "speak to a human, talk to manager, file a complaint"
    }
  }'

Python

requests.put(
    f"{API_URL}/api/agent-config/{agent_id}",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "guardrails": {
            "maxTotalMessages": 30,
            "inactivityTimeoutMinutes": 720,
            "forbiddenTopics": "competitor pricing, internal roadmap, legal advice",
            "escalationTriggers": "speak to a human, talk to manager, file a complaint",
        }
    },
)

Node.js

await fetch(`${API_URL}/api/agent-config/${agentId}`, {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    guardrails: {
      maxTotalMessages: 30,
      inactivityTimeoutMinutes: 720,
      forbiddenTopics: "competitor pricing, internal roadmap, legal advice",
      escalationTriggers: "speak to a human, talk to manager, file a complaint",
    },
  }),
});

Setting maxTotalMessages too low (below 10) may prevent the agent from completing the qualification flow. Test with real conversations before deploying to production.

Attach knowledge bases

Knowledge bases give your agent access to company-specific information via RAG (Retrieval-Augmented Generation). Upload documents first through the Knowledge Base API, then attach them to your agent.

curl

# List knowledge bases available in your account
curl "${API_URL}/api/agent-config/knowledge/documents" \
  -H "X-API-Key: ${API_KEY}"

# Attach a knowledge base to the agent
curl -X POST "${API_URL}/api/agent-config/${AGENT_ID}/knowledge-bases/${KB_ID}" \
  -H "X-API-Key: ${API_KEY}"

# Verify attached knowledge bases
curl "${API_URL}/api/agent-config/${AGENT_ID}/knowledge-bases" \
  -H "X-API-Key: ${API_KEY}"

Python

# Attach a knowledge base
requests.post(
    f"{API_URL}/api/agent-config/{agent_id}/knowledge-bases/{kb_id}",
    headers=headers,
)

# List attached knowledge bases
kbs = requests.get(
    f"{API_URL}/api/agent-config/{agent_id}/knowledge-bases",
    headers=headers,
).json()
print(f"Attached KBs: {len(kbs)}")

Node.js

// Attach a knowledge base
await fetch(`${API_URL}/api/agent-config/${agentId}/knowledge-bases/${kbId}`, {
  method: "POST",
  headers,
});

// List attached knowledge bases
const kbs = await fetch(`${API_URL}/api/agent-config/${agentId}/knowledge-bases`, {
  headers,
}).then(r => r.json());
console.log(`Attached KBs: ${kbs.length}`);

You can attach multiple knowledge bases to a single agent. The agent searches across all attached bases when retrieving context for a response.

Test with the playground

Before deploying your agent in a campaign, test it using the built-in playground. Navigate to Bot > Playground in the dashboard, select your agent, and simulate a conversation. The playground shows the full LLM input (system prompt + RAG context + conversation history) so you can debug prompt behavior.

Key things to verify during testing:

The agent introduces itself correctly and uses the right tone

Stage transitions happen at the right moments

Guardrails trigger when expected (try forbidden topics and escalation phrases)

Knowledge base answers are accurate and relevant

The agent stays on-topic and does not hallucinate

Monitoring agent performance

Once your agent is live, track its effectiveness using the stats endpoint:

curl "${API_URL}/api/agent-config/${AGENT_ID}/stats" \
  -H "X-API-Key: ${API_KEY}"

The stats response includes:

Field	Description
`totalConversations`	Total conversations using this agent
`qualifiedLeads`	Number of leads the agent qualified
`qualificationRate`	Percentage of conversations resulting in qualification
`responseRate`	Percentage of conversations where the lead replied

Next steps

Launch a Campaign

Use your configured agent to run automated outreach at scale.

Knowledge Base API

Upload and manage documents for RAG-powered agent responses.

Agent Config API Reference

Full API reference for all agent configuration endpoints.

Roles & Permissions

Understand which roles can create and edit agent configurations.

Guides

System Prompt & Instructions

Conversation Stages

Guardrails

Knowledge Bases

​Prerequisites

​Step-by-step walkthrough

​Monitoring agent performance

​Next steps

Launch a Campaign

Knowledge Base API

Agent Config API Reference

Roles & Permissions

Prerequisites

Step-by-step walkthrough

Monitoring agent performance

Next steps