AgentLine

AgentLine Open-source telephony API for AI agents — phone numbers, voice calls, and SMS Give your AI agent a real phone number. Make outbound calls, receive inbound calls, and handle SMS — all through one API. No telecom expertise needed.

[](LICENSE) [](https://python.org) [](https://fastapi.tiangolo.com) [](https://modelcontextprotocol.io) [](Dockerfile) [](https://discord.gg/69SVE2jWNr)

Website · Docs · Skill File · Discord

---

What is AgentLine?

AgentLine is an open-source AI-native telephony platform that gives AI agents real phone numbers and human-like voices. It provides a simple REST API and MCP server so AI agents (Claude, Cursor, custom LLM agents) can make and receive phone calls, handle SMS, and retrieve transcripts — without any telecom knowledge.

Your AI Agent  →  AgentLine API  →  Real Phone Calls
                                 →  SMS Messages
                                 →  Call Transcripts

Why AgentLine?

| | AgentLine | Twilio/Vonage | Build It Yourself | |---|---|---|---| | Built for AI agents | ✅ Purpose-built | ❌ Built for call centers | ❌ You stitch it together | | Setup time | 5 minutes | Hours | Weeks | | MCP server | ✅ Native | ❌ None | ❌ Build your own | | Skill file install | ✅ One file | ❌ Complex SDK | ❌ Hundreds of lines | | Voice pipeline | ✅ Included (STT + TTS + LLM) | ❌ BYO | ❌ BYO | | Open source | ✅ MIT | ❌ Proprietary | ✅ Your code |

---

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
• 💬 SMS — Receive and read inbound text messages
• 🔌 MCP Server — Native Model Context Protocol support for Claude Desktop and Cursor
• 📋 Skill File — One-file install for any AI agent (Claude Code, Cursor, OpenClaw)
• 🌍 Multi-Provider — SignalWire (US) with pluggable provider architecture
• 📝 Transcripts — Automatic call transcription with full conversation history
• 📬 Event Mailbox — Poll-based event system for agents without webhook endpoints
• 💰 Built-in Billing — Per-second call billing with balance tracking
• 🐳 Docker Ready — One command to run the entire stack locally

---

Architecture

graph LR
    A["🤖 AI Agent"] -->|REST API / MCP| B["⚡ AgentLine API"]
    B -->|Provision Numbers| C["📱 SignalWire"]
    B -->|Speech-to-Text| D["🎤 Deepgram"]
    B -->|Text-to-Speech| E["🔊 Cartesia"]
    B -->|LLM Reasoning| F["🧠 OpenAI"]
    C -->|Voice & SMS| G["📞 PSTN Network"]
    B -->|Events & Transcripts| A

Voice Pipeline — Hybrid Relay Mode

AgentLine uses an asynchronous Hybrid Relay architecture instead of fragile real-time WebSocket streams:

Caller dials your agent's number
  → SignalWire answers the call
  → Plays TTS greeting to caller
  → Records caller's speech
  → Deepgram transcribes (fast, accurate)
  → LLM generates agent response
  → Cartesia speaks the response
  → Loop continues until call ends
  → Full transcript stored for retrieval

---

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:

| Variable | Required | Description | |----------|----------|-------------| | SUPABASE_URL | Yes | Your Supabase project URL | | SUPABASE_ANON_KEY | Yes | Supabase anonymous key | | SUPABASE_SERVICE_ROLE_KEY | Yes | Supabase service role key (server-side) | | DATABASE_URL | Yes | PostgreSQL connection string | | SIGNALWIRE_PROJECT_ID | Yes | SignalWire project ID | | SIGNALWIRE_TOKEN | Yes | SignalWire API token | | SIGNALWIRE_SPACE_URL | Yes | Your SignalWire space URL | | DEEPGRAM_API_KEY | Yes | Deepgram API key (STT) | | CARTESIA_API_KEY | Yes | Cartesia API key (TTS) | | OPENAI_API_KEY | Yes | OpenAI API key (LLM) | | REDIS_URL | No | Redis URL (defaults to localhost:6379) | | SECRET_KEY | Yes | App secret key | | BASE_URL | Yes | Public URL of your deployment |

---

API Reference

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

Core Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /v1/agents | Create a new AI voice agent | | GET | /v1/agents | List all agents | | PATCH | /v1/agents/{id} | Update agent (prompt, voice, greeting) | | POST | /v1/numbers | Provision a phone number | | GET | /v1/numbers | List phone numbers | | POST | /v1/calls | Make an outbound call | | GET | /v1/calls | List calls | | GET | /v1/calls/{id}/transcript | Get call transcript | | POST | /v1/calls/{id}/hangup | End an active call | | GET | /v1/events | Poll event mailbox (consume) | | GET | /v1/events/peek | Peek at events (non-destructive) | | GET | /v1/messages | List SMS messages | | GET | /v1/billing/balance | Check account balance | | GET | /v1/billing/expenditure | Spending breakdown |

Authentication

All requests require an API key:

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
     -H "Content-Type: application/json" \
     https://api.agentline.cloud/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 sk_live_YOUR_KEY"
      ]
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | create_agent | Create a new AI voice agent | | list_agents | List all agents | | update_agent | Update agent config/prompt/voice | | make_outbound_call | Initiate an outbound phone call | | list_calls | List call history | | get_call_transcript | Get the full transcript of a call | | hangup_call | End an active call | | buy_phone_number | Provision a new phone number | | list_phone_numbers | List all phone numbers | | poll_events | Poll event mailbox | | peek_events | Peek at pending events | | get_account_balance | Check account balance | | list_available_voices | List voice presets |

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](skills/agentline/SKILL.md).

---

Tech Stack

| Component | Technology | |-----------|-----------| | API Framework | FastAPI (async Python) | | Database | PostgreSQL (Supabase) | | Cache | Redis | | Phone Numbers & Calls | SignalWire | | Speech-to-Text | Deepgram Nova-2 | | Text-to-Speech | Cartesia Sonic | | LLM | OpenAI GPT-4o / GPT-4o-mini | | MCP Server | FastAPI-MCP | | Deployment | Docker, Railway |

---

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](schema.sql). It creates tables for:

• accounts — User accounts with balance tracking
• api_keys — Hashed API keys for authentication
• agents — AI voice agent configurations
• phone_numbers — Provisioned phone numbers
• calls — Call records with transcripts
• messages — SMS message records
• event_mailbox — Server-side event queue
• billing_ledger — Immutable billing transaction log

Migrations are in the [migrations/](migrations/) directory.

---

Pricing (Hosted Version)

If using the hosted version at agentline.cloud:

| Item | Cost | |------|------| | Voice calls (inbound/outbound) | $0.10/min (billed per second) | | Phone number | $2.00 (one-time) | | SMS (inbound) | Free |

Self-hosted: you pay only your provider costs (SignalWire, Deepgram, Cartesia, OpenAI).

---

Contributing

We welcome contributions! See [CONTRIBUTING.md](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](LICENSE) — use it for anything. Commercial use welcome.

---

Built with ❤️ by the AgentLine team Give your AI agent a voice. ☎️

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AgentLineHQ
• Source: AgentLineHQ/AgentLine
• License: MIT
• Homepage: https://agentline.cloud

Install and usage instructions live in the source repository linked above.