Guides

Agents

Create a voice agent, change it safely, choose its models and engine, and try it in a text chat.

An agent is a saved configuration: a welcome message, one or more tasks (transcriber, LLM, synthesizer, telephony input and output), call options and prompts. Calls, batches and workflows all refer to an agent by id.

In the dashboard, agents live under Build → Agent Studio.

Create an agent

Send agent_config and agent_prompts to POST /v2/agent.

bash

curl -X POST https://api.sevennadi.si/v2/agent \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "Renewal reminders",
      "agent_welcome_message": "Hi {name}, this is Example Bank calling.",
      "tasks": [{
        "task_type": "conversation",
        "tools_config": {
          "llm_agent": {
            "agent_type": "simple_llm_agent",
            "agent_flow_type": "streaming",
            "llm_config": {"provider": "openai", "model": "gpt-4o-mini"}
          },
          "synthesizer": {
            "provider": "elevenlabs", "stream": true, "buffer_size": 250, "audio_format": "wav",
            "provider_config": {"voice": "Nila", "voice_id": "V9LCAAi4tTlqe9JadbCo", "model": "eleven_turbo_v2_5"}
          },
          "transcriber": {"provider": "deepgram", "model": "nova-2", "language": "en", "stream": true},
          "input": {"provider": "twilio", "format": "wav"},
          "output": {"provider": "twilio", "format": "wav"}
        },
        "toolchain": {"execution": "parallel", "pipelines": [["transcriber", "llm", "synthesizer"]]},
        "task_config": {"hangup_after_silence": 10, "call_terminate": 300}
      }]
    },
    "agent_prompts": {"task_1": {"system_prompt": "You remind customers about renewals. Be brief."}}
  }'

Response, 201:

json

{"agent_id": "3c90c3cc-0d44-4b50-8822-8dd25736052a", "state": "created", "version_id": "8f2b6c1e-0d44-4b50-8822-8dd25736052a"}

The request is validated before it is saved. A problem is a 400 whose message names the first failing path, for example agent_config.tasks.0.task_config.ambient_noise_track must be one of: office-ambience, call-center, coffee-shop, or null.

Update, patch, delete

Call	What it does	Response
`PUT /v2/agent/{agent_id}`	Replaces the whole config and prompts	`{"agent_id": "...", "status": "updated"}`
`PATCH /v2/agent/{agent_id}`	Merges the keys you send	`{"message": "success", "state": "updated"}`
`DELETE /v2/agent/{agent_id}`	Soft-deletes the agent	`{"message": "success", "state": "deleted"}`

A patch merges top-level agent_config keys into the saved config and merges agent_prompts per task. Two keys are shortcuts: synthesizer replaces the synthesizer of every conversation task, and telephony_provider sets the input and output provider (the audio format follows it: wav for Twilio and Plivo, pcm for Exotel and SIP).

bash

curl -X PATCH https://api.sevennadi.si/v2/agent/3c90c3cc-0d44-4b50-8822-8dd25736052a \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"agent_config": {"agent_welcome_message": "Hello {name}!", "telephony_provider": "exotel"}}'

Versions

Every create, update and patch stores a snapshot of the config and prompts. A call records the snapshot that was current when the call was created, and runs on that one, so editing an agent never changes a call that is already queued or scheduled.

Prompts and variables

agent_prompts.task_1.system_prompt is the prompt of the first task. Placeholders written as {name} or {{name}} in prompts and in the welcome message are filled from the call's user_data (see Outbound calling) and, in batches, from the CSV columns. A placeholder with no value is left as written.

Models and the `local` provider

Each task names a provider and model for its transcriber, LLM and synthesizer. GET /user/model/all and GET /api/v1/voice-config/tts list what is available; see Voices and models.

Provider local means the platform's own speech-to-text, LLM and text-to-speech servers. It exists only when the operator has configured them, part by part. Naming local for a part that is not configured is a 400. A local voice is set as:

json

{"provider": "local", "provider_config": {"voice": "<name>", "voice_id": "<name>", "model": "local-tts"}}

local components are priced at zero in the price book; the platform and telephony fees still apply.

Note: Third-party providers need credentials. Add your own with provider keys, or ask the operator which ones the platform supplies.

Choosing the engine

The engine is what actually runs a call.

Engine	What it is
`mock`	A scripted simulation with no phone. See Testing without a phone.
`own`	The platform's real-time voice engine. See Voice engine.

Set agent_config.engine on the agent, or agent_data.engine on a single call. If neither is set, the operator's default applies (the shipped default is mock).

Call options

These live in task_config and are stored as sent:

Silence and length: hangup_after_silence, call_terminate.
Opening and closing: welcome_message_delay (0 to 1000 ms), call_hangup_message (a string or a map of language code to text).
Voicemail: voicemail, voicemail_detection_time, voicemail_detection_duration, voicemail_message.
Sound: ambient_noise with ambient_noise_track (office-ambience, call-center, coffee-shop), noise_cancellation_level (60 to 100).
Keypad and rescheduling: dtmf_enabled, auto_reschedule.
Compliance: ai_disclosure_message, pii_redaction (see Compliance).

Keyword hints go in the transcriber: tools_config.transcriber.keywords is a comma-separated string. A :weight suffix is removed on save for models that take plain terms.

Test chat

POST /agent-chat/{agent_id} runs one text turn against the saved agent, with its prompt, knowledge bases and function tools.

bash

curl -X POST https://api.sevennadi.si/agent-chat/3c90c3cc-0d44-4b50-8822-8dd25736052a \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "When is my renewal due?"}], "user_data": {"name": "Asha"}}'

json

{"reply": "Sure. (mock reply to: When is my renewal due?)", "provider": "mock", "model": null, "passages": []}

provider is mock when no LLM credentials are available: the reply then follows the mock engine's rules, so the chat always answers. With credentials it is the agent's own model. Limits: at most 60 messages, 4,000 characters each, and the last message must be from the user. A failing LLM provider is a 502.

Limitations

There is no endpoint to list or restore earlier versions; snapshots are used internally to pin calls.
On the own engine, a stage runs on the provider the agent selects only when the engine has a client for it (catalogue implemented: true) and the account has saved its key; otherwise it runs on the platform's own model, with a note: line in the call log. See Models.
The mock engine honours voicemail detection, auto reschedule, the hangup message and the welcome delay. Ambient noise, noise cancellation, keypad and keyword settings are only logged there.
tools_config.web_search is validated and stored, but no search is executed.