agentring README

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

agentring

Your AI agent can call you. When it needs a decision, hits a wall or finishes a long job, your phone rings like a real call, even locked and in Doze. A voice AI tells you what's going on, you talk it through, and the agent gets the transcript and carries on. You can also call your agents back from the app and ask them things by voice.

Open source, with no phone numbers, no Twilio and no per-minute telephony fees: calls go over VoIP straight to the app. Use the hosted version at agentring.io, or run everything on your own server.

Get it on Google Play Try it hosted, free

GitHub stars CI Android License: Apache-2.0

https://github.com/user-attachments/assets/4d925f22-727f-4d66-8665-c392cc3d1eb3

Sound on. A real run with Claude Code, a Pixel 6 and the voice AI: a migration fails, Claude Code calls the locked phone, you decide, it carries on. The phone is a screen recording with the call audio (the ringtone was added), the terminal is redrawn from Claude Code's output, and only the waits were cut. Silent version: demo.gif.

Try it in five minutes

With the hosted version there is no server, Firebase project or voice AI key to set up.

  1. Install the app from Google Play (Android 8 or newer).

  2. Sign in at agentring.io with your email (free plan, no card) and scan the QR code on your dashboard with the app. The phone is paired.

  3. Add the MCP server to your agent. The dashboard shows the command with your key:

    claude mcp add --transport http agentring https://agentring.io/mcp \
      --header "Authorization: Bearer ak_…"
    

Then ask your agent: "run the migration and call me if anything fails."

The free plan has 1 phone, 10 call minutes a month with the voice AI included, and 100 messages a day. Other agents (Codex, opencode, OpenClaw, Hermes, n8n): docs/agents.md. To run it all yourself instead, see Self-hosting.

What it does

Things people use it for: "run the migration and call me if anything fails", "ask me before you deploy", "what did CI say?" while driving, a daily call with your assistant about your inbox.

Works with your agent

agentring doesn't care which harness you use: anything that speaks MCP can reach you, and anything you can run as a command can be consulted from a call.

Reaches you You consult it from a call
Claude Code MCP claude -p
Codex MCP codex exec
opencode MCP opencode run
Grok Build MCP, or the plugin
OpenClaw MCP openclaw agent
Hermes MCP hermes -z
n8n, scripts, anything with HTTP REST API, CLI any command, or a small script for an HTTP agent

Copy-paste setup for each: docs/agents.md. OpenClaw and Hermes have one command for all of it: agentring connect openclaw / agentring connect hermes, or install the skill and ask your agent to set agentring up.

The skill installs in any harness that reads skills with npx skills add mutonby/agentring (skills.sh), and from ClawHub as @mutonby/agentring.

Self-hosting

Everything on your own machines, free and without limits. You need:

# 1. The relay, on a server with a domain (ports 80, 443, UDP 50000-50100 and TCP 7881 open)
cd deploy && cp .env.example .env && $EDITOR .env && docker compose up -d --build
#    ... or on your own computer, at its LAN or Tailscale IP
cd deploy && cp .env.local.example .env.local && $EDITOR .env.local \
  && docker compose -f docker-compose.local.yml --env-file .env.local up -d --build
docker compose logs relay | grep -A2 "API key"   # add the same -f/--env-file for the local one

# 2. The computer where your agent runs
uv tool install './daemon[voice]'
agentring init --relay https://relay.example.com --api-key ak_...
agentring pair                         # scan the QR code with the app
agentring msg "hello"                  # the phone gets a notification
echo GEMINI_API_KEY=... >> ~/.agentring/.env  # or OPENAI_API_KEY / XAI_API_KEY / PHONIC_API_KEY
agentring call "Testing agentring" --ai       # + --provider openai|grok|phonic

# 3. Your agent (Claude Code here; others: docs/agents.md)
claude mcp add agentring -- agentring mcp

Install the app from Google Play (recommended: it updates itself, and the same app works with agentring cloud and with your own relay). The APK on Releases is for those who'd rather not use Play; it's signed with a different key, so uninstall one before installing the other. The full tutorial, step by step for both options and with a troubleshooting table: docs/setup.md. If the phone doesn't ring when locked, it's usually the vendor's battery saver: docs/troubleshooting-oem.md.

How it works

 your agent ──MCP/CLI──▶ daemon ──WSS (outbound only)──▶ relay ──FCM push──▶ Android app
     ▲                     │                      (your server)                   │
     └── agents.yaml ◀── voice AI (realtime) ◀──────── LiveKit (call audio) ───────┘

