Agents - Agni

The Agents dashboard is where you design the core intelligence of your voice infrastructure. From this central view, you can monitor the real-time performance of every agent in your organization.

Main agents dashboard showing active and inactive agents

Quick start

Get your first agent live in under 5 minutes:

Click + New Agent

From the dashboard, click + New Agent to open the builder.

Configure prompt and timezone

Write your system prompt. Add local timezone context if you want real-time temporal awareness.

Select model, voice, and accent

Choose your AI model. Select a voice and a preferred accent. Adjust the emotional tone of the agent.

Set a welcome message

Define how the AI agent begins the conversation.

Test with a web call

Use the testing panel to start a live conversation immediately.

Creating a new agent

The agent builder features a simplified, unified workspace. You manage the system prompt on the left side. You configure technical settings on the right side.

The simplified Agni agent builder interface

AI provider settings

Configure the reasoning engine. Define the personality of the voice:

Model: Select Agni Premium for high-fidelity reasoning and complex conversations. Alternatively, select Agni Lite for a budget-friendly option with faster response times.

AI model selection dropdown showing Agni Premium and Agni Lite

Voice & accent: Choose from our library of voices. You can apply a Voice Accent to match local regional preferences. For example, select US Southern to make your agent match a southern US accent. You can also customize the emotional expressiveness with Emotion settings to make interactions sound more human.

Voice settings with accent and emotion selection

Prompt and timezone

Write the guidelines for your agent in the prompt editor. You can also configure the Timezone field:

Timezone: Enable this field to give the agent real-time awareness for a specific area. This option adds a context line directly to the start of your prompt. You must enable it if you want the agent to reference the correct local time during calls.

Timezone setting in prompt configuration

Welcome message

Under the Welcome Message tab, decide how the interaction starts. If the agent speaks first, you can choose a static custom message. Alternatively, select a Dynamic message based on prompt to let the agent tailor the greeting to the call context.

Agent configuration

Functions & tools

Equip your agent with the ability to take action during a call.

Dropdown menu for agent functions like End Call and Transfer

IVR / Press Digit: Navigate automated phone menus. You can set the Pause Detection Delay to ensure the agent waits before pressing a digit.
Custom Functions: Connect your backend system.
- Custom (Server-Side): Configure direct API calls with custom headers and JSON schemas.
- Client Function: Define parameters that the model returns to your local application.

The configuration screen for a server-side custom function

Specialized settings

Speech & speech settings

Fine-tune the audio environment. Add Background Sounds like an office hum or traffic noise. You can adjust the Interruption Sensitivity. Configure Reminder Messages for silent periods.

Call & memory settings

Control telephony rules like Voicemail Detection, Max Duration, and Emergency fallback.

Emergency fallback: Specify a backup phone number. If the AI agent encounters a critical failure (such as an LLM provider outage, severe latency, or an unexpected server error), the call will automatically transfer to this fallback number. This ensures your customers always reach a human when things go wrong instead of being hung up on.
Memory: Enable Memory to let the agent remember past conversations with returning callers. Note: Memory works strictly on inbound and outbound calls. It is not supported on web calls.

Post-call data extraction

Define what data to extract from the transcript. You can capture sentiments and generate summaries. You can also pull custom structured JSON.

Knowledge base

Link a knowledge base to let your agent answer questions using your company documentation.

Testing your agent

The built-in testing environment allows you to test your agent safely before deployment.

The testing sidebar for web and phone calls

Test modalities

Web Call: Talk to your agent directly through your browser. In the Metadata section, click Add to enter metadata as key-value pairs for testing dynamic prompt variables.

Using dynamic variables: To set up dynamic variables, include them in your prompt using double curly braces (for example, {{user_name}}). New input fields will automatically appear in your testing panel to let you pass test values.

Testing panel showing dynamic variable inputs

Phone Call: Enter your phone number to receive a live call from the agent. This allows you to experience agent behavior over a real cellular network.

Pro Tip: After completing a test call, check the post-call data. This lets you verify that data extraction is functioning correctly.

API Reference

This section documents the HTTP API for managing agents.

Endpoints

List agents: GET /api/v1/agents
Get agent: GET /api/v1/agents/{id}
Create agent: POST /api/v1/agents
Update agent: PATCH /api/v1/agents/{id}
Update status: PATCH /api/v1/agents/{id}/status
Delete agent: DELETE /api/v1/agents/{id}
Disconnect Cal.com: POST /api/v1/agents/{id}/disconnect-calcom
Disconnect tools: POST /api/v1/agents/{agent_id}/disconnect-tools

Examples

List agents Request:

GET https://api.ravan.ai/api/v1/agents?search=&limit=20&offset=0

Response:

