Phone Call Agent

AI voice call agent — make outbound calls, generate browser call links, accept inbound calls, and retrieve full transcripts + summaries when calls end. Suppo...

Security Scan

The SKILL.md describes a plausible self-hosted call agent, but the runtime instructions ask you to modify your Claude client config, supply many credentials (including a Cloudflare token and LLM/SIP keys), and run code you must pull from GitHub — while the registry metadata claims no env/config requirements; these mismatches and a prompt-injection pattern are reasons to be cautious.

Purpose & Capability

The skill's stated purpose (outbound/inbound voice calls, transcripts) reasonably explains the need for LLM, STT/TTS, LiveKit and SIP credentials. However, the registry metadata lists no required environment variables, binaries, or config paths while the SKILL.md clearly requires many API keys, a SIP trunk ID, Docker/Python/docker-compose usage, and editing a local Claude config file. That mismatch (declared 'none' vs. many required items in the doc) is incoherent and should be explained by the publisher.

Instruction Scope

The instructions tell the user to git-clone a repository, run docker compose, pip install mcp, and — importantly — edit the user's Claude desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json) to add an MCP server entry. Modifying an agent/client config is outside a simple 'call helper' and grants this skill a privileged integration point; the SKILL.md also contains frontmatter fields (argument-hint/metadata) that triggered a 'system-prompt-override' injection pattern. All of this is within the doc but increases risk and requires careful code review before enabling.

Install Mechanism

There is no formal install spec in the registry entry; the SKILL.md instructs pulling code from GitHub and using Docker Compose and pip. Using a GitHub repo is normal and acceptable, but the registry metadata omits declaring required binaries (git, docker, docker-compose, python, pip). The repo URL is a GitHub host (lower risk than arbitrary IPs), but because the skill asks you to run code and install services, inspect the repository before running.

Credentials

The .env in SKILL.md requests numerous credentials: LLM API key(s), LIVEKIT keys, VOLCENGINE tokens, SIP_OUTBOUND_TRUNK_ID, and CLOUDFLARE_TOKEN for a public tunnel. These are plausible for a call agent, but the registry declared no required env vars — an inconsistency. In particular, a Cloudflare token and any LLM keys are high-value secrets; the SKILL.md does not document minimal scopes or guidance for limited permissions.

Persistence & Privilege

The skill instructs editing the user's Claude desktop config to register an MCP server entry. That changes another application's configuration to enable this skill's process to be launched by Claude — effectively granting the skill a persistent integration point. The skill does not set 'always: true', but modifying another app's config is a privileged operation and should only be done after code review and verifying the publisher.

Scan Findings in Context

[system-prompt-override] unexpected: The SKILL.md frontmatter contains fields (argument-hint, metadata, compatibility) and content patterns that the scanner flagged as potential system-prompt override or injection. While frontmatter can be benign, prompt-injection capability in skill instructions increases risk because it may try to influence the agent's system role or behavior beyond intended operational scope.

What to consider before installing

This skill is plausible for making browser-based and SIP calls, but exercise caution before installing: 1) The registry metadata claims no required env/config, yet the SKILL.md asks you to supply LLM API keys, LiveKit/VOLCENGINE tokens, a SIP trunk ID and a Cloudflare token — verify why these are needed and limit token scopes where possible. 2) The SKILL.md instructs you to modify your Claude client config (~/Library/Application Support/Claude/claude_desktop_config.json) to add an MCP server entry. That registers code you pull from GitHub to be launched by your agent — only do this if you fully trust and have reviewed the repository (particularly backend.mcp_server). 3) Clone and inspect the GitHub repo locally (review Docker compose, backend code, mcp server implementation, and any scripts) before running docker-compose or pip install. 4) Prefer running in an isolated VM/container and avoid exposing high-privilege tokens (Cloudflare token should be scoped/minimized). 5) If you are unsure, ask the publisher for explicit required env variables and the least-privilege guidance, or request a signed/reproducible release. Because the registry metadata and the runtime instructions disagree and a prompt-injection pattern was detected, treat this skill as 'suspicious' until you can audit the upstream code and verify trustworthiness.

