Lampline README

项目的 README,来自 github.com/C4rohan/Lampline。合并为一个 markdown 文件:README.md。

Lampline

Test and run phone agents on your own machine.

Write conversation tests for your phone agents, including Dialogflow CX and CX Agent Studio agents,
run them from Claude Code or CI, and have real phone calls graded by an AI caller.
Open source, and free to run with no API keys.

CI Apache-2.0 Tests Dialogflow CX and CX Agent Studio agents Claude Code plugin 20 model providers Runs local and on-prem Open in GitHub Codespaces

🚀 Quick start  ·  🤖 From Claude Code  ·  🧪 Test a Dialogflow agent  ·  📋 Free phone evals  ·  🔁 Import from Google  ·  👀 Tour  ·  🧠 Models  ·  📞 Phone and SIP  ·  🗺️ Roadmap  ·  📘 Engine docs  ·  🧩 vk CLI


30 seconds: import a Dialogflow CX export, open it in the builder, chat with it while its steps light up, then a real phone call to it played by the Test Caller and graded Passed
Import a Dialogflow CX agent, test it, and grade a real phone call to it. Sample agent and made-up data; replies from Lampline's test model.

pipx install lampline            # the vk command: lint, test, import, export

Have a Dialogflow CX agent? Test it in 10 minutes. Want the whole platform? Quick start: one command, no API keys.

Test. An agent's tests are plain YAML: what the caller says (or a model playing the caller), and what must happen: which steps the call reaches, what the agent must or must never say, which tools it calls. vk test runs them on Lampline, or against a live Dialogflow CX or CX Agent Studio agent, and tells you exactly what went wrong:

$ vk test agents/front-desk
PASS  billing question goes to the billing team  (2 turn(s), 0.8s)  Greeting → Router → Billing → Transfer to staff
PASS  emergency gets the 911 instruction  (1 turn(s), 0.7s)  Greeting → Router
FAIL  caller asks about Saturday hours  (1 turn(s), 0.8s)  Greeting → Router
      - expected to reach 'Hours and location'; steps were Greeting → Router
      - expected the agent to say 'noon'

A starter template run against Lampline's stand-in test model, which is why one test fails.

Fix and review from your coding agent. Lampline ships skills for Claude Code, Cursor and Codex that build an agent with tests, fix failing tests without breaking passing ones, test your Dialogflow agents, and review a change before it goes live (set up).

Run it. The same agents take real calls on hardware you control: a drag-and-drop builder where LLM steps and scripted pages mix, HTTP and MCP tools, records and document search, and phone calls over Twilio, Telnyx or any SIP trunk through jambonz. Import from Dialogflow CX and CX Agent Studio, or export back, whenever you like. Built on Pipecat.

🏠 Local first
One command on a laptop, a GPU box or an on-prem server. No cloud account needed.
🔒 Private by default
No telemetry, bound to localhost, a key on every request, and keys never in your agents or the repo.
🧠 Any model
Claude, OpenAI, Gemini, Vertex AI, Azure OpenAI, Bedrock, Groq, Mistral, DeepSeek, Grok and more, or Ollama on your own hardware.
🧩 Agents as code
Every agent is a folder of YAML and Markdown: reviewed in git, tested with vk, exported back to Google's tools whenever you like.

🚀 Quick start

Just the tests (Python 3.10+; no Docker, no clone):

pipx install lampline                                     # the vk command
vk templates install front-desk --dir agents/front-desk   # a starter agent with tests
vk lint agents/front-desk                                 # offline checks

From here you can test your Dialogflow CX agent in 10 minutes, or start the engine below and run vk test agents/front-desk.

The whole platform (builder, test calls, phone calls). Needs Docker with Compose v2 (Docker Desktop is fine). No API keys or accounts:

git clone https://github.com/C4rohan/lampline && cd lampline
scripts/docker-up.sh --free          # everything on this computer: Ollama, Moonshine and Kokoro

--free runs the model (Qwen3 4B in Ollama) and speech (Moonshine listening, Kokoro speaking) on your own computer. The first start downloads about 3 GB and shows progress; after that it starts in seconds. Replies are slower and simpler than a cloud model's, and you can switch to any provider on the Integrations page whenever you like. On a Mac, the native route is faster, because Ollama uses the GPU outside Docker: install Ollama, then scripts/engine-up.sh --free.

Have API keys? Run scripts/docker-up.sh without --free. Either way it prints a link like http://localhost:7860/#/?key=…: open it once and the page remembers the key. Pick your model and voice on the Integrations page (or put keys like ANTHROPIC_API_KEY, GEMINI_API_KEY, DEEPGRAM_API_KEY in .env; see .env.example). Your agents are in ./agents (edit them, keep them in git) and everything else the engine keeps, settings with your keys, records, knowledge and downloaded models, is in ./.vpe-data. scripts/docker-up.sh --down stops it; --logs follows its log. Plain docker compose up -d --build works too once .env has VPE_DOCKER_API_KEY. Details: engine/README.md.

