personagent 1.1.0

A character for your group chats that knows when to stay quiet, and learns from being corrected.

English · 简体中文

personagent is a character for your group chats: pick one or write your own, and run it on any OpenAI-compatible model. It connects to QQ, WeChat, Telegram and Discord itself, and to KOOK, Feishu, DingTalk, Slack, WeCom, Mattermost and Misskey from the same page.

Start in a local browser chat: add one model key and say hello. When you want the character in a group, connect an app with a phone scan or one or two values.

Connect apps, in the same local page as setup and the character chat. Screenshot from a throwaway setup with a local test model.

Start here

Install it from PyPI and open it:

python -m pip install personagent
personagent

With uv, uvx personagent runs it without a separate install step.

The browser opens on a local page with three views: Chat, Connect apps and Character & settings. Paste your model API key and click Verify & start chatting; one small request checks it. There are 10 model service presets plus any other OpenAI-compatible one, and name and personality presets for the character. The Persona box holds persona.txt; saving it restarts the agent and keeps what it learned. Running personagent again reuses a page that is already open.

Want QQ? Open Connect apps, pick QQ and scan the code with mobile QQ: it creates a bot or picks one you already made, and personagent connects to QQ itself. Pasting the AppID and AppSecret is the fallback. Until the bot is certified, QQ lets it join only groups you own, and which group messages it receives is set in QQ.

On Windows you can also download the source ZIP and double-click start.bat; from a clone, run python quickstart.py. Python 3.10–3.14. See the short getting-started guide; terminal commands and connectors are in the full guide.

Why personagent

	It knows when to stay quiet. It answers when called. Otherwise a model judges whether a person would chime in: no dice roll. A burst of messages gets one reply, not one each.
	It learns from corrections that hold up. A change needs two agreeing reactions from the same chat, one of them strong. A troll or a bystander cannot retrain it. Every change is on record, and any of them can be rolled back.
	It is easy to start, and lives where your group is. Browser setup and chat in English or Chinese, with 11 model services and optional advanced settings. It joins QQ, WeChat, Telegram and Discord by itself and a dozen more apps from the same page; a local dashboard shows what it did.

• Each chat has its own memory.
• Editing the character keeps what it learned.
• It is measured: personagent eval scores when it speaks, whether it stays in character, and whether corrections stick (results).

Put it in your group

Use Connect apps in the local page. Credentials are checked before they are saved.

• Connected by personagent itself: QQ official bots (scan with mobile QQ), personal WeChat (scan with your phone; one-to-one chats only, since WeChat gives such bots no group messages), Telegram (a BotFather token) and Discord (a bot token, with Message Content Intent on).
• One or two values: KOOK, Feishu/Lark (long connection), DingTalk (Stream mode), Slack (Socket Mode; the guide link pre-fills the app), WeCom AI bot (long connection), Mattermost and Misskey.
• Advanced (needs a public address or other software): WeCom app, WeChat Official Account, QQ webhook, OneBot v11 and Satori.

The second and third groups run through an AstrBot that personagent downloads, with its own Python 3.12, and runs in the background: no dashboard, no second login.

Whatever the page or personagent up starts stops with it, however it ends, and anything a crashed run left behind is stopped at the next start. Everything you connected starts again the next time you open it.

From the terminal: personagent up runs the agent, the direct connections and the managed AstrBot together; init --terminal is the terminal setup; chat talks to the character in the terminal; demo shows it without a key; run starts the server alone; doctor checks the setup; learned reviews what it learned; eval measures it.

Third-party platforms

personagent also works with bridges you may already run. None of them is needed for QQ, WeChat, Telegram or Discord.

• AstrBot: for an AstrBot you already run, personagent connect astrbot installs the astrbot_plugin_personagent plugin, which hands AstrBot's messages to personagent. You can also install it from AstrBot's WebUI by that address and set its connector_token to personagent's CONNECTOR_TOKEN.
• NapCat, or another OneBot v11 implementation, under Advanced in Connect apps.
• Koishi, through the Satori connector.
• Matrix, and through mautrix bridges WhatsApp, Signal and more.

Setup for each is in the user guide and the deployment guide; the Chinese step-by-step guide covers QQ from zero.

How it compares

From each project's documentation, October 2026. "Not documented" means we found no description of it, not that it cannot be done; AstrBot's plugin market has learning plugins, one with a review queue and rollback.

Another project may fit better if you want a one-click desktop app with every setting in a WebUI (MaiBot, AstrBot), a large plugin ecosystem, or slang learning, sticker packs and image memory as headline features (MaiBot, AstrBot's plugins). personagent does not replace AstrBot or Koishi: it can run behind one you already have, so you keep its platforms and plugins and add a character that holds back and learns on the record.

Measured

personagent eval runs the real agent on labelled cases in English and Chinese and writes a report with every case and its verdict:

The reports, with every case, reply and verdict, are in docs/evals/2026-10-03. What "picked over a plain assistant" looks like, from the same run (same model, same message):

One run on one model is a sample, so expect some noise between runs; the persona and learning suites are scored by a judge that is a different model from the one being measured. The user guide explains each suite, the misses and how to run it yourself.

Documentation

• User guide (中文): install, setup, the terminal chat, connectors, teaching it, the dashboard, troubleshooting.
• Deployment guide: running it for real: connectors, QQ, exposing the endpoints, costs, and what to check when the bot goes quiet.
• 中文部署教程: QQ from zero, step by step.
• Connector protocol: one signed HTTP request per message, for writing your own connector.
• Tools: the scripts in tools/, for running from a clone.
• Changelog, including upgrading from 0.4.
• Contributing · Security policy · Disclaimer

Privacy

Everything personagent stores stays on your machine, in one home folder: .env with your keys, persona.txt, runtime/, and platforms/ with the managed AstrBot and the direct connections' credentials. The model provider you choose does see the conversations it answers. Before you connect it to real people, tell them it is a bot and get their consent; the guide lists exactly what goes where.

Status

1.1.0 is on PyPI, released 2026-10-15. QQ is the most exercised platform, through AstrBot in 1.0 and directly since 1.1. The WeChat, Telegram and Discord connections check credentials against the real services before saving and are otherwise tested against stand-ins; the Satori and Matrix connectors are tested against stand-ins. CI runs the tests on Linux with Python 3.10–3.14 and on Windows with Python 3.12, plus jobs that install the package and drive the command and the local page.

License

MIT © 2026 Qiankang (Kant) Wang.

Acknowledgements

• AstrBot, satori-python with Koishi, and matrix-nio with the mautrix bridges carry personagent onto chat platforms, and NapCat through OneBot v11.
• QQ, WeChat, Telegram and Discord are reached through their own documented APIs, WeChat as described in Tencent's openclaw-weixin protocol notes; websockets runs the QQ and Discord gateways python-qrcode draws the QQ and WeChat login codes, and cryptography opens the bot secret QQ returns sealed.
• Platform logos on the local page come from Simple Icons, SVG Logos, IconPark, MingCute and TDesign Icons, plus KOOK's and OneBot's own; each logo is its owner's trademark.
• FastAPI and httpx run the service and its model calls, and uv runs it with uvx personagent.
• Learning from reactions draws on Self-Feeding Chatbot, Alexa self-learning and BlenderBot 3x; the lorebook and output filters follow SillyTavern's World Info and regex extensions.