convez.ai
MCP ServerAutomaçãoAvançado
saiprasadgudari

Maestro - Orquestrador de Agentes Multi-Plataforma

saiprasadgudari/agent-orchestrator

Backend portável para orquestração de agentes IA em múltiplos canais de chat

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que oferece uma camada de operações para agentes de IA rodarem nativamente em plataformas de chat (Slack, Discord, Teams, Telegram, Mattermost, etc.) com gerenciamento centralizado de sessões, memória, agendamento e segurança. Ideal para equipes que querem integrar agentes de codificação diretamente nos fluxos de comunicação existentes.

Instalação

$npx convez-ai saiprasadgudari/agent-orchestrator

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar agentes de codificação Claude nativamente em Slack/Discord/Teams
  • Gerenciar sessões isoladas de agentes com memória persistente e histórico
  • Agendar jobs de automação que disparam novas sessões de agentes
  • Auditar e monitorar execução de agentes com dashboard centralizado
  • Integrar múltiplas plataformas de chat com a mesma lógica de orquestração

Veredito

Sistema maduro de backend para orquestração de agentes IA em produção. Arquitetura bem pensada (abstração por ChatAdapter, isolamento de sessões, safety guards), mas requer expertise em Python/DevOps para deployment em produção — não é ferramenta plug-and-play para iniciantes.

README

A tradução para o português deste README ainda está na fila.

Maestro

Maestro is a multi-platform agent operations layer for teams that want AI coding agents to work inside the conversations where engineering decisions already happen.

It is built around a simple idea: chat platforms should be replaceable infrastructure, not application logic. The daemon talks to Slack, Discord, Telegram, Mattermost, Teams, webhooks, or a bundled local SQLite chat through the same ChatAdapter interface. Everything downstream of that interface stays the same: session orchestration, memory, scheduling, sandboxing, audit, and the dashboard.

Why This Project Exists

Most agent demos are tied to one chat platform or one toy UI. Maestro is designed as a portable backend system:

  • Run the full product locally with only Python, uv, SQLite, and Claude Code.
  • Swap chat backends by changing chat.backend in config/config.yaml.
  • Keep agent sessions isolated in disposable workspaces.
  • Give each session the same MCP tool surface regardless of platform.
  • Track live sessions, memory, schedules, and chat state from one dashboard.
  • Treat safety as an implementation concern: pre-tool guards, read-only agent settings, credential filters, and post-session audit.

That makes Maestro useful as both a runnable project and a serious backend/system-design portfolio piece.

System Shape

Maestro is a single Python service with a small set of durable stores:

Chat backend
  local SQLite | Slack | Discord | Telegram | Mattermost | Teams | webhook
        |
        v
ChatAdapter interface
        |
        v
ChatListener daemon
  - access control
  - active session registry
  - FIFO queue and concurrency limits
  - scheduler binding
  - dashboard API
        |
        v
Agent session runtime
  - fresh workspace
  - generated mcp.json
  - Claude Code subprocess
  - per-session MCP tools
        |
        v
Durable state
  chat.db | memory index | schedules.db | session history

The important design decision is that chat transport code is kept at the edge. The daemon receives platform-neutral Message, Channel, User, and ChatEvent objects, then runs the same orchestration path for every backend.

Core Capabilities

Multi-platform chat adapters

BackendModuleNotes
Locallib/chat/local.pySQLite-backed demo and development backend
Slacklib/chat/slack.pyWeb API plus Socket Mode
Discordlib/chat/discord.pyGateway client bridged into the daemon
Telegramlib/chat/telegram.pyBot API long-polling, no SDK required
Mattermostlib/chat/mattermost.pyREST v4 plus WebSocket
Teamslib/chat/teams.pyMicrosoft identity and Bot Framework style integration
Webhooklib/chat/webhook.pyGeneric inbound/outbound integration point

Agent orchestration

  • One isolated session per accepted chat request.
  • Configurable max_concurrent_sessions with FIFO overflow.
  • Per-session mcp.json generated with runtime context.
  • Session monitor for clean exits, crashes, and stale sessions.
  • Workspace cleanup after completion.