Prefer no Docker? scripts/engine-up.sh runs the engine natively (Python 3.11+) at http://localhost:7860, which also lets browser calls reach it directly. Free, private speech: Integrations → Whisper and Kokoro → Download models, or Moonshine for listening, which transcribes while the caller talks.

📋 Test any phone agent for free

Lampline's Evals tab phones a voice agent over a real phone line, plays the caller with an AI Test Caller, and grades the call against what should happen. It works on any agent with a phone number: one built in Lampline, Dialogflow CX, CX Agent Studio, Vapi, Retell, or your IVR.

A graded eval: the call's transcript, the agent's response time as the caller heard it, and each check passed
  • Free calls through Google Voice. The Lampline Phone Bridge extension (Chrome or Edge) connects the call's audio to the Test Caller inside the browser: no cables, Windows or Mac. Or use any phone on speaker.
  • Graded, with reasons. You write who is calling, what they want and what must happen; your model grades the transcript, check by check. A call that heard nothing shows Didn't run, never Failed.
  • Tough callers. Background noise, accents, interruptions, long pauses, hesitant or rambling speech.
  • The agent's speed, as callers hear it. Typical and p95 response time, phone line included.
  • Bring your test scripts. Paste Hammer, Cyara or spreadsheet tests and they become runnable cases. Replay any failed call.
  • Improve an agent from its failures. Lampline runs your test cases as text chats, rewrites the prompts of the steps where checks failed, and keeps a change only if more checks pass and nothing that passed breaks. You review the before and after, then apply.

How to run evals →

Only call agents you own or are allowed to test. You press Call yourself: Google Voice doesn't allow automated dialing.

🤖 Use it from Claude Code, Cursor or Codex

