EchoBot keeps a Live2D character and a background agent in separate contexts

Why the character and the tool list are kept apart

EchoBot is a Python application for an anime style AI companion with Live2D support, and the README is written in Chinese with an English version alongside it. The interesting engineering is not the avatar, it is the routing.

The problem the project names is that a conventional AI agent has to load a large tool list and skill system, which naturally costs tokens and responds slowly, and that mixing character settings with task instructions causes persona dilution and badly hurts execution efficiency.

The answer is a three layer architecture called Decision, Roleplay and Agent.

The Decision layer is responsible for accurately and quickly judging user intent. It uses a hybrid approach of rules plus a lightweight LLM, described as a dual engine. Explicit instructions skip the large model and trigger a background task directly, while ambiguous intent is classified by the lightweight model. The routing then splits: everyday small talk goes to the Roleplay layer, and complex tasks silently wake the Agent Core while the Roleplay layer tells the user the task has started.

The Roleplay layer exists to provide emotional value and immersion. Its context is clean, with the tool-use and skills metadata stripped out, and it is optimised for text and voice generation so the tone stays vivid and replies stay fast without going out of character. It is also context aware, switching phrasing depending on the system state, such as chatting, a background task starting, or a task finishing.

The Agent Core runs quietly in the background and completes the assigned work, integrating tools, a skills library, and long and short term memory, with operating system and local file read and write permissions. When the task completes, the results are passed back and the character reports them to you personally.

The two workflows in the README show this in practice. For a morning greeting the Decision layer classifies it as chat and forwards it. For a request to write a Python scraper, a rule hit triggers two lines at once: the Roleplay layer replies immediately with an acknowledgement while the Agent Core silently calls a search tool, writes the code, tests it, and hands the result back for the character to deliver.

Getting it running: dependencies, .env and the web endpoint

The quick start is short. Python 3.11 or newer is recommended, and the dependencies install with:

pip install -r requirements.txt

The requirements file is organised into groups. The core group is fastapi, uvicorn, pydantic, loguru, PyYAML, Pillow and openai. The memory group pulls in agentscope and reme-ai, pinned at reme-ai[light]==0.3.1.8. The ASR and TTS group adds edge-tts and sherpa-onnx, and the gateway group adds qq-botpy for QQ and python-telegram-bot for Telegram. There is a commented out document processing block listing defusedxml, lxml, openpyxl, pdf2image, pdfplumber and pypdf, which is a useful signal that document handling is planned rather than wired in.

Configuration is a .env file copied from .env.example and filled in with your LLM provider details, in OpenAI compatible format:

LLM_API_KEY=your_api_key_here
LLM_MODEL=deepseek-chat
LLM_BASE_URL=https://api.deepseek.com/v1

The example file in the repository shows the wider configuration surface, and it is worth reading in full before you start. Alongside the LLM keys and base URL there are LLM_TIMEOUT and LLM_MAX_RETRIES, optional extra HTTP headers and an optional extra body merged into every request, a profile selector for hot switching providers from the web UI, ECHOBOT_LLM_SUPPORTS_IMAGE_INPUT which you disable if the model cannot see images, and the token and step budgets: ECHOBOT_LIGHTWEIGHT_MAX_TOKENS=4096 for the decision layer and short roleplay replies, and ECHOBOT_AGENT_MAX_STEPS=50 for the single turn agent tool and skill loop. There are also image and file upload budgets in bytes and pixels, and a flag for whether a short acknowledgement is sent before delegating to the background agent. The .env.example also carries a shell command safety mode setting with values including danger-full-access and a workspace restricted option.

Then the service starts with a single command that brings up both the chat platform gateway and the web interface:

python -m echobot app

And you open the browser at:

http://127.0.0.1:8000/web

Live2D models, backgrounds and the visual controls

The character and the scene are both user replaceable through the web control panel, and the mechanism is file based rather than config based.

A complete Live2D asset is a folder containing files such as .model3.json. The project ships with two Live2D assets built in, and you can upload or switch models from the panel. After an upload the application copies the uploaded folder into the .echobot/live2d directory, and you can also copy the asset folder there by hand, in which case the assistant loads it on the next start. Eye tracking with the mouse is on by default and can be turned off in the panel.

Background images work the same way, uploaded through the panel. Image upload and download are also supported, so you can send a picture to the assistant and it can send one back, for models with vision support. The README names qwen3.5-plus and kimi-k2.5 as examples of models that can do this, and points out the ECHOBOT_LLM_SUPPORTS_IMAGE_INPUT=false setting to reduce mistakes when the model has no vision input.

File upload and download go beyond images, so the assistant can handle documents as well.

