Voice.ai Agents

Build the best conversational AI voice agents with Voice.ai's Agent API.

✨ Features

• Agent Management - Create, update, and delete voice agents
• One-Click Deploy - Deploy agents for phone calls instantly
• Knowledge Base - RAG-powered agents with custom knowledge
• MCP Integration - Connect agents to external tools via MCP
• Phone Numbers - Manage inbound/outbound phone numbers
• Analytics - Track call history and agent performance

⚙️ Configuration

Get Your API Key

1. Go to Voice.ai Developer Dashboard
2. Sign in or create an account
3. Generate a new API key
4. Copy and save it securely

Set Up Authentication (3 Methods)

Method 1: Environment Variable (Recommended)

export VOICE_AI_API_KEY="your-api-key-here"

Method 2: .env File

# Create .env file in project root
echo 'VOICE_AI_API_KEY=your-api-key-here' >> .env

Method 3: OpenClaw Config

{
  "skills": {
    "voice.ai-voice-agents": {
      "api_key": "your-api-key-here"
    }
  }
}

🔐 Before Any Operation

Important: Always verify authentication before running any commands.

# 1. Check if API key is set
echo $VOICE_AI_API_KEY

# 2. Test connection (list agents)
node scripts/agent.js list

# 3. If errors, re-export your key
export VOICE_AI_API_KEY="your-api-key-here"

Silent Initialization

The SDK automatically initializes when you run any command. No manual setup required after setting the API key.

🚀 Quick Start

export VOICE_AI_API_KEY="your-api-key"

# Create an agent
node scripts/agent.js create --name "Support Bot" --prompt "You are a helpful assistant"

# List all agents
node scripts/agent.js list

# Deploy an agent
node scripts/agent.js deploy --id <agent_id>

🤖 Agent Configuration

Parameter	Default	Description
llm_model	gemini-2.5-flash-lite	LLM model for responses
llm_temperature	0.7	Response creativity (0-2)
max_call_duration	900	Max call length in seconds
allow_interruptions	true	Let users interrupt agent
auto_noise_reduction	true	Filter background noise

🎙️ TTS Voice Settings

Parameter	Default	Description
voice_id	-	Voice ID for agent speech
model	auto	TTS model (auto-selected)
language	en	Language code
temperature	1.0	Voice expressiveness (0-2)
top_p	0.8	Sampling parameter (0-1)

🌍 Supported Languages

auto, en, ca, sv, es, fr, de, it, pt, pl, ru, nl

💻 CLI Usage

# Create a new agent
node scripts/agent.js create --name "My Agent" --prompt "System prompt here" --greeting "Hello!"

# List all agents
node scripts/agent.js list

# Get agent details
node scripts/agent.js get --id <agent_id>

# Update an agent
node scripts/agent.js update --id <agent_id> --prompt "New prompt"

# Deploy an agent
node scripts/agent.js deploy --id <agent_id>

# Pause an agent
node scripts/agent.js pause --id <agent_id>

# Delete an agent
node scripts/agent.js delete --id <agent_id>

🤖 OpenClaw Integration

JSON Configuration

{
  "name": "voice.ai-voice-agents",
  "enabled": true,
  "config": {
    "api_key": "${VOICE_AI_API_KEY}",
    "default_model": "gemini-2.5-flash-lite",
    "auto_deploy": false
  }
}

Chat Triggers

OpenClaw automatically activates this skill when you mention:

• "voice agent", "voice bot", "phone agent"
• "create agent", "deploy agent", "list agents"
• "Voice.ai", "voice ai"

🗣️ User-Friendly Language

When User Says...	Skill Does...
"Create a support agent"	Creates agent with support-focused prompt
"Show my agents"	Lists all agents with status
"Deploy the agent"	Deploys agent for phone calls
"Update the greeting"	Updates agent greeting message
"Delete the test agent"	Deletes specified agent
"What agents do I have?"	Lists agents in friendly format
"Make an FAQ bot"	Creates agent with FAQ template
"Connect to my MCP server"	Configures MCP integration

📁 Project Files

voice-ai-agents/
├── SKILL.md                    # This documentation
├── voice-ai-agents.yaml        # Skill configuration
├── voice-ai-agents-sdk.js      # JavaScript SDK
└── scripts/
    └── agent.js                # CLI tool

File	Purpose
SKILL.md	Documentation and OpenClaw skill definition
voice-ai-agents.yaml	API config, models, defaults
voice-ai-agents-sdk.js	Full SDK with all API methods
scripts/agent.js	Command-line interface

❌ Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid or missing API key	Check VOICE_AI_API_KEY is set correctly
403 Forbidden	API key lacks permissions	Generate new key with proper scopes
404 Not Found	Agent ID doesn't exist	Run list to get valid agent IDs
429 Too Many Requests	Rate limit exceeded	Wait 60 seconds and retry
500 Server Error	Voice.ai API issue	Check status page
ENOTFOUND	Network error	Check internet connection
Agent not deployed	Agent exists but not active	Run deploy --id <agent_id>

Graceful Error Messages

The SDK provides user-friendly error messages:

❌ Authentication failed. Please check your API key.
   Get one at: https://voice.ai/app/dashboard/developers

❌ Agent "support-bot" not found. 
   Run 'node scripts/agent.js list' to see available agents.

❌ Rate limit reached. Please wait 60 seconds before retrying.

📝 Triggers

These phrases activate the Voice.ai Agents skill in OpenClaw:

Category	Trigger Phrases
Create	"create voice agent", "make a phone bot", "new agent"
List	"show agents", "list my agents", "what agents exist"
Deploy	"deploy agent", "activate agent", "start the bot"
Update	"update agent", "change prompt", "edit greeting"
Delete	"delete agent", "remove bot", "destroy agent"
Info	"agent details", "show agent", "get agent info"

🔗 MCP Server Integration

Connect your agent to external tools:

const agent = await client.createAgent({
  name: "MCP Agent",
  config: {
    prompt: "You can use tools to help users",
    mcp_servers: [{
      name: "my-tools",
      url: "https://my-server.com/mcp",
      auth_type: "bearer_token",
      auth_token: "secret"
    }]
  }
});

📚 Knowledge Base (RAG)

Add custom knowledge to your agent:

# Create agent with knowledge base
node scripts/agent.js create --name "FAQ Bot" --kb-id 123

🔗 Links

• Get API Key ← Start here!
• Voice Agents Guide
• Agent API Reference
• Status Page

📋 Changelog

Version	Date	Changes
1.0.0	2026-01-31	Initial release with full agent management

---

Made with ❤️ by Nick Gill