Lampline agents are plain files (agent.yaml and prompts/*.md), and vk lints and tests them from the terminal, so a coding agent can build, test and review a phone agent for you. Four skills teach it how:

Claude Code, from the plugin marketplace in this repo:

/plugin marketplace add C4rohan/lampline
/plugin install lampline@lampline

On Claude Code 2.1.275 or later, one line does both: /plugin install lampline --marketplace C4rohan/lampline.

Cursor, Codex and other agents read AGENTS.md. To copy the skills into a project instead, run vk skills install --target claude (or --target agents, --target gemini).

Claude Desktop, Cursor and other MCP clients: vk mcp serves your agent folders as tools: list, lint, run tests, read and change a step's prompt, and see which real calls failed their checks (set up).

Then ask, for example: "Build a phone agent for a dental office that books cleanings, with tests", "Make the failing tests in agents/front-desk pass", "Write regression tests for my Dialogflow CX agent", or "Review my change to agents/front-desk before it goes live".

🔁 Bring your Dialogflow CX and CX Agent Studio agents

Export an agent from Google's console, drop the .zip on New agent → Import, and it opens in the builder: flows, pages, forms, routes, playbooks and tools carried over, with a report of anything to check before it takes calls. It works the other way too: Export writes any agent back as a Dialogflow CX package or a CX Agent Studio app.

Importing a Dialogflow CX export: what came over, and what to review

📥 Import. A Dialogflow CX package or a CX Agent Studio app (JSON or YAML). The conversion runs on your computer and never runs code from the export.

The imported agent in the builder: flows, scripted pages and a playbook

✏️ Ready to edit. Pages become scripted pages, playbooks become LLM steps, flows group them, and webhooks and OpenAPI tools become tools.

From Dialogflow CX Becomes
Flows and pages Flows of scripted pages: entry messages said word for word
Form parameters, entity types Form fields with their types, choices and synonyms, patterns and keypad input
Intent and condition routes, no-match handlers Transfers the model decides, rules, and "no match" transfers
Playbooks LLM steps with their goal, guidelines and steps
Webhooks, OpenAPI tools, data store tools Tools (webhooks answer with a mock until connected) and local knowledge search
From CX Agent Studio Becomes
Root agent and child agents A root agent with sub-agents and transfers both ways
Global instruction, variables Global instructions and context variables
OpenAPI toolsets, Python tools, data stores HTTP tools, tools with example answers, and local knowledge search

From the terminal: vk import auto export.zip and vk export dfcx|ces agents/<name>. The full mapping, both ways, and what doesn't carry over yet: cli/README.md.

👀 A quick tour

A 25-second tour: the agent list, the builder with a transfer to a person, speech options in Integrations, and the Calls page with a call's details
Sample data only.

Test call: a chat with a scripted agent, the step it's on, and the details it collected

🧪 Test calls. Chat or talk through your microphone. The steps light up as the call moves, and every collected detail shows on the right.

Integrations: model providers as tiles, with the one in use highlighted

🧠 20 model providers. Pick one, paste a key, press Test connection. Speech runs in the cloud or free on your own computer.

Phone numbers and SIP, and contact centers marked coming soon

📞 Phone calls and SIP. Twilio, Telnyx, or your own SIP trunk, PBX or SBC through jambonz. Genesys, Avaya, Cisco and more are coming.

Data: an appointments collection with sample records

🗄️ Data of its own. Collections agents look up and save during calls, and document search over your FAQs, all on your machine.

Screenshots use the bundled sample agents and made-up data.

🏠 Where it runs

Status
Local and on-prem ✅ Available One Docker container, or the engine natively, on any machine you control
Google Cloud 🔜 Coming soon A one-command deployment to your own Google Cloud project

🧠 Models

Pick one on the Integrations page; each starts on a sensible default model you can change, and Test connection checks the key.

Provider Key
Claude (Anthropic) ANTHROPIC_API_KEY
OpenAI, or any OpenAI-compatible endpoint OPENAI_API_KEY, VPE_LLM_BASE_URL
Gemini GEMINI_API_KEY
Gemini on Vertex AI GOOGLE_CLOUD_PROJECT plus a service account key or this computer's Google credentials
Azure OpenAI AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT
Amazon Bedrock AWS keys, or this computer's AWS credentials
Groq, Mistral, DeepSeek, Grok (xAI), Together AI, Fireworks AI, OpenRouter, Cerebras, NVIDIA NIM, Qwen, SambaNova, Nebius, Novita AI each provider's API key
Ollama none: open models on this computer or your own server

📞 Phone calls and SIP

Twilio a Twilio number rings your agent; outbound calls from triggers
Telnyx the same, through a TeXML application
SIP through jambonz any SIP trunk, PBX or session border controller: point a jambonz application at the engine

The Phone numbers page has the webhook to copy and the steps for each. Details: engine/README.md.

🏢 Contact centers (coming soon)

Genesys Cloud, Avaya, Cisco Webex Contact Center, Cisco UCCE and PCCE, Amazon Connect, NICE CXone, Five9 and Twilio Flex show on the Integrations page as coming soon. Until each lands, most of them can already send calls to your agents over a SIP trunk through jambonz. The plan for each: docs/ROADMAP.md.

⚙️ How it works

flowchart LR
  you((You)) --> app[Lampline app<br/>builder, tests, integrations :7860]
  app --> engine[Engine<br/>Pipecat pipelines]
  phone((Callers)) --> carriers[Twilio · Telnyx ·<br/>SIP via jambonz]
  carriers --> engine
  engine --> agents[(agents/<br/>YAML + Markdown)]
  engine --> data[(Records and<br/>knowledge, SQLite)]
  engine --> models{{Model and speech<br/>cloud APIs or local<br/>Whisper · Moonshine · Parakeet · Kokoro · Qwen3-TTS · Ollama}}
  engine -- tools --> hooks[Your APIs and<br/>MCP servers]

The engine reads the agent folders on every call, so a change is live on the next call. Settings and keys live in a chmod 600 file outside the repo.

💰 What a voice-agent call actually costs

Monthly totals for 4-minute calls at list prices (October 2026). Staff time is not included. Reproduce or change any assumption with python3 costs/cost_model.py.

Deployment 10k calls/mo 50k calls/mo 200k calls/mo
CX Agent Studio (list price, baseline) $5,000 $25,000 $100,000
On-prem server (no GPU) + Google model APIs $1,384 $6,235 $24,426
On-prem GPU servers + self-hosted models $681 $1,363 $3,748
Cloud Run + Google model APIs (coming soon) $1,423 $6,356 $24,908
GKE production + mixed vendors: Deepgram, Claude Haiku, Fish Audio (coming soon) $1,105 $3,612 $13,037
GKE production + self-hosted models on L4 GPUs, 3-yr CUD (coming soon) $1,054 $1,675 $3,888

What the numbers say:

Every row, per-call figures and assumptions: costs/COSTS.md.

🧩 Agents as code (vk)

Build and change agents from a terminal or an AI coding agent as well as the builder. Each agent is a folder: agent.yaml for the graph and one Markdown file per prompt, so changes are reviewable in git.

pipx install lampline               # installs the `vk` command (from a clone: pip install -e cli)
vk templates install front-desk     # start from a ready-made agent
vk lint agents/front-desk           # graph checks + a scan for real-looking patient data
vk test agents/front-desk           # runs tests/*.yaml conversations on the engine
vk import dfcx export.zip           # bring an agent over from Dialogflow CX or CX Agent Studio
vk skills install --target claude   # the four coding-agent skills (or install the Claude Code plugin, above)

Details in cli/README.md. The engine itself, its builder, tools, data and knowledge: engine/README.md.

🗺️ Roadmap

The full list: docs/ROADMAP.md.

✅ Tested

CI runs on every push and pull request to dev, qa and prod:

Issues and PRs welcome (against dev; how dev, qa and prod work). See CONTRIBUTING.md, SECURITY.md, the code of conduct and the changelog.

🙌 Credit and citation

Lampline is created and maintained by Rohan Salvi. If you use it in a project, product, paper or talk, please credit "Lampline by Rohan Salvi" and link this repository. GitHub's Cite this repository button (from CITATION.cff) gives APA and BibTeX:

@software{salvi_lampline_2026,
  author  = {Salvi, Rohan},
  title   = {Lampline: open-source, self-hosted voice agents},
  year    = {2026},
  version = {0.3.0},
  url     = {https://github.com/C4rohan/lampline}
}

If you redistribute Lampline or build on it, the Apache-2.0 licence requires you to keep the NOTICE file, which carries this attribution.

📄 License

Apache-2.0. The engine uses Pipecat (BSD-2-Clause), installed from PyPI; other credits are in NOTICE. Not affiliated with Google or any provider named here. Prices are list-price estimates that change often; check them before budgeting.

Lampline (C4rohan/Lampline)

正在搜索数据库…

这是什么?Lampline 是一个开源平台,用于在你自己的电脑上构建、测试和运行 AI 电话智能体。它包括拖放式构建器、命令行工具(vk),以及免费的 AI Test Caller,后者会给你的智能体打电话并对通话进行评分。
这是一个框架,还是需要注册的托管服务?它是自托管软件:你可以通过 Docker 运行引擎和构建器界面,也可以直接用 Python 原生运行;每个智能体都是一个普通文件夹,里面是 YAML 和 Markdown 文件,你可以用 git 保存它们。
怎样才能让它运行起来?如果想完全在本地运行、无需注册账号,请执行 scripts/docker-up.sh --free(首次运行会下载约 3 GB 的本地模型);如果你已经有 API 密钥,则执行不带 --free 的 scripts/docker-up.sh。不使用 Docker 的原生方式是 scripts/engine-up.sh。
试用时需要 API 密钥或其他特殊软件吗?--free 模式不需要 API 密钥,所有功能都在本地运行。你只需要带 Compose v2 的 Docker(如果用原生方式运行,则需要 Python 3.11+)。Claude、OpenAI、Gemini 等服务的 API 密钥是可选的,之后可以在「集成」页面添加。
免费的无密钥模式有什么缺点?免费模式使用小型本地模型和本地语音,因此回复比云端服务商更慢,也更简单;之后你可以随时在「集成」页面切换到任何付费服务商。
AI Test Caller 能在任何电脑上使用吗?基于浏览器的 Phone Bridge 扩展(适用于 Chrome 或 Edge)无需任何线缆,就能在 Windows 或 Mac 上连接测试通话;引擎本身则可以通过 Docker 或原生方式,在 macOS、Linux 和 Windows 的任何机器上运行。
它会向外部回传信息,或把我的智能体数据发送到别处吗?不会。引擎没有遥测功能,只绑定到 localhost,每个请求都需要密钥,并且绝不会把你的模型密钥保存在智能体或代码仓库中。
我能导入现有的 Dialogflow CX 或 CX Agent Studio 智能体吗?可以。把导出的 .zip 文件拖到「新建代理 → 导入」中,智能体就会在构建器中打开,其中的流程、页面、表单和工具都会原样保留;你也可以把 Lampline 智能体导出回这两种格式中的任意一种。
AI Test Caller 到底是怎样测试我的智能体的?你先写明谁会打来电话以及必须发生什么,它会通过真实的电话通话(或聊天)扮演来电者,并逐项为通话记录打分。它还能改写未通过的提示词,并且只有在之前通过的项目都没有被破坏时,才会保留这次修改。
Claude Code、Cursor 和 Codex 的技能有什么用?共有四项技能(voice-agent-builder、voice-agent-fixer、dialogflow-tester、voice-agent-reviewer),可以让编程智能体构建带测试的智能体、修复失败的测试、对照其 Lampline 副本测试 Dialogflow 智能体,并在上线前审查改动。
电话呼叫是怎样接入智能体的?通过 Twilio 或 Telnyx 号码,或者通过 jambonz 连接的任何 SIP 中继、PBX 或会话边界控制器接入;Genesys、Avaya 等呼叫中心集成则列为即将推出。
作者
C4rohan
大小
11.8 MB
星标
494
时长
1个月
提交 · 90 天