call-use

Give your AI agent the ability to make real phone calls.

call-use is an open-source outbound call-control runtime that lets AI agents dial real phones, navigate IVR menus, talk to humans, and return structured results. Think browser-use, but for phone calls.

Early release (v0.1) — Core functionality works. API may change before v1.0. Report issues.

from call_use import CallAgent

outcome = await CallAgent(
    phone="+18001234567",
    instructions="Cancel my internet subscription",
    approval_required=False,
).call()

print(outcome.disposition)   # "completed"
print(outcome.transcript)    # [{speaker: "agent", text: "..."}, ...]

Features

• Four interfaces — Python SDK, CLI, MCP server, and REST API. Use whichever fits your stack.
• IVR navigation — Navigate phone menus, press DTMF buttons, handle hold music automatically.
• Human takeover — Pause the AI mid-call, join as a human, then hand control back to the agent.
• Approval flow — Agent pauses and asks permission before taking sensitive actions.
• Structured outcomes — Every call returns typed results: transcript, events, disposition, duration.
• Phone validation — E.164 format enforcement, premium-rate blocking, Caribbean NPA blocking.
• Framework integrations — Works with LangChain, CrewAI, OpenAI Agents, and any MCP-compatible client.
• Rate limiting — Built-in per-key sliding window for the REST API.

Installation

pip install call-use

Quick Start

Prerequisites

call-use connects four external services into a voice AI pipeline:

Configuration

Set these environment variables (or use a .env file):

Start the worker

The worker process handles the actual voice pipeline:

call-use-worker start

Make a call

Python SDK:

import asyncio
from call_use import CallAgent

async def main():
    agent = CallAgent(
        phone="+18001234567",
        instructions="Ask about store hours",
        approval_required=False,
    )
    outcome = await agent.call()
    print(f"{outcome.disposition.value}: {outcome.duration_seconds:.0f}s")
    for t in outcome.transcript:
        print(f"  [{t['speaker']}] {t['text']}")

asyncio.run(main())

CLI — any agent that can run shell commands can make calls:

call-use dial "+18001234567" -i "Ask about store hours"

Events stream to stderr in real-time; structured JSON result goes to stdout.

MCP Server — native integration for Claude Code, Codex, and other MCP clients:

{
  "mcpServers": {
    "call-use": {
      "command": "call-use-mcp",
      "env": {
        "LIVEKIT_URL": "wss://...",
        "LIVEKIT_API_KEY": "...",
        "LIVEKIT_API_SECRET": "...",
        "SIP_TRUNK_ID": "...",
        "DEEPGRAM_API_KEY": "your-deepgram-api-key",
        "OPENAI_API_KEY": "..."
      }
    }
  }
}

Exposes four async tools: dial (returns immediately), status, cancel, result.

Architecture

┌──────────┐         ┌──────────────┐         ┌────────────┐         ┌──────┐
│ Your Code│────────▶│ LiveKit Cloud│────────▶│ Twilio SIP │────────▶│ PSTN │
│ (SDK/CLI)│  gRPC   │              │  agent  │            │  SIP    │      │
└──────────┘         │  Room + Data │  dispatch            │         │ ☎    │
                     │   Channels   │         └────────────┘         └──────┘
                     └──────┬───────┘
                            │
                     ┌──────┴───────┐
                     │ call-use     │
                     │ worker       │
                     │              │
                     │ Deepgram STT │
                     │ GPT-4o LLM   │
                     │ OpenAI TTS   │
                     └──────────────┘

Two processes: your code dispatches a call task into a LiveKit room; the worker joins the room, dials via SIP, runs the voice conversation, and publishes the structured outcome.

Human Takeover

Pause the AI agent, join the call yourself, then hand control back:

call_task = asyncio.create_task(agent.call())

# ... when a human needs to take over:
token = await agent.takeover()   # returns LiveKit JWT
# ... join the room with the token, talk to the callee ...
await agent.resume()             # agent takes over again

result = await call_task

Approval Flow

The agent pauses and asks before taking sensitive actions:

agent = CallAgent(
    phone="+18001234567",
    instructions="Cancel my subscription. If they offer a discount, ask me first.",
    approval_required=True,
    on_approval=lambda data: "approved" if input(f"Approve '{data['details']}'? [y/n]: ").strip().lower() == "y" else "rejected",
)

REST API

For multi-tenant deployments:

from call_use import create_app
app = create_app(api_key="your-secret-key")
# uvicorn your_module:app

All endpoints require an X-API-Key header.

Examples

Documentation

Full documentation at docs.call-use.com — getting started, guides, API reference, and architecture deep-dive.

Contributing

git clone https://github.com/agent-next/call-use.git
cd call-use
pip install -e ".[dev]"
make check  # lint + typecheck + test (100% coverage) + build

See CONTRIBUTING.md for guidelines.

Troubleshooting

Known Limitations

• In-memory state — REST API call state is lost on restart; use LiveKit room metadata for recovery.
• Single worker — Horizontal scaling requires a shared state backend.
• US/Canada only — Outbound PSTN via Twilio SIP; international and inbound calling are planned.

Legal Notice

call-use is a developer tool for legitimate business automation. Users are solely responsible for complying with all applicable telecommunications laws including TCPA, FCC regulations on AI-generated voices (FCC 24-17), Do Not Call registry, and state recording consent laws. See SECURITY.md for details.

License

MIT