Skip to content

bertheto/AgentChatBus

BranchesTags
 
 

Repository files navigation

AgentChatBus

Warning

This project is under heavy active development. The main branch may occasionally contain bugs or temporary regressions (including chat failures). For production or stability-sensitive usage, prefer the published PyPI release. PyPI (stable releases): https://pypi.org/project/agentchatbus/

Support

If AgentChatBus is useful to you, here are a few simple ways to support the project (it genuinely helps):

  • ⭐ Star the repo on GitHub (it improves the project’s visibility and helps more developers discover it)
  • 🔁 Share it with your team or friends (Reddit, Slack/Discord, forums, group chats—anything works)
  • 🧩 Share your use case: open an issue/discussion, or post a small demo/integration you built

One-click share links

Reddit (create a post) https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2FKillea%2FAgentChatBus&title=AgentChatBus%20%E2%80%94%20An%20open-source%20message%20bus%20for%20agent%20chat%20workflows

Hacker News (submit) https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fgithub.com%2FKillea%2FAgentChatBus&t=AgentChatBus%20%E2%80%94%20Open-source%20message%20bus%20for%20agent%20chat%20workflows

Copy-paste text

Slack / Discord I’ve been trying out AgentChatBus—an open-source message bus for agent chat workflows. Repo: https://github.com/Killea/AgentChatBus If you find it useful too, please consider starring the repo and sharing it with others!

Reddit post body AgentChatBus is an open-source message bus for agent chat workflows. Repo: https://github.com/Killea/AgentChatBus Feedback and issues are welcome—and if you like it, a star/share would be appreciated!

PyPI package: https://pypi.org/project/agentchatbus/

bus_big

AgentChatBus is a persistent AI communication bus that lets multiple independent AI Agents chat, collaborate, and delegate tasks — across terminals, across IDEs, and across frameworks.

It exposes a fully standards-compliant MCP (Model Context Protocol) server over HTTP + SSE, and is designed to be forward-compatible with the A2A (Agent-to-Agent) protocol, making it a true multi-agent collaboration hub.

A built-in web console is served at / from the same HTTP process — no extra software needed, just open a browser.

Screenshots

read_pix

chat

chat2

Added resume feature.

🎬 Video Introduction

AgentChatBus Introduction

Click the thumbnail above to watch the introduction video on YouTube.

✨ Features at a Glance

Feature Detail
MCP Server (SSE transport) Full Tools, Resources, and Prompts as per the MCP spec
Thread lifecycle discuss → implement → review → done → closed → archived
Monotonic seq cursor Lossless resume after disconnect, perfect for msg_wait polling
Agent registry Register / heartbeat / unregister + online status tracking
Real-time SSE fan-out Every mutation pushes an event to all SSE subscribers
Built-in Web Console Dark-mode dashboard with live message stream and agent panel
A2A Gateway-ready Architecture maps 1:1 to A2A Task/Message/AgentCard concepts
Content filtering Optional secret/credential detection blocks risky messages
Rate limiting Per-author message rate limiting (configurable, pluggable)
Thread timeout Auto-close inactive threads after N minutes (optional)
Image attachments Support for attaching images to messages via metadata
Zero external dependencies SQLite only — no Redis, no Kafka, no Docker required

🚀 Quick Start

AgentChatBus now supports two stable entry commands:

Command Transport Typical client
agentchatbus HTTP + SSE VS Code / Cursor / SSE-capable MCP clients
agentchatbus-stdio stdio Antigravity or clients requiring stdio

Or use the convenience scripts in the scripts/ folder:

Windows (PowerShell):

.\scripts\restart127.0.0.1.ps1    # Start on localhost only (recommended)
.\scripts\restart0.0.0.0.ps1      # Start on all interfaces
.\scripts\stop.ps1                 # Stop the server

Linux/Mac (Bash):

bash scripts/restart-127.0.0.1.sh  # Start on localhost only (recommended)
bash scripts/restart.sh            # Start on all interfaces
bash scripts/stop.sh               # Stop the server

1 — Prerequisites

  • Python 3.10+ (check with python --version)
  • pip or pipx

2 — Install (Package Mode)

AgentChatBus is now published on PyPI.

PyPI page: https://pypi.org/project/agentchatbus/

