Create agents programmatically for full control and integration with your development workflow:
Example: Creating a New Customer Support Agent
Copy
Ask AI
// Note: we are using a template variable for customerNameconst createAgent = async () => { const response = await fetch('https://api.ultravox.ai/api/agents', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': 'your-api-key' }, body: JSON.stringify({ name: 'Customer Support Agent', callTemplate: { systemPrompt: "You are Anna, a friendly customer support agent for Acme Inc. You are talking to {{customerName}}. You should help them with their questions about our products and services. If you can't answer a question, offer to connect them with a human support agent.", voice: "Jessica", temperature: 0.4, recordingEnabled: true, firstSpeakerSettings: { agent: { text: "Hello! This is Anna from Acme customer support. How can I help you today?" } }, selectedTools: [ { toolName: 'knowledgebaseLookup' }, { toolName: 'orderStatus' }, { toolName: 'transferToHuman' } ] } }) }); return await response.json();};
Design effective system prompts that define your agent’s personality and knowledge. Here’s an example prompt using various template variables that will be populated at call creation time using the templateContext property:
Example: Defining an Agent System Prompt
Copy
Ask AI
You are {{agentName}}, a {{role}} for {{companyName}}. Your personality: {{personality}}Your expertise: {{expertise}}Guidelines:- Always be {{tone}} and professional- If you don't know something, offer to transfer the call to a human agent using the 'transferToHuman' tool- Keep responses concise but helpful- Reference the customer as {{customerName}} when appropriateContext about this conversation:- Customer type: {{customerTier}}- Previous interaction: {{lastInteraction}}
Start Simple: Begin with mono prompts that handle your core use case in a single system prompt. This approach works well for:
Straightforward customer support
Information lookup
Basic transaction flows
Add Complexity When Needed: If mono prompting isn’t sufficient for your use case, gradually add:
Inline instructions for multi-step processes → Guiding Agents
Call stages for completely different conversation phases → Call Stages
Don’t Over-Engineer: Resist the temptation to add complexity early. Most voice applications can be built successfully with simple agent configurations.