Memory and scheduling

  • SQLite memory store with FTS5 lexical search.
  • Optional vector search through sqlite-vec.
  • Lightweight knowledge graph support.
  • APScheduler-backed recurring and one-shot jobs.
  • Scheduled jobs can launch new agent sessions.

Safety and observability

  • PreToolUse guards for SSH keys, unsafe GitHub operations, and env-var leakage.
  • Central sensitive environment variable inventory.
  • Read-only merged Claude settings inside each session workspace.
  • LLM-as-judge audit pass for completed session transcripts.
  • Built-in HTTP dashboard for sessions, chat, memory, schedules, and health.

Quick Start

Prerequisites:

python3.12
uv
node
claude

Install and run:

uv sync --extra dev
uv run python -m lib.listener

By default, Maestro uses the local SQLite chat backend:

chat:
  backend: "local"
  store_path: "./data/chat.db"

In another shell, post a local chat message:

from lib.chat import post_user_message

post_user_message(
    "general",
    "release-check",
    "you@example.com",
    "@maestro inspect the latest failure and summarize what changed",
)

The dashboard runs at:

http://localhost:8150

Running On Real Chat Platforms

Change chat.backend and provide the matching credentials:

# Slack
uv sync --extra slack
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...

# Discord
uv sync --extra discord
export DISCORD_BOT_TOKEN=...

# Telegram
export TELEGRAM_BOT_TOKEN=...

# Mattermost
uv sync --extra mattermost
export MATTERMOST_URL=https://mattermost.example.com
export MATTERMOST_TOKEN=...

# Teams
uv sync --extra teams
export TEAMS_APP_ID=...
export TEAMS_APP_PASSWORD=...
export TEAMS_TENANT_ID=...

# Generic webhook
export WEBHOOK_OUTBOUND_URL=https://your-service.example.com/inbound

Then run the same daemon:

uv run python -m lib.listener

No orchestration code changes are needed when switching platforms.

Adding A Chat Backend

Implement ChatAdapter:

from lib.chat.adapter import ChatAdapter
from lib.chat.types import ChatEvent, Identity, Message


class MyChatAdapter(ChatAdapter):
    def identity(self) -> Identity: ...
    def listen(self, on_event) -> None: ...
    def post(self, channel: str, thread: str, text: str) -> int: ...
    def history(
        self,
        channel: str,
        thread: str | None = None,
        *,
        limit: int = 50,
        after: int | None = None,
    ) -> list[Message]: ...

Register it in lib/chat/__init__.py, add config validation if needed, and copy an adapter test from tests/test_chat_adapters.py.

For platforms with string-native IDs, use lib/chat/idmap.py. For platforms that cannot reliably fetch history, use lib/chat/msgcache.py to mirror messages into SQLite.

Project Layout

PathResponsibility
lib/listener.pyMain daemon, session table, queue, event handling
lib/chat/Chat adapter interface and platform implementations
lib/session_spawn.pyWorkspace setup and Claude Code launch
lib/session_monitor.pyExit classification, stale-session handling, queue drain
lib/workspace.pyEphemeral workspaces and generated session MCP config
lib/mcp_server.pyMaestro MCP server for memory and scheduling
lib/chat/mcp_server.pyAgent-facing chat tools
lib/memory.pySQLite memory, search, and knowledge graph
lib/scheduler.pyAPScheduler integration
lib/http_server.pyDashboard and JSON inspection endpoints
hooks/Security and session lifecycle hooks
static/Dashboard frontend
tests/Pytest coverage for contracts, adapters, guards, memory, scheduler, dashboard APIs

Quality Bar

The repository includes broad regression coverage:

uv run python -m pytest tests -q
uv run ruff check .
node --test static/dashboard.test.mjs
node static/dashboard.lint.mjs

Current verified state:

697 pytest tests passed
ruff clean
20 dashboard tests passed
dashboard structural lint passed

Tech Stack

Python 3.12, SQLite, SQLAlchemy, APScheduler, FastMCP, MCP, Claude Code CLI, pytest, Ruff, vanilla HTML/CSS/JavaScript, Node built-in test runner, optional Slack SDK, Discord.py, websocket-client, and MSAL.

Ver o original no GitHub

Bom para

Relacionados