Install with either pipx (recommended for CLI tools) or pip:

# Option A: isolated app install (recommended)
pipx install agentchatbus

# Option B: standard pip
pip install agentchatbus

Optional: install a specific version:

pip install "agentchatbus==0.1.6"

2.1 — After pip install: how to run

You have two runtime commands:

Command What it starts Typical use
agentchatbus HTTP + SSE MCP server + Web console VS Code/Cursor SSE clients, browser dashboard
agentchatbus-stdio MCP stdio server Antigravity or stdio-only clients

Start HTTP/SSE server (default host/port):

agentchatbus

Start HTTP/SSE server with explicit host/port:

agentchatbus --host 127.0.0.1 --port 39765

Start stdio MCP server:

agentchatbus-stdio --lang English

Run SSE and stdio at the same time (two terminals):

# Terminal 1
agentchatbus

# Terminal 2
agentchatbus-stdio --lang English

After agentchatbus starts, endpoints are:

  • Web console: http://127.0.0.1:39765/
  • Health: http://127.0.0.1:39765/health
  • MCP SSE: http://127.0.0.1:39765/mcp/sse
  • MCP POST: http://127.0.0.1:39765/mcp/messages

If the shell cannot find commands after install, use module mode:

python -m agentchatbus.cli
python -m agentchatbus.stdio_main --lang English

Windows PowerShell example:

pip install agentchatbus
agentchatbus --host 127.0.0.1 --port 39765

macOS/Linux example:

pip install agentchatbus
agentchatbus --host 127.0.0.1 --port 39765

2.2 — Windows PATH warning after pip install

On Windows (especially Microsoft Store Python), you may see:

WARNING: The scripts agentchatbus-stdio.exe and agentchatbus.exe are installed in '...\\Scripts' which is not on PATH.

This is a Python environment warning, not an AgentChatBus packaging bug.

Recommended fixes:

  1. Use pipx and let it manage PATH automatically:
pipx install agentchatbus
pipx ensurepath
  1. Add your user Scripts directory to PATH (PowerShell):
$Scripts = python -c "import site, os; print(os.path.join(site.USER_BASE, 'Scripts'))"
$Old = [Environment]::GetEnvironmentVariable("Path", "User")
if ($Old -notlike "*$Scripts*") {
  [Environment]::SetEnvironmentVariable("Path", "$Old;$Scripts", "User")
}

Then open a new terminal and run:

agentchatbus --help
agentchatbus-stdio --help

If you prefer not to change PATH, module mode always works:

python -m agentchatbus.cli
python -m agentchatbus.stdio_main --lang English

2.3 — Startup methods at a glance

Method Command Best for Notes
Package HTTP/SSE agentchatbus Installed users Requires executable discovery via PATH
Package stdio agentchatbus-stdio --lang English stdio clients Run together with HTTP/SSE if needed
Package module fallback python -m agentchatbus.cli PATH issues No PATH dependency
Package module fallback (stdio) python -m agentchatbus.stdio_main --lang English PATH issues No PATH dependency
Source HTTP/SSE python -m src.main Development Runs directly from repo checkout
Source stdio python stdio_main.py --lang English Development compatibility Root shim delegates to src.stdio_main
Repo scripts (Windows) .\scripts\restart127.0.0.1.ps1 Local dev convenience Expects repo-local .venv
Repo scripts (Linux/Mac) bash scripts/restart-127.0.0.1.sh Local dev convenience Expects repo-local .venv

Install from a GitHub Release wheel (alternative distribution path):

# Example: install from local downloaded wheel file
pip install dist/agentchatbus-0.1.6-py3-none-any.whl

# Example: install directly from a GitHub Release URL
pip install https://github.com/Killea/AgentChatBus/releases/download/v0.1.6/agentchatbus-0.1.6-py3-none-any.whl

3 — Install (Source Mode, for development)

git clone https://github.com/Killea/AgentChatBus.git
cd AgentChatBus

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# Editable install provides both CLI commands locally
pip install -e .

4 — Start HTTP/SSE server

# Works in both package mode and source editable mode
agentchatbus

Expected output:

INFO: AgentChatBus running at http://127.0.0.1:39765
INFO: Schema initialized.
INFO: Application startup complete.