{
  "success": true,
  "message": "Agents fetched successfully",
  "data": [
    {
      "id": "019eb654-a185-77c6-9555-1d33d120881b",
      "organizationId": "95a4e479-03a7-4f1b-834d-8705756e8e59",
      "agentName": "Input field",
      "status": "ACTIVE",
      "model": "Agni Premium",
      "s2sModel": "Agni Premium",
      "voiceId": "Iris",
      "temperature": 0.7,
      "reminderTriggerMs": 10000,
      "reminderMaxCount": 2,
      "ambientSound": "forest_ambience",
      "ambientSoundVolume": 1,
      "maxCallDurationMs": 600000,
      "ringDurationMs": 32000,
      "voicemailMessage": "",
      "voicemailDetectionTimeoutMs": 7000,
      "postCallAnalysisModel": "gpt-4o-mini",
      "postCallAnalysisData": [
        {
          "choices": ["Negative", "Positive", "Neutral"],
          "description": "what was users sentiment throughout the call",
          "name": "sentiments",
          "type": "enum"
        }
      ],
      "selectedTools": null,
      "knowledgeBase": "8619dc3f-b8f6-4a83-924d-f29478f9dd75",
      "beginMessage": "",
      "startSpeaker": "agent",
      "createdAt": "2026-06-11 10:57:40.229069 +0000 UTC",
      "updatedAt": "2026-06-11 18:26:17.115921 +0000 UTC",
      "webhookUrls": ["https://webhook.site/91014639-55d6-49c9-861a-7f652cf42cf4"],
      "ghlCalendarId": "",
      "calcomCalendarId": "",
      "prompt": "The current date and Time in Asia/Calcutta is {{current_time_Asia/Calcutta}}",
      "endcallOnSilenceDuration": 10000,
      "reminderMessage": "HI are you there??",
      "voicemailCustomPatterns": null,
      "interruptionSensitivity": 0.1,
      "calcomApiKey": "cal_live_...",
      "calcomApiUrl": "https://api.cal.com",
      "callStats": {
        "totalCalls": 3,
        "inboundCalls": 0,
        "outboundCalls": 3,
        "webCalls": 0,
        "totalDurationSec": 0,
        "avgDurationSec": 0,
        "totalCost": 0,
        "lastCallAt": "2026-06-11T11:17:03Z",
        "completedCalls": 0,
        "failedCalls": 0,
        "noAnswerCalls": 3,
        "busyCalls": 0,
        "avgLatencyMs": 0
      },
      "campaignStats": {
        "totalCampaigns": 1,
        "totalContacts": 1,
        "contacted": 1,
        "successful": 1,
        "failed": 0,
        "noAnswer": 0,
        "pending": 0,
        "inProgress": 0
      },
      "calcomAccountName": "Default",
      "calcomStatus": "active",
      "calcomConnectionType": "agent",
      "ghlAssignUserIdList": [],
      "memory": true,
      "calendarTimezone": "Asia/Calcutta",
      "accent": ["india/hindi"],
      "emotion": true,
      "crmSyncProviders": null,
      "salesforceCalendarId": "",
      "salesforceAssignUserIdList": [],
      "emergencyFallback": "+1-555-0100"
    }
  ],
  "meta": {
    "total": "2",
    "limit": 10,
    "offset": 0
  }
}

List agent response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`message`	string	Human-readable API message.
`data`	array	List of agent objects.
`meta`	object	Pagination metadata.

Agent object:

