Voice agents

Waridi Agents are customer-service voice agents that listen, understand and answer in natural Swahili. They are meant to replace "Kwa Kiswahili, bonyeza moja" menus with a conversation.

An agent combines Sikia for listening, your instructions and tools for deciding what to do, and Sauti for speaking. Turn-taking, interruptions and silence are handled for you.

Sandbox only. Agents are available in the sandbox during early access. Production phone numbers are enabled case by case. Write to hello@waridi.io if you want to pilot one.

Create an agent

from waridi import Waridi

client = Waridi()

agent = client.agents.create(
    name="Huduma kwa wateja",
    language="sw-TZ",
    voice="zawadi",
    tts_model="sauti-pro",
    greeting="Karibu! Naitwa Zawadi. Nikusaidie vipi leo?",
    instructions=(
        "You answer calls for a water utility in Dar es Salaam. "
        "Speak Swahili first and switch to English only if the caller does. "
        "Keep answers short. Never read out full account numbers."
    ),
    tools=[{
        "name": "check_balance",
        "description": "Look up a customer's unpaid water bill by meter number.",
        "url": "https://example.com/hooks/balance",
        "parameters": {"meter_number": {"type": "string"}},
    }],
    handoff={"phone": "+255700000000", "when": "caller asks for a person"},
)
print(agent.id)

import { Waridi } from "@waridi/sdk";

const client = new Waridi();

const agent = await client.agents.create({
  name: "Huduma kwa wateja",
  language: "sw-TZ",
  voice: "zawadi",
  ttsModel: "sauti-pro",
  greeting: "Karibu! Naitwa Zawadi. Nikusaidie vipi leo?",
  instructions:
    "You answer calls for a water utility in Dar es Salaam. " +
    "Speak Swahili first and switch to English only if the caller does. " +
    "Keep answers short. Never read out full account numbers.",
  tools: [{
    name: "check_balance",
    description: "Look up a customer's unpaid water bill by meter number.",
    url: "https://example.com/hooks/balance",
    parameters: { meter_number: { type: "string" } },
  }],
  handoff: { phone: "+255700000000", when: "caller asks for a person" },
});
console.log(agent.id);

curl https://api.waridi.io/v1/agents \
  -H "Authorization: Bearer $WARIDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Huduma kwa wateja",
    "language": "sw-TZ",
    "voice": "zawadi",
    "tts_model": "sauti-pro",
    "greeting": "Karibu! Naitwa Zawadi. Nikusaidie vipi leo?",
    "instructions": "You answer calls for a water utility in Dar es Salaam. Speak Swahili first.",
    "tools": [{"name": "check_balance", "url": "https://example.com/hooks/balance", "parameters": {"meter_number": {"type": "string"}}}]
  }'

Response:

{
  "id": "agt_01J9ZB4X7N",
  "object": "agent",
  "name": "Huduma kwa wateja",
  "status": "ready",
  "language": "sw-TZ",
  "voice": "zawadi",
  "sip_uri": "sip:agt_01J9ZB4X7N@sip.waridi.io",
  "created_at": "2026-10-12T09:30:00Z"
}

Agent fields

Field	Type	Description
name	string	For your own reference
language	string	sw-TZ (default) or sw-KE. The agent follows callers who switch to English
voice	string	Any preview or consented cloned voice
tts_model	string	sauti-standard or sauti-pro
greeting	string	First thing the agent says. Keep it under 10 seconds
instructions	string	How the agent should behave. You can write these in English or Swahili
tools	object[]	Webhooks the agent may call. We POST JSON arguments and speak from your JSON reply
handoff	object	Where to transfer the call when a person is needed
max_call_seconds	integer	Default 600
webhook_url	string	Receives call.started, call.ended and transcript events

Talking to an agent

• Phone: route a SIP trunk to the agent's sip_uri. See Telephony.
• Browser or app: create a session with POST /v1/agents/{agent_id}/sessions and connect over WebRTC.
• Your own audio pipeline: open wss://api.waridi.io/v1/stream with agent_id in session.start.

Tool calls

When the agent decides to call a tool, we send your URL a request like this and wait up to 5 seconds for a reply. While it waits, the agent says a short filler such as "Subiri kidogo…".

{
  "type": "tool.call",
  "agent_id": "agt_01J9ZB4X7N",
  "call_id": "call_01J9ZC0F2E",
  "tool": "check_balance",
  "arguments": {"meter_number": "DSM-448812"}
}

Reply with any JSON. The agent turns it into speech, for example {"balance_tzs": 15000, "due": "2026-10-30"}.

Good practice

• Tell callers they are speaking with an automated assistant, and offer a person.
• Keep instructions short and specific. Long prompts make agents slower and vaguer.
• Test with real recordings of your callers, including noisy ones and code-switched ones.