The voice AI is the voice, your agent is the brain: a realtime speech model handles the conversation and hands real work to your agents. Pick the one you like:

Voice AI --provider Key
Gemini Live (default, free tier) gemini GEMINI_API_KEY
OpenAI Realtime openai OPENAI_API_KEY
Grok Voice (xAI) grok XAI_API_KEY
Phonic phonic PHONIC_API_KEY
OpenRouter: speech-to-text, any chat model, text-to-speech, experimental (details) openrouter OPENROUTER_API_KEY
Your own server, e.g. HF speech-to-speech + a small model on llama.cpp (experimental) local none

Set AGENTRING_VOICE_PROVIDER in ~/.agentring/.env to use one for every call, from the CLI and from MCP. How they compare (latency, tool use), how to measure them yourself (agentring voice bench), the local setup and how to add another one: docs/voice.md.

More: architecture · protocol · voice AI

Privacy and security

Self-hosted, everything runs on your own servers and accounts (for the hosted version, see its privacy policy). Messages and call metadata are stored on your relay. Push notifications go through your own Firebase project; they are signed, not encrypted, so Google's FCM can read pushed text. Call audio goes through your LiveKit server and, with the voice AI, to the provider you chose (Google, OpenAI, xAI or Phonic); on Google's free tier, Google may use that data to improve its products.

Over the phone, the voice AI acts on what it hears, so give it only the tools and agents you'd trust someone holding your phone with. Details and the threat model: SECURITY.md.

Limitations

Development

cd relay && npm ci && npm test                         # relay
cd daemon && uv run --extra voice pytest               # daemon (+ e2e against the relay build)
cd app-android && ./gradlew :core:test :app:assembleDebug

CI builds the APK and runs an end-to-end test on an Android emulator against a real relay. See CONTRIBUTING.md and docs/release.md.

License

Apache-2.0

agentring (mutonby/agentring)

正在搜索数据库…

这是什么?当你的 AI 代理需要你做决定、遇到问题或完成一项长时间任务时,它可以通过 VoIP 给你的手机打电话。即使手机锁屏,电话也会响起,语音 AI 会说明情况,并把通话记录返回给代理。你也可以在应用里直接呼叫你的代理。
这是应用、服务器还是库?它由三部分组成:部署在你服务器上的自托管中继服务(TypeScript,通话音频使用 LiveKit)、与代理一起运行的 Python 守护进程(包含 CLI 和 MCP 服务器),以及用于配对、通话和消息的 Kotlin Android 应用。
我该怎么把它跑起来?在带有域名的 Linux 服务器上用 Docker 运行中继服务;如果手机和你的电脑在同一网络中,也可以直接在自己的电脑上运行。创建一个免费的 Firebase 项目,安装 Android 应用,通过二维码完成配对,并把 MCP 服务器添加到你的代理中。不想自己托管?可以使用 agentring.io 上的托管版本。完整指南见 docs/setup.md。
开始之前需要准备什么?一台装有 Docker 并绑定了域名的 Linux 服务器,或一台装有 Docker 的自有电脑;一个免费的 Firebase 项目(它能让锁屏的手机响铃);一个语音 AI 的密钥(Gemini 有免费套餐,也可以选择 OpenAI、xAI 或 Phonic);以及一部 Android 手机。
有哪些需要注意的限制?目前仅支持 Android,暂不支持 iOS。Android Auto 处于测试版,只能通过 Releases 中的 APK 使用,Google Play 上没有。每个中继服务只能有一位用户,不支持账户。
它和通过 Twilio 打电话有什么不同?它完全不需要电话号码和电信服务商。通话通过 VoIP 从你自己的 LiveKit 服务器直接发送到你的手机,因此没有按分钟计费的运营商费用。
我能主动呼叫代理,而不是等它打给我吗?可以。在应用中点击 'Call agent',然后用语音与它对话。通话过程中,语音 AI 可以向你的代理请求帮助;如果某个代理响应较慢,而你已经挂断电话,它的回答会稍后以消息的形式送达。
如果我错过了来电会怎样?未接来电会变成一条消息,你可以直接在通知栏里回复,不会错过任何内容。
我到底会拿它来做什么?比如「运行迁移,如果有任何失败就打电话给我」、「部署前先问我」,或者每天与你的助手通话,聊聊你的收件箱。
作者
mutonby
大小
3.2 MB
星标
449
时长
26天
提交 · 90 天