qd-evolve 0.1.0

Multi-agent AI framework with A2A protocol support, group chat, persistent memory, and extensible tool system

QD-Evolve

Multi-agent AI framework with A2A protocol support, group chat, persistent memory, and extensible tool system.

• DESIGN.md — design philosophy, invariants, architecture, implementation

Installation

Prerequisites

• Python 3.13+ — required by requires-python
• uv — packaging tool used for dependency management. Install with:

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

  Or on macOS/Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Mosquitto v5 broker (MQTT/GChat mode only) — download

Setup

# 1. Clone the repository
git clone https://github.com/juzcn/qd-evolve
cd qd-evolve

# 2. Create virtual environment and install all dependencies
uv sync

# Optional: install BOAT bridge extras
uv sync --extra boat

# 3. Configure
#    Copy and edit the example below, or start from scratch.
#    Edit config.json with your API keys and models.

Configuration

Minimal config.json for single-agent chat:

{
  "default_provider": "openai",
  "default_model": "gpt-4o",
  "max_iterations": 20,
  "tool_output_limit": 8000,
  "providers": [
    {
      "name": "openai",
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1",
      "api": "openai-completions",
      "models": [
        { "name": "gpt-4o", "context_window": 128000, "max_tokens": 4096 }
      ]
    }
  ]
}

See Configuration below for full multi-agent, MQTT, and toolbox setup.

Verify

# Start single-agent chat — should see the prompt
qd-evolve

Quick Start

# Single-agent chat
qd-evolve

# Multi-agent A2A chat
qd-evolve a2a

# Run an agent as standalone A2A HTTP server
qd-evolve a2a serve --agent <name>

# Multi-agent MQTT chat (requires Mosquitto v5 broker)
qd-evolve mqtt

# Run an agent as MQTT-accessible server
qd-evolve mqtt serve --agent <name>

# Group chat — WeChat-style multi-agent group (requires Mosquitto v5 broker)
# Supports: AI agents, terminal human agents, WeChat human agents
qd-evolve gchat --agent <name>

# Manage tool enable/disable/preload
qd-evolve toolbox --agent <name>

# Browse and search conversation memories
qd-evolve memory --agent <name>

Four Systems

System	Entry	Transport	Use Case
Chat	qd-evolve	In-process only	Single-agent, no network
A2A	qd-evolve a2a	HTTP + in-proc	Multi-agent over HTTP/SSE
MQTT	qd-evolve mqtt	MQTT v5 + in-proc	Multi-agent over MQTT
GChat	qd-evolve gchat	MQTT v5 (group topics)	WeChat-style group chat

Each system is fully independent — no protocol fallback between them. See DESIGN.md for the full architecture.

Configuration

All configuration via config.json. No CLI config commands, no .env files.

Provider & Model

{
  "default_provider": "openai",
  "default_model": "gpt-4o",
  "providers": {
    "openai": {
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1",
      "api": "openai-completions",
      "models": {
        "gpt-4o": { "context_window": 128000, "cost": { "input": 2.5, "output": 10 } }
      }
    },
    "anthropic": {
      "api_key": "sk-ant-...",
      "api": "anthropic",
      "models": { "claude-sonnet-4-6": { "context_window": 200000 } }
    },
    "deepseek": {
      "api_key": "...",
      "base_url": "https://api.deepseek.com/v1",
      "api": "openai-completions",
      "models": { "deepseek-r1": { "reasoning": true } }
    }
  }
}

Three API types: openai-completions, openai-response, anthropic. Set at provider level via api field. Streaming is global (stream field). Reasoning/thinking is per-model (reasoning: true). Per-model cost tracking via ModelCost.

Multi-Agent