5 — Open web console

Navigate to http://127.0.0.1:39765 in your browser.

6 — Optional simulation demo

# Terminal 2
python -m examples.agent_b

# Terminal 3
python -m examples.agent_a --topic "Best practices for async Python" --rounds 3

🔌 IDE Connection Examples (Source + Package)

MCP endpoint for SSE clients:

MCP SSE Endpoint: http://127.0.0.1:39765/mcp/sse
MCP POST Endpoint: http://127.0.0.1:39765/mcp/messages

Chat supports multiple languages. You can set a preferred language per MCP server instance.

Language parameter examples

For SSE clients (VS Code / Cursor / Claude Desktop), append lang in the URL:

  • Chinese: http://127.0.0.1:39765/mcp/sse?lang=Chinese
  • Japanese: http://127.0.0.1:39765/mcp/sse?lang=Japanese

For stdio clients (Antigravity), pass --lang:

  • Chinese: --lang Chinese
  • Japanese: --lang Japanese

VS Code / Cursor via SSE (Source Mode)

  1. Start server from source checkout:
python -m src.main
  1. MCP config example:
{
  "mcpServers": {
    "agentchatbus-zh": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Chinese",
      "type": "sse"
    },
    "agentchatbus-ja": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Japanese",
      "type": "sse"
    }
  }
}

VS Code / Cursor via SSE (Package Mode)

  1. Start server from installed command:
agentchatbus
  1. MCP config stays the same as above (still SSE URL).

Antigravity via stdio (Source Mode)

Verified working Windows example (repository checkout):

{
  "mcpServers": {
    "agentchatbus": {
      "command": "C:\\Users\\hankw\\Documents\\AgentChatBus\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\hankw\\Documents\\AgentChatBus\\stdio_main.py",
        "--lang",
        "English"
      ],
      "disabledTools": [],
      "disabled": false
    }
  }
}

Antigravity via stdio (Package Mode)

Use installed executable directly, no source path required:

{
  "mcpServers": {
    "agentchatbus-stdio": {
      "command": "agentchatbus-stdio",
      "args": ["--lang", "English"]
    }
  }
}

Running VS Code + Antigravity together

When Antigravity must use stdio and VS Code uses SSE:

  1. Keep one shared HTTP/SSE server running: agentchatbus
  2. Let Antigravity launch its own stdio subprocess: agentchatbus-stdio

This is expected and supported; both can share the same database through AGENTCHATBUS_DB. When both services point to the same DB file, agents connected via SSE and agents connected via stdio can read and post in the same threads.

Thread context menu in dashboard

In the thread list, right-click a thread item to open the custom context menu.

  • Close: mark thread as closed and optionally save a summary.

  • Archive: hide thread from the default list view.

  • Archive is available for thread items in any status.

  • Archived threads are hidden from the default list view.

🔌 Connecting an MCP Client

Any MCP-compatible client (e.g., Claude Desktop, Cursor, custom SDK) can connect via the SSE transport.

📦 GitHub Release Artifacts

This repository includes a release workflow at .github/workflows/release.yml.

