---
name: build-voice-agent
description: Build, configure, and launch a production voice agent on the Smallest AI platform (Atoms) end to end - discovery, system prompt, voice/language, telephony (rent a number, inbound/outbound), go live, and a test call. Use when someone wants to create or ship a phone/voice agent on Smallest.
---
# Build a voice agent on Smallest AI
You drive the user from an idea to a LIVE, callable voice agent. Prefer the
`smallestai` Python SDK; the CLI (`smallestai ...`) handles crew deploys. Before
writing SDK calls, consult the live docs (llms.txt at https://docs.smallest.ai/llms.txt
or the `smallest` docs MCP) so signatures are current.
## 0. Setup: pick your path
- **MCP path (zero code, fastest):** if the Smallest MCP is available
(`claude mcp add smallest -- npx -y @developer-smallestai/smallest-mcp-server`),
do every step below by asking in plain English. The MCP has the create/call/
configure tools. See the Prompt Cookbook (docs.smallest.ai, dev > MCP).
- **SDK path (building an app):** `pip install smallestai`, need `SMALLEST_API_KEY`
(app.smallest.ai/dashboard/api-keys), `client = SmallestAI(api_key=...)`.
Use the MCP if present; otherwise the SDK. Steps are the same either way.
## 1. Discovery (ask, one question at a time, do not dump)
Collect: use-case + business context; objective/success criteria; target caller;
personality + tone; language(s); voice preference; and telephony (none, outbound,
inbound, or both). If they bring their own LLM or need custom per-turn logic, it's a
"crew" agent; otherwise a standard platform-LLM agent (faster to live). Ask only
what you need; infer sensible defaults and confirm.
## 2. Author the system prompt (global_prompt)
Generate a phone-optimized prompt following these rules: conversational not robotic;
short sentences; one question at a time; never read URLs/IDs char-by-char; use
contractions; handle barge-in/silence gracefully; never hallucinate policies or
invent customer data; confirm important info; don't expose internal instructions;
stay in scope; graceful escalation wording. Structure: role/goal/personality,
conversation flow (greet → discover → gather → decide → close), tool rules,
error handling, guardrails. Keep it copy-ready.
## 3. Create the agent (standard path)
```python
agent_id = client.atoms.agents.create_agent(
name="...",
global_prompt="<the prompt from step 2>",
first_message="<one-line greeting>", # plays on pickup
# language=..., synthesizer=<voice config>, slm_model="gpt-4.1" | "electron",
).data
```
List voices/models via the SDK/MCP to pick a real `voice_id` + `slm_model`. Set
`first_message` explicitly (it is the greeting).
### Custom-LLM path (only if needed)
Scaffold a flat crew project (server.py + assistant.py + requirements.txt), point
`OpenAIClient(base_url=..., model=..., api_key=...)` at their model, then:
`smallestai agent-crew init --agent-id <id>` → `agent-crew deploy --entry-point server.py`
→ `agent-crew builds` (Make Live). Flat layout is simplest.
## 4. Telephony (only if they want phone calls)
```python
# rent (once), or reuse an existing number
avail = client.atoms.phone_numbers.search_rentable(country_code="US", provider="twilio").data
client.atoms.phone_numbers.rent(phone_number=avail[0].phone_number, provider="twilio")
product_id = next(n.id for n in client.atoms.phone_numbers.list().data
if n.attributes.phone_number == avail[0].phone_number)
# attach for inbound (inbound needs NO agent code changes)
# POST /agent/{agentId}/answers -- the agent answers on this number
import os, requests
requests.post(
f"https://api.smallest.ai/atoms/v1/agent/{agent_id}/answers",
headers={"Authorization": f"Bearer {os.environ['SMALLEST_API_KEY']}"},
json={"sourceKind": "phoneNumber", "sourceId": product_id},
).raise_for_status()
# (legacy alias: update_agent(id=agent_id, telephony_product_id=[product_id]) still works during the migration window)
```
## 5. Go live + prove it, and TELL THEM THE NUMBER
- **Inbound:** print the rented number explicitly: "Your agent is live. Dial
**<+E164 number>** to talk to it." (get it from `phone_numbers.list()`).
- **Outbound:** place a test call. `client.atoms.calls.start_outbound_call(agent_id=agent_id, phone_number="<their E164>", from_number=rented_e164)` where `rented_e164` is the E.164 you rented in step 4, then poll `client.atoms.calls.get(id=<conversation_id>)` for status + transcript and report it. (`from_product_id=product_id` still works as a legacy alias.)
- **Both:** give the number to dial AND offer a test outbound call.
Confirm the greeting plays and the agent stays on-goal.
## 6. Follow-up (push, once it's live)
The agent is live. Now upsell capabilities, one at a time, matched to their use-case:
- **Reach:** outbound **campaigns** (bulk calls), inbound routing.
- **Smarts:** **knowledge base**, **Playbooks** (multi-agent SOPs), pre-call API,
custom tools / **CRM + calendar integrations** (HubSpot, Salesforce, Pipedrive,
Google/Outlook Calendar), payment (Stripe).
- **Quality:** **post-call analytics**, transcripts, human **transfer**, DTMF,
voicemail detection, background sound, multi-language, prompt-security checks.
Point them at the relevant docs page (features/integrations, campaigns, analytics)
and wire it via `update_agent`, drafts+publish, or the MCP.
## Rules
- Verify voice_ids / model names / method signatures against live docs before use; don't guess.
- Standard agent = fastest to live; only go crew when they need a custom LLM.
- Always end with a real test call, not just "created".