{
  "agents_config": {
    "chat_agent": "planner",
    "agents": [
      {
        "name": "planner",
        "description": "Plans and delegates tasks",
        "provider": "openai",
        "model": "gpt-4o",
        "memory_db": "planner.db",
        "server": { "host": "127.0.0.1", "port": 8001 },
        "toolbox": { "tools": {}, "bridge": { "oat:boat": "enabled" } }
      },
      {
        "name": "human",
        "description": "Human for approvals",
        "provider": "human",
        "server": { "host": "127.0.0.1", "port": 8002 }
      },
      {
        "name": "wechat_user",
        "description": "Human via WeChat iLink",
        "provider": "wechat-human",
        "server": { "host": "127.0.0.1", "port": 8003 }
      }
    ],
    "topology": { "relations": [] }
  }
}

Per-agent provider/model with global fallback. provider: "human" for terminal human agents, "wechat-human" for WeChat iLink bridge. Each agent has its own memory DB, server config, and toolbox state. WeChat human agents persist their session token via the wechat_session field.

MQTT Broker

{
  "agents_config": {
    "mqtt_broker": {
      "host": "127.0.0.1",
      "port": 1883,
      "will_delay_interval": 5
    }
  }
}

Requires external Mosquitto v5 broker. Per-agent credentials via MqttConfig on each AgentEntry.

Toolbox

Tool enable/disable/preload per agent, managed via qd-evolve toolbox --agent <name> (Textual TUI) or by editing config.json directly.

{
  "agents_config": {
    "agents": [{
      "name": "planner",
      "toolbox": {
        "tools": { "run_shell": "preloaded", "web_search": "enabled" },
        "mcp_servers": { "filesystem": "disabled" },
        "bridge": { "oat:boat": "enabled", "oat:coat": "disabled" },
        "cli": { "git": "preloaded" },
        "skills": { "code-review": "preloaded" }
      }
    }]
  }
}

Three states: enabled (on-demand schema), preload (schema at startup), disabled (invisible to agent).

Runtime Features

Slash Commands

Command	Description
/models	Switch provider/model
/agents	Switch agent
/tools	List tools
/load <tool>	Load tool schema
/memory	List saved memories with full content
/compress	Force context compression
/clear	Clear conversation
/help	Show help
/quit	Exit

Heartbeat

Agent-managed idle detection. When no activity for heartbeat_idle_seconds, sends a heartbeat prompt to the LLM. If LLM responds with ".", stays silent. Set 0 to disable. Mode-specific templates selected automatically.

Replay Mode

--replay <file> feeds pre-recorded inputs for automated testing. --output <file> captures output.

Token Stats

Per-turn and cumulative input/output tokens with context window usage percentage.

A2A Protocol

Full A2A v1.0 implementation:

• Agent discovery: /.well-known/agent.json
• Methods: message/send, message/stream, tasks/get, tasks/cancel, tasks/resubscribe, tasks/pushNotification, agent/getExtendedAgentCard
• Task lifecycle: submitted → working → completed / failed / canceled / input_required
• SSE streaming: message/stream returns StreamResponse events
• Push notifications: webhook callbacks on task completion

Group Chat

WeChat-style multi-agent group via MQTT. All configured agents form a single group.

• AI agents: Background loop processes @mentions, runs agent in parallel, publishes responses
• Terminal human agents (provider: "human"): Interactive prompt — type messages, see group activity
• WeChat human agents (provider: "wechat-human"): Bidirectional WeChat iLink bridge — long-poll for incoming WeChat messages, forward group responses back to WeChat. QR login on startup, session persisted to config.json
• @all mentions everyone; specific @agent_name directs to one agent

Project Layout

qd-evolve/
├── qd_evolve/       # Main package (agent, core, tools, utils, _templates)
├── tools/           # User tools (func, cli, skills, mcp, bridge)
├── templates/       # User Jinja2 template overrides
├── tests/           # pytest suite
├── config.json      # All configuration
├── memory.db        # Conversation memory (SQLite + sqlite-vec)
└── pyproject.toml   # Dependencies and build config

See DESIGN.md for architecture and full module map.

Requirements

• Python 3.13+
• uv for dependency management
• External Mosquitto v5 broker (MQTT/GChat mode only)
• API keys for configured providers

License

MIT