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

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}"

stats = requests.get(
    f"{API_URL}/api/agent-config/{agent_id}/stats",
    headers=headers,
).json()

print(f"Total conversations: {stats['totalConversations']}")
print(f"Qualification rate: {stats['qualificationRate']}%")
print(f"Response rate: {stats['responseRate']}%")

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

console.log(`Total conversations: ${stats.totalConversations}`);
console.log(`Qualification rate: ${stats.qualificationRate}%`);
console.log(`Response rate: ${stats.responseRate}%`);

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.