An open-source, self-hosted AI voice call agent. Give it a phone number and a task — it calls the person, has a natural conversation, and returns the full transcript and outcome back to you.

Works in two modes:

• Outbound — agent dials a real phone number via SIP, or generates a browser call link
• Inbound — agent answers incoming calls from your SIP trunk

---

Quick Start

git clone https://github.com/Littlesheepxy/phone-call-agent
cd phone-call-agent
cp .env.example .env
# Fill in .env with your API keys (see Configuration below)
docker compose up

Services started:

Service	URL	Purpose
Backend API	http://localhost:8001	FastAPI + MCP server
Web UI	http://localhost:3000	Dashboard + share-link landing page
LiveKit	ws://localhost:7880	WebRTC media server

Public URL (needed for share links to work on other devices)

# No account needed — temporary URL, good for testing:
docker compose --profile quick-tunnel up quick-tunnel

# Permanent URL (free Cloudflare account):
# Set CLOUDFLARE_TOKEN= in .env, then:
docker compose --profile tunnel up tunnel

---

Configuration (.env)

# LiveKit (included in docker compose — defaults work out of the box)
LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

# LLM — pick one
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

# STT (speech-to-text)
ASR_PROVIDER=openai_whisper   # or: volcengine (lower latency for Chinese)

# TTS (text-to-speech)
TTS_PROVIDER=openai           # or: volcengine
TTS_VOICE=alloy

# Volcengine / Doubao (recommended for Chinese — lower latency, better quality)
VOLCENGINE_LLM_API_KEY=...
VOLCENGINE_LLM_MODEL=doubao-pro-32k-241215
VOLCENGINE_ASR_APP_ID=...
VOLCENGINE_ASR_TOKEN=...
VOLCENGINE_TTS_APP_ID=...
VOLCENGINE_TTS_TOKEN=...

# SIP trunk (only needed for real outbound phone calls)
SIP_OUTBOUND_TRUNK_ID=...     # LiveKit SIP trunk ID

# Optional: called with transcript + summary JSON when each call ends
WEBHOOK_URL=https://your-app.com/call-webhook

# Public base URL for share links (set to your tunnel/domain)
PUBLIC_URL=https://your-tunnel.trycloudflare.com

---

How Share Links Work

The core workflow: Claude generates a browser call link → sends it to anyone → they click and talk to the AI → Claude gets the transcript back.

Claude (via MCP)
  │
  ├── create_share_link("follow_up", mode="outbound")
  │     └── returns: https://abc123.trycloudflare.com/call/web-xxx?token=...
  │
  │   [you send this URL to the person you want to call]
  │
  ├── Person opens link in any browser (phone, laptop — no app needed)
  │     └── WebRTC audio call starts instantly
  │
  └── get_call_result(room_name, wait_seconds=300)
        └── returns transcript + summary the moment they hang up

Step 1 — Start the tunnel so the link works for others

By default the link points to localhost — only works on your machine. To make it work for anyone:

# Option A: No account needed (temporary URL, good for demos)
docker compose --profile quick-tunnel up quick-tunnel
# Prints something like: https://abc123.trycloudflare.com

# Option B: Permanent URL (free Cloudflare account)
# 1. Get a tunnel token at dash.cloudflare.com → Zero Trust → Tunnels
# 2. Add to .env:  CLOUDFLARE_TOKEN=your-token-here
# 3. Run:
docker compose --profile tunnel up tunnel

Step 2 — Set PUBLIC_URL in .env

PUBLIC_URL=https://abc123.trycloudflare.com

Restart the backend so it uses the new URL:

docker compose restart agent

Step 3 — Ask Claude to make a call

You: "帮我跟进一下张三的Q1合同签署"

Claude:
  → create_share_link("follow_up", mode="outbound")
  → "请点击此链接，AI 会主动跟进合同事宜：https://abc123.trycloudflare.com/call/web-xxx?token=..."
  → [waits for the call to end]
  → "张三确认将于本周五提交合同。"

