AgentLine

Website · Docs · Changelog · Skill File · Discord

What is AgentLine?

AgentLine is an open-source AI phone agent / voice agent telephony API. It gives coding agents and LLM apps a real US phone number, a voice pipeline (STT + LLM + TTS), and the ability to place outbound calls, answer inbound calls, handle SMS, and walk IVR / DTMF menus — over REST or MCP.

Use it as a self-hosted alternative to stitching Twilio Programmable Voice + Deepgram + a voice LLM yourself, or as an open-source counterpart to hosted voice-agent products (Vapi, Retell, Bland).

Your AI Agent (Claude, Cursor, OpenClaw, Hermes, Codex)
        →  AgentLine REST / MCP
        →  Real PSTN phone calls, SMS, transcripts

Works with Claude Code, Claude Desktop, Cursor, OpenClaw, Hermes, Codex, and any MCP or HTTP client.

Why AgentLine?

Use cases

• AI receptionist — answer inbound calls with a custom greeting and system prompt
• Outbound voice agent — reminders, follow-ups, feedback, and business inquiries
• MCP telephony — “call this number” from Claude Code, Cursor, or OpenClaw
• IVR navigation — press real DTMF keys on phone menus and leave voicemail
• Owner task line — call your agent from a registered number and give it work to run after hangup

Features

• 📞 Voice Calls — Make and receive real phone calls through a simple API
• 🎙️ AI Voice Pipeline — Built-in STT (Deepgram) + LLM (GPT-4o) + TTS (Cartesia) pipeline
• 🎛️ DTMF / IVR — Real touch-tone audio so outbound agents can navigate phone menus and leave voicemail
• ⚡ Semantic turn-taking — Adaptive end-of-turn detection with fast barge-in instead of a fixed pause
• 👤 Owner task mode — Calls from a registered owner number capture instructions for later execution
• 💬 SMS — Receive and read inbound text messages
• 🔌 MCP Server — Native Model Context Protocol tools for Claude Desktop, Claude Code, Cursor, OpenClaw, and Codex
• 📋 Skill File — One-file install for Claude Code, Cursor, OpenClaw, Hermes, and similar runtimes
• 🌍 Pluggable carriers — SignalWire, Twilio, Plivo, Telnyx, or your own class
• 🎙️ Pluggable voice runtimes — built-in pipeline, LiveKit, Pipecat, or your own
• 📝 Transcripts — Automatic call transcription with full conversation history
• 🔄 Persistent Agent Relay — outbound WebSocket with reconnect, ACK/replay, turn-safe context, and runtime-aware setup
• 🪝 Per-agent webhooks — Signed JSON POSTs as a fallback when a relay cannot run
• 📬 Event Mailbox — durable fallback for agents without a relay or webhook
• 🐳 Docker Ready — One command to run the API, Postgres, and Redis locally

Architecture

graph LR
    A["🤖 AI Agent"] -->|REST API / MCP| B["⚡ AgentLine API"]
    B -->|Telephony hook| C["📱 SignalWire, Twilio, Plivo, Telnyx, or yours"]
    B -->|Voice runtime hook| H["🎙️ Built-in, LiveKit, or Pipecat"]
    H -->|Built-in only| D["🎤 STT hook"]
    H -->|Built-in only| E["🔊 TTS hook"]
    H -->|Built-in only| F["🧠 LLM hook"]
    C -->|Voice and SMS| G["📞 PSTN"]
    B -->|Events and transcripts| A

Voice runtimes

VOICE_RUNTIME picks who holds the conversation. An agent can override it with voice_runtime.

The built-in path is:

Caller audio → Deepgram STT → semantic turn-taking
  → OpenAI-compatible LLM (or live relay context) → Cartesia TTS → caller

Carriers, runtimes, and the registration API are in docs/providers.md. A copy-paste example is in examples/hooks.py.

• Semantic turn-taking waits longer when the caller is mid-thought and answers immediately on a complete question.
• Barge-in flushes playback as soon as the caller starts speaking.
• DTMF turns [DTMF:1] markers into real touch-tone audio for IVR menus.
• Relay mode (optional) pushes each caller turn to a local agent over an outbound WebSocket and speaks the returned context verbatim.

Quick Start

Option 1: Docker Compose (Recommended)

git clone https://github.com/agentlineHQ/AgentLine.git
cd AgentLine
cp .env.example .env
# Fill in your API keys in .env (see Configuration below)
docker-compose up -d

This starts:

• API server at http://localhost:8000
• PostgreSQL at localhost:5432 (schema auto-applied)
• Redis at localhost:6379

Option 2: Local Development

git clone https://github.com/agentlineHQ/AgentLine.git
cd AgentLine
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cp .env.example .env
# Fill in your API keys
uvicorn agentline.main:app --reload

Option 3: Use the Hosted Version

Skip self-hosting — sign up at agentline.cloud and get an API key instantly.

Configuration

Copy .env.example to .env and fill in your credentials:

LiveKit's in-process audio bridge needs pip install -r requirements-livekit.txt. The default Pipecat bot needs pip install -r requirements-pipecat.txt. SIP mode for LiveKit does not need the LiveKit Python package.

API Reference

Once running, visit http://localhost:8000/docs for the interactive Swagger UI.

Core Endpoints

Authentication

All requests require an API key (al_live_...; legacy sk_live_... keys are still accepted):

curl -H "Authorization: Bearer al_live_YOUR_KEY" \
     -H "Content-Type: application/json" \
     http://localhost:8000/v1/agents

MCP Server Integration

AgentLine includes a built-in MCP (Model Context Protocol) server, so AI agents like Claude Desktop and Cursor can use telephony tools natively.

Connect from Claude Desktop

Add to your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "agentline": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote@latest",
        "http://localhost:8000/mcp",
        "--header", "Authorization: Bearer al_live_YOUR_KEY"
      ]
    }
  }
}

Available MCP Tools

Test with MCP Inspector

npx @modelcontextprotocol/inspector http://localhost:8000/mcp

Skill File — Install in 30 Seconds

AgentLine ships with a skill file that lets any AI agent gain telephony powers instantly:

https://agentline.cloud/skill.md

How to use:

1. Copy the skill URL above
2. Add it to your AI agent (Claude Code, Cursor, OpenClaw, etc.)
3. Set your AGENTLINE_API_KEY environment variable
4. Tell your agent: "Call +1234567890" — it just works!

The skill file is also included in this repo at skills/agentline/SKILL.md.

Tech Stack

Deployment

Docker

docker build -t agentline .
docker run -p 8000:8000 --env-file .env agentline

Any Cloud Provider

AgentLine runs anywhere that supports Python 3.12+ and Docker: AWS, GCP, Azure, Fly.io, Render, Railway, etc.

Database Schema

The database schema is in schema.sql. It creates tables for:

• accounts — API accounts
• api_keys — Hashed API keys for authentication
• agents — AI voice agent configurations, including an optional voice_runtime
• phone_numbers — Provisioned phone numbers and which carrier owns them
• calls — Call records with transcripts
• messages — SMS message records
• event_mailbox — Server-side event queue

Migrations are in the migrations/ directory.

Cost

This repository does not bill anyone. You pay the carrier, speech vendor, model host, LiveKit, or Pipecat deployment you configure.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• 🐛 Bug reports — Open an issue
• 💡 Feature requests — Open an issue
• 🔧 Pull requests — Fork, branch, PR

Community

• 💬 Discord — Chat with the team and other builders
• 🐦 Twitter — Updates and announcements
• 📖 Docs — Full API documentation
• 📝 Blog — Guides and tutorials

License

MIT — use it for anything. Commercial use welcome.