The visual controls are unusually detailed. The panel exposes filter, lighting and particle effects, and holding Alt while clicking a slider restores its default. The documented parameter groups are switches for the global effect, background blur, light position effect, light position drift and air particles; rendering parameters including background blur from 0 to 16, hue from minus 180 to 180 degrees, saturation from 0 to 200 percent and contrast from 0 to 200 percent; lighting detail parameters for light position X and Y, glow intensity, vignette intensity and grain intensity; and a particle system with density, opacity, size and speed. It is a lot of surface for what is essentially a Live2D renderer, and it is the part of the project with no equivalent in a plain chat application.

Scheduled work, routing modes and the voice stack

Three subsystems make this more than a chat window, and each has its own configuration.

Scheduling has two mechanisms. Cron jobs trigger at a specific time, and you can create one conversationally, for example by asking the assistant to remind you of a meeting in half an hour, with the task data stored in .echobot/cron/jobs.json. Heartbeat jobs trigger at a fixed interval, defaulting to every 30 minutes, with the interval adjusted through ECHOBOT_HEARTBEAT_INTERVAL_SECONDS in the .env file, and the file itself editable from the web panel or by editing .echobot/HEARTBEAT.md in the project directory.

Routing mode lets you override the decision layer from the web interface. Automatic decision is the default, recognising intent and choosing whether to wake the background agent. Pure chat disables background tasks entirely to prevent accidental wakeups, which is the mode to use when you only want company. Forced agent skips intent recognition and sends every message down the background task path, turning the assistant into a plain productivity tool.

Voice is half duplex, and the README says the web interface pauses listening during playback to avoid echo. Two text to speech backends are built in: edge-tts, which is online, free and needs no API key, and kokoro-multi-lang-v1_1 for local offline synthesis, which downloads its weights on first use. Speech input uses a Sensevoice model built on sherpa-onnx, recognised locally and offline, with its weights downloaded on first start. The interface supports press to talk and an always-on microphone mode.

Both directions can also be replaced. EchoBot supports TTS and ASR endpoints that follow the OpenAI protocol, so the built in models can be swapped for your own local or cloud service. The example given is running Qwen3-TTS or Fish Speech S2 Pro locally through vLLM Omni Speech, configured with ECHOBOT_TTS_OPENAI_MODEL and ECHOBOT_TTS_OPENAI_BASE_URL, and for speech recognition a Qwen3-ASR deployment with ECHOBOT_ASR_OPENAI_MODEL and ECHOBOT_ASR_OPENAI_BASE_URL.

Where EchoBot is the wrong tool

Three limits, and the first one is the security model, which the README is upfront about.

The first is what the Agent Core is allowed to do. The README states that the agent core has operating system and local file read and write permissions, and the .env.example exposes a shell command safety mode with a danger-full-access option. If you point this at a machine with credentials on it, the agent core can read and write your files and run commands, with a persona layer sitting on top as the interface. That is a legitimate design for a personal companion you control, and it is a poor fit for a shared or hosted deployment. Anyone evaluating this needs to read what the safety mode actually restricts before leaving it at its default.

The second is that the whole system is local and single user. The web interface runs on 127.0.0.1, the cron jobs and heartbeat files live in a .echobot directory in the project, the Live2D assets are copied into that same directory, and the channels are your own QQ bot and Telegram bot. There is no documented multi-tenant model, no authentication layer described for the web interface, and no separation between users. Treating this as a service for other people is not what it was built for.

The third is that the routing is a heuristic, and the project acknowledges it by giving you the override. The decision layer is a rule engine plus a lightweight model, which is fast and cheap, and which will occasionally misclassify. Pure chat and forced agent exist precisely because the automatic mode is not always right, and a user of a system with a Live2D character watching them will notice a misclassification immediately in a way they might not notice in a plain chat interface.

The alternative approach, for comparison, is a general agent framework with a tool-calling loop and a plain interface, where every tool schema is in the context. The difference in approach is that EchoBot deliberately splits the context so the character never sees the tools, which is what makes the persona stable and the replies fast, and what makes the tool use harder to audit from the transcript. If your requirement is a reliable, reviewable automation of real tasks, a framework where the tool calls are visible in the log is easier to trust, and EchoBot is the wrong shape for it.

Editorial conclusion

Adopt EchoBot if you are building a personal assistant with a Live2D front end and you want the character conversation kept free of tool schemas and skills, because that separation is the whole design and the reason a casual reply stays fast. Do not adopt it as a general agent framework, since the package is oriented around a single character, a single local user and a specific set of channels, and it grants the agent operating system and local file permissions. Verify first that your language model endpoint is OpenAI compatible and reachable, that you are comfortable with the shell command safety mode setting in the .env file and with what it permits the agent to run, that the cron and heartbeat features write where the documentation says, in .echobot/cron/jobs.json and .echobot/HEARTBEAT.md, and that the last push on 2026-08-16 and the v1.0.3 release from 2026-04-15 reflect the version you actually clone.

Frequently asked questions

Official sources

1. Issues
2. KdaiP/EchoBot on GitHub
3. License: MIT
4. README
5. Releases