Getting Started

Create Your First Agent
in 5 Minutes

Follow this guide to set up your development environment and deploy your first voice AI agent.

Choose Your Path

Visual Wizard (Recommended)

Create personas through our guided console - no code required

Developer CLI

Full control with command-line tools and SDK

✨

Create with Visual Wizard

The fastest way to create and publish a persona

Sign In to Console

Go to the Developer Console and sign in with Google or GitHub. This creates your developer account automatically.

Start Persona Wizard

Go to Create Persona and follow the 6-step wizard:

1. Identity

Name & tagline

2. Personality

Traits & style

3. Voice

Pick & preview

4. Knowledge

Expertise tags

5. Behaviors

Greetings

6. Review

Submit

Choose a Voice

Browse our curated library of Cartesia voices. Click any voice to hear a preview with your custom greeting text.

Submit for Review

The wizard validates your persona automatically. Fix any errors, then submit for marketplace review. Approval typically takes 2-5 business days.

Create Your First Persona →

— OR —

⌘

Developer CLI Setup

Full control with TypeScript SDK and CLI tools

Prerequisites

Before you begin, make sure you have the following installed:

Node.js 18+ - Download
npm or pnpm - Package manager
Git - For cloning the repository

Clone the Repository

Start by cloning the Ferni agents repository:

            
bash

          git clone https://github.com/ferni-ai/ferni-agents.git
cd ferni-agents
npm install

Set Up Environment

Copy the example environment file and add your API keys:

            
bash

          cp .env.example .env

Then edit .env and add your keys:

            
.env

          # Required: OpenAI API key for LLM
OPENAI_API_KEY=sk-...

# Required: Cartesia API key for voice synthesis
CARTESIA_API_KEY=...

# Optional: LiveKit for real-time audio
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...

Create Your Agent

Use the CLI to scaffold a new agent from a template:

            
bash

          # Create a new agent with the 'coach' template
npm run agents create my-coach --template coach

# This creates:
# src/personas/bundles/my-coach/
#   ├── content/
#   │   ├── identity.json      # Name, voice, personality
#   │   ├── behaviors.json     # Conversation patterns
#   │   └── knowledge.json     # Domain expertise
#   └── index.ts               # Entry point

Customize Your Agent

Edit the identity file to personalize your agent:

            
            
            
          
identity.json

          {
  "name": "Luna",
  "displayName": "Luna the Life Coach",
  "tagline": "Your thoughtful companion for growth",
  
  "voice": {
    "provider": "cartesia",
    "voiceId": "a0e99841-438c-4a64-b679-ae501e7d6091",
    "settings": {
      "speed": 1.0,
      "emotion": "friendly"
    }
  },
  
  "personality": {
    "warmth": 0.85,
    "humorLevel": 0.6,
    "formality": 0.3,
    "traits": ["empathetic", "encouraging", "insightful"]
  },
  
  "systemPrompt": "You are Luna, a warm and insightful life coach..."
}
        

Start Talking!

Run your agent locally and start a conversation:

            
bash

          # Start your agent
PERSONA_ID=my-coach npm run dev

# Output:
# 🎙️ Voice agent running on http://localhost:8080
# 📡 WebSocket server ready
# Ready to chat!

Open http://localhost:8080 in your browser and start talking to your agent!