SIPHON logo

Getting Started

Getting Started

Build your first AI Voice Agent in under 10 minutes.

1. Prerequisites

Before starting, ensure you have:

  • Python 3.10 or higher installed.
  • LiveKit credentials (Cloud or self-hosted):
  • API keys for your preferred LLM/STT/TTS providers (for example, OpenAI).

2. Installation

Install the SIPHON framework via pip:

pip install siphon-ai

3. Create your Agent

Create a file named agent.py and add the following code. This creates a simple agent that mimics a helpful receptionist.

from siphon.agent import Agent
from siphon.plugins import openai, cartesia, deepgram
from dotenv import load_dotenv

load_dotenv()  # loading .env variables

# Initialize your AI stack
llm = openai.LLM()
tts = cartesia.TTS()
stt = deepgram.STT()

# Define the Agent
agent = Agent(
    agent_name="Receptionist",
    llm=llm,
    tts=tts,
    stt=stt,
    system_instructions="You are a helpful receptionist for a dental clinic. Answer succinctly.",
)

if __name__ == "__main__":
  # One-time setup (fresh machine): download required files
  agent.download_files()
  
  # Start the agent worker in development mode
  agent.dev()

  # Start the agent worker in production mode
  # agent.start()

If you’ve already run download_files() once on this machine, you can skip it and run agent.dev() (development) or agent.start() (production) directly.

Environment configuration

SIPHON reads secrets from environment variables (recommended via a .env file).

At minimum you will typically need:

LIVEKIT_URL=...
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...

OPENAI_API_KEY=...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...

4. Run the Agent

Start your agent in development mode:

python agent.py

You should see:

INFO   livekit.agents     process initialized {"pid": 51167, "inference": true, "elapsed_time": 25.43}  # will be different for you
INFO   livekit.agents     HTTP server listening on :33239  # will be different for you
INFO   livekit.agents     registered worker {"agent_name": "Receptionist", "id": "AW_vpmG4uVvtXg3", "url": "wss://<LIVEKIT_URL>", "region": "<LIVEKIT_REGION>", "protocol": 16}

Production & Scaling

To scale your agent for production, simply run this command on multiple servers. This architecture allows for "Zero Config" horizontal scaling—it automatically detects new workers and load balances incoming calls across them. Learn more about Scaling.

5. Next steps (inbound/outbound)

At this point your agent worker is running. Choose your next step based on what you want to build:

  • Inbound calling (receive calls): configure a phone number/trunk to route calls to your agent.
  • Outbound calling (place calls): create an outbound trunk and initiate calls from code.

If you want provider-specific SIP examples (Twilio, Telnyx, Plivo, Wavix), see: Provider-specific quickstarts

Next Steps