Field	Type	Description
`id`	string	Unique agent ID.
`organizationId`	string	Organization ID that owns the agent.
`agentName`	string	Agent display name.
`status`	string	Agent status, for example `ACTIVE`.
`model`	string	Primary model used by the agent.
`s2sModel`	string	Speech-to-speech model used by the agent.
`voiceId`	string	Selected voice name or ID.
`temperature`	number	Model temperature.
`reminderTriggerMs`	number	Silence duration before a reminder is triggered, in milliseconds.
`reminderMaxCount`	number	Maximum reminder attempts during silence.
`ambientSound`	string	Background sound preset.
`ambientSoundVolume`	number	Background sound volume.
`maxCallDurationMs`	number	Maximum call duration in milliseconds.
`ringDurationMs`	number	Maximum ringing duration in milliseconds.
`voicemailMessage`	string	Message used when voicemail is detected.
`voicemailDetectionTimeoutMs`	number	Voicemail detection timeout in milliseconds.
`postCallAnalysisModel`	string	Model used for post-call analysis.
`postCallAnalysisData`	array	Structured fields extracted after a call.
`selectedTools`	array or null	Tool IDs selected for the agent.
`knowledgeBase`	string	Linked knowledge base ID, or an empty string when not configured.
`beginMessage`	string	Opening message for the agent.
`startSpeaker`	string	Speaker that starts the call, for example `agent`.
`createdAt`	string	Agent creation timestamp.
`updatedAt`	string	Agent update timestamp.
`webhookUrls`	array	Webhook URLs called for agent events or data sync.
`ghlCalendarId`	string	GoHighLevel calendar ID.
`calcomCalendarId`	string	Cal.com calendar ID.
`prompt`	string	Agent system prompt.
`endcallOnSilenceDuration`	number	Silence duration before ending the call, in milliseconds.
`reminderMessage`	string	Reminder message spoken during silence.
`voicemailCustomPatterns`	array or null	Custom voicemail detection patterns.
`interruptionSensitivity`	number	Sensitivity for user interruptions.
`calcomApiKey`	string	Cal.com API key configured for the agent.
`calcomApiUrl`	string	Cal.com API base URL.
`campaignStats`	object	Campaign performance stats. Present only when campaign data is available.
`callStats`	object	Call performance stats.
`calcomAccountName`	string	Connected Cal.com account name.
`calcomStatus`	string	Cal.com connection status.
`calcomConnectionType`	string	Cal.com connection owner type.
`ghlAssignUserIdList`	array	GoHighLevel user IDs assigned to the agent.
`memory`	boolean	Whether agent memory is enabled.
`calendarTimezone`	string	Calendar timezone used for scheduling.
`accent`	array	Selected voice accent values.
`emotion`	boolean	Whether emotional voice behavior is enabled.
`crmSyncProviders`	array or null	CRM sync providers configured for the agent.
`salesforceCalendarId`	string	Salesforce calendar ID.
`salesforceAssignUserIdList`	array	Salesforce user IDs assigned to the agent.
`emergencyFallback`	string	Fallback phone number used during critical failures.

Post-call analysis item:

Field	Type	Description
`name`	string	Extracted field name.
`type`	string	Field type, for example `string` or `enum`.
`description`	string	Instructions for extracting this field.
`choices`	array	Allowed values for enum fields. Present when `type` is `enum`.

Call stats:

Field	Type	Description
`totalCalls`	number	Total calls handled by the agent.
`inboundCalls`	number	Inbound call count.
`outboundCalls`	number	Outbound call count.
`webCalls`	number	Web call count.
`totalDurationSec`	number	Total call duration in seconds.
`avgDurationSec`	number	Average call duration in seconds.
`totalCost`	number	Total call cost.
`lastCallAt`	string	Timestamp of the latest call.
`completedCalls`	number	Completed call count.
`failedCalls`	number	Failed call count.
`noAnswerCalls`	number	No-answer call count.
`busyCalls`	number	Busy call count.
`avgLatencyMs`	number	Average latency in milliseconds.

Campaign stats:

Field	Type	Description
`totalCampaigns`	number	Total campaigns linked to the agent.
`totalContacts`	number	Total contacts across campaigns.
`contacted`	number	Contacts already contacted.
`successful`	number	Successful campaign calls.
`failed`	number	Failed campaign calls.
`noAnswer`	number	Campaign calls with no answer.
`pending`	number	Contacts pending outreach.
`inProgress`	number	Campaign calls currently in progress.

Meta object:

Field	Type	Description
`total`	string or number	Total matching agents.
`limit`	number	Page size used for the request.
`offset`	number	Pagination offset used for the request.

Get agent Request:

GET https://api.ravan.ai/api/v1/agents/{id}

Response:

{
  "success": true,
  "message": "Agent fetched successfully",
  "data": {
    "id": "8f1c2e9a-...",
    "agentName": "Sales Bot",
    "status": "active",
    "model": "gpt-4o",
    "voiceId": "voice_123",
    "createdAt": "2026-06-01T10:00:00Z",
    "updatedAt": "2026-06-08T12:00:00Z"
  }
}

Create agent Request (example payload):

POST https://api.ravan.ai/api/v1/agents

{
  "agentName": "Sales Bot",
  "model": "gpt-4o",
  "s2sModel": "gpt-4o-realtime",
  "voiceId": "voice_123",
  "temperature": 0.7,
  "prompt": "You are a helpful sales agent...",
  "beginMessage": "Hi, thanks for calling!"
}

Response:

{ "success": true, "message": "Agent created successfully", "data": { "id": "new-uuid", "agentName": "Sales Bot", "status": "active" } }

Update agent Request:

PATCH https://api.ravan.ai/api/v1/agents/{id}

{ "agentName": "Sales Bot v2", "temperature": 0.6, "prompt": "Updated prompt..." }

Response:

{ "success": true, "message": "Agent updated successfully", "data": { "id": "...", "agentName": "Sales Bot v2" } }

Update status Request:

