SIPHON logo

Core Concepts

Core Concepts

SIPHON is built on a small set of building blocks. Understanding these concepts will help you reason about inbound and outbound calling, configuration, and production behavior.

This section is split into multiple sections:

1. Agents

An Agent in SIPHON represents a worker that handles a specific type of call. It is the "brain" of the operation.

Configuration

Each agent is configured with:

  • Name: Unique identifier (e.g., "Receptionist").
  • Instructions: The system prompt that defines its personality.
  • Tools: Functions the agent can call (e.g., check_calendar, book_appointment).

Lifecycle

Every call goes through a lifecycle:

  1. on_enter: Called when the agent joins the room.
  2. monitor_call: Loop that checks for hangups or silence.
  3. on_exit: Cleanup, saving metadata, or post-call processing.

2. Dispatch

Dispatch is the mechanism that routes a phone number to a specific Agent.

When a call comes in:

  1. The SIP Provider sends a request to LiveKit.
  2. SIPHON checks its dispatch rules.
  3. If a match is found (e.g., "called number is +15550001"), SIPHON creates a room and assigns the configured Agent.

In SIPHON, you can manage dispatch rules programmatically:

from siphon.telephony.inbound import Dispatch

dispatch = Dispatch(
    dispatch_name="customer-support",
    agent_name="SupportBot",
    sip_trunk_id="TRUNK_123",
    # Or omit sip_trunk_id and provide a number so SIPHON can look up/create a trunk:
    # sip_number="+15550001",
)

dispatch.agent()

3. Plugins

SIPHON is provider-agnostic. You are not locked into OpenAI or any specific vendor. This is achieved through Plugins.

Supported plugins include:

  • LLMs: OpenAI, Anthropic, Groq, Mistral,....etc
  • STT (Transcriber): Deepgram, AssemblyAI, Google,.....etc
  • TTS (Voice): ElevenLabs, Cartesia, OpenAI,....etc

You can mix and match these in your agent configuration:

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

agent = Agent(
    agent_name="Receptionist",
    llm=openai.LLM(model="gpt-4.1-mini"),
    stt=deepgram.STT(),
    tts=cartesia.TTS(),
    system_instructions="You are a helpful receptionist.",
)