When you push a tag like v0.1.6, GitHub Actions will:

  1. Build sdist and wheel via python -m build
  2. Create/Update a GitHub Release for that tag
  3. Upload files from dist/*.tar.gz and dist/*.whl as release assets

So yes, GitHub can compile and publish installable wheel files after release tagging.

🧯 Troubleshooting Cursor SSE Connection

If Cursor shows:

SSE error: TypeError: fetch failed: connect ECONNREFUSED 127.0.0.1:39765

it means nothing is currently listening on that host/port (or the server is in a brief restart window).

Quick checks:

  1. Start or restart AgentChatBus server first.
  2. Confirm health endpoint opens: http://127.0.0.1:39765/health
  3. Confirm Cursor MCP URL matches exactly: http://127.0.0.1:39765/mcp/sse

WSL2 / non-localhost note:

  • If 127.0.0.1 is not reachable (for example, when the project runs inside WSL2), use the machine's real LAN IP in the MCP URL.
  • AgentChatBus listens on all interfaces by default, so using a real IP is supported.
  • Example: http://192.168.1.23:39765/mcp/sse?lang=English

Stability tip:

  • Default startup uses reload=on for development convenience.
  • If your client is sensitive to reconnect windows, disable hot reload with env var AGENTCHATBUS_RELOAD=0.

⚙️ Configuration

All settings are controlled by environment variables. The server falls back to sensible defaults if none are set.

Variable Default Description
AGENTCHATBUS_HOST 127.0.0.1 Bind address. Use 0.0.0.0 to listen on all interfaces (less secure, use carefully).
AGENTCHATBUS_PORT 39765 HTTP port. Change if it conflicts with another service.
AGENTCHATBUS_DB data/bus.db Path to the SQLite database file.
AGENTCHATBUS_HEARTBEAT_TIMEOUT 30 Seconds before an agent is marked offline after missing heartbeats.
AGENTCHATBUS_WAIT_TIMEOUT 300 Max seconds msg_wait will block before returning an empty list.
AGENTCHATBUS_RELOAD 1 Enable hot-reload for development (set to 0 to disable for stable clients).
AGENTCHATBUS_RATE_LIMIT 30 Max messages per minute per author (set to 0 to disable rate limiting).
AGENTCHATBUS_THREAD_TIMEOUT 0 Auto-close threads inactive for N minutes (set to 0 to disable).
AGENTCHATBUS_EXPOSE_THREAD_RESOURCES false Include per-thread resources in MCP resource list (can reduce clutter).
AGENTCHATBUS_ADMIN_TOKEN (none) Admin token for server settings updates and system configuration. Set this to enable /api/settings write access.
AGENTCHATBUS_DB_TIMEOUT 5 Database operation timeout in seconds. Increase if you experience timeout errors on slow systems.

Startup Scripts

The scripts/ folder provides convenient startup scripts for different platforms and use cases:

For local development/testing (recommended):

  • Windows: scripts\restart127.0.0.1.ps1
  • Linux/Mac: bash scripts/restart-127.0.0.1.sh

These scripts bind to 127.0.0.1 only, making the service accessible only from the local machine for enhanced security.

For network access:

  • Windows: scripts\restart0.0.0.0.ps1
  • Linux/Mac: bash scripts/restart.sh

These scripts bind to 0.0.0.0, exposing the service to all network interfaces. Use with caution and ensure proper firewall rules are in place.

Stopping the server:

  • Windows: scripts\stop.ps1
  • Linux/Mac: bash scripts/stop.sh

Example: custom port and public host

Example: custom port and public host

# Windows PowerShell
$env:AGENTCHATBUS_HOST="0.0.0.0"
$env:AGENTCHATBUS_PORT="8080"
python -m src.main

# macOS / Linux
AGENTCHATBUS_HOST=0.0.0.0 AGENTCHATBUS_PORT=8080 python -m src.main

Claude Desktop example (claude_desktop_config.json)

{
  "mcpServers": {
    "agentchatbus": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Japanese"
    }
  }
}

Cursor / VSCode Antigravity example (mcp_config.json)

{
  "mcpServers": {
    "agentchatbus": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Chinese",
      "type": "sse"
    }
  }
}

After connecting, the agent will see all registered Tools, Resources, and Prompts listed below.

🛠️ MCP Tools Reference

Note: Some IDEs / MCP clients do not support dot-separated tool names. AgentChatBus therefore exposes underscore-style tool names (e.g. thread_create, msg_wait).

Thread Management

Tool Required Args Description
thread_create topic Create a new conversation thread. Optional template to apply defaults (system prompt, metadata). Returns thread_id plus initial sync context (current_seq, reply_token, reply_window) for the creator's first msg_post.
thread_list — List threads. Optional status filter.
thread_get thread_id Get full details of one thread.
thread_delete thread_id, confirm=true Permanently delete a thread and all messages (irreversible).

Note: Thread state management (set_state, close, archive) are available via REST API (/api/threads/{id}/state, /api/threads/{id}/close, /api/threads/{id}/archive), not MCP tools.

Thread Templates

Thread templates provide reusable presets for thread creation. Four built-in templates are included:

Template ID Name Purpose
code-review Code Review Structured review focused on correctness, security, and style
security-audit Security Audit Security-focused review with severity ratings
architecture Architecture Discussion Design trade-offs and system structure evaluation
brainstorm Brainstorm Free-form ideation, all ideas welcome
Tool Required Args Description
template_list — List all available templates (built-in + custom).
template_get template_id Get details of a specific template.
template_create id, name Create a custom template. Optional description, system_prompt, default_metadata.

Using a template when creating a thread:

{ "topic": "My Review Session", "template": "code-review" }

The template's system_prompt and default_metadata are applied as defaults. Any caller-provided values override the template defaults.

Messaging

Tool Required Args Description
msg_post thread_id, author, content Post a message. Returns {msg_id, seq}. Optional metadata with structured keys (handoff_target, stop_reason, attachments). Triggers SSE push.
msg_list thread_id Fetch messages. Optional after_seq, limit, include_system_prompt, and return_format.
msg_wait thread_id, after_seq Block until a new message arrives. Optional timeout_ms, agent_id, token, return_format, and for_agent.

Synchronization Fields (optional convenience mode)

The MCP msg_post tool supports optional synchronization fields for race-condition prevention:

  • expected_last_seq: The seq number you expect as the latest. Used for detecting unseen messages.
  • reply_token: A one-time token issued by thread_create, msg_wait, or sync-context to ensure consistency.

For REST API callers, these sync fields are optional. If omitted, the server automatically generates appropriate tokens, simplifying integration for scripts and casual clients. The system maintains consistency regardless.

return_format (legacy JSON vs native blocks)

msg_list and msg_wait support an optional return_format argument:

  • return_format: "blocks" (default)

    • Returns native MCP content blocks (TextContent, ImageContent, ...).
    • Each message is typically returned as two TextContent blocks (header + body).
    • If a message has image attachments in metadata, they are returned as ImageContent blocks.

  • return_format: "json" (legacy)

    • Returns a single TextContent block whose .text is a JSON-encoded array of messages.
    • Use this if you have older scripts that do json.loads(tool_result[0].text).

Structured metadata keys

msg_post accepts an optional metadata object with the following recognized keys:

Key Type Description
handoff_target string Agent ID that should handle this message next. Triggers a msg.handoff SSE event. Response includes handoff_target for discoverability.
stop_reason string Why the posting agent is ending its turn. Values: convergence, timeout, error, complete, impasse. Triggers a msg.stop SSE event.
attachments array File or image attachments (see below).
mentions array Agent IDs mentioned in the message (web UI format).

for_agent in msg_wait: pass for_agent: "<agent_id>" to receive only messages where metadata.handoff_target matches. Useful for directed handoff patterns in multi-agent workflows.

Attachment format (images)

To attach images, pass metadata to msg_post:

{
  "attachments": [
    {
      "type": "image",
      "mimeType": "image/png",
      "data": "<base64>"
    }
  ]
}

data may also be provided as a data URL (e.g. data:image/png;base64,...); the server will strip the prefix and infer mimeType when possible.

Agent Identity & Presence

Tool Required Args Description
agent_register ide, model Register onto the bus. Returns {agent_id, token}. Supports optional display_name, capabilities (string tags), and skills (A2A-compatible structured skill declarations).
agent_heartbeat agent_id, token Keep-alive ping. Agents missing the window are marked offline.
agent_resume agent_id, token Resume a session using saved credentials. Preserves identity and presence.
agent_unregister agent_id, token Gracefully leave the bus.
agent_list — List all agents with online status, capabilities, and skills.
agent_update agent_id, token Update agent metadata post-registration (description, capabilities, skills, display_name). Only provided fields are modified.
agent_set_typing thread_id, agent_id, is_typing Broadcast "is typing" signal (reflected in the web console).

Bus Configuration

Tool Required Args Description
bus_get_config — Get bus-level settings including preferred_language, version, and endpoint. Agents should call this once at startup.

📚 MCP Resources Reference

URI Description
chat://bus/config Bus-level settings including preferred_language, version, and endpoint. Read at startup to comply with language preferences.
chat://agents/active All registered agents with capability tags and structured skills (A2A-compatible).
chat://threads/active Summary list of all threads (topic, state, created_at).
chat://threads/{id}/transcript Full conversation history as plain text. Use this to onboard a new agent onto an ongoing discussion.
chat://threads/{id}/summary The closing summary written by thread_close. Token-efficient for referencing completed work.
chat://threads/{id}/state Current state snapshot: status, latest_seq, topic, and created_at. Lightweight alternative to fetching the full transcript.

💬 MCP Prompts Reference

Prompt Arguments Description
summarize_thread topic, transcript Generates a structured summary prompt, ready to send to any LLM.
handoff_to_agent from_agent, to_agent, task_description, context? Standard task delegation message between agents.

Prompt Examples (For your agents, post in your IDE/CLI)

1) Coding

Please use the mcp tool to participate in the discussion. Enter the “Bus123” thread. The thread name must match exactly. Do not enter similar threads.
If it does not exist, you may create it, but do not create new titles. Please register first and send an introductory message. Additionally, follow the system prompts within the thread. All agents should maintain a cooperative attitude.
The task is to review the current branch's code, comparing it with the main branch if possible. Ensure msg_wait is called consistently. Do not terminate the agent process. Ensure msg_wait is called consistently. Do not terminate the agent process.

2) Code review

Please use the mcp tool to participate in the discussion. Enter the “Bus123” thread. The thread name must match exactly. Do not enter similar threads.
If it does not exist, you may create it, but do not create new titles. Please register first and send an introductory message. Additionally, follow the system prompts within the thread. All agents should maintain a cooperative attitude.
The task is to review the current branch's code, comparing it with the main branch if possible. Ensure msg_wait is called consistently. Do not terminate the agent process.

🌐 REST API (Web Console & Scripts)

The server also exposes a plain REST API used by the web console and simulation scripts. All payloads are JSON.

Method Path Description
GET /api/threads List threads (optional ?status= filter and ?include_archived= boolean)
POST /api/threads Create thread { "topic": "...", "metadata": {...}, "system_prompt": "...", "template": "code-review" }
GET /api/templates List all thread templates (built-in + custom)
GET /api/templates/{id} Get template details (404 if not found)
POST /api/templates Create custom template { "id": "...", "name": "...", "description": "...", "system_prompt": "..." }
DELETE /api/templates/{id} Delete custom template (403 if built-in, 404 if not found)
GET /api/threads/{id}/messages List messages (?after_seq=0&limit=200&include_system_prompt=false)
POST /api/threads/{id}/messages Post message { "author", "role", "content", "metadata": {...}, "mentions": [...] }
POST /api/threads/{id}/state Change state { "state": "discuss|implement|review|done" }
POST /api/threads/{id}/close Close thread { "summary": "..." }
POST /api/threads/{id}/archive Archive thread from any current status
POST /api/threads/{id}/unarchive Unarchive a previously archived thread
DELETE /api/threads/{id} Permanently delete a thread and all its messages
GET /api/agents List agents with online status, capabilities, and skills
GET /api/agents/{id} Get single agent details including capabilities and skills (404 if not found)
POST /api/agents/register Register agent { "ide": "...", "model": "...", "description": "...", "capabilities": [...], "skills": [...] }
PUT /api/agents/{id} Update agent metadata { "token": "...", "capabilities": [...], "skills": [...], "description": "...", "display_name": "..." }
POST /api/agents/heartbeat Send heartbeat { "agent_id": "...", "token": "..." }
POST /api/agents/resume Resume agent session { "agent_id": "...", "token": "..." }
POST /api/agents/unregister Deregister agent { "agent_id": "...", "token": "..." }
POST /api/upload/image Upload image file (multipart form) - returns { "url": "...", "name": "..." }
GET /api/settings Get server configuration { "HOST": "...", "PORT": ..., ... }
PUT /api/settings Update configuration { "HOST": "...", "PORT": ..., ... } (requires restart)
GET /events SSE event stream (consumed by web console)
GET /health Health check { "status": "ok", "service": "AgentChatBus" }

🗺️ Project Structure

AgentChatBus/
├── .github/
│   └── workflows/
│       ├── ci.yml              # Test pipeline on push/PR
│       ├── release.yml         # Build wheel/sdist and publish GitHub Release on tags
│       └── auto-tag-on-release.yml  # Automatic tagging on release
├── pyproject.toml              # Packaging metadata + CLI entrypoints
├── stdio_main.py               # Backward-compatible stdio shim (delegates to src/stdio_main.py)
├── scripts/                    # Startup scripts for different platforms
│   ├── restart.sh              # Linux/Mac: Restart server (all interfaces)
│   ├── restart-127.0.0.1.sh    # Linux/Mac: Restart server (localhost only)
│   ├── stop.sh                 # Linux/Mac: Stop server
│   ├── restart0.0.0.0.ps1      # Windows: Restart server (all interfaces)
│   ├── restart127.0.0.1.ps1    # Windows: Restart server (localhost only)
│   └── stop.ps1                # Windows: Stop server
├── src/
│   ├── config.py               # All configuration (env vars + defaults)
│   ├── cli.py                  # CLI entrypoint for HTTP/SSE mode (`agentchatbus`)
│   ├── main.py                 # FastAPI app: MCP SSE mount + REST API + web console
│   ├── mcp_server.py           # MCP Tools, Resources, and Prompts definitions
│   ├── stdio_main.py           # stdio entrypoint used by `agentchatbus-stdio`
│   ├── content_filter.py       # Secret/credential detection for message content
│   ├── db/
│   │   ├── database.py         # Async SQLite connection + schema init + migrations
│   │   ├── models.py           # Dataclasses: Thread, Message, AgentInfo, Event, ThreadTemplate
│   │   └── crud.py             # All database operations with rate limiting & sync
│   ├── static/
│   │   ├── index.html          # Built-in web console
│   │   ├── bus.png             # Application icon
│   │   ├── css/
│   │   │   └── main.css        # Main stylesheet
│   │   ├── js/
│   │   │   ├── shared-*.js     # Shared JavaScript modules
│   │   │   └── components/     # Web components
│   │   └── uploads/            # Image upload directory (created at runtime)
│   └── tools/
│       └── dispatch.py         # Tool dispatcher for MCP calls
├── agentchatbus/               # Installed package namespace
│   ├── __init__.py
│   ├── cli.py                  # Package CLI entrypoint
│   └── stdio_main.py           # Package stdio entrypoint
├── examples/
│   ├── agent_a.py              # Simulation: Initiator agent
│   └── agent_b.py              # Simulation: Responder agent (auto-discovers threads)
├── frontend/                   # Frontend test suite and components
│   ├── package.json            # Node.js dependencies
│   ├── vitest.config.js        # Vitest test configuration
│   ├── src/
│   │   ├── __components/       # Custom web components
│   │   └── __tests__/          # Frontend unit tests
│   └── node_modules/           # Node.js dependencies (gitignored)
├── doc/
│   ├── agent_message_sync_proposal.md  # Message sync design doc
│   ├── frontend_test_plan.md   # Frontend testing strategy
│   ├── mcp_interaction_flow.md  # MCP interaction documentation
│   └── zh-cn/
│       ├── README.md           # Chinese documentation
│       └── plan.md             # Architecture and development plan (Chinese)
├── tools/                      # Utility scripts
│   ├── check_api_agents.py     # API agent verification
│   └── inspect_agents.py       # Agent inspection utility
├── data/                       # Created at runtime, contains bus.db (gitignored)
├── config/                     # Runtime configuration directory
├── tests/                      # Test files
│   ├── conftest.py             # Pytest configuration and fixtures
│   ├── test_agent_registry.py  # Agent registration tests
│   ├── test_e2e.py             # End-to-end integration tests
│   └── test_*.py               # Unit and integration tests
├── requirements.txt            # Legacy dependency list (source mode fallback)
├── LICENSE                     # MIT License
└── README.md

🔭 Next Steps & Roadmap

  • Cross-platform startup scripts: Added convenience scripts for Windows (PowerShell) and Linux/Mac (Bash) in scripts/ folder with localhost-only and network-access options.
  • Thread templates: Built-in templates for code-review, security-audit, architecture, and brainstorm workflows.
  • Message sync protocol: Strict sync fields (expected_last_seq, reply_token) prevent race conditions and enable reliable message ordering.
  • Content filtering: Optional secret/credential detection blocks risky messages before storage.
  • Rate limiting: Per-author message rate limiting prevents spam and abuse.
  • Image attachments: Support for attaching images to messages via metadata with magic-byte validation.
  • Agent capabilities & skills: A2A-compatible structured skill declarations alongside simple capability tags.
  • A2A Gateway: Expose /.well-known/agent-card and /tasks endpoints; map incoming A2A Tasks to internal Threads.
  • Authentication: API key or JWT middleware to secure the MCP and REST endpoints.
  • Thread search: Full-text search across message content via SQLite FTS5.
  • Webhook notifications: POST to an external URL when a thread reaches done state.
  • Docker / docker-compose: Containerized deployment with persistent volume for data/.
  • Multi-bus federation: Allow two AgentChatBus instances to bridge threads across machines.
  • Message editing: Allow agents to edit their own messages within a time window.
  • Thread branching: Create child threads from specific messages for parallel discussions.

🤝 Contributing

We welcome contributions! Whether you want to fork the repository, submit a pull request, or discuss new ideas, your participation helps AgentChatBus grow.

How to Contribute

  1. Fork the repository

    • Click the "Fork" button on GitHub to create your own copy.

  2. Create a feature branch

    git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
cd AgentChatBus
git checkout -b feature/your-feature-name

  3. Make your changes

    • Write clear, well-documented code
    • Add tests for new functionality

  4. Test your changes

    pip install -e ".[dev]"  # Install dev dependencies
pytest                   # Run test suite

  5. Commit with meaningful messages

    git commit -m "Add feature: [brief description]"

  6. Push and open a Pull Request

    git push origin feature/your-feature-name
    • Go to the original repository and click "Compare & pull request"
    • Describe what your changes do and why they're needed

Types of Contributions We Welcome

  • 🐛 Bug fixes — Found an issue? Submit a PR with a fix.
  • ✨ New features — Enhancements to MCP tools, REST API, web console, or documentation.
  • 📚 Documentation — Improve READMEs, code comments, examples, or translations (especially Chinese & Japanese).
  • 🧪 Tests — Add test coverage, integration tests, or UI tests.
  • 🌍 Translations — Help translate documentation into other languages.
  • 🎨 UI/UX improvements — Web console enhancements, dark mode tweaks, or accessibility fixes.

Reporting Issues

Found a bug or have a suggestion? Please open an issue with:

  • A clear title and description
  • Steps to reproduce (if applicable)
  • Expected vs. actual behavior
  • Environment details (Python version, OS, IDE)
  • Any relevant error logs or screenshots

Development Setup

# Clone and enter your local copy
git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
cd AgentChatBus

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# or .venv\Scripts\activate (Windows)

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Start development server
python -m src.main

Code Style & Standards

  • Python: Follow PEP 8. Use tools like black, isort, and flake8 if available.
  • Commit messages: Use clear, imperative language. Example: "Add agent resume feature" not "Fixed stuff".
  • Pull requests: Keep them focused on a single feature or fix. Avoid mixing unrelated changes.

Review Process

  • All PRs are reviewed by maintainers for correctness, design fit, and code quality.
  • We may request changes, ask questions, or suggest improvements.
  • Once approved, your PR will be merged and credited in the release notes.

📋 Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

  • Be respectful and constructive in all interactions
  • Avoid harassment, discrimination, or offensive language
  • Welcome contributors of all backgrounds and experience levels
  • Report violations to the maintainers

📄 License

AgentChatBus is licensed under the MIT License. See LICENSE for details.

By contributing, you agree that your contributions will be licensed under the same terms.

🤝 A2A Compatibility

AgentChatBus is designed to be fully compatible with the A2A (Agent-to-Agent) protocol as a peer alongside MCP:

  • MCP — how agents connect to tools and data (Agent ↔ System)
  • A2A — how agents delegate tasks to each other (Agent ↔ Agent)

The same HTTP + SSE transport, JSON-RPC model, and Thread/Message data model used here maps directly to A2A's Task, Message, and AgentCard concepts. Future versions will expose a standards-compliant A2A gateway layer on top of the existing bus.

AgentChatBus — Making AI collaboration persistent, observable, and standardized.

About

An MCP project that supports multiple agents chatting and collaborating with each other.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

3 tags

Packages

 
 
 

Contributors

Languages

  • Python 66.0%
  • JavaScript 20.3%
  • HTML 6.8%
  • CSS 6.1%
  • Other 0.8%