PATCH https://api.ravan.ai/api/v1/agents/{id}/status

{ "status": "inactive" }

Response:

{ "success": true, "message": "Agent status updated successfully", "data": { "id": "...", "status": "inactive" } }

Delete agent Request:

DELETE https://api.ravan.ai/api/v1/agents/{id}

Response: 200 OK with empty body {} Disconnect Cal.com Request:

POST https://api.ravan.ai/api/v1/agents/{id}/disconnect-calcom

Response: {} Disconnect tools Request:

POST https://api.ravan.ai/api/v1/agents/{agent_id}/disconnect-tools

Response:

{ "success": true, "message": "Agent tools disconnected successfully. Reverting to organization defaults." }

Tools API

Manage reusable tools (org-level or agent-scoped) used by agents.

Endpoints

List tools: GET /api/v1/tools
Get tool: GET /api/v1/tools/{id}
Create tool: POST /api/v1/tools
Update tool: PATCH /api/v1/tools/{id}
Delete tool: DELETE /api/v1/tools/{id}
Duplicate tool: POST /api/v1/tools/{id}/duplicate
Toggle tool: PATCH /api/v1/tools/{id}/toggle
Bulk-remove from agent: DELETE /api/v1/agents/{agent_id}/tools

JSON uses camelCase; unpopulated fields are omitted. AgentTool example shape:

{
  "id": "uuid",
  "organizationId": "uuid",
  "name": "book_appointment",
  "description": "Books a calendar slot",
  "type": "function",
  "definition": { "parameters": { "type": "object", "properties": {} } },
  "isActive": true,
  "agentId": "",
  "enabledFunctions": { "values": ["book", "cancel"] }
}

Examples

List tools (optionally scoped to an agent) Request:

GET https://api.ravan.ai/api/v1/tools?agent_id=<uuid>&limit=20&offset=0

Response:

{
  "success": true,
  "message": "Tools fetched successfully",
  "data": [ { "id": "...", "name": "book_appointment", "isActive": true } ],
  "meta": { "total": 1, "limit": 20, "offset": 0 }
}

Get tool Request:

GET https://api.ravan.ai/api/v1/tools/{id}

Response:

{ "success": true, "message": "Tool fetched successfully", "data": { "id": "...", "name": "book_appointment" } }

Create tool Request (CreateAgentToolRequest):

POST https://api.ravan.ai/api/v1/tools

{
  "name": "book_appointment",
  "description": "Books a calendar slot for the caller",
  "type": "function",
  "agentId": "",
  "definition": {
    "parameters": {
      "type": "object",
      "properties": {
        "datetime": { "type": "string" },
        "name": { "type": "string" }
      },
      "required": ["datetime"]
    }
  },
  "enabledFunctions": { "values": ["book", "cancel"] }
}

Response:

{ "success": true, "message": "Tool created successfully", "data": { "id": "new-uuid", "name": "book_appointment" } }

Update tool Request:

PATCH https://api.ravan.ai/api/v1/tools/{id}

{ "name": "book_appointment_v2", "description": "Updated", "definition": { "parameters": {} }, "enabledFunctions": { "values": ["book"] } }

Response:

{ "success": true, "message": "Tool updated successfully", "data": { "id": "..." } }

Delete tool Request:

DELETE https://api.ravan.ai/api/v1/tools/{id}

Response: 200 OK with empty body {} Duplicate tool Request:

POST https://api.ravan.ai/api/v1/tools/{id}/duplicate

{ "agentId": "8f1c2e9a-..." }

Response:

{ "success": true, "message": "Tool duplicated successfully", "data": { "id": "clone-uuid" } }

Toggle tool Request:

PATCH https://api.ravan.ai/api/v1/tools/{id}/toggle

{ "isEnabled": false }

Response:

{ "success": true, "message": "Tool toggled successfully", "data": { "id": "...", "isActive": false } }

Bulk-remove tools from an agent Request (X-Api-Key protected):

DELETE https://api.ravan.ai/api/v1/agents/{agent_id}/tools

{ "ids": ["tool-uuid-1", "tool-uuid-2"] }

Response: 200 OK with empty body {}

​Quick start

​Creating a new agent

​AI provider settings

​Prompt and timezone

​Welcome message

​Agent configuration

​Functions & tools

​Specialized settings

​Testing your agent

​Test modalities

​API Reference

​Endpoints

​Examples

​List agent response fields

​Tools API

​Endpoints

​Examples

Quick start

Creating a new agent

AI provider settings

Prompt and timezone

Welcome message

Agent configuration

Functions & tools

Specialized settings

Testing your agent

Test modalities

API Reference

Endpoints

Examples

List agent response fields

Tools API

Endpoints

Examples