The person receiving the link just opens it in a browser — no app, no phone number, no account needed.

---

MCP Server Setup

After docker compose up, connect the MCP server to Claude Desktop:

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "phone-call-agent": {
      "command": "python",
      "args": ["-m", "backend.mcp_server"],
      "cwd": "/path/to/phone-call-agent",
      "env": {
        "AGENT_API_URL": "http://localhost:8001"
      }
    }
  }
}

Install the MCP dependency first:

cd phone-call-agent && pip install mcp>=1.0.0

---

MCP Tools

Once connected, Claude has access to these tools:

list_skills

List all available call skills (loaded from skills/*.md).

→ follow_up: 跟进待处理事项 (outbound)
→ appointment_reminder: 提醒联系人即将到来的预约 (outbound)
→ customer_survey: 服务后进行简短满意度调查 (outbound)

create_share_link(skill_id, mode?)

Generate a browser-based call URL — no phone number needed.

• mode: "outbound" → AI speaks first (agent initiates the conversation)
• mode: "inbound" → user speaks first (agent waits and responds)
• Default: use the skill's own mode setting

Returns share_url, room_name, mode, expires_in.

make_voice_call(to, skill_id, context)

Dial a real phone number via SIP. Requires SIP_OUTBOUND_TRUNK_ID in .env.

• to: E.164 phone number e.g. "[phone]"
• context: fills {{variable}} placeholders in the skill's system prompt

get_call_result(room_name, wait_seconds?)

Retrieve the transcript and summary of a completed call.

• wait_seconds: long-poll up to 300 seconds — returns the moment the call ends
• Returns: transcript[], summary.outcome, summary.summary, summary.sentiment

get_skill(skill_id)

Get a skill's details including context variables.

check_pending_inbound / accept_inbound_call(room_name, skill_id)

Handle incoming SIP calls — list pending calls and accept them with a chosen skill.

---

Skills

Skills are Markdown files in skills/ — YAML frontmatter + LLM system prompt:

---
name: my_skill
description: 简短描述
language: zh          # zh | en | auto
mode: outbound        # outbound | inbound | both
max_duration: 300
context_variables:
  - contact_name
  - topic
---
你是 Relay，一个 AI 助理。联系人：{{contact_name}}。话题：{{topic}}。

No code changes needed. Add a file → restart → immediately available via MCP.

---

Typical Agent Workflow

User: "帮我跟进一下张三的Q1合同签署"

Claude:
  1. list_skills() → 找到 follow_up
  2. create_share_link("follow_up", mode="outbound")
     → share_url: https://your-tunnel.../call/web-xxx?token=...
  3. 把链接发给用户：
     "请点击此链接，AI 会主动跟进您的合同事宜：[链接]"
  4. get_call_result(room_name, wait_seconds=300)
     → 通话结束后立即返回
  5. 总结并回复：
     "张三确认将于本周五提交合同。通话时长 2 分 18 秒。"

---

Architecture

User prompt
    │
    ▼
Claude (MCP client)
    │  tools: create_share_link / get_call_result
    ▼
phone-call-agent backend (FastAPI :8001)
    │
    ├── LiveKit room (WebRTC)
    │       ├── AI agent (Pipecat pipeline)
    │       │       ├── VAD (Silero)
    │       │       ├── STT (Whisper / Volcengine)
    │       │       ├── LLM (GPT-4o / Doubao)
    │       │       └── TTS (OpenAI / Volcengine)
    │       └── User (browser via share link, or SIP phone)
    │
    └── Results stored → GET /calls/{room}/result

---

Supported Providers

Component	Options
LLM	OpenAI (gpt-4o, gpt-4o-mini), Volcengine Doubao, any OpenAI-compatible
STT	OpenAI Whisper, Volcengine ASR (recommended for Chinese)
TTS	OpenAI TTS, Volcengine TTS (recommended for Chinese)
Phone	Any LiveKit SIP trunk provider
WebRTC	LiveKit (self-hosted, included in docker compose)